@antoneeo/agentic-sdlc-skill 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -1,10 +1,30 @@
 # Changelog - Agentic SDLC Skill
 
-Tutte le modifiche significative a questa skill saranno documentate in questo file.
-
-## [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.
+Tutte le modifiche significative a questa skill saranno documentate in questo file.
+
+## [1.5.0] - 2026-06-13
+### Added
+- Introdotta la Regola Zero di triage (`L1`, `L2`, `L3`, `Spike`) per rendere il processo proporzionale al rischio.
+- Aggiunta simbiosi esplicita con devPNT: in Hybrid la `M-VISION` guida la milestone, il Master Plan resta roadmap strategica e l'Action Plan governa l'esecuzione tattica.
+- Aggiunti support file dentro la skill runtime: `templates.md`, `ENFORCEMENT.md`, `scripts/sdlc_check.py`.
+- `agentic-sdlc-install-skill` ora installa la skill nativa anche in `~/.gemini/skills/agentic-sdlc/`.
+- Aggiunto validatore meccanico opzionale per frontmatter ANALYSIS, Vision state, indice feature e audit stale.
+
+### Changed
+- Il nome pubblico resta `agentic-sdlc`; la proposta v2 e' stata integrata come evoluzione, non come skill parallela.
+- Aggiornati `agentic-sdlc-init`, template, protocolli generati, README e metadata.
+- La modalita Standalone resta completa; devPNT e' un livello di governance superiore, non un prerequisito.
+
+## [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

package/README.md

