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

.gitignore

@@ -20,3 +20,6 @@ htmlcov/
 # OS
 .DS_Store
 Thumbs.db
+
+# OpenCode configuration with sensitive data
+.opencode/opencode.json

.opencode/agents/context_auditor_agent.md

@@ -0,0 +1,18 @@
+description: Garante della documentazione aggiornata e prevenzione allucinazioni
+mode: subagent
+tools:
+context7: true
+read: true
+sequential-thinking: true
+
+@context-auditor
+
+Il tuo scopo è garantire che ogni riga di codice prodotta dallo staff sia basata su documentazione reale e aggiornata.
+
+Responsabilità
+
+Eseguire ricerche semantiche tramite context7 su ogni nuova libreria introdotta.
+
+Validare le proposte del @python-developer confrontandole con le API reali.
+
+Utilizzare sequential-thinking per analizzare se una soluzione proposta è la più moderna ed efficiente disponibile.

.opencode/agents/n8n_specialist_agent.md

@@ -0,0 +1,18 @@
+description: Esperto in automazione e orchestrazione n8n
+mode: subagent
+tools:
+n8n: true
+bash: true
+read: true
+
+@n8n-specialist
+
+Sei un esperto di automazione n8n. Il tuo compito è interfacciare LogWhisperer AI con l'istanza Docker su 192.168.254.12.
+
+Focus Operativo
+
+Configurazione e testing dei Webhook di ricezione log.
+
+Monitoraggio delle esecuzioni per garantire che il "Metodo Sacchi" venga applicato nei prompt dell'LLM interno a n8n.
+
+Troubleshooting della connessione tra lo script Bash locale e l'API di n8n.

.opencode/skills/context7_documentation_retrivial/SKILL.md

@@ -0,0 +1,19 @@
+Skill: Context7 Documentation Retrieval
+
+Istruzioni per l'utilizzo di Context7 per eliminare allucinazioni su API e librerie.
+
+Quando usare questa Skill
+
+Prima di scrivere codice Python che utilizza librerie esterne (es. requests, pytest, supabase-py).
+
+Quando si scrivono script Bash che utilizzano tool specifici (es. curl, jq).
+
+Per verificare le ultime specifiche del Model Context Protocol (MCP).
+
+Metodologia
+
+Usa context7.search inserendo la libreria e la versione desiderata.
+
+Integra i risultati nel contesto prima di generare il codice.
+
+Se il codice generato fallisce i test, usa context7 per verificare se l'API utilizzata è deprecata.

.opencode/skills/n8n_automation_mastery/SKILL.md

@@ -0,0 +1,17 @@
+Skill: n8n Automation Mastery
+
+Questa skill istruisce l'agente su come interagire con l'istanza n8n locale (192.168.254.12).
+
+Procedure Operative
+
+Discovery: Prima di ogni operazione su n8n, usa n8n.list_workflows per identificare l'ID del workflow relativo a LogWhisperer.
+
+Validazione: Se un workflow deve ricevere dati dallo script Bash, usa n8n.get_workflow per verificarne i nodi di ingresso (Webhook).
+
+Test di Integrazione: Dopo aver implementato una modifica allo script Bash, usa n8n.execute_workflow per simulare la ricezione di un log e verificare che l'alert arrivi a destinazione.
+
+Vincoli
+
+Non eliminare workflow esistenti senza autorizzazione del @tech-lead.
+
+Usa sempre l'ambiente di test di n8n per le prove di esecuzione.

CHANGELOG.md

@@ -9,18 +9,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- docs: Project Review Sprint 1 with agent staff analysis
+- feat: Configure MCP servers for enhanced AI capabilities
-  - Product Manager UVP alignment assessment
+  - sequential-thinking MCP for structured problem solving
-  - Tech Lead architecture coherence review
+  - context7 MCP for contextual library documentation retrieval
-  - Security Auditor risk analysis
+  - n8n MCP for workflow automation integration
-  - Sprint 1 review document in `docs/reviews/s`
+- docs: Add agent-specific configurations in `.opencode/agents/`
+  - @n8n_specialist_agent for n8n workflow management
+  - @context_auditor_agent for documentation alignment checks
+- docs: Add skill playbooks in `.opencode/skills/`
+  - TDD_Python_Specialist: Test-driven development workflow
+  - Git_and_Changelog: Conventional commits and changelog standards
+  - n8n_automation_mastery: n8n workflow best practices
+  - context7_documentation_retrivial: Context-aware documentation lookup
+- docs: Add requirements.txt with Python dependencies (pytest, requests)
 
 ### Changed
 
-- docs: Updated README.md with project status badges and improved structure
+- docs: Update README.md with complete project structure
-- docs: Updated PRD status to reflect Sprint 1 completion
+  - Add MCP configuration section
-- docs: Updated ingestion script spec status to "Completed"
+  - Document all agent configurations
-- docs: Updated Sprint 1 verification report with Project Review reference
+  - Include skill playbooks in project tree
+  - Update setup instructions with requirements.txt
+- docs: Refactor setup documentation structure (moved to `docs/1.setup_procedure/`)
 
 ## [0.1.1] - 2026-04-02
 

README.md

@@ -40,6 +40,13 @@ Agentic Dev: OpenCode.ai
 
 Il progetto segue una metodologia **Spec-Driven** e **TDD** (Test-Driven Development).
 
