From b565895df18a4f43e40e69ff3c77824e610222fc Mon Sep 17 00:00:00 2001
From: Luca Sacchi Ricciardi <luca@lucasacchi.net>
Date: Thu, 2 Apr 2026 16:53:12 +0200
Subject: [PATCH] docs: update AGENTS.md with complete agent rules and workflow

---
 AGENTS.md | 103 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 67 insertions(+), 36 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c1099c5..559bed5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,51 +1,82 @@
-LogWhisperer AI - Agent Rules
+# LogWhisperer AI - Agent Rules
 
-Metodologia di Lavoro
+Regole operative per gli agenti AI che collaborano su questo progetto.
 
-Spec-Driven: Prima di ogni modifica, l'agente deve aggiornare o confermare le specifiche in docs/.
+---
 
-TDD (Test-Driven Development): Non scrivere logica senza un test fallimentare preventivo. Usa pytest.
+## Metodologia di Lavoro
 
-Sacchi Method: Applica sempre "Safety first, little often, double check". Verifica i permessi prima di eseguire comandi bash distruttivi.
+### Spec-Driven
+Prima di ogni modifica, l'agente deve aggiornare o confermare le specifiche in `docs/specs/`.
 
-Git Workflow:
+### TDD (Test-Driven Development)
+Non scrivere logica senza un test fallimentare preventivo. Usa pytest.
 
-Usa Conventional Commits (es. feat:, fix:, docs:, test:).
+### Sacchi Method
+Applica sempre "**Safety first, little often, double check**". Verifica i permessi prima di eseguire comandi bash distruttivi.
 
-Ogni commit deve essere atomico.
+### 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
 
-Aggiorna CHANGELOG.md seguendo lo standard Common Changelog.
+---
 
-Definizione dei Ruoli (Sub-agents)
+## Staff di Agenti
 
-@tech-lead: Responsabile dell'architettura e della validazione delle specifiche (PRD).
+Configurazioni dettagliate in `.opencode/agents/`:
 
-@developer: Scrive il codice Python e lo script Bash seguendo i test.
+| 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 |
 
-@qa-engineer: Scrive ed esegue i test, garantendo la copertura delle feature critiche.
+---
 
+## Workflow Operativo
 
-### 3. Configurazione Tecnica (`opencode.json`)
-Per gestire il progetto con Python e attivare le potenzialità agentiche, configura il file di impostazioni di OpenCode (solitamente in `~/.config/opencode/opencode.json` o localmente se supportato):
-
-Assicurati che i **Tools** siano abilitati per permettere all'agente di usare il terminale nel tuo `venv`.
-
-
-
-### 4. Uso delle Skills (Il potenziamento)
-Per un risultato eccellente, useremo le **Skills**. Le skills sono playbook che OpenCode carica on-demand. Crea una cartella `.opencode/skills/` e aggiungi questi file:
-
-- **python_expert.md**: Istruzioni su come gestire il venv, installare dipendenze con `pip` e seguire il PEP8.
-- **tdd_workflow.md**: Una guida passo-passo che obbliga l'agente a: 
-    1. Creare il test. 
-    2. Eseguire il test (deve fallire). 
-    3. Scrivere il codice minimo. 
-    4. Rieseguire il test (deve passare).
-- **git_standard.md**: Istruzioni rigide su come scrivere i messaggi di commit e aggiornare il changelog.
-
-### 5. Avvio e Operatività
-Ora sei pronto. Avvia OpenCode nella root del progetto:
-
-```bash
-opencode
 ```
+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
+```
+
+---
+
+## Struttura Configurazione
+
+```
+.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/
+```
+
+---
+
+## Skills Disponibili
+
+Skills condivise in `.opencode/skills/`:
+
+- **TDD_Python_Specialist/**: Workflow TDD (RED → GREEN → REFACTOR)
+- **Git_and_Changelog/**: Conventional commits, Common Changelog
+
+---
+
+*Per configurazioni dettagliate, vedere i file in `.opencode/agents/`*