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:**
```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"