5c7dd95974
- 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)
282 lines
9.4 KiB
Markdown
282 lines
9.4 KiB
Markdown
# 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
|