+### Prerequisiti
+
+- **Python** 3.12 o superiore
+- **Bash** 4.0+
+- **curl** (GNU coreutils)
+- **Node.js** 18+ (per i MCP servers)
+
 ### Clone e setup
 
 ```bash
@@ -52,9 +59,29 @@ python3 -m venv venv
 source venv/bin/activate
 
 # Installazione dipendenze
-pip install pytest
+pip install -r requirements.txt
 ```
 
+### Configurazione MCP (OpenCode.ai)
+
+Il progetto utilizza tre MCP (Model Context Protocol) servers per estendere le capacità dell'agente AI:
+
+1. **sequential-thinking** - Problem solving strutturato
+2. **context7** - Recupero documentazione contestuale delle librerie
+3. **n8n** - Integrazione con workflow automation
+
+La configurazione è già presente in `.opencode/opencode.json`. Per utilizzarla:
+
+```bash
+# Assicurati di avere npx installato
+npm install -g npx
+
+# Avvia OpenCode
+opencode
+```
+
+**Nota sulla sicurezza:** Le credenziali n8n sono configurate nel file `.opencode/opencode.json`. Non committare mai questo file con credenziali di produzione.
+
 ### Eseguire i Test
 
 ```bash
@@ -117,7 +144,8 @@ opencode
 - `docs/prd.md` - Product Requirements Document
 - `docs/specs/` - Specifiche tecniche per ogni sprint
 - `docs/reviews/` - Project Review post-sprint
-- `docs/sprintN_verification.md` - Report verifica sprint
+- `docs/1.setup_procedure/` - Procedure di setup OpenCode.ai
+- `docs/sprint1_verification.md` - Report verifica sprint
 
 ## 📁 Struttura del Progetto
 
@@ -127,12 +155,16 @@ LogWhispererAI/
 ├── CHANGELOG.md                 # Log modifiche
 ├── README.md                    # Questo file
 ├── LICENSE.md                   # Licenza proprietaria
+├── requirements.txt             # Dipendenze Python (pytest, requests)
 ├── docs/
 │   ├── prd.md                   # Product Requirements Document
 │   ├── specs/
 │   │   └── ingestion_script.md  # Specifica tecnica Sprint 1
 │   ├── reviews/
 │   │   └── sprint1_review.md    # Project Review Sprint 1
+│   ├── 1.setup_procedure/       # Setup OpenCode.ai
+│   │   ├── setup.md             # Procedura setup
+│   │   └── agents.md            # Configurazione agenti
 │   └── sprint1_verification.md  # Report verifica
 ├── scripts/
 │   ├── logwhisperer.sh          # Script principale
@@ -141,8 +173,22 @@ LogWhispererAI/
 │   ├── __init__.py
 │   └── test_logwhisperer.py     # Test suite Python
 └── .opencode/
-    ├── agents/                  # Configurazioni agenti
+    ├── opencode.json            # Configurazione MCP servers
-    └── skills/                  # Skills TDD e Git
+    ├── 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
+    │   ├── n8n_specialist_agent.md
+    │   └── context_auditor_agent.md
+    └── skills/                  # Playbook condivisi
+        ├── TDD_Python_Specialist/
+        ├── Git_and_Changelog/
+        ├── n8n_automation_mastery/
+        └── context7_documentation_retrivial/
 ```
 
 ## ⚖️ Licenza e Note Legali
@@ -167,4 +213,3 @@ Per i dettagli completi, consultare il file [LICENSE.md](LICENSE.md).
 <p align="center">
   <em>LogWhispererAI - "Safety first, little often, double check"</em>
 </p>
-

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
+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`.
-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
 
 ---
 
-## Staff di Agenti
+## Core Team (Agenti Principali)
 
-Configurazioni dettagliate in `.opencode/agents/`:
+### @product-manager
+**Il Garante del Valore**
 
-| Agente | Ruolo | Focus |
+Assicura che ogni feature contribuisca alla UVP (Unique Value Proposition) e all'Activation Rate.
-|--------|-------|-------|
+
-| `@tech-lead` | L'Architetto | Validazione specifiche, architettura |
+**Responsabilità:**
-| `@product-manager` | Il Garante del Valore | PRD, roadmap, priorità |
+- Monitorare il file `docs/prd.md`
-| `@python-developer` | Il Costruttore TDD | Implementazione Python (PEP8) |
+- Identificare ed eliminare le "vanity features"
-| `@bash-expert` | Lo Specialista Ingestion | Script Bash (low footprint) |
+- Gestire la roadmap degli Sprint
-| `@security-auditor` | Il Guardiano | Vulnerabilità, protezione dati |
+- Definire priorità e scope dei task
-| `@qa-engineer` | Il Tester | Test suite, copertura, regressioni |
+
-| `@documentation-agent` | Il Cronista | Changelog, docs, commit messages |
+**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/
+.opencode/agents/
-├── agents/              # Configurazioni agenti individuali
+├── tech-lead.md
-│   ├── tech-lead.md
+├── product-manager.md
-│   ├── product-manager.md
+├── python-developer.md
-│   ├── python-developer.md
+├── bash-expert.md
-│   ├── bash-expert.md
+├── security-auditor.md
-│   ├── security-auditor.md
+├── qa-engineer.md
-│   ├── qa-engineer.md
+├── documentation-agent.md
-│   └── documentation-agent.md
+├── n8n_specialist_agent.md
-└── skills/              # Playbook condivisi
+└── context_auditor_agent.md
-    ├── TDD_Python_Specialist/
-    └── Git_and_Changelog/
 ```
 
 ---
 
-## 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)
+- **Safety first**: Verifica permessi e impatti prima di agire
-- **Git_and_Changelog/**: Conventional commits, Common Changelog
+- **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.*

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