# Prompt Zero: OpenRouter API Key Monitor - Project Kickoff

## 🎯 Missione

Sviluppare **OpenRouter API Key Monitor**, un'applicazione web multi-utente per monitorare l'utilizzo delle API key della piattaforma OpenRouter.

**Repository:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher`  
**PRD:** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/prd.md`

---

## 📊 Stato Attuale

- ✅ **PRD Completo**: Requisiti funzionali e non funzionali definiti
- ✅ **Team Configurato**: 3 agenti specializzati pronti
- ❌ **Nessun Codice**: Progetto da zero
- ❌ **Nessuna Specifica Tecnica**: Da creare

---

## 👥 Team di Sviluppo

| Agente | Ruolo | File Config |
|--------|-------|-------------|
| `@spec-architect` | Definisce specifiche e architettura | `.opencode/agents/spec-architect.md` |
| `@tdd-developer` | Implementazione TDD | `.opencode/agents/tdd-developer.md` |
| `@git-manager` | Gestione commit Git | `.opencode/agents/git-manager.md` |

---

## 🔄 Workflow Obbligatorio

```
┌─────────────────────────────────────────────────────────────┐
│  FASE 1: SPECIFICA                                          │
│  @spec-architect                                            │
│  └── Legge PRD → Crea architecture.md, kanban.md           │
│                                                             │
│  ↓                                                          │
│                                                             │
│  FASE 2: IMPLEMENTAZIONE                                    │
│  @tdd-developer                                             │
│  └── RED → GREEN → REFACTOR per ogni task                  │
│                                                             │
│  ↓                                                          │
│                                                             │
│  FASE 3: COMMIT                                             │
│  @git-manager                                               │
│  └── Commit atomico + Conventional Commits                 │
└─────────────────────────────────────────────────────────────┘
```

---

## 🚀 Task Iniziale: Fase 1 - Specifica

**AGENTE:** `@spec-architect`

**OBIETTIVO:** Analizzare il PRD e creare le specifiche tecniche dettagliate.

### Azioni Richieste

1. **Leggere** `/home/google/Sources/LucaSacchiNet/openrouter-watcher/prd.md`

2. **Creare** la struttura di output:
   ```
   /home/google/Sources/LucaSacchiNet/openrouter-watcher/export/
   ├── prd.md              # Requisiti prodotti (estratto/dettaglio)
   ├── architecture.md     # Architettura sistema
   ├── kanban.md           # Task breakdown
   └── progress.md         # Tracciamento progresso
   ```

3. **Produrre** `architecture.md` con:
   - Stack tecnologico dettagliato (Python 3.11+, FastAPI, SQLite, SQLAlchemy, JWT)
   - Struttura cartelle progetto
   - Diagrammi flusso dati
   - Schema database completo (DDL)
   - Interfacce API (OpenAPI specs)
   - Sicurezza (cifratura, autenticazione)

4. **Produrre** `kanban.md` con:
   - Task breakdown per Fase 1 (MVP)
   - Stima complessità
   - Dipendenze tra task
   - Regola "little often": task < 2 ore

5. **Inizializzare** `progress.md` con:
   - Feature corrente: "Fase 1 - MVP"
   - Stato: "🔴 Pianificazione"
   - Percentuale: 0%

### Criteri di Accettazione

- [ ] Architecture.md completo con tutte le sezioni
- [ ] Kanban.md con task pronti per @tdd-developer
- [ ] Progress.md inizializzato
- [ ] Tutti i path usano `/home/google/Sources/LucaSacchiNet/openrouter-watcher/`

---

## 📋 Requisiti Chiave (Dal PRD)

### Funzionalità MVP (Fase 1)

1. **Autenticazione Utenti**
   - Registrazione/login multi-utente
   - JWT-based authentication
   - Password hash (bcrypt)

2. **Gestione API Key**
   - CRUD API key OpenRouter
   - Cifratura AES-256 in database
   - Validazione key con OpenRouter API

3. **Dashboard**
   - Statistiche utilizzo
   - Grafici temporali
   - Costi e richieste

4. **API Pubblica**
   - Endpoint autenticati (Bearer token)
   - Solo lettura dati
   - Rate limiting

### Stack Tecnologico

- **Backend:** Python 3.11+, FastAPI
- **Database:** SQLite + SQLAlchemy
- **Frontend:** HTML + HTMX (semplice)
- **Auth:** JWT + bcrypt
- **Task Background:** APScheduler

---

## 🛡️ Vincoli e Best Practices

### Sicurezza (Critico)
- API key sempre cifrate (AES-256)
- Password hash con bcrypt
- SQL injection prevention
- XSS prevention
- CSRF protection
- Rate limiting

### Qualità
- Test coverage ≥ 90%
- TDD obbligatorio
- Conventional commits
- Commit atomici

### Organizzazione
- Task "little often" (< 2 ore)
- Documentazione in `/export/`
- Bug complessi in `/docs/bug_ledger.md`

---

## 📁 Struttura Progetto Attesa

```
/home/google/Sources/LucaSacchiNet/openrouter-watcher/
├── prd.md                      # Questo PRD
├── prompt/
│   └── prompt-zero.md         # Questo file
├── .opencode/
│   ├── agents/                # Configurazioni agenti
│   └── skills/                # Skill condivise
├── export/                    # Output spec-driven (da creare)
│   ├── prd.md
│   ├── architecture.md
│   ├── kanban.md
│   └── progress.md
├── docs/                      # Documentazione (da creare)
│   ├── bug_ledger.md
│   └── architecture.md
├── src/                       # Codice sorgente (da creare)
│   └── openrouter_monitor/
│       ├── __init__.py
│       ├── main.py
│       ├── config.py
│       ├── database.py
│       ├── models/
│       ├── routers/
│       ├── services/
│       └── utils/
├── tests/                     # Test suite (da creare)
│   ├── unit/
│   ├── integration/
│   └── conftest.py
├── requirements.txt
└── README.md
```

---

## ✅ Checklist Pre-Sviluppo

- [ ] @spec-architect ha letto questo prompt
- [ ] Cartella `export/` creata
- [ ] `architecture.md` creato con schema DB
- [ ] `kanban.md` creato con task Fase 1
- [ ] `progress.md` inizializzato

---

## 🎬 Prossima Azione

**@spec-architect**: Inizia analizzando il PRD in `prd.md` e crea le specifiche tecniche in `export/`.

**NON iniziare l'implementazione** finché le specifiche non sono approvate.

---

## 📞 Note per il Team

- **Domande sul PRD?** Leggi prima `prd.md` completamente
- **Ambiguità?** Chiedi prima di procedere
- **Vincoli tecnici?** Documentali in `architecture.md`
- **Task troppo grandi?** Spezza in task più piccoli

---

**Data Creazione:** 2025-04-07  
**Versione:** 1.0  
**Stato:** Pronto per kickoff