diff --git a/.opencode/WORKFLOW.md b/.opencode/WORKFLOW.md new file mode 100644 index 0000000..2e511cd --- /dev/null +++ b/.opencode/WORKFLOW.md @@ -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: + ``` + (): + + [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" diff --git a/.opencode/agents/git-manager.md b/.opencode/agents/git-manager.md new file mode 100644 index 0000000..218c558 --- /dev/null +++ b/.opencode/agents/git-manager.md @@ -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 + +``` +(): + +[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/` | `feat/notebook-crud` | +| Bugfix | `fix/` | `fix/webhook-retry` | +| Hotfix | `hotfix/` | `hotfix/auth-bypass` | +| Release | `release/v` | `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 # 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` diff --git a/.opencode/agents/security-reviewer.md b/.opencode/agents/security-reviewer.md new file mode 100644 index 0000000..211141a --- /dev/null +++ b/.opencode/agents/security-reviewer.md @@ -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" diff --git a/.opencode/agents/spec-architect.md b/.opencode/agents/spec-architect.md new file mode 100644 index 0000000..0e48c83 --- /dev/null +++ b/.opencode/agents/spec-architect.md @@ -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 diff --git a/.opencode/agents/tdd-developer.md b/.opencode/agents/tdd-developer.md new file mode 100644 index 0000000..f9cd01a --- /dev/null +++ b/.opencode/agents/tdd-developer.md @@ -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___` +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_.py` +- Funzioni: `test___` +- Classi: `Test` + +### 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% diff --git a/.opencode/opencode.json b/.opencode/opencode.json new file mode 100644 index 0000000..5e3ed0e --- /dev/null +++ b/.opencode/opencode.json @@ -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" + ] + } + } +} diff --git a/.opencode/skills/project-guidelines/SKILL.md b/.opencode/skills/project-guidelines/SKILL.md new file mode 100644 index 0000000..61ac4b0 --- /dev/null +++ b/.opencode/skills/project-guidelines/SKILL.md @@ -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 +``` +(): + +[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 diff --git a/README.md b/README.md index 7fa86ec..d05835b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,281 @@ -# template-opencode +# Template OpenCode -Configurazione Sacchi-Style di Opencode.ai \ No newline at end of file +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 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..2d15a97 --- /dev/null +++ b/docs/architecture.md @@ -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* diff --git a/docs/bug_ledger.md b/docs/bug_ledger.md new file mode 100644 index 0000000..de800f0 --- /dev/null +++ b/docs/bug_ledger.md @@ -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)* diff --git a/export/architecture.md b/export/architecture.md new file mode 100644 index 0000000..67c9efe --- /dev/null +++ b/export/architecture.md @@ -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* diff --git a/export/githistory.md b/export/githistory.md new file mode 100644 index 0000000..11ce2a1 --- /dev/null +++ b/export/githistory.md @@ -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* + diff --git a/export/kanban.md b/export/kanban.md new file mode 100644 index 0000000..6a785f9 --- /dev/null +++ b/export/kanban.md @@ -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* diff --git a/export/prd.md b/export/prd.md new file mode 100644 index 0000000..f612121 --- /dev/null +++ b/export/prd.md @@ -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* diff --git a/export/progress.md b/export/progress.md new file mode 100644 index 0000000..ae16370 --- /dev/null +++ b/export/progress.md @@ -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* diff --git a/prompt/prompt-zero.md b/prompt/prompt-zero.md new file mode 100644 index 0000000..886c6c8 --- /dev/null +++ b/prompt/prompt-zero.md @@ -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