@antoneeo/agentic-sdlc-skill 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.0.9] - 2026-05-10
+### Added
+- New **Smart Discovery** system during project initialization.
+- Official support for **Codex AI** via automatic `.codex/hooks.json` injection.
+- Support for **Cursor** and **Windsurf** via `.cursorrules`.
+- Binary command `agentic-sdlc-init` for use via `npx`.
+- `postinstall` script for global AI CLI detection (Claude, Gemini, Codex).
+- Full English localization for all user-facing messages and scripts.
+
+### Changed
+- Updated `init.js` to support the new `ai_docs/` directory structure defined in v1.0.8.
+
+## [1.0.8] - 2026-05-10
+### Aggiunto
+- Skill evoluta in "Hybrid Edition": integrazione opzionale con **devPNT** (server MCP) per governance avanzata tramite database e piani gerarchici.
+- Fase di Discovery per il rilevamento automatico dell'ambiente (Standalone vs Hybrid).
+- Supporto per ADR (Architecture Decision Records) e Knowledge Layer (KL) nella fase di chiusura.
+
+### Modificato
+- Riorganizzazione dei percorsi di documentazione (`ai_docs/strategic/`, `ai_docs/audit/`, `ai_docs/solutions/`).
+- Aggiornata la documentazione funzionale (`architecture_overview.md`, `external_interfaces.md`) con definizioni più precise.
+
 ## [1.0.7] - 2026-05-10
 ### Modificato
 - Aggiornata l'attribuzione dell'autore (Antonio Pinto) e il copyright in tutti i file (`package.json`, `README.md`, `SKILL.md`).

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Protocollo SDLC Documentation-First per Gemini CLI.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Protocollo SDLC Documentation-First per Gemini CLI. Gestisce audit, analisi, sviluppo e chiusura feature con documentazione sincronizzata.",
   "keywords": [
     "gemini-cli",
@@ -14,6 +14,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "agentic-sdlc-init": "scripts/init.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
   "files": [
     "skills",
     "gemini-extension.json",

package/scripts/init.js

@@ -1,93 +1,147 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
 
 const cwd = process.cwd();
 
-// 1. Definizione dei percorsi
+// Helper for command checking
+function checkCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// 1. Path definitions
 const directories = [
-  path.join(cwd, 'docs'),
-  path.join(cwd, 'docs', 'solutions')
+  path.join(cwd, 'ai_docs'),
+  path.join(cwd, 'ai_docs', 'strategic'),
+  path.join(cwd, 'ai_docs', 'audit'),
+  path.join(cwd, 'ai_docs', 'solutions'),
+  path.join(cwd, '.codex')
 ];
 
 const files = {
-  architecture: path.join(cwd, 'docs', 'architecture.md'),
-  existingFeatures: path.join(cwd, 'docs', 'existing_features.md'),
-  featuresHistory: path.join(cwd, 'docs', 'features_history.md'),
+  architecture: path.join(cwd, 'ai_docs', 'strategic', 'architecture.md'),
+  existingFeatures: path.join(cwd, 'ai_docs', 'strategic', 'existing_features.md'),
+  featuresHistory: path.join(cwd, 'ai_docs', 'strategic', 'features_history.md'),
+  auditPlan: path.join(cwd, 'ai_docs', 'audit', 'audit_plan.md'),
+  handoff: path.join(cwd, 'ai_docs', 'audit', 'handoff.md'),
   claudeConfig: path.join(cwd, 'CLAUDE.md'),
-  geminiConfig: path.join(cwd, 'GEMINI.md')
+  geminiConfig: path.join(cwd, 'GEMINI.md'),
+  codexHooks: path.join(cwd, '.codex', 'hooks.json'),
+  cursorRules: path.join(cwd, '.cursorrules')
 };
 
-// 2. Il contenuto del Protocollo (System Prompt)
-const protocolContent = `# Protocollo Operativo "Agentic SDLC"
-
-Sei un ingegnere del software senior che segue rigorosamente un processo "Documentation-First". Non implementare MAI codice senza aver completato i passaggi documentali precedenti. Utilizza i tool a tua disposizione (lettura file, scrittura file, esecuzione comandi) per rispettare le seguenti fasi.
-
-## 1. Fase di Audit e Allineamento
-Prima di rispondere a qualsiasi richiesta operativa:
-- Controlla l'esistenza della cartella \`/docs\`.
-- Se \`/docs\` non esiste o mancano i documenti fondamentali, creali analizzando il codice sorgente:
-    1. \`docs/architecture.md\`: Deve contenere Stack Tecnologico, Struttura delle Directory e Pattern architetturali principali.
-    2. \`docs/existing_features.md\`: Elenco puntato delle funzionalità già presenti.
-    3. \`docs/features_history.md\`: Deve essere aggiornato rigorosamente con questo schema:
-       | ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |
-
-## 2. Fase di Analisi della Richiesta
-Per ogni nuova feature:
-- Crea \`docs/solutions/ANALYSIS_[nome_feature].md\` (Obiettivo, Impatto, Piano, Strategia Test).
-- Aggiungi una riga in \`docs/features_history.md\` con stato \`[PLANNED]\`.
-
-## 3. Fase di Sviluppo e Test
-Solo dopo la Fase 2:
-1. Aggiorna lo stato a \`[IN_PROGRESS]\`.
-2. Implementa il codice.
-3. **Obbligatorio:** Scrivi i test automatici (pattern AAA).
-4. Esegui i test. Se falliscono, correggi e riesegui finché Exit Code non è 0.
-
-## 4. Fase di Chiusura
-A completamento:
-- Aggiorna \`architecture.md\` e \`existing_features.md\` se necessario.
-- Aggiorna \`docs/features_history.md\` impostando lo stato a \`[COMPLETED]\`.
+// 2. Operational Protocol (System Prompt)
+const protocolContent = `# "Agentic SDLC" Operational Protocol
+
+You are a senior software engineer strictly following a "Documentation-First" process. NEVER implement code without completing the preceding documentation steps. Use your tools (file read/write, shell execution) to adhere to the following phases.
+
+## 1. Audit and Alignment Phase
+Before responding to any operational request:
+- Check for the existence of the \`ai_docs/\` folder.
+- If \`ai_docs/\` is missing or essential documents are absent, create them by analyzing the source code:
+    1. \`ai_docs/strategic/architecture.md\`: Tech Stack, Directory Structure, Architecture Patterns.
+    2. \`ai_docs/strategic/existing_features.md\`: List of current features.
+    3. \`ai_docs/strategic/features_history.md\`: Feature history table (ID, Name, Status, Dates).
+    4. \`ai_docs/audit/audit_plan.md\`: Codebase analysis plan in batches.
+
+## 2. Request Analysis Phase
+For every new feature request:
+- Create \`ai_docs/solutions/ANALYSIS_[feature_name].md\` (Objective, Impact, Action Plan, Test Strategy).
+- Add a entry in \`features_history.md\` with status \`[PLANNED]\`.
+
+## 3. Development and Testing Phase
+Only after Phase 2 is complete:
+1. Update feature status to \`[IN_PROGRESS]\`.
+2. Implement code surgically following the plan.
+3. **Mandatory:** Write automated tests following the **AAA (Arrange, Act, Assert)** pattern.
+4. Execute tests. If they fail, fix and re-run until Exit Code is 0.
+
+## 4. Closing Phase
+Upon feature completion:
+- Update \`architecture.md\` and \`existing_features.md\` if necessary.
+- Update \`features_history.md\` setting status to \`[COMPLETED]\`.
 `;
 
-// Contenuto per l'inizializzazione della tabella
-const historyBoilerplate = `# Storico Features
+const codexHooksContent = JSON.stringify({
+  hooks: {
+    SessionStart: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: `echo '${protocolContent.replace(/'/g, "'\\''")}'`
+          }
+        ]
+      }
+    ]
+  }
+}, null, 2);
+
+const historyBoilerplate = `# Feature History
 
-| ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |
+| ID | Feature Name | Status | Start Date | End Date | Analysis Doc | Notes |
 |:---|:---|:---|:---|:---|:---|:---|
-| 000 | Init Progetto | [COMPLETED] | - | - | - | Inizializzazione automatica |
+| 000 | Project Init | [COMPLETED] | - | - | - | Automatic initialization |
 `;
 
