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"
|
||||
Reference in New Issue
Block a user