@antoneeo/agentic-sdlc-skill 1.4.0 → 1.5.0

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

@@ -0,0 +1,55 @@
+# Enforcement meccanico (opzionale, consigliato per i team)
+
+Le regole a livello di prompt dipendono dalla disciplina del modello e degradano con contesti lunghi, compaction e istruzioni concorrenti. Tre livelli di garanzia crescente:
+
+## 1. Validazione interattiva (default, nessun setup)
+
+L'agente esegue alla chiusura (Fase 5) un solo gate:
+
+```
+python "<dir_skill>/scripts/sdlc_check.py" check
+```
+
+(`check` = validate + stale in un comando.) Exit code ≠ 0 ⇒ la feature non si dichiara chiusa. È il livello minimo previsto dalla skill.
+
+## 2. Check in CI (consigliato per i team)
+
+Copia `scripts/sdlc_check.py` nel repository (es. `tools/sdlc_check.py`) e aggiungi alla pipeline:
+
+```
+python tools/sdlc_check.py validate
+```
+
+Effetto: indice non rigenerato, frontmatter invalidi, sezione sicurezza mancante o stati incoerenti **bloccano la pipeline** invece di affidarsi alla memoria dell'agente. Funziona perché i documenti viaggiano nello stesso PR del codice (regola di Fase 5).
+
+Nota: la copia nel repo è quella autoritativa per la CI; aggiornala quando aggiorni la skill.
+
+## 3. Hook PreToolUse (gate sulle scritture)
+
+Blocca Edit/Write su percorsi protetti quando nessuna `ANALYSIS_*.md` è `IN_PROGRESS`. In `.claude/settings.json` del progetto:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<utente>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" gate --hook --protected \"src/auth;src/crypto\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Semantica: exit code 2 + messaggio su stderr ⇒ la scrittura viene bloccata e il messaggio è mostrato all'agente, che deve creare l'ANALYSIS (Fase 3) prima di riprovare.
+
+**Avvertenze d'uso:**
+- Il gate è volutamente grossolano: applicato a tutto `src/` bloccherebbe anche i task L1/L2 legittimi previsti dal Triage. Usalo **solo su directory security-critical** (`--protected "src/auth;src/crypto"`), dove "mai senza analisi" è la policy desiderata.
+- I percorsi in `--protected` sono prefissi relativi alla radice del progetto, separati da `;`.
+- `ai_docs/`, `tests/` e `test/` sono sempre esclusi dal blocco.
+- L'hook assume che la working directory sia la radice del progetto (comportamento standard degli hook di Claude Code).

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

