docs: update documentation with MCP configuration and agent catalog

- Add MCP servers documentation (n8n, context7, sequential-thinking) - Update README.md with complete project structure and requirements.txt - Transform agents.md into comprehensive agent staff catalog (9 agents) - Update CHANGELOG.md with [Unreleased] MCP entries - Fix ingestion_script.md acceptance criteria checkboxes - Add .opencode/opencode.json to .gitignore for security - Include new agent configs: n8n_specialist_agent, context_auditor_agent - Include new skill playbooks: n8n_automation, context7_documentation Security: API credentials in .opencode/opencode.json are now gitignored
2026-04-02 18:21:21 +02:00
parent 9205c4ef32
commit 3a455e48d2
9 changed files with 405 additions and 67 deletions
--- a/docs/1.setup_procedure/agents.md
+++ b/docs/1.setup_procedure/agents.md
@@ -1,40 +1,244 @@
-# LogWhisperer AI - Agent Rules
+# LogWhisperer AI - Agent Staff Catalog

-Regole operative per gli agenti AI che collaborano su questo progetto.
+Catalogo completo degli agenti AI specializzati che collaborano sul progetto LogWhisperer AI.

 ---

-## Metodologia di Lavoro
+## Overview

-### Spec-Driven
-Prima di ogni modifica, l'agente deve aggiornare o confermare le specifiche in `docs/specs/`.
-
-### TDD (Test-Driven Development)
-Non scrivere logica senza un test fallimentare preventivo. Usa pytest.
-
-### Sacchi Method
-Applica sempre "**Safety first, little often, double check**". Verifica i permessi prima di eseguire comandi bash distruttivi.
-
-### Git Workflow
- **Conventional Commits**: usa `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
- **Atomic Commits**: un commit per singola modifica funzionale
- **Changelog**: aggiorna `CHANGELOG.md` seguendo lo standard Common Changelog
+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`.

 ---

-## Staff di Agenti
+## Core Team (Agenti Principali)

-Configurazioni dettagliate in `.opencode/agents/`:
+### @product-manager
+**Il Garante del Valore**

-| Agente | Ruolo | Focus |
-|--------|-------|-------|
-| `@tech-lead` | L'Architetto | Validazione specifiche, architettura |
-| `@product-manager` | Il Garante del Valore | PRD, roadmap, priorità |
-| `@python-developer` | Il Costruttore TDD | Implementazione Python (PEP8) |
-| `@bash-expert` | Lo Specialista Ingestion | Script Bash (low footprint) |
-| `@security-auditor` | Il Guardiano | Vulnerabilità, protezione dati |
-| `@qa-engineer` | Il Tester | Test suite, copertura, regressioni |
-| `@documentation-agent` | Il Cronista | Changelog, docs, commit messages |
+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 LogWhisperer AI 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

 ---

@@ -49,34 +253,38 @@ Configurazioni dettagliate in `.opencode/agents/`:
 6. @documentation-agent → aggiorna changelog e commit
 ```

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

-## Struttura Configurazione
+## Configurazione Files

+Ogni agente ha una configurazione individuale in:
 ```
-.opencode/
-├── agents/              # Configurazioni agenti individuali
-│   ├── tech-lead.md
-│   ├── product-manager.md
-│   ├── python-developer.md
-│   ├── bash-expert.md
-│   ├── security-auditor.md
-│   ├── qa-engineer.md
-│   └── documentation-agent.md
-└── skills/              # Playbook condivisi
-    ├── TDD_Python_Specialist/
-    └── Git_and_Changelog/
+.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
 ```

 ---

-## Skills Disponibili
+## Metodologia Comune

-Skills condivise in `.opencode/skills/`:
+Tutti gli agenti seguono i principi del **Metodo Sacchi**:

- **TDD_Python_Specialist/**: Workflow TDD (RED → GREEN → REFACTOR)
- **Git_and_Changelog/**: Conventional commits, Common Changelog
+- **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 configurazioni dettagliate, vedere i file in `.opencode/agents/`*
+*Per attivare un agente durante la sessione OpenCode, usa @nome-agente nel prompt.*
--- a/docs/specs/ingestion_script.md
+++ b/docs/specs/ingestion_script.md
@@ -94,7 +94,7 @@ scripts/
  logwhisperer.sh          # Script principale
  install.sh               # Script di installazione (setup config, systemd)
 tests/
-  conftest.py
+  __init__.py
  test_logwhisperer.py     # Test Python con subprocess
 docs/
  specs/
@@ -103,13 +103,13 @@ docs/

 ## 6. Criteri di Accettazione

- [ ] Lo script legge da almeno 2 source di log configurabili
- [ ] Rileva pattern di errore (case-insensitive)
- [ ] Invia POST JSON al webhook con payload corretto
- [ ] Gestisce retry su fallimento HTTP
- [ ] Non blocca il sistema se il webhook è down
- [ ] Test Python passano con pytest
- [ ] Script installabile con un solo comando
+- [x] Lo script legge da almeno 2 source di log configurabili
+- [x] Rileva pattern di errore (case-insensitive)
+- [x] Invia POST JSON al webhook con payload corretto
+- [x] Gestisce retry su fallimento HTTP
+- [x] Non blocca il sistema se il webhook è down
+- [x] Test Python passano con pytest
+- [x] Script installabile con un solo comando

 ## 7. Note di Sicurezza