Template OpenCode

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

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

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

# 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