@@ -1,101 +1,141 @@
----
-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).
-
-## Valori Tecnici
-
-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.
-- **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à. 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:
-    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/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]`.
+---
+name: agentic-sdlc
+description: Protocollo SDLC Documentation-First con triage proporzionale, Vision come guida, modalita Standalone completa e simbiosi opzionale con devPNT. Usare per feature, bug significativi, refactor, audit e manutenzione documentata.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+
+# Agentic SDLC
+
+Questa skill guida lo sviluppo software con un processo Documentation-First proporzionale al rischio. Deve funzionare pienamente anche senza devPNT. Quando devPNT e' disponibile e configurato per il progetto corrente, la skill lavora in simbiosi con la sua governance: M-VISION, Master Plan, Action Plan e artefatti versionati diventano il quadro autorevole per milestone e implementazione.
+
+File di supporto nella directory della skill:
+- `templates.md`: template per Vision, ANALYSIS, Spike, audit plan e handoff.
+- `scripts/sdlc_check.py`: validatore meccanico per `ai_docs/` (`check`, `validate`, `index`, `stale`, `mark`, `gate`).
+- `ENFORCEMENT.md`: setup opzionale per CI e hook.
+
+Leggi questi file solo quando servono. `SKILL.md` e' il contratto operativo; i support file sono risorse progressive.
+
+## Valori Tecnici
+
+- **Comprendi prima di agire:** non modificare codice senza capire root cause, vincoli e forma attuale.
+- **Mantieni coerenza architetturale:** rispetta layer, responsabilita, naming, pattern e convenzioni esistenti.
+- **Applica DRY e semplicita:** non duplicare logica o conoscenza; astrai solo se riduce complessita reale.
+- **Preserva qualita:** ogni modifica deve mantenere o migliorare stabilita, testabilita e manutenibilita.
+- **Verifica tecnicamente:** chiudi lavoro implementativo con test, lint, smoke check o motivo esplicito.
+- **Mantieni memoria utile:** documenta decisioni e stato operativo rilevanti, non testo riempitivo.
+- **Proteggi la Vision:** ogni decisione deve restare allineata a benefici attesi, utenti, non-obiettivi e segnali di successo.
+
+Se una patch sembra facile ma non capisci perche il codice attuale e' fatto cosi, indaga prima.
+
+## Regola Zero: Triage
+
+Classifica sempre la richiesta prima di scegliere il processo. Dichiara il livello scelto all'utente quando inizi il lavoro operativo.
+
+| Livello | Criteri | Processo richiesto |
+|---|---|---|
+| **L1 - Triviale** | Circa 10 righe in 1-2 file; nessun cambio API, dipendenza o comportamento nuovo; refusi o fix che ripristinano comportamento gia atteso | Implementa. Esegui test pertinenti se esistono. Nessun nuovo documento. |
+| **L2 - Piccolo** | Root cause chiara; massimo 3 file; nessuna nuova dipendenza o API pubblica; rischio basso | Mini-analisi nel messaggio: obiettivo, impatto, sicurezza, test. Test obbligatori. Nessun nuovo documento salvo aggiornare analisi/handoff esistenti se utile. |
+| **L3 - Significativo** | Oltre 3 file, API/contratti, nuova dipendenza, comportamento visibile, area security-sensitive, cambio architetturale o design non ovvio | Workflow completo: Vision Gate, analisi, piano, implementazione, test, chiusura. |
+| **Spike** | Esplorazione time-boxed per ridurre incertezza | Codice non mergiabile in main. Esito in `ai_docs/solutions/SPIKE_[tema].md`. Per produzione riclassifica come L2 o L3. |
+
+Regole trasversali:
+- Parsing input esterni, authN/authZ, crittografia, rete, dati personali e filesystem sono security-sensitive: mai L1.
+- Se durante L1/L2 emerge impatto maggiore, fermati, riclassifica e dichiaralo.
+- Nel dubbio scegli il livello piu alto.
+- L'audit completo non parte per L1/L2 salvo richiesta esplicita.
+
+## Modalita Operative
+
+### Standalone completa
+
+Usa questa modalita quando devPNT non e' disponibile, non e' configurato per il progetto corrente o l'utente chiede esplicitamente un workflow solo filesystem.
+
+Fonte di verita:
+- Vision: `ai_docs/vision/project_vision.md`, `roadmap.md`, `principles.md`.
+- Feature/analisi: `ai_docs/solutions/ANALYSIS_[feature].md`.
+- Audit/handoff: `ai_docs/audit/`.
+- Storico feature: `ai_docs/strategic/features_history.md` manuale o generato dal validatore, in base alla struttura adottata dal progetto.
+
+La modalita Standalone non e' ridotta: deve poter gestire audit, feature, bug significativi, test, handoff e chiusura senza devPNT.
+
+### Hybrid in simbiosi con devPNT
+
+Usa questa modalita quando i tool `devpnt_*` sono disponibili e puntano al progetto corrente.
+
+Gerarchia autorevole:
+1. **M-VISION devPNT**: faro strategico della milestone. Prima di design o codice, leggila e verifica benefici, success signals, scope-in e non-goals.
+2. **Master Plan devPNT**: roadmap strategica e milestone.
+3. **Action Plan devPNT**: lavoro tattico corrente per il goal attivo.
+4. **Artefatti governati devPNT**: `D-UC`, `P-TM`, `E-ISP`, `E-TDD`, `E-TP`, ADR.
+5. **`ai_docs/` locale**: contesto leggibile, fallback Standalone, handoff locale o shadow/mirror quando utile.
+
+Regole Hybrid:
+- devPNT e' la fonte governata per piani e artefatti; non creare una seconda verita in `ai_docs/`.
+- La skill resta autonoma: se devPNT non c'e', passa a Standalone senza perdere capacita.
+- Se richiesta utente, Vision locale e M-VISION divergono, fermati e rendi esplicito il conflitto.
+- Non creare o modificare milestone senza rispettare la M-VISION.
+- Non accettare automaticamente proposte devPNT: presenta la preview e attendi conferma esplicita.
+- Se il protocollo devPNT locale impone bootstrap, piani o gate piu severi, seguili.
+
+## Workflow L3
+
+### 1. Audit e Allineamento
+
+- Leggi `ai_docs/audit/handoff.md` se esiste; se ha Data/Branch non coerenti, trattalo come storico.
+- Se `ai_docs/` manca o e' incompleta, crea struttura e documenti minimi analizzando il progetto a lotti.
+- In Standalone usa `ai_docs/audit/audit_plan.md` per mappatura e stato.
+- In Hybrid preferisci la mappatura devPNT/KL quando disponibile; non duplicare la governance dei piani.
+- Per template dettagliati usa `templates.md`.
 
 ### 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.
+
+Standalone:
+- Leggi `project_vision.md`, `roadmap.md`, `principles.md`.
+- Se un documento dichiara `Stato: DRAFT`, trattalo come ipotesi: segnala conflitti, ma non bloccare una richiesta esplicita dell'utente.
+- Se dichiara `Stato: APPROVED`, e la richiesta confligge, fermati e chiedi scelta: aggiornare Vision o modificare/rifiutare la richiesta.
+- Non promuovere mai una Vision a `APPROVED` senza conferma dell'utente.
+
+Hybrid:
+- Leggi la M-VISION della milestone o chiedi/crea il passaggio richiesto dal protocollo devPNT.
+- Verifica che la richiesta serva un beneficio o success signal della M-VISION.
+- Se la richiesta aggiunge scope non autorizzato, trattala come divergenza di Vision.
+
+### 3. Analisi della Richiesta
+
+Standalone L3:
+- Crea o aggiorna `ai_docs/solutions/ANALYSIS_[feature].md`.
+- Sezioni minime: Obiettivo, Vision della Feature o Allineamento alla Vision, Impatto, Sicurezza e Threat Model, Piano d'Azione, Strategia di Test, Diario/Stato Corrente.
+- Per feature che attraversano piu milestone o piu analisi, crea anche `ai_docs/vision/features/VISION_[feature].md`.
+
+Hybrid L3:
+- Ripristina Master Plan, Action Plan e documenti collegati.
+- Usa devPNT per piani e artefatti governati.
+- Usa `ai_docs/solutions/SHADOW_[doc_key]_vX.Y.md` solo come shadow leggibile quando serve; in divergenza vince devPNT.
+
+### 4. Sviluppo e Test
+
+- Implementa solo dopo il gate documentale richiesto dal livello.
+- Modifica in modo chirurgico, coerente con il piano.
+- Scrivi o aggiorna test automatici pertinenti; usa AAA per unit test quando applicabile.
+- Se l'ambiente non permette test automatici, dichiara verifica alternativa e motivo.
+- Circuit breaker: dopo 3 esecuzioni consecutive senza progresso sui test, fermati e chiedi istruzioni.
+- Aggiorna il Diario dell'ANALYSIS o l'Action Plan quando completi milestone, incontri blocchi o cambi decisione.
+
+### 5. Chiusura
+
+- Esegui test/lint/smoke check pertinenti.
+- Verifica allineamento con Vision locale o M-VISION devPNT.
+- Aggiorna solo i documenti effettivamente impattati.
+- In Hybrid proponi ADR/KL quando ci sono decisioni architetturali.
+- In Standalone, se il progetto adotta `sdlc_check.py`, esegui `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` o la copia locale equivalente.
+- I documenti aggiornati devono viaggiare nello stesso commit/PR del codice che descrivono.
+
+## Enforcement Meccanico
+
+Il prompt non e' enforcement. Quando il progetto richiede garanzie ripetibili:
+- leggi `ENFORCEMENT.md`;
+- usa `scripts/sdlc_check.py validate` in CI;
+- usa `scripts/sdlc_check.py gate` solo per directory security-critical, non per tutto il repository.
+
+Il validatore e' un supporto, non un prerequisito universale: la skill deve restare usabile anche in ambienti senza Python o senza hook, dichiarando cosa non puo' verificare automaticamente.