# 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

```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