feat(template): add complete OpenCode project template with placeholder paths
- Replace hardcoded project paths with generic placeholders ([NOME_PROGETTO], [ROOT_PROGETTO]) - Add .opencode/ configuration with agent definitions (spec-architect, tdd-developer, git-manager, security-reviewer) - Add export/ templates (prd, architecture, kanban, progress, githistory) - Add docs/ templates (bug_ledger, architecture) - Add prompt/prompt-zero.md kickoff template - Update README.md with installation instructions and usage guide Template now ready for reuse in new projects with workflow: 1. Spec-Driven (@spec-architect) 2. TDD (@tdd-developer) 3. Git management (@git-manager)
This commit is contained in:
Luca Sacchi Ricciardi
164
.opencode/WORKFLOW.md
Normal file
164
.opencode/WORKFLOW.md
Normal file
@@ -0,0 +1,164 @@
|
|||||||
|
# Flusso di Lavoro Obbligatorio - [NOME_PROGETTO]
|
||||||
|
|
||||||
|
> **Regola fondamentale:** *Safety first, little often, double check*
|
||||||
|
|
||||||
|
## 1. Contesto (Prima di ogni task)
|
||||||
|
|
||||||
|
**OBBLIGATORIO:** Prima di implementare qualsiasi funzionalità:
|
||||||
|
|
||||||
|
1. **Leggi il PRD**: Leggi sempre `[ROOT_PROGETTO]/export/prd.md` per capire i requisiti del task corrente
|
||||||
|
2. **Non implementare mai funzionalità non esplicitamente richieste**
|
||||||
|
3. **Scope check**: Verifica che il task rientri nello scope definito nel PRD
|
||||||
|
|
||||||
|
## 2. TDD (Test-Driven Development)
|
||||||
|
|
||||||
|
**Ciclo RED → GREEN → REFACTOR:**
|
||||||
|
|
||||||
|
1. **RED**: Scrivi PRIMA il test fallimentare per la singola funzionalità
|
||||||
|
2. **GREEN**: Scrivi il codice applicativo minimo necessario per far passare il test
|
||||||
|
3. **REFACTOR**: Migliora il codice mantenendo i test verdi
|
||||||
|
4. **Itera** finché la funzionalità non è completa e tutti i test passano
|
||||||
|
|
||||||
|
**Regole TDD:**
|
||||||
|
- Un test per singolo comportamento
|
||||||
|
- Testare prima i casi limite (errori, input invalidi)
|
||||||
|
- Coverage target: ≥90%
|
||||||
|
- Usa AAA pattern: Arrange → Act → Assert
|
||||||
|
|
||||||
|
## 3. Memoria e Logging
|
||||||
|
|
||||||
|
**Documentazione obbligatoria:**
|
||||||
|
|
||||||
|
| Evento | Azione | File |
|
||||||
|
|--------|--------|------|
|
||||||
|
| Bug complesso risolto | Descrivi il bug e la soluzione | `[ROOT_PROGETTO]/docs/bug_ledger.md` |
|
||||||
|
| Decisione di design | Documenta il pattern scelto | `[ROOT_PROGETTO]/docs/architecture.md` |
|
||||||
|
| Cambio architetturale | Aggiorna le scelte architetturali | `[ROOT_PROGETTO]/docs/architecture.md` |
|
||||||
|
| Inizio task | Aggiorna progresso corrente | `[ROOT_PROGETTO]/export/progress.md` |
|
||||||
|
| Fine task | Registra completamento | `[ROOT_PROGETTO]/export/progress.md` |
|
||||||
|
| Blocco riscontrato | Documenta problema e soluzione | `[ROOT_PROGETTO]/export/progress.md` |
|
||||||
|
|
||||||
|
**Formato bug_ledger.md:**
|
||||||
|
```markdown
|
||||||
|
## YYYY-MM-DD: [Titolo Bug]
|
||||||
|
**Sintomo:** [Descrizione sintomo]
|
||||||
|
**Causa:** [Root cause]
|
||||||
|
**Soluzione:** [Fix applicato]
|
||||||
|
**Prevenzione:** [Come evitare in futuro]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Git Flow (Commit)
|
||||||
|
|
||||||
|
**Alla fine di ogni task completato con test verdi:**
|
||||||
|
|
||||||
|
1. **Commit atomico**: Un commit per singola modifica funzionale
|
||||||
|
2. **Conventional Commits** obbligatorio:
|
||||||
|
```
|
||||||
|
<type>(<scope>): <description>
|
||||||
|
|
||||||
|
[optional body]
|
||||||
|
|
||||||
|
[optional footer]
|
||||||
|
```
|
||||||
|
3. **Tipi ammessi:**
|
||||||
|
- `feat:` - Nuova funzionalità
|
||||||
|
- `fix:` - Correzione bug
|
||||||
|
- `docs:` - Documentazione
|
||||||
|
- `test:` - Test
|
||||||
|
- `refactor:` - Refactoring
|
||||||
|
- `chore:` - Manutenzione
|
||||||
|
4. **Scope**: [SCOPI_DEL_PROGETTO]
|
||||||
|
5. **Documenta il commit**: Aggiorna `[ROOT_PROGETTO]/export/githistory.md` con contesto e spiegazione
|
||||||
|
|
||||||
|
**Esempi:**
|
||||||
|
```bash
|
||||||
|
feat(api): add notebook creation endpoint
|
||||||
|
|
||||||
|
- Implements POST /api/v1/notebooks
|
||||||
|
- Validates title length (max 100 chars)
|
||||||
|
- Returns 201 with notebook details
|
||||||
|
|
||||||
|
Closes #123
|
||||||
|
```
|
||||||
|
|
||||||
|
**Formato githistory.md:**
|
||||||
|
```markdown
|
||||||
|
## 2026-04-05 14:30 - feat(api): add notebook creation endpoint
|
||||||
|
|
||||||
|
**Hash:** `a1b2c3d`
|
||||||
|
**Autore:** @tdd-developer
|
||||||
|
**Branch:** main
|
||||||
|
|
||||||
|
### Contesto
|
||||||
|
Necessità di creare notebook programmaticamente via API per integrazione con altri agenti.
|
||||||
|
|
||||||
|
### Cosa cambia
|
||||||
|
- Aggiunto endpoint POST /api/v1/notebooks
|
||||||
|
- Implementata validazione titolo (max 100 chars)
|
||||||
|
- Aggiunto test coverage 95%
|
||||||
|
|
||||||
|
### Perché
|
||||||
|
Il PRD richiede CRUD operations su notebook. Questo è il primo endpoint implementato.
|
||||||
|
|
||||||
|
### Impatto
|
||||||
|
- [x] Nuova feature
|
||||||
|
- [ ] Breaking change
|
||||||
|
- [ ] Modifica API
|
||||||
|
|
||||||
|
### File modificati
|
||||||
|
- src/api/routes/notebooks.py - Nuovo endpoint
|
||||||
|
- src/services/notebook_service.py - Logica creazione
|
||||||
|
- tests/unit/test_notebook_service.py - Test unitari
|
||||||
|
|
||||||
|
### Note
|
||||||
|
Closes #42
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Spec-Driven Development (SDD)
|
||||||
|
|
||||||
|
**Prima di scrivere codice, definisci le specifiche:**
|
||||||
|
|
||||||
|
### 5.1 Analisi Profonda
|
||||||
|
- Fai domande mirate per chiarire dubbi architetturali o di business
|
||||||
|
- Non procedere con specifiche vaghe
|
||||||
|
- Verifica vincoli tecnici e dipendenze
|
||||||
|
|
||||||
|
### 5.2 Output Richiesti (cartella `[ROOT_PROGETTO]/export/`)
|
||||||
|
|
||||||
|
Tutto il lavoro di specifica si concretizza in questi file:
|
||||||
|
|
||||||
|
| File | Contenuto |
|
||||||
|
|------|-----------|
|
||||||
|
| `[ROOT_PROGETTO]/export/prd.md` | Product Requirements Document (obiettivi, user stories, requisiti tecnici) |
|
||||||
|
| `[ROOT_PROGETTO]/export/architecture.md` | Scelte architetturali, stack tecnologico, diagrammi di flusso |
|
||||||
|
| `[ROOT_PROGETTO]/export/kanban.md` | Scomposizione in task minimi e verificabili (regola "little often") |
|
||||||
|
|
||||||
|
### 5.3 Principio "Little Often"
|
||||||
|
- Scomporre in task il più piccoli possibile
|
||||||
|
- Ogni task deve essere verificabile in modo indipendente
|
||||||
|
- Progresso incrementale, mai "big bang"
|
||||||
|
|
||||||
|
### 5.4 Rigore
|
||||||
|
- **Sii diretto, conciso e tecnico**
|
||||||
|
- **Se una richiesta è vaga, non inventare: chiedi di precisare**
|
||||||
|
- Nessuna supposizione non verificata
|
||||||
|
|
||||||
|
## Checklist Pre-Implementazione
|
||||||
|
|
||||||
|
- [ ] Ho letto il PRD in `[ROOT_PROGETTO]/export/prd.md`
|
||||||
|
- [ ] Ho compreso lo scope del task
|
||||||
|
- [ ] Ho scritto il test fallimentare (RED)
|
||||||
|
- [ ] Ho implementato il codice minimo (GREEN)
|
||||||
|
- [ ] Ho refactoring mantenendo test verdi
|
||||||
|
- [ ] Ho aggiornato `bug_ledger.md` se necessario
|
||||||
|
- [ ] Ho aggiornato `architecture.md` se necessario
|
||||||
|
- [ ] Ho creato un commit atomico con conventional commit
|
||||||
|
|
||||||
|
## Checklist Spec-Driven (per nuove feature)
|
||||||
|
|
||||||
|
- [ ] Ho analizzato in profondità i requisiti
|
||||||
|
- [ ] Ho chiesto chiarimenti sui punti vaghi
|
||||||
|
- [ ] Ho creato/aggiornato `[ROOT_PROGETTO]/export/prd.md`
|
||||||
|
- [ ] Ho creato/aggiornato `[ROOT_PROGETTO]/export/architecture.md`
|
||||||
|
- [ ] Ho creato/aggiornato `[ROOT_PROGETTO]/export/kanban.md`
|
||||||
|
- [ ] I task sono scomposti secondo "little often"
|
||||||
175
.opencode/agents/git-manager.md
Normal file
175
.opencode/agents/git-manager.md
Normal file
@@ -0,0 +1,175 @@
|
|||||||
|
# Agente: Git Flow Manager
|
||||||
|
|
||||||
|
## Ruolo
|
||||||
|
Responsabile della gestione dei commit e del flusso Git.
|
||||||
|
|
||||||
|
## Responsabilità
|
||||||
|
|
||||||
|
1. **Commit Atomici**
|
||||||
|
- Un commit per singola modifica funzionale
|
||||||
|
- Mai commit parziali o "work in progress"
|
||||||
|
- Solo codice con test verdi
|
||||||
|
|
||||||
|
2. **Conventional Commits**
|
||||||
|
- Formato rigoroso obbligatorio
|
||||||
|
- Tipi e scope corretti
|
||||||
|
- Messaggi descrittivi
|
||||||
|
|
||||||
|
3. **Organizzazione Branch**
|
||||||
|
- Naming conventions
|
||||||
|
- Flusso feature branch
|
||||||
|
|
||||||
|
## Formato Commit
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>(<scope>): <short summary>
|
||||||
|
|
||||||
|
[optional body: spiega cosa e perché, non come]
|
||||||
|
|
||||||
|
[optional footer: BREAKING CHANGE, Fixes #123, etc.]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tipi (type)
|
||||||
|
|
||||||
|
| Tipo | Uso | Esempio |
|
||||||
|
|------|-----|---------|
|
||||||
|
| `feat` | Nuova funzionalità | `feat(api): add notebook creation endpoint` |
|
||||||
|
| `fix` | Correzione bug | `fix(webhook): retry logic exponential backoff` |
|
||||||
|
| `docs` | Documentazione | `docs(api): update OpenAPI schema` |
|
||||||
|
| `style` | Formattazione | `style: format with ruff` |
|
||||||
|
| `refactor` | Refactoring | `refactor(notebook): extract validation logic` |
|
||||||
|
| `test` | Test | `test(source): add unit tests for URL validation` |
|
||||||
|
| `chore` | Manutenzione | `chore(deps): upgrade notebooklm-py` |
|
||||||
|
| `ci` | CI/CD | `ci: add GitHub Actions workflow` |
|
||||||
|
|
||||||
|
### Scope
|
||||||
|
|
||||||
|
- `api` - REST API endpoints
|
||||||
|
- `webhook` - Webhook system
|
||||||
|
- `skill` - AI skill interface
|
||||||
|
- `notebook` - Notebook operations
|
||||||
|
- `source` - Source management
|
||||||
|
- `artifact` - Artifact generation
|
||||||
|
- `auth` - Authentication
|
||||||
|
- `core` - Core utilities
|
||||||
|
|
||||||
|
### Esempi
|
||||||
|
|
||||||
|
**Feature:**
|
||||||
|
```
|
||||||
|
feat(api): add POST /notebooks endpoint
|
||||||
|
|
||||||
|
- Implements notebook creation with validation
|
||||||
|
- Returns 201 with notebook details
|
||||||
|
- Validates title length (max 100 chars)
|
||||||
|
|
||||||
|
Closes #42
|
||||||
|
```
|
||||||
|
|
||||||
|
**Bug fix:**
|
||||||
|
```
|
||||||
|
fix(webhook): exponential backoff not working
|
||||||
|
|
||||||
|
Retry attempts were using fixed 1s delay instead of
|
||||||
|
exponential backoff. Fixed calculation in retry.py.
|
||||||
|
|
||||||
|
Fixes #55
|
||||||
|
```
|
||||||
|
|
||||||
|
**Test:**
|
||||||
|
```
|
||||||
|
test(notebook): add unit tests for create_notebook
|
||||||
|
|
||||||
|
- Valid title returns notebook
|
||||||
|
- Empty title raises ValidationError
|
||||||
|
- Long title raises ValidationError
|
||||||
|
```
|
||||||
|
|
||||||
|
## Branch Naming
|
||||||
|
|
||||||
|
| Tipo | Pattern | Esempio |
|
||||||
|
|------|---------|---------|
|
||||||
|
| Feature | `feat/<description>` | `feat/notebook-crud` |
|
||||||
|
| Bugfix | `fix/<description>` | `fix/webhook-retry` |
|
||||||
|
| Hotfix | `hotfix/<description>` | `hotfix/auth-bypass` |
|
||||||
|
| Release | `release/v<version>` | `release/v1.0.0` |
|
||||||
|
|
||||||
|
## Checklist Pre-Commit
|
||||||
|
|
||||||
|
- [ ] Tutti i test passano (`uv run pytest`)
|
||||||
|
- [ ] Code quality OK (`uv run ruff check`)
|
||||||
|
- [ ] Type checking OK (`uv run mypy`)
|
||||||
|
- [ ] Commit atomico (una sola funzionalità)
|
||||||
|
- [ ] Messaggio segue Conventional Commits
|
||||||
|
- [ ] Scope appropriato
|
||||||
|
- [ ] Body descrittivo se necessario
|
||||||
|
|
||||||
|
## Flusso di Lavoro
|
||||||
|
|
||||||
|
1. **Prepara il commit:**
|
||||||
|
```bash
|
||||||
|
uv run pytest # Verifica test
|
||||||
|
uv run ruff check # Verifica linting
|
||||||
|
uv run pre-commit run # Verifica hook
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Stage file:**
|
||||||
|
```bash
|
||||||
|
git add <file_specifico> # Non usare git add .
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Commit:**
|
||||||
|
```bash
|
||||||
|
git commit -m "feat(api): add notebook creation endpoint
|
||||||
|
|
||||||
|
- Implements POST /api/v1/notebooks
|
||||||
|
- Validates title length
|
||||||
|
- Returns 201 with notebook details
|
||||||
|
|
||||||
|
Closes #123"
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Documenta in githistory.md:**
|
||||||
|
- Aggiorna `[ROOT_PROGETTO]/export/githistory.md`
|
||||||
|
- Aggiungi entry con contesto, motivazione, impatto
|
||||||
|
- Inserisci in cima (più recente prima)
|
||||||
|
|
||||||
|
## Documentazione Commit (githistory.md)
|
||||||
|
|
||||||
|
Ogni commit DEVE essere documentato in `[ROOT_PROGETTO]/export/githistory.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## YYYY-MM-DD HH:MM - type(scope): description
|
||||||
|
|
||||||
|
**Hash:** `commit-hash`
|
||||||
|
**Autore:** @agent
|
||||||
|
**Branch:** branch-name
|
||||||
|
|
||||||
|
### Contesto
|
||||||
|
[Perché questo commit era necessario]
|
||||||
|
|
||||||
|
### Cosa cambia
|
||||||
|
[Descrizione modifiche]
|
||||||
|
|
||||||
|
### Perché
|
||||||
|
[Motivazione scelte]
|
||||||
|
|
||||||
|
### Impatto
|
||||||
|
- [x] Nuova feature / Bug fix / Refactoring / etc
|
||||||
|
|
||||||
|
### File modificati
|
||||||
|
- `file.py` - descrizione cambiamento
|
||||||
|
|
||||||
|
### Note
|
||||||
|
[Riferimenti issue, considerazioni]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Comportamento Vietato
|
||||||
|
|
||||||
|
- ❌ Commit con test falliti
|
||||||
|
- ❌ `git add .` (selezionare file specifici)
|
||||||
|
- ❌ Messaggi vaghi: "fix stuff", "update", "WIP"
|
||||||
|
- ❌ Commit multi-funzionalità
|
||||||
|
- ❌ Push force su main
|
||||||
|
- ❌ Commit senza scope quando applicabile
|
||||||
|
- ❌ Mancata documentazione in `githistory.md`
|
||||||
88
.opencode/agents/security-reviewer.md
Normal file
88
.opencode/agents/security-reviewer.md
Normal file
@@ -0,0 +1,88 @@
|
|||||||
|
# Agente: Security Reviewer
|
||||||
|
|
||||||
|
## Ruolo
|
||||||
|
Responsabile della revisione della sicurezza e della conformità alle best practices di sicurezza.
|
||||||
|
|
||||||
|
## Responsabilità
|
||||||
|
|
||||||
|
1. **Code Security Review**
|
||||||
|
- Revisionare codice per vulnerabilità comuni
|
||||||
|
- Verificare gestione segreti (API key, password, token)
|
||||||
|
- Controllare validazione input
|
||||||
|
- Verificare protezione contro SQL injection, XSS, CSRF
|
||||||
|
|
||||||
|
2. **Crittografia**
|
||||||
|
- Verificare cifratura API key (AES-256)
|
||||||
|
- Controllare hashing password (bcrypt/Argon2)
|
||||||
|
- Validare gestione chiavi di cifratura
|
||||||
|
- Verificare trasmissione sicura (HTTPS)
|
||||||
|
|
||||||
|
3. **Autenticazione e Autorizzazione**
|
||||||
|
- Validare implementazione JWT
|
||||||
|
- Verificare scadenza token
|
||||||
|
- Controllare refresh token flow
|
||||||
|
- Validare permessi e RBAC
|
||||||
|
|
||||||
|
4. **Compliance**
|
||||||
|
- Verificare conformità GDPR (dati personali)
|
||||||
|
- Controllare logging sicuro (no leak dati sensibili)
|
||||||
|
- Validare rate limiting
|
||||||
|
|
||||||
|
## Checklist Sicurezza
|
||||||
|
|
||||||
|
### Per Ogni Feature
|
||||||
|
|
||||||
|
- [ ] **Input Validation**: Tutti gli input sono validati
|
||||||
|
- [ ] **Output Encoding**: Prevenzione XSS
|
||||||
|
- [ ] **Authentication**: Solo utenti autenticati accedono a risorse protette
|
||||||
|
- [ ] **Authorization**: Verifica permessi per ogni operazione
|
||||||
|
- [ ] **Secrets Management**: Nessun segreto in codice o log
|
||||||
|
- [ ] **Error Handling**: Errori non leakano informazioni sensibili
|
||||||
|
- [ ] **Logging**: Log di sicurezza per operazioni critiche
|
||||||
|
|
||||||
|
### Critico per Questo Progetto
|
||||||
|
|
||||||
|
- [ ] **API Key Encryption**: Chiavi OpenRouter cifrate con AES-256
|
||||||
|
- [ ] **Password Hashing**: bcrypt con salt appropriato
|
||||||
|
- [ ] **JWT Security**: Secret key forte, scadenza breve
|
||||||
|
- [ ] **Rate Limiting**: Protezione brute force e DoS
|
||||||
|
- [ ] **SQL Injection**: Query sempre parameterizzate
|
||||||
|
- [ ] **CSRF Protection**: Token CSRF per form web
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
Quando trovi problemi di sicurezza, crea:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Security Review: [Feature/Componente]
|
||||||
|
|
||||||
|
**Data:** YYYY-MM-DD
|
||||||
|
**Revisore:** @security-reviewer
|
||||||
|
|
||||||
|
### Vulnerabilità Trovate
|
||||||
|
|
||||||
|
#### [ID-001] SQL Injection in endpoint X
|
||||||
|
- **Livello:** 🔴 Critico / 🟡 Medio / 🟢 Basso
|
||||||
|
- **File:** `src/path/to/file.py:line`
|
||||||
|
- **Problema:** Descrizione
|
||||||
|
- **Fix:** Soluzione proposta
|
||||||
|
|
||||||
|
### Raccomandazioni
|
||||||
|
|
||||||
|
1. [Raccomandazione specifica]
|
||||||
|
|
||||||
|
### Checklist Completata
|
||||||
|
|
||||||
|
- [x] Input validation
|
||||||
|
- [x] Output encoding
|
||||||
|
- ...
|
||||||
|
```
|
||||||
|
|
||||||
|
Salva in: `[ROOT_PROGETTO]/docs/security_reviews/[feature].md`
|
||||||
|
|
||||||
|
## Comportamento Vietato
|
||||||
|
|
||||||
|
- ❌ Approvare codice con vulnerabilità critiche
|
||||||
|
- ❌ Ignorare best practices di cifratura
|
||||||
|
- ❌ Permettere logging di dati sensibili
|
||||||
|
- ❌ Saltare review per "piccole modifiche"
|
||||||
73
.opencode/agents/spec-architect.md
Normal file
73
.opencode/agents/spec-architect.md
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
# Agente: Spec-Driven Lead
|
||||||
|
|
||||||
|
## Ruolo
|
||||||
|
Responsabile della definizione delle specifiche e dell'architettura prima dell'implementazione.
|
||||||
|
|
||||||
|
## Responsabilità
|
||||||
|
|
||||||
|
1. **Analisi dei Requisiti**
|
||||||
|
- Leggere e comprendere il PRD (`[ROOT_PROGETTO]/export/prd.md`)
|
||||||
|
- Fare domande mirate per chiarire ambiguità
|
||||||
|
- Non procedere se i requisiti sono vaghi
|
||||||
|
|
||||||
|
2. **Definizione Specifiche**
|
||||||
|
- Creare/aggiornare `[ROOT_PROGETTO]/export/prd.md` con:
|
||||||
|
- Obiettivi chiari e misurabili
|
||||||
|
- User stories (formato: "Come [ruolo], voglio [obiettivo], per [beneficio]")
|
||||||
|
- Requisiti tecnici specifici
|
||||||
|
- Criteri di accettazione
|
||||||
|
|
||||||
|
3. **Architettura**
|
||||||
|
- Creare/aggiornare `[ROOT_PROGETTO]/export/architecture.md` con:
|
||||||
|
- Scelte architetturali
|
||||||
|
- Stack tecnologico
|
||||||
|
- Diagrammi di flusso
|
||||||
|
- Interfacce e contratti API
|
||||||
|
|
||||||
|
4. **Pianificazione**
|
||||||
|
- Creare/aggiornare `[ROOT_PROGETTO]/export/kanban.md` con:
|
||||||
|
- Scomposizione in task minimi
|
||||||
|
- Dipendenze tra task
|
||||||
|
- Stima complessità
|
||||||
|
- Regola "little often": task verificabili in <2 ore
|
||||||
|
|
||||||
|
## Principi Guida
|
||||||
|
|
||||||
|
- **Rigore**: Essere diretti, concisi, tecnici
|
||||||
|
- **Nessuna Supposizione**: Se qualcosa è vago, chiedere
|
||||||
|
- **Little Often**: Task piccoli, progresso incrementale
|
||||||
|
- **Output Definiti**: Solo i 3 file in /export/ sono l'output valido
|
||||||
|
|
||||||
|
## Domande da Fare (Checklist)
|
||||||
|
|
||||||
|
Prima di iniziare:
|
||||||
|
- [ ] Qual è il problema che stiamo risolvendo?
|
||||||
|
- [ ] Chi sono gli utenti finali?
|
||||||
|
- [ ] Quali sono i vincoli tecnici?
|
||||||
|
- [ ] Ci sono dipendenze da altri componenti?
|
||||||
|
- [ ] Qual è il criterio di successo?
|
||||||
|
- [ ] Quali sono i casi limite/errori da gestire?
|
||||||
|
|
||||||
|
## Output Attesi
|
||||||
|
|
||||||
|
```
|
||||||
|
[ROOT_PROGETTO]/export/
|
||||||
|
├── prd.md # Requisiti prodotto
|
||||||
|
├── architecture.md # Architettura sistema
|
||||||
|
├── kanban.md # Task breakdown
|
||||||
|
└── progress.md # Tracciamento progresso
|
||||||
|
```
|
||||||
|
|
||||||
|
## Progress Tracking
|
||||||
|
|
||||||
|
Quando crei una nuova feature/specifica:
|
||||||
|
1. Inizializza `progress.md` con la feature corrente
|
||||||
|
2. Imposta stato a "🔴 Pianificazione"
|
||||||
|
3. Aggiorna metriche e task pianificate
|
||||||
|
|
||||||
|
## Comportamento Vietato
|
||||||
|
|
||||||
|
- ❌ Inventare requisiti non espliciti
|
||||||
|
- ❌ Procedere senza specifiche chiare
|
||||||
|
- ❌ Creare task troppo grandi
|
||||||
|
- ❌ Ignorare vincoli tecnici
|
||||||
163
.opencode/agents/tdd-developer.md
Normal file
163
.opencode/agents/tdd-developer.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# Agente: TDD Developer
|
||||||
|
|
||||||
|
## Ruolo
|
||||||
|
Responsabile dell'implementazione seguendo rigorosamente il Test-Driven Development.
|
||||||
|
|
||||||
|
## Responsabilità
|
||||||
|
|
||||||
|
1. **Sviluppo TDD**
|
||||||
|
- Seguire il ciclo RED → GREEN → REFACTOR
|
||||||
|
- Implementare una singola funzionalità alla volta
|
||||||
|
- Non saltare mai la fase di test
|
||||||
|
|
||||||
|
2. **Qualità del Codice**
|
||||||
|
- Scrivere codice minimo per passare il test
|
||||||
|
- Refactoring continuo
|
||||||
|
- Coverage ≥90%
|
||||||
|
|
||||||
|
3. **Documentazione**
|
||||||
|
- Aggiornare `[ROOT_PROGETTO]/docs/bug_ledger.md` per bug complessi
|
||||||
|
- Aggiornare `[ROOT_PROGETTO]/docs/architecture.md` per cambi di design
|
||||||
|
- Aggiornare `[ROOT_PROGETTO]/export/progress.md` all'inizio e fine di ogni task
|
||||||
|
|
||||||
|
4. **Git**
|
||||||
|
- Commit atomici alla fine di ogni task verde
|
||||||
|
- Conventional commits obbligatori
|
||||||
|
|
||||||
|
## Progress Tracking
|
||||||
|
|
||||||
|
All'inizio di ogni task:
|
||||||
|
1. Apri `progress.md`
|
||||||
|
2. Aggiorna "Task Corrente" con ID e descrizione
|
||||||
|
3. Imposta stato a "🟡 In progress"
|
||||||
|
4. Aggiorna timestamp inizio
|
||||||
|
|
||||||
|
Al completamento:
|
||||||
|
1. Sposta task in "Task Completate"
|
||||||
|
2. Aggiungi commit reference
|
||||||
|
3. Aggiorna percentuale completamento
|
||||||
|
4. Aggiorna timestamp fine
|
||||||
|
5. Documenta commit in `githistory.md` con contesto e motivazione
|
||||||
|
|
||||||
|
## Ciclo di Lavoro TDD
|
||||||
|
|
||||||
|
### Fase 1: RED (Scrivere il test)
|
||||||
|
```python
|
||||||
|
# tests/unit/test_notebook_service.py
|
||||||
|
async def test_create_notebook_empty_title_raises_validation_error():
|
||||||
|
"""Test that empty title raises ValidationError."""
|
||||||
|
# Arrange
|
||||||
|
service = NotebookService()
|
||||||
|
|
||||||
|
# Act & Assert
|
||||||
|
with pytest.raises(ValidationError, match="Title cannot be empty"):
|
||||||
|
await service.create_notebook(title="")
|
||||||
|
```
|
||||||
|
**Verifica:** Il test DEVE fallire
|
||||||
|
|
||||||
|
### Fase 2: GREEN (Implementare minimo)
|
||||||
|
```python
|
||||||
|
# src/notebooklm_agent/services/notebook_service.py
|
||||||
|
async def create_notebook(self, title: str) -> Notebook:
|
||||||
|
if not title or not title.strip():
|
||||||
|
raise ValidationError("Title cannot be empty")
|
||||||
|
# ... implementazione minima
|
||||||
|
```
|
||||||
|
**Verifica:** Il test DEVE passare
|
||||||
|
|
||||||
|
### Fase 3: REFACTOR (Migliorare)
|
||||||
|
```python
|
||||||
|
# Pulire codice, rimuovere duplicazione, migliorare nomi
|
||||||
|
# I test devono rimanere verdi
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pattern di Test (AAA)
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def test_create_notebook_valid_title_returns_created():
|
||||||
|
# Arrange - Setup
|
||||||
|
title = "Test Notebook"
|
||||||
|
service = NotebookService()
|
||||||
|
|
||||||
|
# Act - Execute
|
||||||
|
result = await service.create_notebook(title)
|
||||||
|
|
||||||
|
# Assert - Verify
|
||||||
|
assert result.title == title
|
||||||
|
assert result.id is not None
|
||||||
|
assert result.created_at is not None
|
||||||
|
```
|
||||||
|
|
||||||
|
## Regole di Test
|
||||||
|
|
||||||
|
1. **Un test = Un comportamento**
|
||||||
|
2. **Testare prima i casi d'errore**
|
||||||
|
3. **Nomi descrittivi**: `test_<behavior>_<condition>_<expected>`
|
||||||
|
4. **No logic in tests**: No if/else, no loop
|
||||||
|
5. **Isolamento**: Mock per dipendenze esterne
|
||||||
|
|
||||||
|
## Struttura Test
|
||||||
|
|
||||||
|
```
|
||||||
|
tests/
|
||||||
|
├── unit/ # Logica pura, no I/O
|
||||||
|
│ ├── test_services/
|
||||||
|
│ └── test_core/
|
||||||
|
├── integration/ # Con dipendenze mockate
|
||||||
|
│ └── test_api/
|
||||||
|
└── e2e/ # Flussi completi
|
||||||
|
└── test_workflows/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Convenzioni
|
||||||
|
|
||||||
|
### Nomenclatura
|
||||||
|
- File: `test_<module>.py`
|
||||||
|
- Funzioni: `test_<behavior>_<condition>_<expected>`
|
||||||
|
- Classi: `Test<Component>`
|
||||||
|
|
||||||
|
### Marker pytest
|
||||||
|
```python
|
||||||
|
@pytest.mark.unit
|
||||||
|
def test_pure_function():
|
||||||
|
pass
|
||||||
|
|
||||||
|
@pytest.mark.integration
|
||||||
|
def test_with_http():
|
||||||
|
pass
|
||||||
|
|
||||||
|
@pytest.mark.e2e
|
||||||
|
def test_full_workflow():
|
||||||
|
pass
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_async():
|
||||||
|
pass
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentazione Bug
|
||||||
|
|
||||||
|
Quando risolvi un bug complesso, aggiungi a `[ROOT_PROGETTO]/docs/bug_ledger.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## 2026-04-05: Race condition in webhook dispatch
|
||||||
|
|
||||||
|
**Sintomo:** Webhook duplicati inviati sotto carico
|
||||||
|
|
||||||
|
**Causa:** Manca lock su dispatcher, richieste concorrenti causano doppia delivery
|
||||||
|
|
||||||
|
**Soluzione:** Aggiunto asyncio.Lock() nel dispatcher, sequentializza invio
|
||||||
|
|
||||||
|
**Prevenzione:**
|
||||||
|
- Test di carico obbligatori per componenti async
|
||||||
|
- Review focus su race condition
|
||||||
|
- Documentare comportamento thread-safe nei docstring
|
||||||
|
```
|
||||||
|
|
||||||
|
## Comportamento Vietato
|
||||||
|
|
||||||
|
- ❌ Scrivere codice senza test prima
|
||||||
|
- ❌ Implementare più funzionalità insieme
|
||||||
|
- ❌ Ignorare test che falliscono
|
||||||
|
- ❌ Commit con test rossi
|
||||||
|
- ❌ Copertura <90%
|
||||||
29
.opencode/opencode.json
Normal file
29
.opencode/opencode.json
Normal file
@@ -0,0 +1,29 @@
|
|||||||
|
{
|
||||||
|
"$schema": "https://opencode.ai/config.json",
|
||||||
|
"mcp": {
|
||||||
|
"sequential-thinking": {
|
||||||
|
"type": "local",
|
||||||
|
"command": [
|
||||||
|
"npx",
|
||||||
|
"-y",
|
||||||
|
"@modelcontextprotocol/server-sequential-thinking"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"context7": {
|
||||||
|
"type": "local",
|
||||||
|
"command": [
|
||||||
|
"npx",
|
||||||
|
"-y",
|
||||||
|
"@context7/mcp-server"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"universal-skills": {
|
||||||
|
"type": "local",
|
||||||
|
"command": [
|
||||||
|
"npx",
|
||||||
|
"-y",
|
||||||
|
"github:jacob-bd/universal-skills-manager"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
221
.opencode/skills/project-guidelines/SKILL.md
Normal file
221
.opencode/skills/project-guidelines/SKILL.md
Normal file
@@ -0,0 +1,221 @@
|
|||||||
|
---
|
||||||
|
name: project-guidelines
|
||||||
|
description: Linee guida per lo sviluppo del progetto. Usa questa skill per comprendere l'architettura, le convenzioni di codice e il workflow di sviluppo.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Project Guidelines - [NOME PROGETTO]
|
||||||
|
|
||||||
|
> ⚠️ **NOTA**: Personalizza questo file con il nome e la descrizione del tuo progetto!
|
||||||
|
|
||||||
|
## Panoramica del Progetto
|
||||||
|
|
||||||
|
**[NOME PROGETTO]** è [breve descrizione del progetto - da personalizzare].
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Leggere Prima
|
||||||
|
1. **Workflow**: `.opencode/WORKFLOW.md` - Flusso di lavoro obbligatorio
|
||||||
|
2. **PRD**: `prd.md` - Requisiti prodotto
|
||||||
|
3. **AGENTS.md**: Linee guida generali del progetto (se esiste)
|
||||||
|
|
||||||
|
### Agenti Disponibili (in `.opencode/agents/`)
|
||||||
|
|
||||||
|
| Agente | Ruolo | Quando Usare |
|
||||||
|
|--------|-------|--------------|
|
||||||
|
| `@spec-architect` | Definisce specifiche e architettura | Prima di nuove feature |
|
||||||
|
| `@tdd-developer` | Implementazione TDD | Durante sviluppo |
|
||||||
|
| `@git-manager` | Gestione commit Git | A fine task |
|
||||||
|
|
||||||
|
## Flusso di Lavoro (OBBLIGATORIO)
|
||||||
|
|
||||||
|
### Per Nuove Feature
|
||||||
|
|
||||||
|
```
|
||||||
|
1. @spec-architect → Legge PRD, definisce specifiche
|
||||||
|
↓
|
||||||
|
Crea/aggiorna:
|
||||||
|
- /export/prd.md
|
||||||
|
- /export/architecture.md
|
||||||
|
- /export/kanban.md
|
||||||
|
↓
|
||||||
|
2. @tdd-developer → Implementa seguendo TDD
|
||||||
|
↓
|
||||||
|
RED → GREEN → REFACTOR
|
||||||
|
↓
|
||||||
|
3. @git-manager → Commit atomico
|
||||||
|
↓
|
||||||
|
Conventional Commit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Per Bug Fix
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Leggi bug_ledger.md per pattern simili
|
||||||
|
2. Scrivi test che riproduce il bug
|
||||||
|
3. Implementa fix
|
||||||
|
4. Aggiorna bug_ledger.md
|
||||||
|
5. Commit con tipo "fix:"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Regole Fondamentali
|
||||||
|
|
||||||
|
### 1. TDD (Test-Driven Development)
|
||||||
|
- **RED**: Scrivi test fallimentare PRIMA
|
||||||
|
- **GREEN**: Scrivi codice minimo per passare
|
||||||
|
- **REFACTOR**: Migliora mantenendo test verdi
|
||||||
|
|
||||||
|
### 2. Spec-Driven
|
||||||
|
- Leggi sempre `prd.md` prima di implementare
|
||||||
|
- Non implementare funzionalità non richieste
|
||||||
|
- Output specifiche in `/export/`
|
||||||
|
|
||||||
|
### 3. Little Often
|
||||||
|
- Task piccoli e verificabili
|
||||||
|
- Progresso incrementale
|
||||||
|
- Commit atomici
|
||||||
|
|
||||||
|
### 4. Memoria
|
||||||
|
- Bug complessi → `docs/bug_ledger.md`
|
||||||
|
- Decisioni design → `docs/architecture.md`
|
||||||
|
- Progresso task → `export/progress.md` (aggiorna inizio/fine task)
|
||||||
|
|
||||||
|
### 5. Git
|
||||||
|
- Conventional commits obbligatori
|
||||||
|
- Commit atomici
|
||||||
|
- Test verdi prima del commit
|
||||||
|
- Documenta contesto in `export/githistory.md`
|
||||||
|
|
||||||
|
## Struttura Progetto (Personalizza)
|
||||||
|
|
||||||
|
```
|
||||||
|
[nome-progetto]/
|
||||||
|
├── src/ # Codice sorgente
|
||||||
|
│ └── [nome_package]/
|
||||||
|
│ ├── [moduli]/ # Moduli applicativi
|
||||||
|
│ └── ...
|
||||||
|
├── tests/ # Test suite
|
||||||
|
│ ├── unit/
|
||||||
|
│ ├── integration/
|
||||||
|
│ └── e2e/
|
||||||
|
├── docs/ # Documentazione
|
||||||
|
│ ├── bug_ledger.md # Log bug risolti
|
||||||
|
│ └── architecture.md # Decisioni architetturali
|
||||||
|
├── export/ # Output spec-driven
|
||||||
|
│ ├── prd.md # Product Requirements
|
||||||
|
│ ├── architecture.md # Architettura
|
||||||
|
│ ├── kanban.md # Task breakdown
|
||||||
|
│ ├── progress.md # Tracciamento progresso
|
||||||
|
│ └── githistory.md # Storico commit
|
||||||
|
├── .opencode/ # Configurazione OpenCode
|
||||||
|
│ ├── WORKFLOW.md # Flusso di lavoro
|
||||||
|
│ ├── agents/ # Configurazioni agenti
|
||||||
|
│ └── skills/ # Skill condivise
|
||||||
|
├── scripts/ # Script utilità
|
||||||
|
├── prd.md # Product Requirements (root)
|
||||||
|
├── AGENTS.md # Linee guida generali (opzionale)
|
||||||
|
└── SKILL.md # Questo file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Convenzioni di Codice (Personalizza)
|
||||||
|
|
||||||
|
### [Linguaggio - es. Python/JavaScript/Go]
|
||||||
|
- Versione: [es. 3.10+]
|
||||||
|
- Stile: [es. PEP 8 / StandardJS / gofmt]
|
||||||
|
- Type hints: [obbligatorio/consigliato]
|
||||||
|
- Line length: [es. 100 caratteri]
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- Framework: [pytest/jest/go test]
|
||||||
|
- Coverage target: ≥90%
|
||||||
|
- Pattern: AAA (Arrange-Act-Assert)
|
||||||
|
- Mock per dipendenze esterne
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
```
|
||||||
|
<type>(<scope>): <description>
|
||||||
|
|
||||||
|
[body]
|
||||||
|
|
||||||
|
[footer]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tipi:** feat, fix, docs, test, refactor, chore, ci, style
|
||||||
|
**Scope:** [personalizza in base al progetto - es. api, db, ui, core]
|
||||||
|
|
||||||
|
## Risorse
|
||||||
|
|
||||||
|
| File | Scopo |
|
||||||
|
|------|-------|
|
||||||
|
| `prd.md` | Requisiti prodotto |
|
||||||
|
| `AGENTS.md` | Linee guida progetto (se esiste) |
|
||||||
|
| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
|
||||||
|
| `.opencode/agents/` | Configurazioni agenti |
|
||||||
|
| `docs/bug_ledger.md` | Log bug risolti |
|
||||||
|
| `docs/architecture.md` | Decisioni architetturali |
|
||||||
|
| `export/progress.md` | Tracciamento progresso task |
|
||||||
|
| `export/githistory.md` | Storico commit con contesto |
|
||||||
|
| `CHANGELOG.md` | Changelog |
|
||||||
|
| `CONTRIBUTING.md` | Guida contribuzione |
|
||||||
|
|
||||||
|
## Comandi Utili (Personalizza)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test
|
||||||
|
[comando test] # Tutti i test
|
||||||
|
[comando test --coverage] # Con coverage
|
||||||
|
|
||||||
|
# Qualità
|
||||||
|
[comando lint] # Linting
|
||||||
|
[comando format] # Formattazione
|
||||||
|
[comando type-check] # Type checking
|
||||||
|
|
||||||
|
# Pre-commit
|
||||||
|
[comando pre-commit]
|
||||||
|
|
||||||
|
# Server/Run
|
||||||
|
[comando run]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
### Setup Iniziale (da fare una volta)
|
||||||
|
- [ ] Personalizzato `SKILL.md` con nome progetto
|
||||||
|
- [ ] Creata struttura cartelle `src/`
|
||||||
|
- [ ] Configurato ambiente di sviluppo
|
||||||
|
- [ ] Inizializzato `prd.md` con requisiti
|
||||||
|
- [ ] Inizializzato `export/kanban.md` con task
|
||||||
|
|
||||||
|
### Pre-Implementazione
|
||||||
|
- [ ] Ho letto `prd.md`
|
||||||
|
- [ ] Ho compreso lo scope
|
||||||
|
- [ ] Ho letto `.opencode/WORKFLOW.md`
|
||||||
|
|
||||||
|
### Durante Implementazione
|
||||||
|
- [ ] Test scritto prima (RED)
|
||||||
|
- [ ] Codice minimo (GREEN)
|
||||||
|
- [ ] Refactoring (REFACTOR)
|
||||||
|
|
||||||
|
### Post-Implementazione
|
||||||
|
- [ ] Tutti i test passano
|
||||||
|
- [ ] Coverage ≥90%
|
||||||
|
- [ ] `bug_ledger.md` aggiornato (se bug)
|
||||||
|
- [ ] `architecture.md` aggiornato (se design)
|
||||||
|
- [ ] `progress.md` aggiornato (inizio/fine task)
|
||||||
|
- [ ] `githistory.md` aggiornato (contesto commit)
|
||||||
|
- [ ] Commit con conventional commits
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Per dettagli su flusso di lavoro, vedere `.opencode/WORKFLOW.md`*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Note per l'Utente
|
||||||
|
|
||||||
|
Questo è un template. Per usarlo:
|
||||||
|
|
||||||
|
1. **Sostituisci** `[NOME PROGETTO]` con il nome reale
|
||||||
|
2. **Descrivi** il progetto nella sezione Panoramica
|
||||||
|
3. **Personalizza** la struttura cartelle in base al tuo stack
|
||||||
|
4. **Aggiungi** comandi specifici del tuo linguaggio/framework
|
||||||
|
5. **Definisci** gli scope dei commit pertinenti al tuo progetto
|
||||||
282
README.md
282
README.md
@@ -1,3 +1,281 @@
|
|||||||
# template-opencode
|
# Template OpenCode
|
||||||
|
|
||||||
Configurazione Sacchi-Style di Opencode.ai
|
Template riutilizzabile per configurare OpenCode su nuovi progetti con best practices, workflow TDD e Spec-Driven Development.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Installazione Rapida
|
||||||
|
|
||||||
|
### 1. Clona o copia il template nel tuo progetto
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Naviga nella cartella del tuo progetto
|
||||||
|
cd /path/to/tuo-progetto
|
||||||
|
|
||||||
|
# Copia la struttura del template
|
||||||
|
cp -r /path/to/template-opencode/.opencode .
|
||||||
|
cp -r /path/to/template-opencode/export .
|
||||||
|
cp -r /path/to/template-opencode/docs .
|
||||||
|
cp -r /path/to/template-opencode/prompt .
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Personalizza i placeholder
|
||||||
|
|
||||||
|
Sostituisci tutti i placeholder nel progetto:
|
||||||
|
|
||||||
|
| Placeholder | Descrizione | Dove sostituire |
|
||||||
|
|-------------|-------------|-----------------|
|
||||||
|
| `[NOME_PROGETTO]` | Nome del tuo progetto | `SKILL.md`, `WORKFLOW.md`, `prompt/prompt-zero.md` |
|
||||||
|
| `[ROOT_PROGETTO]` | Path completo del progetto | Tutti i file in `.opencode/agents/` |
|
||||||
|
| `[SCOPI_DEL_PROGETTO]` | Scopi per i commit | `WORKFLOW.md` |
|
||||||
|
|
||||||
|
**Comando rapido:**
|
||||||
|
```bash
|
||||||
|
# Sostituisci [NOME_PROGETTO] con il nome reale
|
||||||
|
find . -type f -name "*.md" -exec sed -i 's/\[NOME_PROGETTO\]/MioProgetto/g' {} \;
|
||||||
|
|
||||||
|
# Sostituisci [ROOT_PROGETTO] con il path reale (esempio: /home/user/mio-progetto)
|
||||||
|
find . -type f -name "*.md" -exec sed -i 's|\[ROOT_PROGETTO\]|/path/to/mio-progetto|g' {} \;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Inizializza il progetto
|
||||||
|
|
||||||
|
#### In `.opencode/skills/project-guidelines/SKILL.md`:
|
||||||
|
- [ ] Sostituisci `[NOME PROGETTO]` con il nome del progetto
|
||||||
|
- [ ] Aggiungi descrizione del progetto
|
||||||
|
- [ ] Personalizza la struttura delle cartelle
|
||||||
|
- [ ] Definisci comandi specifici del tuo linguaggio
|
||||||
|
- [ ] Aggiungi risorse specifiche
|
||||||
|
|
||||||
|
#### In `.opencode/WORKFLOW.md`:
|
||||||
|
- [ ] Aggiorna `[NOME_PROGETTO]` con il nome
|
||||||
|
- [ ] Aggiorna `[ROOT_PROGETTO]` con il path completo
|
||||||
|
- [ ] Personalizza `[SCOPI_DEL_PROGETTO]` con gli scope del progetto (es: api, db, ui, core)
|
||||||
|
|
||||||
|
#### In `.opencode/opencode.json`:
|
||||||
|
- Configurazione MCP già presente, puoi aggiungere server extra se necessario
|
||||||
|
|
||||||
|
#### In `export/prd.md`:
|
||||||
|
- [ ] Sostituisci con i requisiti del tuo prodotto
|
||||||
|
- [ ] Definisci obiettivi e user stories
|
||||||
|
- [ ] Specifica stack tecnologico
|
||||||
|
|
||||||
|
#### In `prompt/prompt-zero.md`:
|
||||||
|
- [ ] Personalizza `[NOME_PROGETTO]` e `[ROOT_PROGETTO]`
|
||||||
|
- [ ] Descrivi il progetto nella sezione Missione
|
||||||
|
- [ ] Aggiungi funzionalità MVP specifiche
|
||||||
|
- [ ] Personalizza stack tecnologico
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 Struttura del Template
|
||||||
|
|
||||||
|
```
|
||||||
|
template-opencode/
|
||||||
|
├── .opencode/ # Configurazione OpenCode
|
||||||
|
│ ├── agents/ # Configurazioni agenti
|
||||||
|
│ │ ├── spec-architect.md # Agente per specifiche
|
||||||
|
│ │ ├── tdd-developer.md # Agente per sviluppo TDD
|
||||||
|
│ │ ├── git-manager.md # Agente per Git
|
||||||
|
│ │ └── security-reviewer.md # Agente per sicurezza
|
||||||
|
│ ├── skills/
|
||||||
|
│ │ └── project-guidelines/
|
||||||
|
│ │ └── SKILL.md # Skill progetto (da personalizzare)
|
||||||
|
│ ├── WORKFLOW.md # Flusso di lavoro dettagliato
|
||||||
|
│ ├── opencode.json # Configurazione MCP
|
||||||
|
│ ├── package.json # Dipendenze
|
||||||
|
│ └── .gitignore # Esclusioni
|
||||||
|
├── prompt/
|
||||||
|
│ └── prompt-zero.md # Prompt kickoff progetto (da personalizzare)
|
||||||
|
├── export/ # Output specifiche (template)
|
||||||
|
│ ├── prd.md # Product Requirements (template)
|
||||||
|
│ ├── architecture.md # Architettura (template)
|
||||||
|
│ ├── kanban.md # Task breakdown (template)
|
||||||
|
│ ├── progress.md # Tracciamento progresso (template)
|
||||||
|
│ └── githistory.md # Storico commit (template)
|
||||||
|
└── docs/ # Documentazione (template)
|
||||||
|
├── bug_ledger.md # Log bug (template)
|
||||||
|
└── architecture.md # Decisioni architetturali (template)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Workflow di Sviluppo
|
||||||
|
|
||||||
|
Il template implementa un workflow **Spec-Driven + TDD**:
|
||||||
|
|
||||||
|
### Fase 1: Specifica (@spec-architect)
|
||||||
|
```
|
||||||
|
Legge PRD → Crea architecture.md, kanban.md → Inizializza progress.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fase 2: Implementazione (@tdd-developer)
|
||||||
|
```
|
||||||
|
RED → GREEN → REFACTOR per ogni task
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fase 3: Commit (@git-manager)
|
||||||
|
```
|
||||||
|
Commit atomico + Conventional Commits + Documenta in githistory.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Flusso di Lavoro Dettagliato
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ @spec-architect │
|
||||||
|
│ → Legge PRD in export/prd.md │
|
||||||
|
│ → Crea specifiche in export/ │
|
||||||
|
│ → Inizializza kanban e progress │
|
||||||
|
└─────────────┬───────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ @tdd-developer │
|
||||||
|
│ → RED: Scrive test fallimentare │
|
||||||
|
│ → GREEN: Implementa codice minimo │
|
||||||
|
│ → REFACTOR: Migliora codice │
|
||||||
|
└─────────────┬───────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ @git-manager │
|
||||||
|
│ → Commit atomico │
|
||||||
|
│ → Conventional commit │
|
||||||
|
│ → Documenta in githistory.md │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Checklist Setup Completo
|
||||||
|
|
||||||
|
### Prima dello sviluppo:
|
||||||
|
- [ ] Copiato `.opencode/` nel progetto
|
||||||
|
- [ ] Copiato `export/` nel progetto
|
||||||
|
- [ ] Copiato `docs/` nel progetto
|
||||||
|
- [ ] Copiato `prompt/` nel progetto
|
||||||
|
- [ ] Sostituito `[NOME_PROGETTO]` con nome reale
|
||||||
|
- [ ] Sostituito `[ROOT_PROGETTO]` con path reale
|
||||||
|
- [ ] Personalizzato `SKILL.md` con dettagli progetto
|
||||||
|
- [ ] Aggiornato `WORKFLOW.md` con scope commit
|
||||||
|
- [ ] Creato `export/prd.md` con requisiti prodotto
|
||||||
|
- [ ] Personalizzato `prompt/prompt-zero.md`
|
||||||
|
- [ ] Verificato che tutti i file template siano presenti
|
||||||
|
|
||||||
|
### Per ogni nuova feature:
|
||||||
|
- [ ] `@spec-architect` ha creato/aggiornato specifiche
|
||||||
|
- [ ] Task scomposti in `kanban.md`
|
||||||
|
- [ ] `@tdd-developer` ha implementato con TDD
|
||||||
|
- [ ] Test coverage ≥ 90%
|
||||||
|
- [ ] `@git-manager` ha creato commit convenzionale
|
||||||
|
- [ ] `progress.md` e `githistory.md` aggiornati
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Documentazione
|
||||||
|
|
||||||
|
| File | Scopo |
|
||||||
|
|------|-------|
|
||||||
|
| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
|
||||||
|
| `.opencode/agents/` | Configurazioni specifiche per ruolo |
|
||||||
|
| `.opencode/skills/project-guidelines/SKILL.md` | Linee guida progetto |
|
||||||
|
| `export/` | Template per output specifiche |
|
||||||
|
| `docs/` | Template per documentazione |
|
||||||
|
| `prompt/prompt-zero.md` | Prompt kickoff progetto |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Personalizzazione
|
||||||
|
|
||||||
|
### Aggiungere un nuovo agente
|
||||||
|
|
||||||
|
1. Crea file in `.opencode/agents/nome-agente.md`
|
||||||
|
2. Definisci ruolo e responsabilità
|
||||||
|
3. Aggiungi riferimento in `SKILL.md`
|
||||||
|
|
||||||
|
### Aggiungere una skill
|
||||||
|
|
||||||
|
1. Crea cartella in `.opencode/skills/nome-skill/`
|
||||||
|
2. Crea `SKILL.md` con metadati e istruzioni
|
||||||
|
3. Aggiungi riferimenti nei file necessari
|
||||||
|
|
||||||
|
### Modificare il workflow
|
||||||
|
|
||||||
|
1. Aggiorna `.opencode/WORKFLOW.md`
|
||||||
|
2. Sincronizza modifiche negli agenti interessati
|
||||||
|
3. Aggiorna `SKILL.md` se necessario
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Convenzioni
|
||||||
|
|
||||||
|
### TDD (Test-Driven Development)
|
||||||
|
- **RED**: Scrivi test che fallisce prima
|
||||||
|
- **GREEN**: Implementa codice minimo
|
||||||
|
- **REFACTOR**: Migliora codice mantenendo test verdi
|
||||||
|
|
||||||
|
### Conventional Commits
|
||||||
|
```
|
||||||
|
type(scope): description
|
||||||
|
|
||||||
|
[body]
|
||||||
|
|
||||||
|
[footer]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tipi:** feat, fix, docs, test, refactor, chore, ci, style
|
||||||
|
**Scope:** personalizza in base al progetto (api, db, ui, core, ...)
|
||||||
|
|
||||||
|
### Principi "Little Often"
|
||||||
|
- Task piccoli e verificabili (< 2 ore)
|
||||||
|
- Progresso incrementale
|
||||||
|
- Commit atomici
|
||||||
|
|
||||||
|
### Safety First
|
||||||
|
- Verifica prima di procedere
|
||||||
|
- Test sempre verdi prima del commit
|
||||||
|
- Documenta bug complessi e decisioni architetturali
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🆘 Risoluzione Problemi
|
||||||
|
|
||||||
|
### Problemi comuni:
|
||||||
|
|
||||||
|
**1. I placeholder non sono stati sostituiti:**
|
||||||
|
```bash
|
||||||
|
# Cerca placeholder rimasti
|
||||||
|
grep -r "\[NOME_PROGETTO\]\|\[ROOT_PROGETTO\]" . --include="*.md"
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Agente non trova i file:**
|
||||||
|
- Verifica che `[ROOT_PROGETTO]` sia il path assoluto corretto
|
||||||
|
- Verifica che i file in `export/` esistano
|
||||||
|
|
||||||
|
**3. Configurazione MCP non funziona:**
|
||||||
|
- Verifica che Node.js sia installato
|
||||||
|
- Esegui `npm install` nella cartella `.opencode/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Supporto
|
||||||
|
|
||||||
|
Per domande o problemi:
|
||||||
|
1. Consulta `.opencode/WORKFLOW.md`
|
||||||
|
2. Verifica le configurazioni agenti
|
||||||
|
3. Controlla i template in `export/`
|
||||||
|
4. Apri una issue nel repository del template
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 Licenza
|
||||||
|
|
||||||
|
MIT License - vedi file LICENSE
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Versione**: 1.0.0
|
||||||
|
**Aggiornato**: 2026-04-07
|
||||||
|
|||||||
59
docs/architecture.md
Normal file
59
docs/architecture.md
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
# Architecture Decision Records
|
||||||
|
|
||||||
|
> Registro delle decisioni architetturali e dei pattern di design utilizzati.
|
||||||
|
|
||||||
|
## Formato
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## [YYYY-MM-DD] - [Titolo Decisione]
|
||||||
|
|
||||||
|
### Contesto
|
||||||
|
[Background e motivazione]
|
||||||
|
|
||||||
|
### Decisione
|
||||||
|
[Cosa è stato deciso]
|
||||||
|
|
||||||
|
### Conseguenze
|
||||||
|
- Positivo: [Benefici]
|
||||||
|
- Negativo: [Trade-off]
|
||||||
|
|
||||||
|
### Alternative Considerate
|
||||||
|
- [Alternativa 1]: [Perché scartata]
|
||||||
|
- [Alternativa 2]: [Perché scartata]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Esempio Template
|
||||||
|
|
||||||
|
## 2026-04-05 - Uso di FastAPI come framework API
|
||||||
|
|
||||||
|
### Contesto
|
||||||
|
Necessità di un framework web async per l'API REST con documentazione OpenAPI automatica.
|
||||||
|
|
||||||
|
### Decisione
|
||||||
|
Adottare FastAPI come framework principale per:
|
||||||
|
- Supporto nativo async/await
|
||||||
|
- Validazione automatica con Pydantic
|
||||||
|
- Documentazione OpenAPI/Swagger integrata
|
||||||
|
- Performance elevate
|
||||||
|
|
||||||
|
### Conseguenze
|
||||||
|
- **Positivo:**
|
||||||
|
- Sviluppo più rapido con type hints
|
||||||
|
- Documentazione API sempre aggiornata
|
||||||
|
- Validazione input automatica
|
||||||
|
- Supporto nativo async per I/O bound operations
|
||||||
|
|
||||||
|
- **Negativo:**
|
||||||
|
- Curva di apprendimento per sviluppatori nuovi
|
||||||
|
- Dipendenza da Pydantic v2
|
||||||
|
|
||||||
|
### Alternative Considerate
|
||||||
|
- **Flask**: Scartato per mancanza di supporto async nativo
|
||||||
|
- **Django REST Framework**: Scartato per essere troppo pesante per API-only
|
||||||
|
- **Starlette**: Scartato in favore di FastAPI che include più funzionalità out-of-box
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Aggiungere nuove decisioni in ordine cronologico crescente*
|
||||||
36
docs/bug_ledger.md
Normal file
36
docs/bug_ledger.md
Normal file
@@ -0,0 +1,36 @@
|
|||||||
|
# Bug Ledger
|
||||||
|
|
||||||
|
> Registro dei bug complessi risolti con sintomo, causa, soluzione e prevenzione.
|
||||||
|
|
||||||
|
## Formato
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## YYYY-MM-DD: [Titolo Bug]
|
||||||
|
**Sintomo:** [Descrizione sintomo]
|
||||||
|
**Causa:** [Root cause]
|
||||||
|
**Soluzione:** [Fix applicato]
|
||||||
|
**Prevenzione:** [Come evitare in futuro]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Esempio Template
|
||||||
|
|
||||||
|
## 2026-04-05: Race condition in webhook dispatch
|
||||||
|
|
||||||
|
**Sintomo:** Webhook duplicati inviati sotto carico elevato
|
||||||
|
|
||||||
|
**Causa:** Manca meccanismo di lock nel dispatcher, richieste concorrenti causano doppia delivery
|
||||||
|
|
||||||
|
**Soluzione:**
|
||||||
|
- Aggiunto `asyncio.Lock()` nel dispatcher
|
||||||
|
- Sequentializza invio webhook per lo stesso evento
|
||||||
|
|
||||||
|
**Prevenzione:**
|
||||||
|
- Test di carico obbligatori per componenti async
|
||||||
|
- Code review focus su race condition
|
||||||
|
- Documentare comportamento thread-safe nei docstring
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Aggiungere nuovi bug in ordine cronologico decrescente (più recente in cima)*
|
||||||
92
export/architecture.md
Normal file
92
export/architecture.md
Normal file
@@ -0,0 +1,92 @@
|
|||||||
|
# Architecture Document (Export)
|
||||||
|
|
||||||
|
> Decisioni architetturali e diagrammi di flusso.
|
||||||
|
|
||||||
|
## Istruzioni
|
||||||
|
|
||||||
|
Questo file deve essere creato/aggiornato dall'agente `@spec-architect` durante la fase di analisi.
|
||||||
|
|
||||||
|
## Contenuto Richiesto
|
||||||
|
|
||||||
|
1. **Scelte Architetturali**
|
||||||
|
- Pattern architetturali
|
||||||
|
- Motivazioni
|
||||||
|
- Trade-off
|
||||||
|
|
||||||
|
2. **Stack Tecnologico**
|
||||||
|
- Tecnologie e versioni
|
||||||
|
- Motivazioni scelta
|
||||||
|
|
||||||
|
3. **Diagrammi di Flusso**
|
||||||
|
- Architettura sistema
|
||||||
|
- Flussi dati
|
||||||
|
- Sequenze operazioni
|
||||||
|
|
||||||
|
4. **Interfacce e Contratti**
|
||||||
|
- API contracts
|
||||||
|
- Interfacce tra componenti
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Architecture - [Nome Progetto/Feature]
|
||||||
|
|
||||||
|
## 1. Overview
|
||||||
|
|
||||||
|
[Descrizione ad alto livello]
|
||||||
|
|
||||||
|
## 2. System Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
[ASCII art o riferimento a diagramma]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Componenti
|
||||||
|
|
||||||
|
### 3.1 [Nome Componente]
|
||||||
|
**Responsabilità:**
|
||||||
|
-
|
||||||
|
|
||||||
|
**Interfacce:**
|
||||||
|
- Input:
|
||||||
|
- Output:
|
||||||
|
|
||||||
|
**Dipendenze:**
|
||||||
|
-
|
||||||
|
|
||||||
|
## 4. Data Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
[Descrizione flusso dati]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. API Contracts
|
||||||
|
|
||||||
|
### [Endpoint]
|
||||||
|
```
|
||||||
|
POST /api/v1/...
|
||||||
|
Request:
|
||||||
|
body: { ... }
|
||||||
|
|
||||||
|
Response:
|
||||||
|
200: { ... }
|
||||||
|
400: { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Decisioni
|
||||||
|
|
||||||
|
### [DEC-001] - [Titolo]
|
||||||
|
**Decisione:**
|
||||||
|
|
||||||
|
**Motivazione:**
|
||||||
|
|
||||||
|
**Alternative:**
|
||||||
|
|
||||||
|
**Conseguenze:**
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Questo file verrà popolato durante la fase di specifica*
|
||||||
46
export/githistory.md
Normal file
46
export/githistory.md
Normal file
@@ -0,0 +1,46 @@
|
|||||||
|
# Git History - [NOME_PROGETTO]
|
||||||
|
|
||||||
|
> Registro storico dei commit con spiegazione dettagliata del contesto e della motivazione.
|
||||||
|
|
||||||
|
## Formato
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## YYYY-MM-DD HH:MM - [TYPE](scope): [Titolo Commit]
|
||||||
|
|
||||||
|
**Hash:** `abc1234`
|
||||||
|
**Autore:** @agent
|
||||||
|
**Branch:** main/feature/...
|
||||||
|
|
||||||
|
### Contesto
|
||||||
|
[Spiegazione del contesto in cui è stato fatto il commit - perché era necessario]
|
||||||
|
|
||||||
|
### Cosa cambia
|
||||||
|
[Descrizione dettagliata delle modifiche introdotte]
|
||||||
|
|
||||||
|
### Perché
|
||||||
|
[Motivazione delle scelte fatte, problemi risolti]
|
||||||
|
|
||||||
|
### Impatto
|
||||||
|
- [ ] Breaking change
|
||||||
|
- [ ] Modifica API
|
||||||
|
- [ ] Nuova feature
|
||||||
|
- [ ] Bug fix
|
||||||
|
- [ ] Refactoring
|
||||||
|
- [ ] Documentazione
|
||||||
|
|
||||||
|
### File modificati
|
||||||
|
- `path/to/file1.py` - [breve descrizione cambiamento]
|
||||||
|
- `path/to/file2.py` - [breve descrizione cambiamento]
|
||||||
|
|
||||||
|
### Note
|
||||||
|
[Eventuali note aggiuntive, riferimenti a issue, PR]
|
||||||
|
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Storico Commit
|
||||||
|
|
||||||
|
*I commit più recenti in cima*
|
||||||
|
|
||||||
116
export/kanban.md
Normal file
116
export/kanban.md
Normal file
@@ -0,0 +1,116 @@
|
|||||||
|
# Kanban Board (Export)
|
||||||
|
|
||||||
|
> Scomposizione del progetto in task minimi e verificabili.
|
||||||
|
|
||||||
|
## Istruzioni
|
||||||
|
|
||||||
|
Questo file deve essere creato/aggiornato dall'agente `@spec-architect` durante la fase di analisi.
|
||||||
|
|
||||||
|
## Principio "Little Often"
|
||||||
|
|
||||||
|
- Task il più piccoli possibile
|
||||||
|
- Ogni task verificabile in <2 ore
|
||||||
|
- Progresso incrementale
|
||||||
|
- Dipendenze chiare
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stati
|
||||||
|
|
||||||
|
- 🔴 **TODO** - Da fare
|
||||||
|
- 🟡 **IN PROGRESS** - In corso
|
||||||
|
- 🟢 **DONE** - Completato
|
||||||
|
- ⚪ **BLOCKED** - Bloccato (vedi dipendenze)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Kanban - [Nome Progetto]
|
||||||
|
|
||||||
|
## Colonna: 🔴 TODO
|
||||||
|
|
||||||
|
### Task-001: [Titolo task]
|
||||||
|
**Descrizione:** [Breve descrizione]
|
||||||
|
**Criteri Done:**
|
||||||
|
- [ ] Criterio 1
|
||||||
|
- [ ] Criterio 2
|
||||||
|
**Dipendenze:** Nessuna / Task-XXX
|
||||||
|
**Stima:** XS(1h) / S(2h) / M(4h) / L(8h)
|
||||||
|
**Assegnato:** @agent
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Colonna: 🟡 IN PROGRESS
|
||||||
|
|
||||||
|
### Task-XXX: [Titolo]
|
||||||
|
**Iniziato:** YYYY-MM-DD
|
||||||
|
**Assegnato:** @agent
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Colonna: 🟢 DONE
|
||||||
|
|
||||||
|
### Task-XXX: [Titolo]
|
||||||
|
**Completato:** YYYY-MM-DD
|
||||||
|
**Commit:** `feat: ...`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Colonna: ⚪ BLOCKED
|
||||||
|
|
||||||
|
### Task-XXX: [Titolo]
|
||||||
|
**Bloccato da:** Task-YYY
|
||||||
|
**Motivo:** [Spiegazione]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Esempio Board
|
||||||
|
|
||||||
|
# Kanban - [NOME_PROGETTO]
|
||||||
|
|
||||||
|
## 🔴 TODO
|
||||||
|
|
||||||
|
### TASK-001: Setup progetto base
|
||||||
|
**Descrizione:** Inizializzare struttura progetto Python con uv
|
||||||
|
**Criteri Done:**
|
||||||
|
- [ ] pyproject.toml configurato
|
||||||
|
- [ ] Struttura cartelle src/
|
||||||
|
- [ ] Pre-commit hooks installati
|
||||||
|
**Dipendenze:** Nessuna
|
||||||
|
**Stima:** XS
|
||||||
|
**Assegnato:** @tdd-developer
|
||||||
|
|
||||||
|
### TASK-002: Implementare NotebookService.create()
|
||||||
|
**Descrizione:** Servizio per creazione notebook con validazione
|
||||||
|
**Criteri Done:**
|
||||||
|
- [ ] Test unitari passanti
|
||||||
|
- [ ] Validazione titolo
|
||||||
|
- [ ] Integrazione notebooklm-py
|
||||||
|
**Dipendenze:** TASK-001
|
||||||
|
**Stima:** S
|
||||||
|
**Assegnato:** @tdd-developer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🟡 IN PROGRESS
|
||||||
|
|
||||||
|
*Vuoto*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🟢 DONE
|
||||||
|
|
||||||
|
*Vuoto*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚪ BLOCKED
|
||||||
|
|
||||||
|
*Vuoto*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Questo file verrà popolato durante la fase di specifica*
|
||||||
94
export/prd.md
Normal file
94
export/prd.md
Normal file
@@ -0,0 +1,94 @@
|
|||||||
|
# Product Requirements Document (Export)
|
||||||
|
|
||||||
|
> Versione iniziale del PRD da definire durante la fase di specifica.
|
||||||
|
|
||||||
|
## Istruzioni
|
||||||
|
|
||||||
|
Questo file deve essere creato/aggiornato dall'agente `@spec-architect` durante la fase di analisi.
|
||||||
|
|
||||||
|
## Contenuto Richiesto
|
||||||
|
|
||||||
|
1. **Obiettivi**
|
||||||
|
- Obiettivi di business
|
||||||
|
- Obiettivi utente
|
||||||
|
- Metriche di successo (KPI)
|
||||||
|
|
||||||
|
2. **User Stories**
|
||||||
|
- Formato: "Come [ruolo], voglio [obiettivo], per [beneficio]"
|
||||||
|
- Acceptance criteria per ogni story
|
||||||
|
|
||||||
|
3. **Requisiti Funzionali**
|
||||||
|
- Requisiti con priorità
|
||||||
|
- Criteri di accettazione
|
||||||
|
|
||||||
|
4. **Requisiti Non Funzionali**
|
||||||
|
- Performance
|
||||||
|
- Sicurezza
|
||||||
|
- Scalabilità
|
||||||
|
|
||||||
|
5. **Stack Tecnologico**
|
||||||
|
- Tecnologie scelte
|
||||||
|
- Versioni
|
||||||
|
- Motivazioni
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# PRD - [Nome Feature]
|
||||||
|
|
||||||
|
## 1. Obiettivi
|
||||||
|
|
||||||
|
### 1.1 Business
|
||||||
|
- [ ]
|
||||||
|
|
||||||
|
### 1.2 Utente
|
||||||
|
- [ ]
|
||||||
|
|
||||||
|
### 1.3 KPI
|
||||||
|
| Metrica | Target |
|
||||||
|
|---------|--------|
|
||||||
|
| | |
|
||||||
|
|
||||||
|
## 2. User Stories
|
||||||
|
|
||||||
|
### US-001
|
||||||
|
**Come** [ruolo],
|
||||||
|
**voglio** [obiettivo],
|
||||||
|
**per** [beneficio]
|
||||||
|
|
||||||
|
**Acceptance Criteria:**
|
||||||
|
- [ ] Criterio 1
|
||||||
|
- [ ] Criterio 2
|
||||||
|
|
||||||
|
## 3. Requisiti Funzionali
|
||||||
|
|
||||||
|
### REQ-001: [Titolo]
|
||||||
|
**Priorità:** Alta/Media/Bassa
|
||||||
|
|
||||||
|
**Descrizione:**
|
||||||
|
[Descrizione dettagliata]
|
||||||
|
|
||||||
|
**Criteri di Accettazione:**
|
||||||
|
- [ ]
|
||||||
|
- [ ]
|
||||||
|
|
||||||
|
## 4. Requisiti Non Funzionali
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
-
|
||||||
|
|
||||||
|
### Sicurezza
|
||||||
|
-
|
||||||
|
|
||||||
|
## 5. Stack Tecnologico
|
||||||
|
|
||||||
|
| Componente | Tecnologia | Versione |
|
||||||
|
|------------|------------|----------|
|
||||||
|
| | | |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Questo file verrà popolato durante la fase di specifica*
|
||||||
109
export/progress.md
Normal file
109
export/progress.md
Normal file
@@ -0,0 +1,109 @@
|
|||||||
|
# Progress Tracking - [NOME_PROGETTO]
|
||||||
|
|
||||||
|
> Tracciamento progresso sviluppo in tempo reale.
|
||||||
|
|
||||||
|
## 🎯 Sprint/Feature Corrente
|
||||||
|
|
||||||
|
**Feature:** `[Nome feature in sviluppo]`
|
||||||
|
**Iniziata:** `YYYY-MM-DD`
|
||||||
|
**Stato:** 🔴 Pianificazione / 🟡 In sviluppo / 🟢 Completata
|
||||||
|
**Assegnato:** `@agent`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Progresso Complessivo
|
||||||
|
|
||||||
|
| Area | Progresso | Stato |
|
||||||
|
|------|-----------|-------|
|
||||||
|
| API Core | 0/10 task | 🔴 Non iniziato |
|
||||||
|
| Webhook System | 0/5 task | 🔴 Non iniziato |
|
||||||
|
| AI Skill | 0/3 task | 🔴 Non iniziato |
|
||||||
|
| Testing | 0/8 task | 🔴 Non iniziato |
|
||||||
|
| Documentazione | 0/4 task | 🔴 Non iniziato |
|
||||||
|
|
||||||
|
**Completamento Totale:** 0%
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Attività in Corso
|
||||||
|
|
||||||
|
### Task Corrente: `[ID-XXX] - Titolo`
|
||||||
|
|
||||||
|
| Campo | Valore |
|
||||||
|
|-------|--------|
|
||||||
|
| **ID** | TASK-XXX |
|
||||||
|
| **Descrizione** | [Breve descrizione] |
|
||||||
|
| **Iniziata** | YYYY-MM-DD HH:MM |
|
||||||
|
| **Assegnato** | @agent |
|
||||||
|
| **Stato** | 🟡 In progress |
|
||||||
|
| **Bloccata da** | Nessuna / TASK-YYY |
|
||||||
|
| **Note** | [Eventuali ostacoli, decisioni] |
|
||||||
|
|
||||||
|
**Passi completati:**
|
||||||
|
- [x] Passo 1
|
||||||
|
- [ ] Passo 2
|
||||||
|
- [ ] Passo 3
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Task Completate (Oggi)
|
||||||
|
|
||||||
|
| ID | Task | Completata | Commit | Assegnato |
|
||||||
|
|----|------|------------|--------|-----------|
|
||||||
|
| | | | | |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📅 Prossime Task
|
||||||
|
|
||||||
|
| Priority | ID | Task | Stima | Dipendenze |
|
||||||
|
|----------|----|------|-------|------------|
|
||||||
|
| P1 | | | | |
|
||||||
|
| P2 | | | | |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚧 Blocchi/Issue
|
||||||
|
|
||||||
|
| ID | Problema | Impatto | Soluzione Proposta | Stato |
|
||||||
|
|----|----------|---------|-------------------|-------|
|
||||||
|
| | | | | 🔴 Aperto |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Decisioni Prese Oggi
|
||||||
|
|
||||||
|
| Data | Decisione | Motivazione | Impatto |
|
||||||
|
|------|-----------|-------------|---------|
|
||||||
|
| | | | |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📈 Metriche
|
||||||
|
|
||||||
|
### Sprint Corrente
|
||||||
|
- **Task pianificate:** 0
|
||||||
|
- **Task completate:** 0
|
||||||
|
- **Task in progress:** 0
|
||||||
|
- **Task bloccate:** 0
|
||||||
|
|
||||||
|
### Qualità
|
||||||
|
- **Test Coverage:** 0%
|
||||||
|
- **Test passanti:** 0/0
|
||||||
|
- **Linting:** ✅ / ❌
|
||||||
|
- **Type Check:** ✅ / ❌
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Aggiornamento
|
||||||
|
|
||||||
|
> **Nota:** Questo file deve essere aggiornato:
|
||||||
|
> - All'inizio di ogni nuova task
|
||||||
|
> - Al completamento di ogni task
|
||||||
|
> - Quando si risolve un blocco
|
||||||
|
> - Quando si prende una decisione architetturale
|
||||||
|
> - A fine giornata lavorativa
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Ultimo aggiornamento: YYYY-MM-DD HH:MM*
|
||||||
224
prompt/prompt-zero.md
Normal file
224
prompt/prompt-zero.md
Normal file
@@ -0,0 +1,224 @@
|
|||||||
|
# Prompt Zero: [NOME_PROGETTO] - Project Kickoff
|
||||||
|
|
||||||
|
## 🎯 Missione
|
||||||
|
|
||||||
|
Sviluppare **[NOME_PROGETTO]**, [descrizione breve del progetto - da personalizzare].
|
||||||
|
|
||||||
|
**Repository:** `[ROOT_PROGETTO]`
|
||||||
|
**PRD:** `[ROOT_PROGETTO]/export/prd.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Stato Attuale
|
||||||
|
|
||||||
|
- ✅ **PRD Completo**: Requisiti funzionali e non funzionali definiti
|
||||||
|
- ✅ **Team Configurato**: Agenti specializzati pronti
|
||||||
|
- ❌ **Nessun Codice**: Progetto da zero
|
||||||
|
- ❌ **Nessuna Specifica Tecnica**: Da creare
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 👥 Team di Sviluppo
|
||||||
|
|
||||||
|
| Agente | Ruolo | File Config |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| `@spec-architect` | Definisce specifiche e architettura | `.opencode/agents/spec-architect.md` |
|
||||||
|
| `@tdd-developer` | Implementazione TDD | `.opencode/agents/tdd-developer.md` |
|
||||||
|
| `@git-manager` | Gestione commit Git | `.opencode/agents/git-manager.md` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Workflow Obbligatorio
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ FASE 1: SPECIFICA │
|
||||||
|
│ @spec-architect │
|
||||||
|
│ └── Legge PRD → Crea architecture.md, kanban.md │
|
||||||
|
│ │
|
||||||
|
│ ↓ │
|
||||||
|
│ │
|
||||||
|
│ FASE 2: IMPLEMENTAZIONE │
|
||||||
|
│ @tdd-developer │
|
||||||
|
│ └── RED → GREEN → REFACTOR per ogni task │
|
||||||
|
│ │
|
||||||
|
│ ↓ │
|
||||||
|
│ │
|
||||||
|
│ FASE 3: COMMIT │
|
||||||
|
│ @git-manager │
|
||||||
|
│ └── Commit atomico + Conventional Commits │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Task Iniziale: Fase 1 - Specifica
|
||||||
|
|
||||||
|
**AGENTE:** `@spec-architect`
|
||||||
|
|
||||||
|
**OBIETTIVO:** Analizzare il PRD e creare le specifiche tecniche dettagliate.
|
||||||
|
|
||||||
|
### Azioni Richieste
|
||||||
|
|
||||||
|
1. **Leggere** `[ROOT_PROGETTO]/export/prd.md`
|
||||||
|
|
||||||
|
2. **Creare** la struttura di output:
|
||||||
|
```
|
||||||
|
[ROOT_PROGETTO]/export/
|
||||||
|
├── prd.md # Requisiti prodotti (estratto/dettaglio)
|
||||||
|
├── architecture.md # Architettura sistema
|
||||||
|
├── kanban.md # Task breakdown
|
||||||
|
└── progress.md # Tracciamento progresso
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Produrre** `architecture.md` con:
|
||||||
|
- Stack tecnologico dettagliato
|
||||||
|
- Struttura cartelle progetto
|
||||||
|
- Diagrammi flusso dati
|
||||||
|
- Schema database completo (DDL)
|
||||||
|
- Interfacce API (OpenAPI specs)
|
||||||
|
- Sicurezza (cifratura, autenticazione)
|
||||||
|
|
||||||
|
4. **Produrre** `kanban.md` con:
|
||||||
|
- Task breakdown per Fase 1 (MVP)
|
||||||
|
- Stima complessità
|
||||||
|
- Dipendenze tra task
|
||||||
|
- Regola "little often": task < 2 ore
|
||||||
|
|
||||||
|
5. **Inizializzare** `progress.md` con:
|
||||||
|
- Feature corrente: "Fase 1 - MVP"
|
||||||
|
- Stato: "🔴 Pianificazione"
|
||||||
|
- Percentuale: 0%
|
||||||
|
|
||||||
|
### Criteri di Accettazione
|
||||||
|
|
||||||
|
- [ ] Architecture.md completo con tutte le sezioni
|
||||||
|
- [ ] Kanban.md con task pronti per @tdd-developer
|
||||||
|
- [ ] Progress.md inizializzato
|
||||||
|
- [ ] Tutti i path usano `[ROOT_PROGETTO]/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Requisiti Chiave (Dal PRD)
|
||||||
|
|
||||||
|
### Funzionalità MVP (Fase 1)
|
||||||
|
|
||||||
|
[DA PERSONALIZZARE - Inserire le funzionalità principali del progetto]
|
||||||
|
|
||||||
|
1. **[Feature 1]**
|
||||||
|
- [Dettaglio 1]
|
||||||
|
- [Dettaglio 2]
|
||||||
|
|
||||||
|
2. **[Feature 2]**
|
||||||
|
- [Dettaglio 1]
|
||||||
|
- [Dettaglio 2]
|
||||||
|
|
||||||
|
### Stack Tecnologico (Esempio)
|
||||||
|
|
||||||
|
- **Backend:** [Linguaggio/Framework]
|
||||||
|
- **Database:** [Tipo database]
|
||||||
|
- **Frontend:** [Tecnologia frontend]
|
||||||
|
- **Auth:** [Metodo autenticazione]
|
||||||
|
- **Task Background:** [Scheduler]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛡️ Vincoli e Best Practices
|
||||||
|
|
||||||
|
### Sicurezza (Critico)
|
||||||
|
- [Requisito sicurezza 1]
|
||||||
|
- [Requisito sicurezza 2]
|
||||||
|
- SQL injection prevention
|
||||||
|
- XSS prevention
|
||||||
|
- CSRF protection
|
||||||
|
- Rate limiting
|
||||||
|
|
||||||
|
### Qualità
|
||||||
|
- Test coverage ≥ 90%
|
||||||
|
- TDD obbligatorio
|
||||||
|
- Conventional commits
|
||||||
|
- Commit atomici
|
||||||
|
|
||||||
|
### Organizzazione
|
||||||
|
- Task "little often" (< 2 ore)
|
||||||
|
- Documentazione in `/export/`
|
||||||
|
- Bug complessi in `/docs/bug_ledger.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 Struttura Progetto Attesa
|
||||||
|
|
||||||
|
```
|
||||||
|
[ROOT_PROGETTO]/
|
||||||
|
├── prd.md # Product Requirements
|
||||||
|
├── prompt/
|
||||||
|
│ └── prompt-zero.md # Questo file
|
||||||
|
├── .opencode/
|
||||||
|
│ ├── agents/ # Configurazioni agenti
|
||||||
|
│ └── skills/ # Skill condivise
|
||||||
|
├── export/ # Output spec-driven (da creare)
|
||||||
|
│ ├── prd.md
|
||||||
|
│ ├── architecture.md
|
||||||
|
│ ├── kanban.md
|
||||||
|
│ └── progress.md
|
||||||
|
├── docs/ # Documentazione (da creare)
|
||||||
|
│ ├── bug_ledger.md
|
||||||
|
│ └── architecture.md
|
||||||
|
├── src/ # Codice sorgente (da creare)
|
||||||
|
│ └── [nome_package]/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── main.py
|
||||||
|
│ ├── config.py
|
||||||
|
│ └── ...
|
||||||
|
├── tests/ # Test suite (da creare)
|
||||||
|
│ ├── unit/
|
||||||
|
│ ├── integration/
|
||||||
|
│ └── conftest.py
|
||||||
|
├── requirements.txt / package.json
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ Checklist Pre-Sviluppo
|
||||||
|
|
||||||
|
- [ ] @spec-architect ha letto questo prompt
|
||||||
|
- [ ] Cartella `export/` creata
|
||||||
|
- [ ] `architecture.md` creato con schema DB
|
||||||
|
- [ ] `kanban.md` creato con task Fase 1
|
||||||
|
- [ ] `progress.md` inizializzato
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎬 Prossima Azione
|
||||||
|
|
||||||
|
**@spec-architect**: Inizia analizzando il PRD in `export/prd.md` e crea le specifiche tecniche in `export/`.
|
||||||
|
|
||||||
|
**NON iniziare l'implementazione** finché le specifiche non sono approvate.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Note per il Team
|
||||||
|
|
||||||
|
- **Domande sul PRD?** Leggi prima `export/prd.md` completamente
|
||||||
|
- **Ambiguità?** Chiedi prima di procedere
|
||||||
|
- **Vincoli tecnici?** Documentali in `architecture.md`
|
||||||
|
- **Task troppo grandi?** Spezza in task più piccoli
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Data Creazione:** YYYY-MM-DD
|
||||||
|
**Versione:** 1.0
|
||||||
|
**Stato:** Pronto per kickoff
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Note per l'Utente
|
||||||
|
|
||||||
|
Questo è un template. Per usarlo:
|
||||||
|
|
||||||
|
1. **Sostituisci** `[NOME_PROGETTO]` con il nome reale
|
||||||
|
2. **Descrivi** il progetto nella sezione Missione
|
||||||
|
3. **Personalizza** la sezione "Requisiti Chiave" con i tuoi requisiti
|
||||||
|
4. **Aggiorna** lo stack tecnologico
|
||||||
|
5. **Definisci** gli scope dei commit pertinenti al tuo progetto
|
||||||
Reference in New Issue
Block a user