documente/.opencode/WORKFLOW.md

Flusso di Lavoro Obbligatorio - getNotebooklmPower

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 /home/google/Sources/LucaSacchiNet/getNotebooklmPower/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	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/bug_ledger.md
Decisione di design	Documenta il pattern scelto	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md
Cambio architetturale	Aggiorna le scelte architetturali	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md
Inizio task	Aggiorna progresso corrente	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md
Fine task	Registra completamento	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md
Blocco riscontrato	Documenta problema e soluzione	/home/google/Sources/LucaSacchiNet/getNotebooklmPower/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: api, webhook, skill, notebook, source, artifact, auth, core
5. Documenta il commit: Aggiorna /home/google/Sources/LucaSacchiNet/getNotebooklmPower/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. Prompt Management (Gestione Prompt)

Ogni interazione con il team di agenti deve essere documentata come prompt.

5.1 Salvataggio Prompt

Regola: Ogni prompt ricevuto dall'utente deve essere salvato nella cartella prompts/.

Convenzione naming:

prompts/{NUMERO}-{descrizione}.md

• NUMERO: Progressivo crescente (1, 2, 3, ...)
• descrizione: Nome descrittivo in kebab-case

Esempi:

• prompts/1-avvio.md - Primo prompt, avvio progetto
• prompts/2-implementazione-sources.md - Sprint fonti
• prompts/3-bugfix-webhook-retry.md - Fix bug webhook

5.2 Struttura Prompt

Ogni prompt salvato deve includere:

# {Titolo}

## 📋 Comando per @sprint-lead
{Istruzione principale}

---

## 🎯 Obiettivo
{Descrizione chiara}

---

## 📚 Contesto
{Background e riferimenti}

---

## ✅ Scope
### In Scope
- {Task 1}

### Out of Scope
- {Task escluso}

---

## 🎯 Criteri di Accettazione
- [ ] {Criterio 1}

---

## 🎬 Azioni
1. {Azione 1}

---

*Data: YYYY-MM-DD*
*Priority: P{0-3}*
*Prompt File: prompts/{NUMERO}-{nome}.md*

5.3 Aggiornamento prompts/README.md

Dopo aver salvato un nuovo prompt, aggiornare prompts/README.md:

| File | Descrizione | Data |
|------|-------------|------|
| [1-avvio.md](./1-avvio.md) | Sprint kickoff - Core API | 2026-04-06 |
| [2-xxx.md](./2-xxx.md) | Nuova descrizione | YYYY-MM-DD |

6. Spec-Driven Development (SDD)

Prima di scrivere codice, definisci le specifiche:

6.1 Analisi Profonda

• Fai domande mirate per chiarire dubbi architetturali o di business
• Non procedere con specifiche vaghe
• Verifica vincoli tecnici e dipendenze

6.2 Output Richiesti (cartella /home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/)

Tutto il lavoro di specifica si concretizza in questi file:

File	Contenuto
/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md	Product Requirements Document (obiettivi, user stories, requisiti tecnici)
/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md	Scelte architetturali, stack tecnologico, diagrammi di flusso
/home/google/Sources/LucaSacchiNet/getNotebooklmPower/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 Prompt Management (per ogni nuovo task)

• Ho determinato il prossimo numero progressivo (controlla prompts/)
• Ho creato il file prompts/{NUMERO}-{descrizione}.md
• Ho incluso comando per @sprint-lead
• Ho definito obiettivo chiaro e success criteria
• Ho specificato scope (in/out)
• Ho elencato criteri di accettazione
• Ho aggiornato prompts/README.md con il nuovo prompt
• Ho salvato il prompt prima di iniziare lo sviluppo

Checklist Pre-Implementazione

• Ho letto il PRD in /home/google/Sources/LucaSacchiNet/getNotebooklmPower/prd.md
• Ho letto il prompt corrente in prompts/{NUMERO}-*.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 /home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md
• Ho creato/aggiornato /home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md
• Ho creato/aggiornato /home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/kanban.md
• I task sono scomposti secondo "little often"