documente/prompts/1-avvio.md

Sprint Kickoff: Implementazione Core API - Notebook Management

📋 Comando per @sprint-lead

@sprint-lead Avvia il workflow completo per implementare la gestione notebook CRUD. Questo è lo sprint iniziale per rendere l'API funzionante.

---

🎯 Obiettivo Sprint

Implementare l'API REST completa per la gestione dei notebook NotebookLM, permettendo agli utenti di creare, leggere, aggiornare ed eliminare notebook via API.

Success Criteria:

• Endpoint CRUD /api/v1/notebooks funzionanti con test ≥90% coverage
• Documentazione SKILL.md aggiornata con esempi curl funzionanti
• CI/CD pipeline verde su GitHub Actions

---

📚 Contesto & Background

Stato Attuale

• ✅ Setup progetto completo (struttura, tooling, CI/CD)
• ✅ API base funzionante (health check, dependencies)
• ✅ Core package (config, exceptions, logging)
• ✅ Squadra agenti configurata e pronta

Documentazione Riferimento

• PRD: prd.md - Sezione 4.1 (Requisiti Notebook Management)
• Workflow: .opencode/WORKFLOW.md
• Skill: .opencode/skills/project-guidelines/SKILL.md
• API Design: Da definire (@api-designer)
• NotebookLM-py docs: https://github.com/teng-lin/notebooklm-py

Requisiti dal PRD (REQ-001)

• POST /api/v1/notebooks - Creare notebook
• GET /api/v1/notebooks - Listare notebook (con pagination)
• GET /api/v1/notebooks/{id} - Ottenere dettagli notebook
• PATCH /api/v1/notebooks/{id} - Aggiornare notebook
• DELETE /api/v1/notebooks/{id} - Eliminare notebook

---

✅ Scope (Incluso)

In Scope

1. API Design (@api-designer)

   • Modelli Pydantic (NotebookCreate, NotebookUpdate, NotebookResponse)
   • Query parameters per pagination (limit, offset)
   • Error response standard

2. Implementazione (@tdd-developer + @qa-engineer)

   • Service layer: NotebookService con integrazione notebooklm-py
   • API routes: CRUD endpoints in api/routes/notebooks.py
   • Unit tests: ≥90% coverage
   • Integration tests: Mock HTTP client

3. Security (@security-auditor)

   • API key validation su tutti gli endpoint
   • Input validation (Pydantic)
   • Rate limiting headers

4. Documentazione (@docs-maintainer)

   • Aggiornare SKILL.md con esempi curl
   • Aggiornare CHANGELOG.md
   • Creare docs/api/endpoints.md

5. Quality Gates (@code-reviewer)

   • Code review completa
   • Type hints check
   • No code smells

Out of Scope (Prossimi Sprint)

• Gestione fonti (sources) - Sprint 2
• Chat functionality - Sprint 3
• Content generation - Sprint 4
• Webhook system - Sprint 5
• E2E tests con NotebookLM reale (richiede auth)

---

⚠️ Vincoli & Constraints

1. Tecnici

   • Python 3.10+ con type hints obbligatori
   • FastAPI + Pydantic v2
   • Coverage ≥90%
   • Async/await per I/O bound operations

2. Architetturali

   • Layering: API → Service → Core
   • Dependency injection
   • Nessuna logica business nei router

3. NotebookLM-py

   • Usare NotebookLMClient.from_storage() per auth
   • Gestire rate limiting con retry
   • Wrappare eccezioni in custom exceptions

4. Tempo

   • Stima: 3-5 giorni (complexity: media)
   • Daily standup virtuale ogni mattina

---

🎯 Criteri di Accettazione (Definition of Done)

Per @sprint-lead - Checklist Finale:

• @spec-architect: Specifiche in export/prd.md e export/architecture.md
• @api-designer: Modelli Pydantic in api/models/, API docs in docs/api/
• @security-auditor: Security review completata, no [BLOCKING] issues
• @tdd-developer: Unit tests passanti, coverage ≥90%
• @qa-engineer: Integration tests passanti
• @code-reviewer: Review approvata, no [BLOCKING] issues
• @docs-maintainer: SKILL.md e CHANGELOG.md aggiornati
• @git-manager: Commit atomici con conventional commits
• CI/CD: Pipeline verde su GitHub Actions

Test Manuale di Verifica:

# Avvia server
uv run fastapi dev src/notebooklm_agent/api/main.py

# Test CRUD
curl -X POST http://localhost:8000/api/v1/notebooks \
  -H "X-API-Key: test-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Notebook"}'

curl http://localhost:8000/api/v1/notebooks \
  -H "X-API-Key: test-key"

curl http://localhost:8000/api/v1/notebooks/{id} \
  -H "X-API-Key: test-key"

---

📊 Metriche Target

Metrica	Target	Attuale
API Endpoints	5 CRUD	1 (health)
Test Coverage	≥90%	~60%
Lines of Code	~500	~200
Docs Completeness	100%	20%
CI/CD Status	🟢 Green	🟡 Partial

---

🎬 Azioni Immediate per @sprint-lead

1. Ora: Attiva @spec-architect per analisi dettagliata

   • Leggere PRD sezione 4.1
   • Creare export/kanban.md con task breakdown
   • Definire interfacce NotebookService

2. Quando @spec-architect completa: Attiva @api-designer

   • Progettare modelli Pydantic
   • Definire schema OpenAPI
   • Documentare esempi

3. Poi: Attiva @tdd-developer + @qa-engineer in parallelo

   • RED: Scrivere test
   • GREEN: Implementare codice
   • REFACTOR: Migliorare

4. Infine: Quality gates e deploy

   • @code-reviewer → @docs-maintainer → @git-manager

---

📝 Note Aggiuntive

Pattern da Seguire

# Service Layer
class NotebookService:
    async def create(self, data: NotebookCreate) -> Notebook:
        # Business logic qui
        pass

# API Layer  
@router.post("/")
async def create_notebook(
    data: NotebookCreate,
    service: NotebookService = Depends(get_notebook_service)
):
    return await service.create(data)

Gestione Errori

Usare gerarchia eccezioni in core/exceptions.py:

• ValidationError → HTTP 400
• NotFoundError → HTTP 404
• AuthenticationError → HTTP 401
• NotebookLMError → HTTP 502 (bad gateway)

Rate Limiting NotebookLM

Il client notebooklm-py ha rate limiting aggressivo. Implementare retry con exponential backoff in service layer.

---

🎯 Call to Action

@sprint-lead:

1. Inizializza export/progress.md con questo sprint
2. Attiva @spec-architect per la fase di analisi
3. Programma daily standup per domani mattina
4. Monitora progresso e gestisci blocchi

Team: Seguire il workflow in .opencode/WORKFLOW.md e le linee guida in .opencode/skills/project-guidelines/SKILL.md.

Obiettivo: Notebook CRUD API production-ready entro venerdì! 🚀

---

Data Inizio Sprint: 2026-04-06
Sprint Lead: @sprint-lead
Priority: P0 (Foundation) Prompt File: prompts/1-avvio.md