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

name, description

name	description
project-guidelines	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

# 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