documente/.opencode/skills/project-guidelines/SKILL.md

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

# Project Guidelines - getNotebooklmPower

## Panoramica del Progetto

**getNotebooklmPower** è un'API REST che fornisce accesso programmatico a Google NotebookLM tramite interfaccia webhook.

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

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

**Entry Point**: `@sprint-lead` (coordinatore)

| Agente | Ruolo | Quando Usare |
|--------|-------|--------------|
| `@sprint-lead` | Coordina il team di agenti | Sempre, entry point per ogni task |
| `@spec-architect` | Definisce specifiche e architettura | Prima di nuove feature |
| `@api-designer` | Progetta API e modelli Pydantic | Dopo spec, prima di implementazione |
| `@security-auditor` | Security review | Feature auth/webhook, periodicamente |
| `@tdd-developer` | Implementazione TDD | Durante sviluppo (unit tests) |
| `@qa-engineer` | Integration e E2E tests | Parallelo a tdd-developer |
| `@code-reviewer` | Review qualità codice | Dopo implementazione, prima di commit |
| `@docs-maintainer` | Aggiorna documentazione | Dopo ogni feature |
| `@git-manager` | Gestione commit Git | A fine task |
| `@devops-engineer` | CI/CD e deployment | Setup iniziale, quando serve |
| `@refactoring-agent` | Miglioramento codice | Debito tecnico, manutenzione |

## Flusso di Lavoro (OBBLIGATORIO)

### Per Nuove Feature (Workflow Completo)

```
@sprint-lead (coordinatore)
    ↓
1. @spec-architect → Legge PRD, definisce specifiche
    ↓ Crea/aggiorna: /export/prd.md, architecture.md, kanban.md
    ↓
2. @api-designer → Progetta API e modelli Pydantic
    ↓ Definisce: api/models/, docs/api/endpoints.md
    ↓
3. @security-auditor (se auth/webhook) → Security review architettura
    ↓ Verifica: OWASP, input validation, secrets management
    ↓
4. @tdd-developer (unit tests) + @qa-engineer (integration)
    ↓ Implementa: RED → GREEN → REFACTOR
    ↓ Coverage target: ≥90%
    ↓
5. @code-reviewer → Review qualità codice
    ↓ Verifica: clean code, SOLID, type hints, docstrings
    ↓ Output: review.md con [BLOCKING], [WARNING], [SUGGESTION]
    ↓
6. @docs-maintainer → Aggiorna documentazione
    ↓ Aggiorna: README.md, SKILL.md, CHANGELOG.md
    ↓
7. @git-manager → Commit atomico
    ↓ Conventional Commit + githistory.md
    ↓
8. @devops-engineer (se necessario) → Deploy, monitoring
```

### Per Bug Fix Rapido

```
@sprint-lead
    ↓
1. Leggi bug_ledger.md per pattern simili
2. @tdd-developer → Scrive test che riproduce il bug
3. @tdd-developer → Implementa fix
4. @qa-engineer → Integration test
5. @code-reviewer → Review rapida
6. @git-manager → Commit con tipo "fix:"
```

### Per Refactoring

```
@sprint-lead
    ↓
1. @refactoring-agent → Identifica debito tecnico
    ↓ Analizza: complessità, duplicazione, coverage
    ↓
2. @refactoring-agent + @tdd-developer → Esegue refactoring
    ↓ Vincolo: test esistenti devono passare
    ↓
3. @code-reviewer → Review qualità
4. @git-manager → Commit con tipo "refactor:"
```

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

### 6. Prompt Management (Nuovo)
- **Ogni prompt salvato** in `prompts/{NUMERO}-{descrizione}.md`
- **Numerazione progressiva**: 1, 2, 3, ...
- **Template standard**: Obiettivo, Scope, Accettazione
- **README aggiornato**: Lista tutti i prompt in `prompts/README.md`

## Struttura Progetto

