feat(setup): T01 create project directory structure

- Create src/openrouter_monitor/ package structure - Create models/, routers/, services/, utils/ subpackages - Create tests/unit/ and tests/integration/ structure - Create alembic/, docs/, scripts/ directories - Add test_project_structure.py with 13 unit tests - All tests passing (13/13) Refs: T01
2026-04-07 09:44:41 +02:00
parent 849a65d4d9
commit 75f40acb17
27 changed files with 3094 additions and 0 deletions
--- a/.opencode/WORKFLOW.md
+++ b/.opencode/WORKFLOW.md
@@ -0,0 +1,164 @@
+# Flusso di Lavoro Obbligatorio - getNotebooklmPower
+
+> **Regola fondamentale:** *Safety first, little often, double check*
+
+## 1. Contesto (Prima di ogni task)
+
+**OBBLIGATORIO:** Prima di implementare qualsiasi funzionalità:
+
+1. **Leggi il PRD**: Leggi sempre `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/prd.md` per capire i requisiti del task corrente
+2. **Non implementare mai funzionalità non esplicitamente richieste**
+3. **Scope check**: Verifica che il task rientri nello scope definito nel PRD
+
+## 2. TDD (Test-Driven Development)
+
+**Ciclo RED → GREEN → REFACTOR:**
+
+1. **RED**: Scrivi PRIMA il test fallimentare per la singola funzionalità
+2. **GREEN**: Scrivi il codice applicativo minimo necessario per far passare il test
+3. **REFACTOR**: Migliora il codice mantenendo i test verdi
+4. **Itera** finché la funzionalità non è completa e tutti i test passano
+
+**Regole TDD:**
+- Un test per singolo comportamento
+- Testare prima i casi limite (errori, input invalidi)
+- Coverage target: ≥90%
+- Usa AAA pattern: Arrange → Act → Assert
+
+## 3. Memoria e Logging
+
+**Documentazione obbligatoria:**
+
+| Evento | Azione | File |
+|--------|--------|------|
+| Bug complesso risolto | Descrivi il bug e la soluzione | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/bug_ledger.md` |
+| Decisione di design | Documenta il pattern scelto | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md` |
+| Cambio architetturale | Aggiorna le scelte architetturali | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/docs/architecture.md` |
+| Inizio task | Aggiorna progresso corrente | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+| Fine task | Registra completamento | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+| Blocco riscontrato | Documenta problema e soluzione | `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/progress.md` |
+
+**Formato bug_ledger.md:**
+```markdown
+## YYYY-MM-DD: [Titolo Bug]
+**Sintomo:** [Descrizione sintomo]
+**Causa:** [Root cause]
+**Soluzione:** [Fix applicato]
+**Prevenzione:** [Come evitare in futuro]
+```
+
+## 4. Git Flow (Commit)
+
+**Alla fine di ogni task completato con test verdi:**
+
+1. **Commit atomico**: Un commit per singola modifica funzionale
+2. **Conventional Commits** obbligatorio:
+   ```
+   <type>(<scope>): <description>
+   
+   [optional body]
+   
+   [optional footer]
+   ```
+3. **Tipi ammessi:**
+   - `feat:` - Nuova funzionalità
+   - `fix:` - Correzione bug
+   - `docs:` - Documentazione
+   - `test:` - Test
+   - `refactor:` - Refactoring
+   - `chore:` - Manutenzione
+4. **Scope**: api, webhook, skill, notebook, source, artifact, auth, core
+5. **Documenta il commit**: Aggiorna `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/githistory.md` con contesto e spiegazione
+
+**Esempi:**
+```bash
+feat(api): add notebook creation endpoint
+
+- Implements POST /api/v1/notebooks
+- Validates title length (max 100 chars)
+- Returns 201 with notebook details
+
+Closes #123
+```
+
+**Formato githistory.md:**
+```markdown
+## 2026-04-05 14:30 - feat(api): add notebook creation endpoint
+
+**Hash:** `a1b2c3d`
+**Autore:** @tdd-developer
+**Branch:** main
+
+### Contesto
+Necessità di creare notebook programmaticamente via API per integrazione con altri agenti.
+
+### Cosa cambia
+- Aggiunto endpoint POST /api/v1/notebooks
+- Implementata validazione titolo (max 100 chars)
+- Aggiunto test coverage 95%
+
+### Perché
+Il PRD richiede CRUD operations su notebook. Questo è il primo endpoint implementato.
+
+### Impatto
+- [x] Nuova feature
+- [ ] Breaking change
+- [ ] Modifica API
+
+### File modificati
+- src/api/routes/notebooks.py - Nuovo endpoint
+- src/services/notebook_service.py - Logica creazione
+- tests/unit/test_notebook_service.py - Test unitari
+
+### Note
+Closes #42
+```
+
+## 5. Spec-Driven Development (SDD)
+
+**Prima di scrivere codice, definisci le specifiche:**
+
+### 5.1 Analisi Profonda
+- Fai domande mirate per chiarire dubbi architetturali o di business
+- Non procedere con specifiche vaghe
+- Verifica vincoli tecnici e dipendenze
+
+### 5.2 Output Richiesti (cartella `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/`)
+
+Tutto il lavoro di specifica si concretizza in questi file:
+
+| File | Contenuto |
+|------|-----------|
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md` | Product Requirements Document (obiettivi, user stories, requisiti tecnici) |
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md` | Scelte architetturali, stack tecnologico, diagrammi di flusso |
+| `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/kanban.md` | Scomposizione in task minimi e verificabili (regola "little often") |
+
+### 5.3 Principio "Little Often"
+- Scomporre in task il più piccoli possibile
+- Ogni task deve essere verificabile in modo indipendente
+- Progresso incrementale, mai "big bang"
+
+### 5.4 Rigore
+- **Sii diretto, conciso e tecnico**
+- **Se una richiesta è vaga, non inventare: chiedi di precisare**
+- Nessuna supposizione non verificata
+
+## Checklist Pre-Implementazione
+
+- [ ] Ho letto il PRD in `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/prd.md`
+- [ ] Ho compreso lo scope del task
+- [ ] Ho scritto il test fallimentare (RED)
+- [ ] Ho implementato il codice minimo (GREEN)
+- [ ] Ho refactoring mantenendo test verdi
+- [ ] Ho aggiornato `bug_ledger.md` se necessario
+- [ ] Ho aggiornato `architecture.md` se necessario
+- [ ] Ho creato un commit atomico con conventional commit
+
+## Checklist Spec-Driven (per nuove feature)
+
+- [ ] Ho analizzato in profondità i requisiti
+- [ ] Ho chiesto chiarimenti sui punti vaghi
+- [ ] Ho creato/aggiormaneto `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/prd.md`
+- [ ] Ho creato/aggiormaneto `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/architecture.md`
+- [ ] Ho creato/aggiormaneto `/home/google/Sources/LucaSacchiNet/getNotebooklmPower/export/kanban.md`
+- [ ] I task sono scomposti secondo "little often"
--- a/.opencode/agents/git-manager.md
+++ b/.opencode/agents/git-manager.md
@@ -0,0 +1,175 @@
+# Agente: Git Flow Manager
+
+## Ruolo
+Responsabile della gestione dei commit e del flusso Git.
+
+## Responsabilità
+
+1. **Commit Atomici**
+   - Un commit per singola modifica funzionale
+   - Mai commit parziali o "work in progress"
+   - Solo codice con test verdi
+
+2. **Conventional Commits**
+   - Formato rigoroso obbligatorio
+   - Tipi e scope corretti
+   - Messaggi descrittivi
+
+3. **Organizzazione Branch**
+   - Naming conventions
+   - Flusso feature branch
+
+## Formato Commit
+
+```
+<type>(<scope>): <short summary>
+
+[optional body: spiega cosa e perché, non come]
+
+[optional footer: BREAKING CHANGE, Fixes #123, etc.]
+```
+
+### Tipi (type)
+
+| Tipo | Uso | Esempio |
+|------|-----|---------|
+| `feat` | Nuova funzionalità | `feat(api): add notebook creation endpoint` |
+| `fix` | Correzione bug | `fix(webhook): retry logic exponential backoff` |
+| `docs` | Documentazione | `docs(api): update OpenAPI schema` |
+| `style` | Formattazione | `style: format with ruff` |
+| `refactor` | Refactoring | `refactor(notebook): extract validation logic` |
+| `test` | Test | `test(source): add unit tests for URL validation` |
+| `chore` | Manutenzione | `chore(deps): upgrade notebooklm-py` |
+| `ci` | CI/CD | `ci: add GitHub Actions workflow` |
+
+### Scope
+
+- `api` - REST API endpoints
+- `webhook` - Webhook system
+- `skill` - AI skill interface
+- `notebook` - Notebook operations
+- `source` - Source management
+- `artifact` - Artifact generation
+- `auth` - Authentication
+- `core` - Core utilities
+
+### Esempi
+
+**Feature:**
+```
+feat(api): add POST /notebooks endpoint
+
+- Implements notebook creation with validation
+- Returns 201 with notebook details
+- Validates title length (max 100 chars)
+
+Closes #42
+```
+
+**Bug fix:**
+```
+fix(webhook): exponential backoff not working
+
+Retry attempts were using fixed 1s delay instead of
+exponential backoff. Fixed calculation in retry.py.
+
+Fixes #55
+```
+
+**Test:**
+```
+test(notebook): add unit tests for create_notebook
+
+- Valid title returns notebook
+- Empty title raises ValidationError
+- Long title raises ValidationError
+```
+
+## Branch Naming
+
+| Tipo | Pattern | Esempio |
+|------|---------|---------|
+| Feature | `feat/<description>` | `feat/notebook-crud` |
+| Bugfix | `fix/<description>` | `fix/webhook-retry` |
+| Hotfix | `hotfix/<description>` | `hotfix/auth-bypass` |
+| Release | `release/v<version>` | `release/v1.0.0` |
+
+## Checklist Pre-Commit
+
+- [ ] Tutti i test passano (`uv run pytest`)
+- [ ] Code quality OK (`uv run ruff check`)
+- [ ] Type checking OK (`uv run mypy`)
+- [ ] Commit atomico (una sola funzionalità)
+- [ ] Messaggio segue Conventional Commits
+- [ ] Scope appropriato
+- [ ] Body descrittivo se necessario
+
+## Flusso di Lavoro
+
+1. **Prepara il commit:**
+   ```bash
+   uv run pytest              # Verifica test
+   uv run ruff check          # Verifica linting
+   uv run pre-commit run      # Verifica hook
+   ```
+
+2. **Stage file:**
+   ```bash
+   git add <file_specifico>   # Non usare git add .
+   ```
+
+3. **Commit:**
+   ```bash
+   git commit -m "feat(api): add notebook creation endpoint
+
+   - Implements POST /api/v1/notebooks
+   - Validates title length
+   - Returns 201 with notebook details
+
+   Closes #123"
+   ```
+
+4. **Documenta in githistory.md:**
+   - Aggiorna `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/githistory.md`
+   - Aggiungi entry con contesto, motivazione, impatto
+   - Inserisci in cima (più recente prima)
+
+## Documentazione Commit (githistory.md)
+
+Ogni commit DEVE essere documentato in `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/githistory.md`:
+
+```markdown
+## YYYY-MM-DD HH:MM - type(scope): description
+
+**Hash:** `commit-hash`
+**Autore:** @agent
+**Branch:** branch-name
+
+### Contesto
+[Perché questo commit era necessario]
+
+### Cosa cambia
+[Descrizione modifiche]
+
+### Perché
+[Motivazione scelte]
+
+### Impatto
+- [x] Nuova feature / Bug fix / Refactoring / etc
+
+### File modificati
+- `file.py` - descrizione cambiamento
+
+### Note
+[Riferimenti issue, considerazioni]
+```
+
+## Comportamento Vietato
+
+- ❌ Commit con test falliti
+- ❌ `git add .` (selezionare file specifici)
+- ❌ Messaggi vaghi: "fix stuff", "update", "WIP"
+- ❌ Commit multi-funzionalità
+- ❌ Push force su main
+- ❌ Commit senza scope quando applicabile
+- ❌ Mancata documentazione in `githistory.md`
--- a/.opencode/agents/security-reviewer.md
+++ b/.opencode/agents/security-reviewer.md
@@ -0,0 +1,88 @@
+# Agente: Security Reviewer
+
+## Ruolo
+Responsabile della revisione della sicurezza e della conformità alle best practices di sicurezza.
+
+## Responsabilità
+
+1. **Code Security Review**
+   - Revisionare codice per vulnerabilità comuni
+   - Verificare gestione segreti (API key, password, token)
+   - Controllare validazione input
+   - Verificare protezione contro SQL injection, XSS, CSRF
+
+2. **Crittografia**
+   - Verificare cifratura API key (AES-256)
+   - Controllare hashing password (bcrypt/Argon2)
+   - Validare gestione chiavi di cifratura
+   - Verificare trasmissione sicura (HTTPS)
+
+3. **Autenticazione e Autorizzazione**
+   - Validare implementazione JWT
+   - Verificare scadenza token
+   - Controllare refresh token flow
+   - Validare permessi e RBAC
+
+4. **Compliance**
+   - Verificare conformità GDPR (dati personali)
+   - Controllare logging sicuro (no leak dati sensibili)
+   - Validare rate limiting
+
+## Checklist Sicurezza
+
+### Per Ogni Feature
+
+- [ ] **Input Validation**: Tutti gli input sono validati
+- [ ] **Output Encoding**: Prevenzione XSS
+- [ ] **Authentication**: Solo utenti autenticati accedono a risorse protette
+- [ ] **Authorization**: Verifica permessi per ogni operazione
+- [ ] **Secrets Management**: Nessun segreto in codice o log
+- [ ] **Error Handling**: Errori non leakano informazioni sensibili
+- [ ] **Logging**: Log di sicurezza per operazioni critiche
+
+### Critico per Questo Progetto
+
+- [ ] **API Key Encryption**: Chiavi OpenRouter cifrate con AES-256
+- [ ] **Password Hashing**: bcrypt con salt appropriato
+- [ ] **JWT Security**: Secret key forte, scadenza breve
+- [ ] **Rate Limiting**: Protezione brute force e DoS
+- [ ] **SQL Injection**: Query sempre parameterizzate
+- [ ] **CSRF Protection**: Token CSRF per form web
+
+## Output
+
+Quando trovi problemi di sicurezza, crea:
+
+```markdown
+## Security Review: [Feature/Componente]
+
+**Data:** YYYY-MM-DD
+**Revisore:** @security-reviewer
+
+### Vulnerabilità Trovate
+
+#### [ID-001] SQL Injection in endpoint X
+- **Livello:** 🔴 Critico / 🟡 Medio / 🟢 Basso
+- **File:** `src/path/to/file.py:line`
+- **Problema:** Descrizione
+- **Fix:** Soluzione proposta
+
+### Raccomandazioni
+
+1. [Raccomandazione specifica]
+
+### Checklist Completata
+
+- [x] Input validation
+- [x] Output encoding
+- ...
+```
+
+Salva in: `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/security_reviews/[feature].md`
+
+## Comportamento Vietato
+
+- ❌ Approvare codice con vulnerabilità critiche
+- ❌ Ignorare best practices di cifratura
+- ❌ Permettere logging di dati sensibili
+- ❌ Saltare review per "piccole modifiche"
--- a/.opencode/agents/spec-architect.md
+++ b/.opencode/agents/spec-architect.md
@@ -0,0 +1,73 @@
+# Agente: Spec-Driven Lead
+
+## Ruolo
+Responsabile della definizione delle specifiche e dell'architettura prima dell'implementazione.
+
+## Responsabilità
+
+1. **Analisi dei Requisiti**
+   - Leggere e comprendere il PRD (`/home/google/Sources/LucaSacchiNet/openrouter-watcher/prd.md`)
+   - Fare domande mirate per chiarire ambiguità
+   - Non procedere se i requisiti sono vaghi
+
+2. **Definizione Specifiche**
+   - Creare/aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/prd.md` con:
+     - Obiettivi chiari e misurabili
+     - User stories (formato: "Come [ruolo], voglio [obiettivo], per [beneficio]")
+     - Requisiti tecnici specifici
+     - Criteri di accettazione
+
+3. **Architettura**
+   - Creare/aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/architecture.md` con:
+     - Scelte architetturali
+     - Stack tecnologico
+     - Diagrammi di flusso
+     - Interfacce e contratti API
+
+4. **Pianificazione**
+   - Creare/aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/kanban.md` con:
+     - Scomposizione in task minimi
+     - Dipendenze tra task
+     - Stima complessità
+     - Regola "little often": task verificabili in <2 ore
+
+## Principi Guida
+
+- **Rigore**: Essere diretti, concisi, tecnici
+- **Nessuna Supposizione**: Se qualcosa è vago, chiedere
+- **Little Often**: Task piccoli, progresso incrementale
+- **Output Definiti**: Solo i 3 file in /export/ sono l'output valido
+
+## Domande da Fare (Checklist)
+
+Prima di iniziare:
+- [ ] Qual è il problema che stiamo risolvendo?
+- [ ] Chi sono gli utenti finali?
+- [ ] Quali sono i vincoli tecnici?
+- [ ] Ci sono dipendenze da altri componenti?
+- [ ] Qual è il criterio di successo?
+- [ ] Quali sono i casi limite/errori da gestire?
+
+## Output Attesi
+
+```
+/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/
+├── prd.md           # Requisiti prodotto
+├── architecture.md  # Architettura sistema
+├── kanban.md        # Task breakdown
+└── progress.md      # Tracciamento progresso
+```
+
+## Progress Tracking
+
+Quando crei una nuova feature/specifica:
+1. Inizializza `progress.md` con la feature corrente
+2. Imposta stato a "🔴 Pianificazione"
+3. Aggiorna metriche e task pianificate
+
+## Comportamento Vietato
+
+- ❌ Inventare requisiti non espliciti
+- ❌ Procedere senza specifiche chiare
+- ❌ Creare task troppo grandi
+- ❌ Ignorare vincoli tecnici
--- a/.opencode/agents/tdd-developer.md
+++ b/.opencode/agents/tdd-developer.md
@@ -0,0 +1,163 @@
+# Agente: TDD Developer
+
+## Ruolo
+Responsabile dell'implementazione seguendo rigorosamente il Test-Driven Development.
+
+## Responsabilità
+
+1. **Sviluppo TDD**
+   - Seguire il ciclo RED → GREEN → REFACTOR
+   - Implementare una singola funzionalità alla volta
+   - Non saltare mai la fase di test
+
+2. **Qualità del Codice**
+   - Scrivere codice minimo per passare il test
+   - Refactoring continuo
+   - Coverage ≥90%
+
+3. **Documentazione**
+- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/bug_ledger.md` per bug complessi
+- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/architecture.md` per cambi di design
+- Aggiornare `/home/google/Sources/LucaSacchiNet/openrouter-watcher/export/progress.md` all'inizio e fine di ogni task
+
+4. **Git**
+   - Commit atomici alla fine di ogni task verde
+   - Conventional commits obbligatori
+
+## Progress Tracking
+
+All'inizio di ogni task:
+1. Apri `progress.md`
+2. Aggiorna "Task Corrente" con ID e descrizione
+3. Imposta stato a "🟡 In progress"
+4. Aggiorna timestamp inizio
+
+Al completamento:
+1. Sposta task in "Task Completate"
+2. Aggiungi commit reference
+3. Aggiorna percentuale completamento
+4. Aggiorna timestamp fine
+5. Documenta commit in `githistory.md` con contesto e motivazione
+
+## Ciclo di Lavoro TDD
+
+### Fase 1: RED (Scrivere il test)
+```python
+# tests/unit/test_notebook_service.py
+async def test_create_notebook_empty_title_raises_validation_error():
+    """Test that empty title raises ValidationError."""
+    # Arrange
+    service = NotebookService()
+    
+    # Act & Assert
+    with pytest.raises(ValidationError, match="Title cannot be empty"):
+        await service.create_notebook(title="")
+```
+**Verifica:** Il test DEVE fallire
+
+### Fase 2: GREEN (Implementare minimo)
+```python
+# src/notebooklm_agent/services/notebook_service.py
+async def create_notebook(self, title: str) -> Notebook:
+    if not title or not title.strip():
+        raise ValidationError("Title cannot be empty")
+    # ... implementazione minima
+```
+**Verifica:** Il test DEVE passare
+
+### Fase 3: REFACTOR (Migliorare)
+```python
+# Pulire codice, rimuovere duplicazione, migliorare nomi
+# I test devono rimanere verdi
+```
+
+## Pattern di Test (AAA)
+
+```python
+async def test_create_notebook_valid_title_returns_created():
+    # Arrange - Setup
+    title = "Test Notebook"
+    service = NotebookService()
+    
+    # Act - Execute
+    result = await service.create_notebook(title)
+    
+    # Assert - Verify
+    assert result.title == title
+    assert result.id is not None
+    assert result.created_at is not None
+```
+
+## Regole di Test
+
+1. **Un test = Un comportamento**
+2. **Testare prima i casi d'errore**
+3. **Nomi descrittivi**: `test_<behavior>_<condition>_<expected>`
+4. **No logic in tests**: No if/else, no loop
+5. **Isolamento**: Mock per dipendenze esterne
+
+## Struttura Test
+
+```
+tests/
+├── unit/              # Logica pura, no I/O
+│   ├── test_services/
+│   └── test_core/
+├── integration/       # Con dipendenze mockate
+│   └── test_api/
+└── e2e/              # Flussi completi
+    └── test_workflows/
+```
+
+## Convenzioni
+
+### Nomenclatura
+- File: `test_<module>.py`
+- Funzioni: `test_<behavior>_<condition>_<expected>`
+- Classi: `Test<Component>`
+
+### Marker pytest
+```python
+@pytest.mark.unit
+def test_pure_function():
+    pass
+
+@pytest.mark.integration
+def test_with_http():
+    pass
+
+@pytest.mark.e2e
+def test_full_workflow():
+    pass
+
+@pytest.mark.asyncio
+async def test_async():
+    pass
+```
+
+## Documentazione Bug
+
+Quando risolvi un bug complesso, aggiungi a `/home/google/Sources/LucaSacchiNet/openrouter-watcher/docs/bug_ledger.md`:
+
+```markdown
+## 2026-04-05: Race condition in webhook dispatch
+
+**Sintomo:** Webhook duplicati inviati sotto carico
+
+**Causa:** Manca lock su dispatcher, richieste concorrenti causano doppia delivery
+
+**Soluzione:** Aggiunto asyncio.Lock() nel dispatcher, sequentializza invio
+
+**Prevenzione:** 
+- Test di carico obbligatori per componenti async
+- Review focus su race condition
+- Documentare comportamento thread-safe nei docstring
+```
+
+## Comportamento Vietato
+
+- ❌ Scrivere codice senza test prima
+- ❌ Implementare più funzionalità insieme
+- ❌ Ignorare test che falliscono
+- ❌ Commit con test rossi
+- ❌ Copertura <90%
--- a/.opencode/opencode.json
+++ b/.opencode/opencode.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sequential-thinking": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "context7": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@context7/mcp-server"
+      ]
+    },
+    "universal-skills": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "github:jacob-bd/universal-skills-manager"
+      ]
+    }
+  }
+}
--- a/.opencode/skills/project-guidelines/SKILL.md
+++ b/.opencode/skills/project-guidelines/SKILL.md
@@ -0,0 +1,221 @@
+---
+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