-console.log('🚀 Inizializzazione del workflow Agentic SDLC...');
+console.log('🚀 Initializing Agentic SDLC workflow (Discovery Mode)...');
 
-// 3. Creazione delle cartelle
+// 3. Directory creation
 directories.forEach(dir => {
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
-    console.log(`📁 Creata directory: ${path.relative(cwd, dir)}`);
+    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
   }
 });
 
-// 4. Scrittura dei file di base se non esistono
+// 4. Basic file writing
 const writeIfNotExists = (filePath, content, description) => {
   if (!fs.existsSync(filePath)) {
     fs.writeFileSync(filePath, content, 'utf8');
-    console.log(`📄 Creato file: ${path.relative(cwd, filePath)} (${description})`);
+    console.log(`📄 Created file: ${path.relative(cwd, filePath)} (${description})`);
+    return true;
   } else {
-    console.log(`⏭️  Ignorato: ${path.relative(cwd, filePath)} esiste già.`);
+    console.log(`⏭️  Skipped: ${path.relative(cwd, filePath)} already exists.`);
+    return false;
   }
 };
 
-writeIfNotExists(files.architecture, '# Architettura del Progetto\n\n- Stack:\n- Pattern:\n', 'Boilerplate Architettura');
-writeIfNotExists(files.existingFeatures, '# Funzionalità Esistenti\n\n- \n', 'Boilerplate Funzionalità');
-writeIfNotExists(files.featuresHistory, historyBoilerplate, 'Tabella Storico');
-
-// 5. Scrittura delle configurazioni per le CLI (Claude e Gemini)
-writeIfNotExists(files.claudeConfig, protocolContent, 'Regole per Claude Code');
-writeIfNotExists(files.geminiConfig, protocolContent, 'Regole per Gemini CLI');
-
-console.log('\n✅ Setup completato con successo!');
-console.log('💡 Istruzioni d\'uso:');
-console.log('   - Claude Code rileverà automaticamente CLAUDE.md al prossimo avvio.');
-console.log('   - Per Gemini CLI, usa il file GEMINI.md come system prompt passandolo col flag appropriato (es: --system-prompt-file GEMINI.md).');
+writeIfNotExists(files.architecture, '# Project Architecture\n\n- Stack:\n- Patterns:\n', 'Architecture Boilerplate');
+writeIfNotExists(files.existingFeatures, '# Existing Features\n\n- \n', 'Features Boilerplate');
+writeIfNotExists(files.featuresHistory, historyBoilerplate, 'History Table');
+writeIfNotExists(files.auditPlan, '# Audit Plan\n\n| Directory/File | Status | Notes |\n|:---|:---|:---|\n| / | [PENDING] | Initial analysis |\n', 'Audit Plan');
+
+// 5. Client Discovery and Configuration
+console.log('\n--- Environment Analysis ---');
+
+if (checkCommand('claude')) {
+  console.log('✅ Claude Code detected.');
+  writeIfNotExists(files.claudeConfig, protocolContent, 'Claude Configuration');
+}
+
+if (checkCommand('gemini')) {
+  console.log('✅ Gemini CLI detected.');
+  writeIfNotExists(files.geminiConfig, protocolContent, 'Gemini Configuration');
+}
+
+if (checkCommand('codex')) {
+  console.log('✅ Codex AI detected.');
+  writeIfNotExists(files.codexHooks, codexHooksContent, 'Codex AI Hooks');
+}
+
+// Cursor/Windsurf (always recommended)
+writeIfNotExists(files.cursorRules, protocolContent, 'Cursor/Windsurf Rules');
+
+console.log('\n✅ Setup completed successfully!');
+console.log('💡 Next steps:');
+console.log('   1. If using Claude Code, start it: it will read CLAUDE.md.');
+console.log('   2. If using Gemini CLI, commands will use GEMINI.md.');
+console.log('   3. If using Codex, session hooks will inject the protocol.');
+console.log('   4. Start analyzing the codebase following ai_docs/audit/audit_plan.md.');

