--- 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 ``` (): [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`*