template-opencode/.opencode/WORKFLOW.md

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:

## 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:

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:

## 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"