package/scripts/postinstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+
+function checkCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+console.log('\n--- Agentic SDLC Skill Discovery ---');
+
+const agents = [
+  { name: 'Claude Code', cmd: 'claude' },
+  { name: 'Gemini CLI', cmd: 'gemini' },
+  { name: 'Codex AI', cmd: 'codex' }
+];
+
+let detected = false;
+agents.forEach(agent => {
+  if (checkCommand(agent.cmd)) {
+    console.log(`✅ Detected: ${agent.name}`);
+    detected = true;
+  }
+});
+
+if (!detected) {
+  console.log('ℹ️  No specific AI CLI detected globally, but you can still use the skill.');
+}
+
+console.log('\nTo initialize a project with the SDLC protocol, run:');
+console.log('👉 npx agentic-sdlc-init');
+console.log('------------------------------------\n');

package/skills/agentic-sdlc-skill/SKILL.md

@@ -1,63 +1,67 @@
----
-name: agentic-sdlc
-description: Protocollo SDLC "Documentation-First". Utilizzare per gestire lo sviluppo di nuove feature, eseguire l'audit di progetti esistenti e mantenere rigorosamente aggiornata la documentazione tecnica prima, durante e dopo l'implementazione del codice.
-author: Antonio Pinto (https://github.com/Antoneeo)
-copyright: © 2026 Antonio Pinto
----
-
-# Agentic SDLC
-
-Questa skill implementa un workflow rigoroso per lo sviluppo software, assicurando che la documentazione preceda sempre l'implementazione (Documentation-First). Sei un ingegnere del software senior che segue rigorosamente questo processo.
-
-Realizzata da **Antonio Pinto** (https://github.com/Antoneeo).
-
-## Workflow Operativo
-
-### 1. Fase di Audit e Allineamento
-Prima di rispondere a qualsiasi richiesta operativa, verifica lo stato della documentazione del progetto.
-- Controlla la presenza di `ai_docs/handoff.md`. Se esiste, leggilo per riprendere il contesto dell'ultima sessione.
-- Controlla l'esistenza della cartella `/ai_docs`.
-- Se `/ai_docs` non esiste o mancano i documenti fondamentali, non procedere con un'analisi dell'intero progetto in un solo colpo. Esegui invece un'analisi strutturata in step:
-    1. **Mappatura:** Crea un file di tracciamento (es. `ai_docs/audit_plan.md`) elencando le macro-directory e i file chiave da analizzare.
-    2. **Stato dell'Analisi:** Accanto a ogni elemento nel piano, indica lo stato: `[PENDING]`, `[ANALYZED]`, oppure `[SKIPPED]` (con relativa motivazione, es. "file generato", "asset statico").
-    3. **Esecuzione a Lotti (Batching):** Analizza la codebase seguendo l'ordine del file di piano, aggiornando lo stato man mano. Se il progetto è grande, esegui l'analisi a blocchi per evitare di saturare la memoria contestuale, chiedendo conferma all'utente tra un blocco e l'altro se necessario.
-    4. **Creazione Documenti:** Sulla base dei risultati dell'audit, compila i documenti fondamentali rispettando i seguenti formati:
-       - `ai_docs/architecture.md`: Deve seguire questa struttura:
-         - `# Architettura del Progetto`
-         - `## Stack Tecnologico`
-         - `## Struttura delle Directory`
-         - `## Pattern Architetturali`
-       - `ai_docs/existing_features.md`: Deve seguire questa struttura:
-         - `# Funzionalità Esistenti`
-         - Elenco puntato nel formato: `- [ID] **Nome Feature**: Descrizione`
-       - `ai_docs/features_history.md`: Deve essere una tabella Markdown con le seguenti colonne: `| ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |`. Gli stati ammessi sono `[PLANNED]`, `[IN_PROGRESS]`, `[COMPLETED]`.
-
-### 2. Fase di Analisi della Richiesta
-Per ogni nuova feature richiesta dall'utente:
-- Crea `ai_docs/solutions/ANALYSIS_[nome_feature].md`. Il documento deve obbligatoriamente seguire questa struttura:
-  - `# Analisi della Feature: [Nome Feature]`
-  - `## Obiettivo` (Cosa si vuole ottenere e quali problemi risolve)
-  - `## Impatto` (Modifiche ai file esistenti, performance, nuove dipendenze)
-  - `## Piano d'Azione` (Elenco di task con checkbox `[ ]`)
-  - `## Strategia di Test` (Test unitari AAA, test d'integrazione, esempi)
-- Aggiungi la nuova feature in `ai_docs/features_history.md` con stato `[PLANNED]`.
-
-### 3. Fase di Sviluppo e Test
-Solo dopo aver completato la Fase 2:
-1. Aggiorna lo stato della feature in `ai_docs/features_history.md` a `[IN_PROGRESS]`.
-2. Implementa il codice in modo chirurgico seguendo il piano definito. **Importante:** Per ogni file o macro-directory modificata o creata durante lo sviluppo, aggiorna `ai_docs/audit_plan.md` reimpostando (o aggiungendo) il suo stato a `[PENDING]`.
-3. **Obbligatorio:** Scrivi i test automatici seguendo il pattern AAA (Arrange, Act, Assert).
-4. Esegui i test. Se falliscono, correggi il codice e riesegui. **Se i test falliscono per più di 3 volte consecutive, fermati e chiedi istruzioni all'utente.**
-
-### 4. Fase di Chiusura
-A completamento della feature (test passati con Exit Code 0):
-- Rivedi gli elementi contrassegnati come `[PENDING]` in `ai_docs/audit_plan.md` per estrarre eventuali novità strutturali.
-- Aggiorna `architecture.md` e `existing_features.md` sulla base di questa revisione se la feature ha introdotto nuove dipendenze, pattern o capacità.
-- Riporta lo stato dei file appena rivisti in `ai_docs/audit_plan.md` a `[ANALYZED]`.
-- Aggiorna `ai_docs/features_history.md` impostando lo stato a `[COMPLETED]`.
-
-### 5. Gestione delle Sessioni (Handoff)
-Quando viene richiesto di mettere in pausa il lavoro o di chiudere la sessione:
-- Aggiorna (o crea) il file `ai_docs/handoff.md` descrivendo esattamente a che punto ti trovi (es. "Sto lavorando al file X", "L'ultimo test fallito è Y", "Il prossimo passo è Z").
-- Questo file serve per preservare il tuo contesto di ragionamento. Quando avvierai una nuova sessione, la Fase 1 ti chiederà di leggerlo per riprendere il lavoro in modo fluido.
-
+---
+name: agentic-sdlc
+description: Protocollo SDLC "Documentation-First" con integrazione opzionale devPNT. Utilizzare per gestire lo sviluppo di nuove feature, eseguire l'audit di progetti esistenti e mantenere rigorosamente aggiornata la documentazione tecnica prima, durante e dopo l'implementazione del codice.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: © 2026 Antonio Pinto
+---
+
+# Agentic SDLC (Hybrid Edition)
+
+Questa skill implementa un workflow rigoroso per lo sviluppo software, assicurando che la documentazione preceda sempre l'implementazione (Documentation-First). Se rileva la presenza del server MCP **devPNT**, potenzia il workflow utilizzando il database per la governance e i piani gerarchici.
+
+Realizzata da **Antonio Pinto** (https://github.com/Antoneeo).
+
+## Workflow Operativo
+
+### 0. Fase di Discovery (Ambiente)
+Prima di rispondere a qualsiasi richiesta operativa, verifica la disponibilità dei tool `devpnt_*`.
+- **MODALITÀ HYBRID (devPNT presente):** Delega la gestione dei piani (Master/Action) e del versionamento degli artefatti (`D-UC`, `P-TM`, `E-ISP`, `E-TDD`) a devPNT. Usa la cartella `ai_docs/` per salvare le versioni Markdown ("shadow-copy") dei documenti per garantire visibilità e compatibilità.
+- **MODALITÀ STANDALONE (devPNT assente):** Gestisci tutto via filesystem in `ai_docs/`. In caso di progetti complessi, suggerisci l'adozione di devPNT per una governance avanzata.
+
+### 1. Fase di Audit e Allineamento
+Verifica lo stato della documentazione del progetto.
+- Controlla la presenza di `ai_docs/audit/handoff.md`. Se esiste, leggilo per riprendere il contesto dell'ultima sessione.
+- Controlla l'esistenza della cartella `ai_docs/`.
+- Se `ai_docs/` non esiste o mancano i documenti fondamentali, non procedere con un'analisi dell'intero progetto in un solo colpo. Esegui invece un'analisi strutturata in step:
+    1. **Mappatura:** Crea un file di tracciamento (es. `ai_docs/audit/audit_plan.md`) elencando le macro-directory e i file chiave da analizzare. Se in modalità **Hybrid**, puoi usare `devpnt_kl_init_scope` per generare la mappatura iniziale.
+    2. **Stato dell'Analisi:** Accanto a ogni elemento nel piano, indica lo stato: `[PENDING]`, `[ANALYZED]`, oppure `[SKIPPED]` (con relativa motivazione, es. "file generato", "asset statico").
+    3. **Esecuzione a Lotti (Batching):** Analizza la codebase seguendo l'ordine del file di piano, aggiornando lo stato man mano. Se il progetto è grande, esegui l'analisi a blocchi per evitare di saturare la memoria contestuale, chiedendo conferma all'utente tra un blocco e l'altro se necessario.
+    4. **Creazione Documenti:** Sulla base dei risultati dell'audit, compila i documenti fondamentali rispettando i seguenti formati:
+       - `ai_docs/strategic/architecture.md`: Deve seguire questa struttura:
+         - `# Architettura del Progetto`
+         - `## Stack Tecnologico`
+         - `## Struttura delle Directory`
+         - `## Pattern Architetturali`
+       - `ai_docs/strategic/existing_features.md`: Deve seguire questa struttura:
+         - `# Funzionalità Esistenti`
+         - Elenco puntato nel formato: `- [ID] **Nome Feature**: Descrizione`
+       - `ai_docs/strategic/features_history.md`: Deve essere una tabella Markdown con le seguenti colonne: `| ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |`. Gli stati ammessi sono `[PLANNED]`, `[IN_PROGRESS]`, `[COMPLETED]`.
+
+### 2. Fase di Analisi della Richiesta
+Per ogni nuova feature richiesta dall'utente:
+- **Hybrid:** Crea un nodo nel Master Plan e definisci l'Action Plan tramite devPNT. Salva i documenti di design (`D-UC`, `P-TM`, `E-ISP`, `E-TDD`) nel Database e crea contemporaneamente il file Markdown in `ai_docs/solutions/ANALYSIS_[nome_feature].md`.
+- **Standalone:** Crea `ai_docs/solutions/ANALYSIS_[nome_feature].md`. Il documento deve obbligatoriamente seguire questa struttura:
+  - `# Analisi della Feature: [Nome Feature]`
+  - `## Obiettivo` (Cosa si vuole ottenere e quali problemi risolve)
+  - `## Impatto` (Modifiche ai file esistenti, performance, nuove dipendenze)
+  - `## Piano d'Azione` (Elenco di task con checkbox `[ ]`)
+  - `## Strategia di Test` (Test unitari AAA, test d'integrazione, esempi)
+- In entrambe le modalità, aggiungi la nuova feature in `ai_docs/strategic/features_history.md` con stato `[PLANNED]`.
+
+### 3. Fase di Sviluppo e Test
+Solo dopo aver completato la Fase 2:
+1. Aggiorna lo stato della feature in `features_history.md` a `[IN_PROGRESS]`.
+2. Implementa il codice in modo chirurgico seguendo il piano definito. **Importante:** Per ogni file o macro-directory modificata o creata durante lo sviluppo, aggiorna `ai_docs/audit/audit_plan.md` reimpostando (o aggiungendo) il suo stato a `[PENDING]`.
+3. **Obbligatorio:** Scrivi i test automatici seguendo il pattern **AAA (Arrange, Act, Assert)**.
+4. Esegui i test. Se falliscono, correggi il codice e riesegui. **Se i test falliscono per più di 3 volte consecutive, fermati e chiedi istruzioni all'utente.**
+
+### 4. Fase di Chiusura
+A completamento della feature (test passati con Exit Code 0):
+- **Hybrid:** Se la feature ha implicazioni di design, proponi un **ADR** tramite devPNT e aggiorna il Knowledge Layer (KL).
+- **Standalone:** Rivedi gli elementi contrassegnati come `[PENDING]` in `ai_docs/audit/audit_plan.md` per estrarre eventuali novità strutturali. Aggiorna `architecture.md` e `existing_features.md` in `ai_docs/strategic/` se necessario.
+- Riporta lo stato dei file appena rivisti in `ai_docs/audit/audit_plan.md` a `[ANALYZED]`.
+- Aggiorna `features_history.md` impostando lo stato a `[COMPLETED]`.
+
+### 5. Gestione delle Sessioni (Handoff)
+Quando viene richiesto di mettere in pausa il lavoro o di chiudere la sessione:
+- Aggiorna (o crea) il file `ai_docs/audit/handoff.md` descrivendo esattamente a che punto ti trovi (es. "Sto lavorando al file X", "L'ultimo test fallito è Y", "Il prossimo passo è Z"). Questo file serve per preservare il tuo contesto di ragionamento.