@antoneeo/agentic-sdlc-skill 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog - Agentic SDLC Skill
 
-Tutte le modifiche significative a questa skill saranno documentate in questo file.
+Tutte le modifiche significative a questa skill saranno documentate in questo file.
+
+## [1.4.0] - 2026-06-07
+### Added
+- Introdotta la governance della **Vision** con nuova struttura `ai_docs/vision/` (`project_vision.md`, `roadmap.md`, `principles.md`, `features/`).
+- Aggiunto il **Vision Gate** nel workflow operativo: ogni feature significativa deve essere verificata rispetto a obiettivi, non-obiettivi, benefici attesi e segnali di successo prima dell'analisi tecnica.
+- Aggiunti template Vision in `references/` e sezione `Allineamento alla Vision` nel template di analisi.
+- `agentic-sdlc-init` ora crea i documenti Vision boilerplate nei nuovi progetti.
+
+## [1.3.1] - 2026-05-14
+### Fixed
+- Correzione documentazione (README + CHANGELOG) della sintassi per invocare il bin `agentic-sdlc-install-skill`. La forma `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` documentata in 1.3.0 **non funziona** perché npx non riesce a disambiguare il bin quando il pacchetto ne espone più di uno (errore: `could not determine executable to run`). Sintassi corretta: lanciare `agentic-sdlc-install-skill` direttamente dopo `npm install -g`, oppure usare `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` con `-p` esplicito.
+- Nessuna modifica al codice della skill: il bin di 1.3.0 funziona correttamente, era solo la doc a indicare la sintassi sbagliata.
 
 ## [1.3.0] - 2026-05-14
 ### Added
@@ -9,7 +21,8 @@ Tutte le modifiche significative a questa skill saranno documentate in questo fi
 
 ### Usage
 ```bash
-npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
 ```
 
 ## [1.2.4] - 2026-05-14

package/README.md

@@ -2,11 +2,12 @@
 
 A "Documentation-First" SDLC protocol designed to manage the software development lifecycle rigorously. It natively supports **Claude Code** (skill auto-installed in `~/.claude/skills/`), **Gemini CLI** (extension), and **Codex AI** (skill auto-installed in `~/.codex/skills/`).
 
-## Key Features
-- **Documentation-First**: Requires documentation (`docs/`) to be created or updated before writing code.
-- **Automatic Audit**: Analyzes the existing architecture and features.
-- **Traceable Workflow**: Tracks feature status in `features_history.md`.
-- **Built-In Quality**: Native integration of analysis, development, and testing.
+## Key Features
+- **Documentation-First**: Requires documentation (`ai_docs/`) to be created or updated before writing code.
+- **Vision-Guided Governance**: Adds `ai_docs/vision/` and a Vision Gate so features stay aligned with goals, non-goals, and expected benefits.
+- **Automatic Audit**: Analyzes the existing architecture and features.
+- **Traceable Workflow**: Tracks feature status in `features_history.md`.
+- **Built-In Quality**: Native integration of analysis, development, and testing.
 
 ## Installation
 
@@ -28,13 +29,18 @@ The `postinstall` script automatically detects installed CLIs and configures eac
 
 If after `npm install -g` you do **not** see the line `--- Agentic SDLC Skill Discovery ---` in the npm output, and `~/.claude/skills/agentic-sdlc/` does not exist, the `postinstall` hook was skipped by npm. The most common cause is `ignore-scripts=true` in your npm config (set by some Node installers, corporate IT policies, or security tools).
 
-Run the install explicitly via the dedicated bin command — it does not depend on the `postinstall` hook:
+The package ships an explicit `agentic-sdlc-install-skill` command that does the same work but does **not** depend on the `postinstall` hook. After `npm install -g`, the bin shim is created regardless of `ignore-scripts`, so you can simply run:
 
 ```bash
-npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
 ```
 
-Alternatively, fix the npm config and reinstall:
+You should see the `--- Agentic SDLC Skill Discovery ---` banner and `📦 Installed Claude Code skill at: ...`. Then restart Claude Code (or Codex) and the skill will be available.
+
+> **Note on `npx`**: because the package exposes two bin commands, the shorthand `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` does not work — npx cannot disambiguate. If you prefer npx, use the explicit `-p` form: `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill`.
+
+Alternatively, fix the npm config and reinstall (the `postinstall` hook will then run automatically):
 
 ```bash
 npm config set ignore-scripts false
@@ -42,8 +48,6 @@ npm uninstall -g @antoneeo/agentic-sdlc-skill
 npm install -g @antoneeo/agentic-sdlc-skill@latest
 ```
 
