---
name: project-guidelines
description: Linee guida per lo sviluppo del progetto. Usa questa skill per comprendere l'architettura, le convenzioni di codice e il workflow di sviluppo.
---

# Project Guidelines - [NOME PROGETTO]

> ⚠️ **NOTA**: Personalizza questo file con il nome e la descrizione del tuo progetto!

## Panoramica del Progetto

**[NOME PROGETTO]** è [breve descrizione del progetto - da personalizzare].

## Quick Start

### Leggere Prima
1. **Workflow**: `.opencode/WORKFLOW.md` - Flusso di lavoro obbligatorio
2. **PRD**: `prd.md` - Requisiti prodotto
3. **AGENTS.md**: Linee guida generali del progetto (se esiste)

### Agenti Disponibili (in `.opencode/agents/`)

| Agente | Ruolo | Quando Usare |
|--------|-------|--------------|
| `@spec-architect` | Definisce specifiche e architettura | Prima di nuove feature |
| `@tdd-developer` | Implementazione TDD | Durante sviluppo |
| `@git-manager` | Gestione commit Git | A fine task |

## Flusso di Lavoro (OBBLIGATORIO)

### Per Nuove Feature

```
1. @spec-architect → Legge PRD, definisce specifiche
                     ↓
              Crea/aggiorna:
              - /export/prd.md
              - /export/architecture.md
              - /export/kanban.md
                     ↓
2. @tdd-developer → Implementa seguendo TDD
                     ↓
              RED → GREEN → REFACTOR
                     ↓
3. @git-manager → Commit atomico
                     ↓
              Conventional Commit
```

### Per Bug Fix

```
1. Leggi bug_ledger.md per pattern simili
2. Scrivi test che riproduce il bug
3. Implementa fix
4. Aggiorna bug_ledger.md
5. Commit con tipo "fix:"
```

## Regole Fondamentali

### 1. TDD (Test-Driven Development)
- **RED**: Scrivi test fallimentare PRIMA
- **GREEN**: Scrivi codice minimo per passare
- **REFACTOR**: Migliora mantenendo test verdi

### 2. Spec-Driven
- Leggi sempre `prd.md` prima di implementare
- Non implementare funzionalità non richieste
- Output specifiche in `/export/`

### 3. Little Often
- Task piccoli e verificabili
- Progresso incrementale
- Commit atomici

### 4. Memoria
- Bug complessi → `docs/bug_ledger.md`
- Decisioni design → `docs/architecture.md`
- Progresso task → `export/progress.md` (aggiorna inizio/fine task)

### 5. Git
- Conventional commits obbligatori
- Commit atomici
- Test verdi prima del commit
- Documenta contesto in `export/githistory.md`

## Struttura Progetto (Personalizza)

```
[nome-progetto]/
├── src/                          # Codice sorgente
│   └── [nome_package]/
│       ├── [moduli]/             # Moduli applicativi
│       └── ...
├── tests/                        # Test suite
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/                         # Documentazione
│   ├── bug_ledger.md            # Log bug risolti
│   └── architecture.md          # Decisioni architetturali
├── export/                       # Output spec-driven
│   ├── prd.md                   # Product Requirements
│   ├── architecture.md          # Architettura
│   ├── kanban.md                # Task breakdown
│   ├── progress.md              # Tracciamento progresso
│   └── githistory.md            # Storico commit
├── .opencode/                    # Configurazione OpenCode
│   ├── WORKFLOW.md              # Flusso di lavoro
│   ├── agents/                  # Configurazioni agenti
│   └── skills/                  # Skill condivise
├── scripts/                      # Script utilità
├── prd.md                        # Product Requirements (root)
├── AGENTS.md                     # Linee guida generali (opzionale)
└── SKILL.md                      # Questo file
```

## Convenzioni di Codice (Personalizza)

### [Linguaggio - es. Python/JavaScript/Go]
- Versione: [es. 3.10+]
- Stile: [es. PEP 8 / StandardJS / gofmt]
- Type hints: [obbligatorio/consigliato]
- Line length: [es. 100 caratteri]

### Testing
- Framework: [pytest/jest/go test]
- Coverage target: ≥90%
- Pattern: AAA (Arrange-Act-Assert)
- Mock per dipendenze esterne

### Commit
```
<type>(<scope>): <description>

[body]

[footer]
```

**Tipi:** feat, fix, docs, test, refactor, chore, ci, style  
**Scope:** [personalizza in base al progetto - es. api, db, ui, core]

## Risorse

| File | Scopo |
|------|-------|
| `prd.md` | Requisiti prodotto |
| `AGENTS.md` | Linee guida progetto (se esiste) |
| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
| `.opencode/agents/` | Configurazioni agenti |
| `docs/bug_ledger.md` | Log bug risolti |
| `docs/architecture.md` | Decisioni architetturali |
| `export/progress.md` | Tracciamento progresso task |
| `export/githistory.md` | Storico commit con contesto |
| `CHANGELOG.md` | Changelog |
| `CONTRIBUTING.md` | Guida contribuzione |

## Comandi Utili (Personalizza)

```bash
# Test
[comando test]                    # Tutti i test
[comando test --coverage]         # Con coverage

# Qualità
[comando lint]                    # Linting
[comando format]                  # Formattazione
[comando type-check]              # Type checking

# Pre-commit
[comando pre-commit]

# Server/Run
[comando run]
```

## Checklist

### Setup Iniziale (da fare una volta)
- [ ] Personalizzato `SKILL.md` con nome progetto
- [ ] Creata struttura cartelle `src/`
- [ ] Configurato ambiente di sviluppo
- [ ] Inizializzato `prd.md` con requisiti
- [ ] Inizializzato `export/kanban.md` con task

### Pre-Implementazione
- [ ] Ho letto `prd.md`
- [ ] Ho compreso lo scope
- [ ] Ho letto `.opencode/WORKFLOW.md`

### Durante Implementazione
- [ ] Test scritto prima (RED)
- [ ] Codice minimo (GREEN)
- [ ] Refactoring (REFACTOR)

### Post-Implementazione
- [ ] Tutti i test passano
- [ ] Coverage ≥90%
- [ ] `bug_ledger.md` aggiornato (se bug)
- [ ] `architecture.md` aggiornato (se design)
- [ ] `progress.md` aggiornato (inizio/fine task)
- [ ] `githistory.md` aggiornato (contesto commit)
- [ ] Commit con conventional commits

---

*Per dettagli su flusso di lavoro, vedere `.opencode/WORKFLOW.md`*

---

## 📝 Note per l'Utente

Questo è un template. Per usarlo:

1. **Sostituisci** `[NOME PROGETTO]` con il nome reale
2. **Descrivi** il progetto nella sezione Panoramica
3. **Personalizza** la struttura cartelle in base al tuo stack
4. **Aggiungi** comandi specifici del tuo linguaggio/framework
5. **Definisci** gli scope dei commit pertinenti al tuo progetto