lucasacchi/template-opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6852c13668f9daa7a12c52e65edb483acb0cc2bb
template-opencode/README.md
Luca Sacchi Ricciardi 6852c13668 docs(readme): add OpenCode initialization instructions 
Add section explaining how to initialize project with OpenCode:
- Commands to analyze existing codebase
- Instructions to create PRD with spec-architect
- Steps to update agents and skills for the specific project
- Warning about importance of initialization for correct context
2026-04-07 10:15:21 +02:00

330 lines
11 KiB
Markdown
Raw Blame History

# 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
### 4. Inizializza con OpenCode (IMPORTANTE)
Dopo aver copiato i file template, **devi chiedere ad OpenCode di configurare il progetto** per operare correttamente:
#### Comandi da eseguire con OpenCode:
**1. Analizza la codebase esistente:**
```
"@opencode Analizza la codebase di questo progetto e identifica:
- Tecnologie e framework utilizzati
- Struttura delle cartelle
- Pattern architetturali esistenti
- Convenzioni di codice già in uso"
```
**2. Crea il PRD (Product Requirements Document):**
```
"@spec-architect Crea il file export/prd.md con i requisiti del prodotto.
Descrivi: [spiega brevemente cosa deve fare il progetto]
Include: obiettivi, user stories, requisiti funzionali e non funzionali, stack tecnologico"
```
**3. Attualizza agenti e skill:**
```
"@opencode Analizza la cartella .opencode e aggiorna:
- .opencode/skills/project-guidelines/SKILL.md con le convenzioni specifiche di questo progetto
- .opencode/agents/spec-architect.md con il path corretto del progetto
- .opencode/agents/tdd-developer.md con il path corretto e i pattern di test del progetto
- .opencode/agents/git-manager.md con il path corretto
- .opencode/WORKFLOW.md con il nome del progetto e gli scope dei commit appropriati"
```
**4. Crea architettura e task breakdown:**
```
"@spec-architect Leggi export/prd.md e crea:
- export/architecture.md con le scelte architetturali
- export/kanban.md con il breakdown delle task
- export/progress.md inizializzato per il tracciamento"
```
#### ⚠️ Nota Importante
Senza questa inizializzazione, OpenCode **non avrà il contesto corretto** per operare sul progetto. Gli agenti devono essere configurati con:
- Il path assoluto del progetto (`[ROOT_PROGETTO]`)
- Le convenzioni specifiche del linguaggio/framework
- Gli scope dei commit appropriati
- La struttura delle cartelle del progetto
---
## 📁 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
Reference in New Issue View Git Blame Copy Permalink