From 3a455e48d207fc21041eb204bff5062021fcead7 Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Thu, 2 Apr 2026 18:21:21 +0200 Subject: [PATCH] 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 | 3 + .opencode/agents/context_auditor_agent.md | 18 ++ .opencode/agents/n8n_specialist_agent.md | 18 ++ .../context7_documentation_retrivial/SKILL.md | 19 ++ .../skills/n8n_automation_mastery/SKILL.md | 17 + CHANGELOG.md | 28 +- README.md | 55 +++- docs/1.setup_procedure/agents.md | 298 +++++++++++++++--- docs/specs/ingestion_script.md | 16 +- 9 files changed, 405 insertions(+), 67 deletions(-) create mode 100644 .opencode/agents/context_auditor_agent.md create mode 100644 .opencode/agents/n8n_specialist_agent.md create mode 100644 .opencode/skills/context7_documentation_retrivial/SKILL.md create mode 100644 .opencode/skills/n8n_automation_mastery/SKILL.md diff --git a/.gitignore b/.gitignore index 59b0212..0f33f9c 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,6 @@ htmlcov/ # OS .DS_Store Thumbs.db + +# OpenCode configuration with sensitive data +.opencode/opencode.json diff --git a/.opencode/agents/context_auditor_agent.md b/.opencode/agents/context_auditor_agent.md new file mode 100644 index 0000000..6aa50fc --- /dev/null +++ b/.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. diff --git a/.opencode/agents/n8n_specialist_agent.md b/.opencode/agents/n8n_specialist_agent.md new file mode 100644 index 0000000..9b734ab --- /dev/null +++ b/.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. diff --git a/.opencode/skills/context7_documentation_retrivial/SKILL.md b/.opencode/skills/context7_documentation_retrivial/SKILL.md new file mode 100644 index 0000000..52d7dd1 --- /dev/null +++ b/.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. diff --git a/.opencode/skills/n8n_automation_mastery/SKILL.md b/.opencode/skills/n8n_automation_mastery/SKILL.md new file mode 100644 index 0000000..9fdff08 --- /dev/null +++ b/.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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c3578c..235564c 100644 --- a/CHANGELOG.md +++ b/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 - - Product Manager UVP alignment assessment - - Tech Lead architecture coherence review - - Security Auditor risk analysis - - Sprint 1 review document in `docs/reviews/s` +- feat: Configure MCP servers for enhanced AI capabilities + - sequential-thinking MCP for structured problem solving + - context7 MCP for contextual library documentation retrieval + - n8n MCP for workflow automation integration +- 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: Updated PRD status to reflect Sprint 1 completion -- docs: Updated ingestion script spec status to "Completed" -- docs: Updated Sprint 1 verification report with Project Review reference +- docs: Update README.md with complete project structure + - Add MCP configuration section + - Document all agent configurations + - 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 diff --git a/README.md b/README.md index 26451aa..c996bd0 100644 --- a/README.md +++ b/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 - └── skills/ # Skills TDD e Git + ├── opencode.json # Configurazione MCP servers + ├── 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).

LogWhispererAI - "Safety first, little often, double check"

- diff --git a/docs/1.setup_procedure/agents.md b/docs/1.setup_procedure/agents.md index 559bed5..8e69065 100644 --- 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.* diff --git a/docs/specs/ingestion_script.md b/docs/specs/ingestion_script.md index d6816a6..7655e73 100644 --- 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