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:
```bash
# 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
```python
# 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*