```
getNotebooklmPower/
├── prompts/                      # PROMPT ARCHIVE - Tutti i prompt salvati
│   ├── README.md                # Indice e convenzioni
│   ├── 1-avvio.md               # Primo prompt: avvio progetto
│   └── {N}-{descrizione}.md     # Prompt successivi (2, 3, 4...)
├── src/                          # Codice sorgente
│   └── notebooklm_agent/
│       ├── api/                  # FastAPI routes
│       │   ├── main.py          # Entry point
│       │   ├── dependencies.py  # DI container
│       │   ├── routes/          # Endpoint handlers
│       │   └── models/          # Pydantic models
│       ├── services/             # Business logic
│       ├── core/                 # Utilities (config, exceptions, logging)
│       ├── webhooks/             # Webhook system
│       └── skill/                # AI Skill interface
├── tests/                        # Test suite
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/                         # Documentazione utente
│   ├── api/
│   └── examples/
├── .opencode/                    # Configurazione OpenCode
│   ├── WORKFLOW.md              # Flusso di lavoro
│   ├── agents/                  # Configurazioni agenti (11 agenti)
│   ├── skills/                  # Skill condivise
│   └── templates/               # Template per spec-driven workflow
├── prd.md                        # Product Requirements
├── AGENTS.md                     # Linee guida generali
├── SKILL.md                      # Skill definizione
├── CHANGELOG.md                  # Release notes
└── CONTRIBUTING.md               # Guida contribuzione
```

## Convenzioni di Codice

### Python
- Python 3.10+
- PEP 8
- Type hints obbligatori
- Docstrings Google-style
- Line length: 100 caratteri

### Testing
- pytest
- Coverage ≥90%
- AAA pattern (Arrange-Act-Assert)
- Mock per dipendenze esterne

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

[body]

[footer]
```

**Tipi:** feat, fix, docs, test, refactor, chore, ci, style
**Scope:** api, webhook, skill, notebook, source, artifact, auth, core

## Risorse

| File/Directory | Scopo |
|----------------|-------|
| `prompts/` | **ARCHIVIO PROMPT** - Tutti i prompt salvati con numerazione progressiva |
| `prompts/README.md` | Indice e convenzioni per la gestione prompt |
| `prd.md` | Requisiti prodotto |
| `AGENTS.md` | Linee guida progetto |
| `.opencode/WORKFLOW.md` | Flusso di lavoro dettagliato |
| `.opencode/agents/` | Configurazioni agenti (11 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

```bash
# Test
uv run pytest                    # Tutti i test
uv run pytest --cov             # Con coverage
uv run pytest tests/unit/        # Solo unit test

# Qualità
uv run ruff check src/          # Linting
uv run ruff format src/         # Formattazione
uv run mypy src/                # Type checking

# Pre-commit
uv run pre-commit run --all-files

# Server
uv run fastapi dev src/notebooklm_agent/api/main.py
```

## Checklist

### Per Nuovi Prompt (prima di iniziare)
- [ ] Ho determinato il prossimo numero (controlla `ls prompts/`)
- [ ] Ho creato `prompts/{NUMERO}-{descrizione}.md` con template standard
- [ ] Ho incluso comando per @sprint-lead
- [ ] Ho definito obiettivo chiaro e criteri successo
- [ ] Ho aggiornato `prompts/README.md` con il nuovo prompt

### Pre-Implementazione (coordinato da @sprint-lead)
- [ ] @sprint-lead ha attivato il workflow corretto
- [ ] Ho letto il prompt corrente in `prompts/{NUMERO}-*.md`
- [ ] @spec-architect ha definito specifiche in `/export/`
- [ ] Ho letto `prd.md` e `export/architecture.md`
- [ ] Ho compreso lo scope e accettazione criteria

### Durante Implementazione
- [ ] @api-designer ha definito contratti API (se applicabile)
- [ ] @security-auditor ha approvato design (se auth/webhook)
- [ ] Test scritto prima (RED)
- [ ] Codice minimo (GREEN)
- [ ] Refactoring (REFACTOR)
- [ ] @qa-engineer ha scritto integration tests (parallelo)

### Post-Implementazione
- [ ] Tutti i test passano (unit + integration)
- [ ] Coverage ≥90%
- [ ] @code-reviewer ha approvato (no [BLOCKING])
- [ ] @docs-maintainer ha aggiornato documentazione
- [ ] `CHANGELOG.md` aggiornato
- [ ] @git-manager ha creato commit con conventional commits
- [ ] @sprint-lead ha aggiornato `export/progress.md`

---

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