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)
2026-04-07 10:12:41 +02:00
parent 4b2f7318e0
commit 5c7dd95974
16 changed files with 1969 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,281 @@
-# template-opencode
+# Template OpenCode

-Configurazione Sacchi-Style di Opencode.ai
+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