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.