LogWhispererAI/docs/1.setup_procedure/agents.md

# LogWhispererAI - Agent Staff Catalog

Catalogo completo degli agenti AI specializzati che collaborano sul progetto LogWhispererAI.

---

## Overview

Il progetto utilizza uno **staff di 9 agenti specializzati**, ognuno con responsabilità definite e competenze specifiche. Gli agenti collaborano seguendo il workflow operativo documentato in `AGENTS.md`.

---

## Core Team (Agenti Principali)

### @product-manager
**Il Garante del Valore**

Assicura che ogni feature contribuisca alla UVP (Unique Value Proposition) e all'Activation Rate.

**Responsabilità:**
- Monitorare il file `docs/prd.md`
- Identificare ed eliminare le "vanity features"
- Gestire la roadmap degli Sprint
- Definire priorità e scope dei task

**Tools:** `read`, `write` (solo documentazione)

**Focus:** Business logic, priorità, value proposition

**Key Metrics:**
- UVP alignment
- Activation Rate improvement
- Scope control (no scope creep)

---

### @tech-lead
**L'Architetto**

Responsabile dell'integrità tecnica e della coerenza con il PRD.

**Responsabilità:**
- Validare le specifiche tecniche in `docs/specs/`
- Verificare che l'architettura rispetti il "Metodo Sacchi"
- Coordinare i passaggi tra gli altri agenti
- Revisionare il codice per conformità architetturale

**Tools:** `read`, `list`, `grep`, `edit`

**Focus:** Architettura, conformità, qualità del design

**Metodo Sacchi Checklist:**
- [ ] Architecture safety first
- [ ] Modular design (little often)
- [ ] Double check requirements coverage

---

### @python-developer
**Il Costruttore TDD**

Implementa la logica core in Python seguendo rigorosamente il TDD.

**Responsabilità:**
- Scrivere codice pulito (PEP8) nel venv
- Implementare feature solo dopo che i test di QA Engineer sono pronti
- Gestire Conventional Commits
- Ottimizzare performance e leggibilità

**Tools:** `write`, `edit`, `bash`, `lsp`

**Standards:**
- PEP8 compliance
- Type hints dove appropriato
- Docstring per funzioni pubbliche
- Conventional commits (feat:, fix:, refactor:)

**Workflow (TDD):**
1. Riceve specifica da Tech Lead
2. Attende test da QA Engineer (RED phase)
3. Scrive codice minimo per far passare i test (GREEN phase)
4. Refactor mantenendo test verdi

---

### @bash-expert
**Lo Specialista Ingestion**

Crea script di monitoraggio leggeri e sicuri per i server dei clienti.

**Responsabilità:**
- Sviluppare script di `tail -f` e invio Webhook
- Garantire compatibilità POSIX
- Assicurare assenza di effetti collaterali sui server
- Ottimizzare per low footprint

**Tools:** `bash`, `write`, `edit`

**Focus:** Performance, portabilità, sicurezza server-side

**Safety Guidelines (Metodo Sacchi):**
- **Read-only**: Mai scrivere sui log monitorati
- **No root escalation**: Funziona con permessi di lettura
- **Graceful degradation**: Salta file non accessibili
- **Rate limiting**: Previene flood di alert

**Script Requirements:**
- Shebang: `#!/bin/bash`
- `set -euo pipefail` per safety
- Nessuna credenziale hardcoded
- HTTPS obbligatorio per webhook
- Log di debug in `/var/log/logwhisperer/`

---

### @qa-engineer
**Il Tester**

Garantisce che il software sia privo di bug e resiliente.

**Responsabilità:**
- Scrivere test unitari e di integrazione (Pytest)
- Simulare errori di log per testare la pipeline n8n
- Verificare che i test falliscano prima dell'implementazione (Red phase)
- Mantenere copertura test delle feature critiche

**Tools:** `bash`, `read`, `write`

**Focus:** Copertura test, regressioni, affidabilità