@@ -1,84 +1,81 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
-
-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.
-
-## Installation
-
-### Via npm (recommended - installs for all detected CLIs)
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill
-```
-
-The `postinstall` script automatically detects installed CLIs and configures each one:
-
-- **Claude Code**: copies the skill to `~/.claude/skills/agentic-sdlc/`. Restart Claude Code; invoke it through the `Skill` tool as `agentic-sdlc`, or let it trigger automatically from SDLC/audit prompts.
-- **Gemini CLI**: suggests `gemini extensions install` (see below).
-- **Codex AI**: copies the skill to `$CODEX_HOME/skills/agentic-sdlc/` or `~/.codex/skills/agentic-sdlc/`. Restart Codex to load it.
-
-`npm uninstall -g @antoneeo/agentic-sdlc-skill` also removes the skills from `~/.claude/skills/agentic-sdlc/` and `~/.codex/skills/agentic-sdlc/`.
-
-#### Troubleshooting — skill not visible in Claude Code after install
-
-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).
-
-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
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-agentic-sdlc-install-skill
-```
-
-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
-npm uninstall -g @antoneeo/agentic-sdlc-skill
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-```
-
-### 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.
-
-To install this extension, open a terminal in the folder that contains this README and run:
-
-```bash
-gemini extensions install .
-```
-
-*Note: If you are in a different folder, replace `.` with the full path to the skill folder.*
-
-## Global Availability
-Once installation is complete, the skill is **globally available**. You can close this folder and move to **any other project** on your PC: Gemini CLI will automatically recognize the commands and workflow of the `agentic-sdlc` skill.
-
-## Getting Started
-
-After installation, start Gemini CLI and verify that the skill is available:
-
-1. **List available skills:**
-   ```bash
-   /skills list all
-   ```
-2. **Activate the skill:**
-   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.
-
----
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo))
-(c) 2026 Antonio Pinto. All rights reserved.
+# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
+
+`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+
+## Key Features
+
+- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
+- **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
+- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer.
+- **Installed support files**: Claude, Codex, and Gemini receive the full skill folder, including `templates.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
+
+## Installation
+
+### Via npm
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
+```
+
+The installer copies `skills/agentic-sdlc-skill/` recursively into native skill locations:
+
+- Claude Code: `~/.claude/skills/agentic-sdlc/`
+- Codex: `~/.codex/skills/agentic-sdlc/`
+- Gemini CLI: `~/.gemini/skills/agentic-sdlc/`
+
+Restart the relevant agent, or reload skills where the CLI supports it.
+
+The global package also exposes:
+
+```bash
+agentic-sdlc-init
+```
+
+Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+## Runtime Shape
+
+The actual runtime skill is the folder:
+
+```text
+skills/agentic-sdlc-skill/
+├── SKILL.md
+├── templates.md
+├── ENFORCEMENT.md
+└── scripts/
+    └── sdlc_check.py
+```
+
+`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
+
+## Standalone vs Hybrid
+
+Standalone:
+
+- `ai_docs/` is the source of truth.
+- Vision, analysis, audit, handoff, test strategy, and feature history are maintained locally.
+
+Hybrid/devPNT:
+
+- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
+- `ai_docs/` remains useful as readable context, fallback, handoff, or shadow copy.
+- Divergence between user request, local Vision, and devPNT `M-VISION` must be surfaced before implementation.
+
+## Gemini Extension Alternative
+
+You can still install this folder as a Gemini extension:
+
+```bash
+gemini extensions install .
+```
+
+For native Gemini Agent Skills, the npm installer now copies the skill folder into `~/.gemini/skills/agentic-sdlc/`.
+
+## Created By
+
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
+
+(c) 2026 Antonio Pinto. All rights reserved.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.3.1",
-  "description": "Protocollo SDLC Documentation-First per Gemini CLI.",
+  "version": "1.5.0",
+  "description": "Protocollo SDLC Documentation-First con triage, Vision governance e integrazione opzionale devPNT.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.3.1",
-  "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.",
+  "version": "1.5.0",
+  "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex con triage, Vision governance, support file installati e integrazione opzionale devPNT.",
   "keywords": [
     "claude-code",
     "claude-skill",
@@ -25,7 +25,10 @@
     "preuninstall": "node scripts/preuninstall.js"
   },
   "files": [
-    "skills",
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
     "gemini-extension.json",
     "references",
     "README.md",

package/references/analysis_template.md

@@ -1,19 +1,44 @@
-# Analisi della Feature: [Nome Feature]
-
-## Obiettivo
-- Cosa si vuole ottenere?
-- Quali problemi risolve?
-
-## Impatto
-- Modifiche ai file esistenti?
-- Impatti sulle performance?
-- Nuove dipendenze?
-
-## Piano d'Azione
-1. [ ] Sviluppo...
-2. [ ] Test...
-
-## Strategia di Test
-- Test unitari (AAA Pattern)
-- Test d'integrazione
-- Esempi di input e output attesi
+---
+id: F-XXX
+feature: [Nome Feature]
+stato: PLANNED
+livello: L3
+data_inizio: YYYY-MM-DD
+data_fine:
+---
+# Analisi della Feature: [Nome Feature]
+
+## Obiettivo
+- Cosa si vuole ottenere?
+- Quale problema risolve?
+
+## Vision della Feature
+- Documento guida: `ai_docs/vision/project_vision.md` o `ai_docs/vision/features/VISION_[nome_feature].md`.
+- Stato della Vision guida: DRAFT oppure APPROVED.
+- Beneficio atteso.
+- Non-obiettivi / fuori scope.
+- Segnali di successo.
+
+## Impatto
+- File o moduli coinvolti.
+- API, contratti o formati dati impattati.
+- Performance, migrazioni o nuove dipendenze.
+
+## Sicurezza e Threat Model
+- Superfici toccate: input esterni, authN/authZ, crittografia, rete, dati personali, filesystem.
+- Minacce principali.
+- Mitigazioni.
+- Se non c'e' impatto di sicurezza, motivare perche.
+
+## Piano d'Azione
+- [ ] Sviluppo
+- [ ] Test
+- [ ] Chiusura documentale
+
+## Strategia di Test
+- Unit test AAA.
+- Test di integrazione o smoke check.
+- Verifica alternativa se i test automatici non sono eseguibili.
+
+## Diario / Stato Corrente
+- YYYY-MM-DD: Stato iniziale e prossimo passo.

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,21 @@
+# Vision della Feature: [Nome Feature]
+
+Usare un file separato solo quando la feature attraversa piu ANALYSIS o piu milestone. Altrimenti tenere la Vision della Feature dentro `ANALYSIS_[feature].md`.
+
+## 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/features_history_template.md

@@ -1,6 +1,5 @@
-# Storico delle Feature
-
-| ID | Nome Feature | Stato | Data Inizio | Data Fine | Doc. Analisi | Note |
-|:---|:-------------|:------|:------------|:----------|:-------------|:-----|
-| [ID] | Nome | [PLANNED] | YYYY-MM-DD | - | [ANALYSIS_nome.md] | In attesa |
-| [ID] | Altra | [COMPLETED] | YYYY-MM-DD | YYYY-MM-DD | [ANALYSIS_altra.md] | Conclusa |
+<!-- GENERATED by agentic-sdlc - update manually only if the project does not use sdlc_check.py index. -->
+# Feature History
+
+| ID | Feature Name | Level | Status | Start Date | End Date | Analysis Doc |
+|:---|:---|:---|:---|:---|:---|:---|

package/references/principles_template.md

@@ -0,0 +1,13 @@
+# Principi di Vision
+Stato: DRAFT
+
+I principi in questo file guidano trade-off, scope e decisioni tecniche quando piu 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 perche devia dalla Vision].

package/references/project_vision_template.md

@@ -0,0 +1,26 @@
+# Vision del Progetto
+Stato: DRAFT
+
+## North Star
+- Qual e' l'obiettivo finale che il progetto deve preservare nel tempo?
+
+## Problema Centrale
+- Quale problema reale risolve il progetto?
+
+## Utenti Target
+- Chi sono 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 e' esplicitamente fuori scope]
+
+## Segnali di Successo
+- [Indicatore qualitativo o quantitativo]
+- [Comportamento utente o metrica attesa]

package/references/roadmap_template.md

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