-Then restart Claude Code (or Codex) and the skill will be available.
-
 ### Via Gemini CLI (local alternative)
 
 > **Tip:** Before installing, copy this folder from the USB drive to your computer's hard drive (for example, `C:\tools\agentic-sdlc-skill`). This keeps the skill available even after the USB drive is removed.
@@ -71,10 +75,11 @@ After installation, start Gemini CLI and verify that the skill is available:
    The skill activates automatically when it detects requests related to development, audits, or feature management. You can also invoke it explicitly:
    > "Use the agentic-sdlc skill to analyze this project"
 
-## Project Structure
-- `skills/`: Contains the skill logic (`SKILL.md`).
-- `references/`: Markdown templates for architecture, analysis, and feature history.
-- `gemini-extension.json`: Extension manifest.
+## Project Structure
+- `skills/`: Contains the skill logic (`SKILL.md`).
+- `references/`: Markdown templates for Vision, architecture, analysis, and feature history.
+- `ai_docs/vision/`: Project and feature Vision documents created by the SDLC workflow.
+- `gemini-extension.json`: Extension manifest.
 
 ---
 Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo))

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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.3.0",
+  "version": "1.4.0",
   "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex. Auto-installa le skill native in ~/.claude/skills/ e ~/.codex/skills/. Gestisce audit, analisi, sviluppo e chiusura feature con documentazione sincronizzata.",
   "keywords": [
     "claude-code",

package/references/analysis_template.md

@@ -1,13 +1,19 @@
 # Analisi della Feature: [Nome Feature]
 
-## Obiettivo
-- Cosa si vuole ottenere?
-- Quali problemi risolve?
-
-## Impatto
-- Modifiche ai file esistenti?
-- Impatti sulle performance?
-- Nuove dipendenze?
+## Obiettivo
+- Cosa si vuole ottenere?
+- Quali problemi risolve?
+
+## Allineamento alla Vision
+- Quale documento di Vision guida questa feature? (`ai_docs/vision/project_vision.md` o `ai_docs/vision/features/VISION_[nome_feature].md`)
+- Quale beneficio atteso realizza?
+- Quali non-obiettivi o vincoli di Vision devono essere rispettati?
+- Quali segnali di successo dimostreranno che la feature è coerente con la Vision?
+
+## Impatto
+- Modifiche ai file esistenti?
+- Impatti sulle performance?
+- Nuove dipendenze?
 
 ## Piano d'Azione
 1. [ ] Sviluppo...

package/references/architecture_template.md

@@ -6,10 +6,13 @@
 - **Database:** [es. PostgreSQL]
 - **Strumenti di Test:** [es. Jest, Vitest]
 
-## Struttura delle Directory
-- `src/`: Codice sorgente.
-- `docs/`: Documentazione tecnica.
-- `tests/`: Test automatici.
+## Struttura delle Directory
+- `src/`: Codice sorgente.
+- `ai_docs/vision/`: Vision di progetto, roadmap, principi e mini-vision delle feature.
+- `ai_docs/strategic/`: Architettura, feature esistenti e storico feature.
+- `ai_docs/solutions/`: Analisi e piani delle singole feature.
+- `ai_docs/audit/`: Piano di audit e handoff di sessione.
+- `tests/`: Test automatici.
 
 ## Pattern Architetturali
 - [es. MVC, Clean Architecture, Layered Architecture]

package/references/feature_vision_template.md

@@ -0,0 +1,19 @@
+# Vision della Feature: [Nome Feature]
+
+## Problema
+- Quale problema specifico risolve questa feature?
+
+## Beneficio Atteso
+- Quale risultato utile deve produrre per utenti o stakeholder?
+
+## Utenti o Stakeholder
+- Chi beneficia direttamente o indirettamente della feature?
+
+## Segnali di Successo
+- Come sapremo che la feature ha raggiunto l'obiettivo?
+
+## Non-Obiettivi / Fuori Scope
+- Cosa non deve essere incluso in questa feature?
+
+## Vincoli e Principi Collegati
+- Quali principi di `ai_docs/vision/principles.md` guidano questa feature?

package/references/principles_template.md

@@ -0,0 +1,12 @@
+# Principi di Vision
+
+I principi in questo file guidano trade-off, scope e decisioni tecniche quando più soluzioni sono possibili.
+
+## Principi
+- **[Principio]**: [Descrizione pratica del criterio decisionale].
+
+## Trade-off Preferiti
+- Preferire [A] rispetto a [B] quando [condizione].
+
+## Anti-Pattern Strategici
+- [Comportamento o direzione da evitare perché devia dalla Vision].

package/references/project_vision_template.md

@@ -0,0 +1,25 @@
+# Vision del Progetto
+
+## North Star
+- Qual è l'obiettivo finale che il progetto deve preservare nel tempo?
+
+## Problema Centrale
+- Quale problema reale risolve il progetto?
+
+## Utenti Target
+- Chi sono gli utenti o stakeholder principali?
+
+## Valore Atteso
+- Quale beneficio misurabile o osservabile deve produrre il progetto?
+
+## Obiettivi
+- [Obiettivo 1]
+- [Obiettivo 2]
+
+## Non-Obiettivi
+- [Cosa il progetto non vuole diventare]
+- [Cosa è esplicitamente fuori scope]
+
+## Segnali di Successo
+- [Indicatore qualitativo o quantitativo]
+- [Comportamento utente o metrica attesa]

package/references/roadmap_template.md

@@ -0,0 +1,8 @@
+# Roadmap della Vision
+
+| Milestone | Beneficio Atteso | Priorità | Segnali di Successo | Stato |
+|:---|:---|:---|:---|:---|
+| M1 | [Beneficio] | Alta | [Segnale] | [PLANNED] |
+
+## Note di Direzione
+- Decisioni strategiche o cambi di priorità rilevanti.

package/scripts/init.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const fs = require('fs');
 const path = require('path');
@@ -17,58 +17,110 @@ function checkCommand(cmd) {
 }
 
 // 1. Path definitions
-const directories = [
-  path.join(cwd, 'ai_docs'),
-  path.join(cwd, 'ai_docs', 'strategic'),
-  path.join(cwd, 'ai_docs', 'audit'),
-  path.join(cwd, 'ai_docs', 'solutions')
-];
-
-const files = {
-  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'),
+const directories = [
+  path.join(cwd, 'ai_docs'),
+  path.join(cwd, 'ai_docs', 'vision'),
+  path.join(cwd, 'ai_docs', 'vision', 'features'),
+  path.join(cwd, 'ai_docs', 'strategic'),
+  path.join(cwd, 'ai_docs', 'audit'),
+  path.join(cwd, 'ai_docs', 'solutions')
+];
+
+const files = {
+  projectVision: path.join(cwd, 'ai_docs', 'vision', 'project_vision.md'),
+  roadmap: path.join(cwd, 'ai_docs', 'vision', 'roadmap.md'),
+  principles: path.join(cwd, 'ai_docs', 'vision', 'principles.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'),
-  codexAgents: path.join(cwd, 'AGENTS.md'),
-  cursorRules: path.join(cwd, '.cursorrules')
-};
+  handoff: path.join(cwd, 'ai_docs', 'audit', 'handoff.md'),
+  claudeConfig: path.join(cwd, 'CLAUDE.md'),
+  geminiConfig: path.join(cwd, 'GEMINI.md'),
+  codexAgents: path.join(cwd, 'AGENTS.md'),
+  cursorRules: path.join(cwd, '.cursorrules')
+};
 
 // 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 an entry in \`ai_docs/strategic/features_history.md\` with status \`[PLANNED]\`.
-
-## 3. Development and Testing Phase
-Only after Phase 2 is complete:
-1. Update feature status to \`[IN_PROGRESS]\` in \`ai_docs/strategic/features_history.md\`.
-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 \`ai_docs/strategic/architecture.md\` and \`ai_docs/strategic/existing_features.md\` if necessary.
-- Update \`ai_docs/strategic/features_history.md\` setting status to \`[COMPLETED]\`.
-`;
-
-const historyBoilerplate = `# Feature History
+const protocolContent = `# "Agentic SDLC" Operational Protocol
+
+You are a senior software engineer strictly following a "Documentation-First" and "Vision-Guided" 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/\` and \`ai_docs/vision/\` folders.
+- If \`ai_docs/\` is missing or essential documents are absent, create them by analyzing the source code:
+    1. \`ai_docs/vision/project_vision.md\`: North Star, target users, goals, non-goals, success signals.
+    2. \`ai_docs/vision/roadmap.md\`: Milestones, expected benefits, priorities, success signals.
+    3. \`ai_docs/vision/principles.md\`: Stable decision principles and strategic anti-patterns.
+    4. \`ai_docs/strategic/architecture.md\`: Tech Stack, Directory Structure, Architecture Patterns.
+    5. \`ai_docs/strategic/existing_features.md\`: List of current features.
+    6. \`ai_docs/strategic/features_history.md\`: Feature history table (ID, Name, Status, Dates).
+    7. \`ai_docs/audit/audit_plan.md\`: Codebase analysis plan in batches.
+- Never treat architecture or feature history as a substitute for Vision.
+
+## 2. Vision Gate
+For every new feature request or significant behavior change:
+- Read \`ai_docs/vision/project_vision.md\`, \`ai_docs/vision/roadmap.md\`, and \`ai_docs/vision/principles.md\`.
+- If Vision documents are missing, empty, or ambiguous, create or update them before technical analysis.
+- For significant features, create \`ai_docs/vision/features/VISION_[feature_name].md\` covering Problem, Expected Benefit, Users/Stakeholders, Success Signals, Non-Goals, and linked principles.
+- If the request conflicts with Vision, stop and surface the conflict instead of implementing silently.
+
+## 3. Request Analysis Phase
+For every new feature request:
+- Create \`ai_docs/solutions/ANALYSIS_[feature_name].md\` (Objective, Vision Alignment, Impact, Action Plan, Test Strategy).
+- Add an entry in \`ai_docs/strategic/features_history.md\` with status \`[PLANNED]\`.
+
+## 4. Development and Testing Phase
+Only after Phases 2 and 3 are complete:
+1. Update feature status to \`[IN_PROGRESS]\` in \`ai_docs/strategic/features_history.md\`.
+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.
+
+## 5. Closing Phase
+Upon feature completion:
+- Verify the delivered result against \`ai_docs/vision/project_vision.md\` and the feature Vision document, including non-goals.
+- Update \`ai_docs/strategic/architecture.md\` and \`ai_docs/strategic/existing_features.md\` if necessary.
+- Update \`ai_docs/vision/\` documents if goals, non-goals, roadmap, expected benefits, or success signals changed.
+- Update \`ai_docs/strategic/features_history.md\` setting status to \`[COMPLETED]\`.
+`;
+
+const projectVisionBoilerplate = `# Project Vision
+
+## North Star
+- TBD
+
+## Target Users
+- TBD
+
+## Goals
+- TBD
+
+## Non-Goals
+- TBD
+
+## Success Signals
+- TBD
+`;
+
+const roadmapBoilerplate = `# Vision Roadmap
+
+| Milestone | Expected Benefit | Priority | Success Signal | Status |
+|:---|:---|:---|:---|:---|
+| M1 | - | - | - | [PLANNED] |
+`;
+
+const principlesBoilerplate = `# Vision Principles
+
+## Principles
+- TBD
+
+## Strategic Anti-Patterns
+- TBD
+`;
+
+const historyBoilerplate = `# Feature History
 
 | ID | Feature Name | Status | Start Date | End Date | Analysis Doc | Notes |
 |:---|:---|:---|:---|:---|:---|:---|
@@ -95,11 +147,14 @@ const writeIfNotExists = (filePath, content, description) => {
     console.log(`⏭️  Skipped: ${path.relative(cwd, filePath)} already exists.`);
     return false;
   }
-};
-
-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.projectVision, projectVisionBoilerplate, 'Project Vision Boilerplate');
+writeIfNotExists(files.roadmap, roadmapBoilerplate, 'Vision Roadmap Boilerplate');
+writeIfNotExists(files.principles, principlesBoilerplate, 'Vision Principles Boilerplate');
+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
@@ -115,17 +170,17 @@ if (checkCommand('gemini')) {
   writeIfNotExists(files.geminiConfig, protocolContent, 'Gemini Configuration');
 }
 
-if (checkCommand('codex')) {
-  console.log('✅ Codex AI detected.');
-  writeIfNotExists(files.codexAgents, protocolContent, 'Codex AGENTS.md');
-}
+if (checkCommand('codex')) {
+  console.log('✅ Codex AI detected.');
+  writeIfNotExists(files.codexAgents, protocolContent, 'Codex AGENTS.md');
+}
 
 // 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, restart/open the project so it reads AGENTS.md.');
-console.log('   4. Start analyzing the codebase following ai_docs/audit/audit_plan.md.');
+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, restart/open the project so it reads AGENTS.md.');
+console.log('   4. Start analyzing the codebase following ai_docs/audit/audit_plan.md.');

package/scripts/postinstall.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { execSync } = require('child_process');
 const fs = require('fs');

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

@@ -17,64 +17,85 @@ Privilegia qualità e comprensione rispetto alla velocità apparente.
 
 - **Comprendi prima di agire:** non modificare codice senza aver capito il motivo; nei bug cerca la root cause, non workaround.
 - **Mantieni coerenza architetturale:** rispetta layer, responsabilità, naming, pattern e convenzioni esistenti.
-- **Applica DRY e semplicità:** non duplicare logica o conoscenza; crea astrazioni solo se riducono complessità reale.
-- **Preserva la qualità:** ogni modifica deve mantenere o migliorare stabilità, testabilità e manutenibilità.
-- **Verifica tecnicamente:** chiudi ogni task implementativo con test/lint/smoke test, o spiega perché non eseguiti.
-- **Mantieni memoria utile:** documenta decisioni e stato operativo rilevanti, non rumore.
+- **Applica DRY e semplicità:** non duplicare logica o conoscenza; crea astrazioni solo se riducono complessità reale.
+- **Preserva la qualità:** ogni modifica deve mantenere o migliorare stabilità, testabilità e manutenibilità.
+- **Verifica tecnicamente:** chiudi ogni task implementativo con test/lint/smoke test, o spiega perché non eseguiti.
+- **Mantieni memoria utile:** documenta decisioni e stato operativo rilevanti, non rumore.
+- **Proteggi la Vision:** ogni decisione deve restare allineata a obiettivo finale, benefici attesi, utenti target e non-obiettivi dichiarati.
 
 Se una patch sembra facile ma non capisci perché il codice attuale è fatto così, indaga prima di modificarlo.
 
 ## 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.
+### 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à. Mantieni sempre la Vision leggibile in `ai_docs/vision/`.
+- **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:
+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`
+    4. **Creazione Documenti:** Sulla base dei risultati dell'audit, compila i documenti fondamentali rispettando i seguenti formati:
+       - `ai_docs/vision/project_vision.md`: Deve descrivere North Star, utenti target, problema centrale, obiettivi, non-obiettivi e segnali di successo.
+       - `ai_docs/vision/roadmap.md`: Deve descrivere milestone, benefici attesi, priorità e indicatori di avanzamento.
+       - `ai_docs/vision/principles.md`: Deve elencare i principi decisionali stabili che guidano trade-off e scope.
+       - `ai_docs/vision/features/`: Deve contenere una mini-vision per ogni feature significativa.
+       - `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.
+       - `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. Vision Gate
+Prima di analizzare tecnicamente una nuova feature, modifica comportamentale o refactor significativo, ripristina il contesto di Vision:
+- Leggi `ai_docs/vision/project_vision.md`, `ai_docs/vision/roadmap.md` e `ai_docs/vision/principles.md`.
+- Se uno di questi documenti manca, è vuoto o non chiarisce l'obiettivo finale, crealo o aggiornalo prima di procedere.
+- Per ogni feature significativa, crea o aggiorna `ai_docs/vision/features/VISION_[nome_feature].md` con:
+  - `## Problema`
+  - `## Beneficio Atteso`
+  - `## Utenti o Stakeholder`
+  - `## Segnali di Successo`
+  - `## Non-Obiettivi / Fuori Scope`
+  - `## Vincoli e Principi Collegati`
+- Se la richiesta dell'utente confligge con Vision, non implementare in silenzio: esplicita il conflitto e proponi una scelta (aggiornare la Vision oppure modificare/rifiutare la richiesta).
+
+### 3. 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)
+  - `## Allineamento alla Vision` (Quale Vision documenta il beneficio, quali non-obiettivi rispettare)
+  - `## 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]`.
+
+### 4. Fase di Sviluppo e Test
+Solo dopo aver completato le Fasi 2 e 3:
+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.**
+
+### 5. Fase di Chiusura
+A completamento della feature (test passati con Exit Code 0):
+- Verifica che il risultato consegnato rispetti `project_vision.md`, l'eventuale `VISION_[nome_feature].md` e i non-obiettivi dichiarati.
+- **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.
+- Aggiorna i documenti in `ai_docs/vision/` se l'implementazione ha modificato obiettivi, non-obiettivi, milestone, benefici attesi o segnali di successo.
+- 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]`.
+
+### 6. 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.