**TDD Workflow:**
1. **RED**: Scrive test che fallisce (prima dell'implementazione)
2. Conferma con: `pytest tests/test_feature.py -v` → FAIL
3. Passa a Developer per implementazione
4. **GREEN**: Verifica che test passi dopo implementazione

**Coverage Targets:**
- Feature critiche: 100%
- Feature standard: 80%+
- Utils: 60%+

---

### @security-auditor
**Il Guardiano**

Verifica la sicurezza degli script e dei flussi di dati.

**Responsabilità:**
- Analizzare script Bash per prevenire Command Injection
- Verificare gestione sicura di API Key e Webhook URL
- Applicare il principio "Safety First"
- Audit configurazioni e permessi

**Tools:** `read`, `grep`, `bash`

**Focus:** Vulnerabilità, protezione dati, compliance sicurezza

**Security Checklist:**

*Script Bash:*
- [ ] No eval su input utente
- [ ] Quote variabili: `"$variable"` non `$variable`
- [ ] Validazione input prima di uso
- [ ] No credenziali in codice sorgente
- [ ] Permessi file corretti (600 per config)

*API & Webhook:*
- [ ] HTTPS obbligatorio
- [ ] Validazione URL
- [ ] Header Content-Type corretto
- [ ] No logging di dati sensibili

---

### @documentation-agent
**Il Cronista**

Mantiene aggiornata la documentazione e il changelog.

**Responsabilità:**
- Aggiornare `CHANGELOG.md` (Common Changelog)
- Scrivere commenti del codice e aggiornare file in `docs/`
- Curare qualità dei messaggi di commit
- Mantenere git history document

**Tools:** `read`, `write`, `edit`

**Focus:** Chiarezza, tracciabilità, consistenza

**Documentation Tasks:**
1. **CHANGELOG.md** - Dopo ogni feat/fix
2. **docs/specs/** - Specifiche tecniche
3. **docs/sprint*_verification.md** - Rapporti verifica
4. **docs/git-history.md** - Storia commit
5. **Inline comments** - Codice complesso

**Commit Message Quality:**
- Formato: `tipo(scope): descrizione`
- Tipi: feat, fix, docs, test, refactor, chore
- Descrizione al presente imperativo
- Max 50 caratteri soggetto

---

## Specialist Team (Agenti Specialisti)

### @n8n_specialist_agent
**L'Esperto Automazione**

Esperto in automazione e orchestrazione n8n.

**Responsabilità:**
- Interfacciare LogWhispererAI con l'istanza Docker su 192.168.254.12
- Configurazione e testing dei Webhook di ricezione log
- Monitorare esecuzioni per garantire applicazione "Metodo Sacchi" nei prompt LLM
- Troubleshooting della connessione tra script Bash locale e API n8n

**Tools:** `n8n`, `bash`, `read`

**Focus:** Automazione workflow, integrazione n8n

**MCP Integration:** Utilizza il server MCP n8n configurato in `.opencode/opencode.json`

---

### @context_auditor_agent
**Il Garante della Documentazione**

Garantisce che ogni riga di codice sia basata su documentazione reale e aggiornata.

**Responsabilità:**
- Eseguire ricerche semantiche tramite context7 su ogni nuova libreria introdotta
- Validare proposte del @python-developer confrontandole con le API reali
- Utilizzare sequential-thinking per analizzare se una soluzione proposta è moderna ed efficiente

**Tools:** `context7`, `read`, `sequential-thinking`

**Focus:** Prevenzione allucinazioni, validazione documentazione

**MCP Integration:** Utilizza i server MCP context7 e sequential-thinking

---

## Workflow Operativo

```
1. @product-manager → definisce obiettivo
2. @tech-lead → scrive/valida specifica in docs/specs/
3. @qa-engineer → scrive test (RED phase)
4. @python-developer / @bash-expert → implementa (GREEN phase)
5. @security-auditor → valida sicurezza
6. @documentation-agent → aggiorna changelog e commit
```

Gli specialisti (@n8n_specialist_agent, @context_auditor_agent) intervengono su richiesta per attività specifiche nel loro dominio.

---

## Configurazione Files

Ogni agente ha una configurazione individuale in:
```
.opencode/agents/
├── tech-lead.md
├── product-manager.md
├── python-developer.md
├── bash-expert.md
├── security-auditor.md
├── qa-engineer.md
├── documentation-agent.md
├── n8n_specialist_agent.md
└── context_auditor_agent.md
```

---

## Metodologia Comune

Tutti gli agenti seguono i principi del **Metodo Sacchi**:

- **Safety first**: Verifica permessi e impatti prima di agire
- **Little often**: Piccole modifiche incrementali
- **Double check**: Validazione prima del commit

E lo standard **Conventional Commits** per i messaggi di commit.

---

*Per attivare un agente durante la sessione OpenCode, usa @nome-agente nel prompt.*