@antoneeo/agentic-sdlc-skill 1.6.0 → 1.8.0

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

@@ -1,192 +1,250 @@
-# Template dei documenti — Agentic SDLC
-
-Regole generali:
-- Documenti concisi: ≤ ~80 righe ciascuno (handoff ≤ 20). Se un documento cresce oltre, va diviso, non gonfiato.
-- La conformità al template non è l'obiettivo: se una sezione non ha contenuto reale, scrivi esplicitamente perché non si applica. Mai testo riempitivo.
-- Date sempre assolute, in UTC dove indicato.
-
-## Header dei documenti canonici (vision/ reference/ architecture/ functional/ strategic/)
-
-Ogni documento canonico durevole apre con questo frontmatter: alimenta il manifest generato `ai_docs/INDEX.md` e dà a un agente il segnale di freschezza prima che si fidi del contenuto.
-
-```markdown
----
-description: Una riga — cos'è il documento e quando leggerlo.
-status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
-supersedes: vecchio_doc.md   # solo se rimpiazza un altro doc canonico
----
-# Titolo del Documento
-```
-
-Quando un doc ne sostituisce un altro: il nuovo dichiara `supersedes:`, il vecchio passa a `status: SUPERSEDED` (resta come storico, non si cancella). `sdlc_check.py validate` avvisa se `status` manca o se un doc superseduto è ancora `CURRENT`.
-
-## ai_docs/vision/project_vision.md
-
-```markdown
-# Vision del Progetto
-Stato: DRAFT
-<!-- Stato: DRAFT (ricostruita dall'agente, NON è autorità di gating)
-     oppure APPROVED (da <chi>, <data>) — solo dopo conferma esplicita dell'utente -->
-
-## North Star
-## Utenti Target
-## Problema Centrale
-## Obiettivi
-## Non-Obiettivi
-## Segnali di Successo
-```
-
-## ai_docs/vision/roadmap.md
-
-```markdown
-# Roadmap
-Stato: DRAFT
-
-## Milestone
-<!-- per ciascuna: beneficio atteso, priorità, indicatore di avanzamento -->
-```
-
-## ai_docs/vision/principles.md
-
-```markdown
-# Principi Decisionali
-Stato: DRAFT
-
-<!-- elenco puntato dei principi stabili che guidano trade-off e scope, dal più critico -->
-```
-
-## ai_docs/vision/features/VISION_[nome_feature].md
-
-Solo per feature che attraversano più ANALYSIS o più milestone: negli altri casi la vision di feature vive nella sezione `## Vision della Feature` dell'ANALYSIS.
-
-```markdown
-# Vision Feature: [Nome]
-
-## Problema
-## Beneficio Atteso
-## Utenti o Stakeholder
-## Segnali di Successo
-## Non-Obiettivi / Fuori Scope
-## Vincoli e Principi Collegati
-```
-
-## ai_docs/solutions/ANALYSIS_[nome_feature].md
-
-Il frontmatter è la fonte di verità dello stato della feature (l'indice `features_history.md` si genera da qui).
-
-```markdown
----
-id: F-001
-feature: Nome Feature
-stato: PLANNED
-livello: L3
-data_inizio: 2026-06-11
-data_fine:
----
-# Analisi della Feature: [Nome]
-
-## Obiettivo
-<!-- cosa si vuole ottenere e quali problemi risolve -->
-
-## Vision della Feature
-<!-- beneficio atteso e problema risolto; allineamento alla vision di progetto
-     (citare il documento e il suo stato DRAFT/APPROVED); non-obiettivi/fuori scope
-     di questa feature; segnali di successo; stakeholder solo se non ovvi.
-     È l'unico posto della vision di feature: il file separato VISION_[feature].md
-     si crea solo se la feature attraversa più ANALYSIS o più milestone. -->
-
-## Impatto
-<!-- file esistenti toccati, API/contratti, performance, nuove dipendenze -->
-
-## Sicurezza e Threat Model
-<!-- SEMPRE obbligatoria, anche in standalone.
-     Superfici toccate: input esterni, authN/authZ, crittografia, rete, dati personali, filesystem.
-     Minacce principali e mitigazioni. "Nessun impatto di sicurezza" va motivato, non dichiarato. -->
-
-## Piano d'Azione
-- [ ] ...
-
-## Strategia di Test
-<!-- unit AAA, integrazione, esempi. Se l'ambiente non è eseguibile (firmware/HIL):
-     verifica alternativa esplicita e motivo. -->
-
-## Diario / Stato Corrente
-<!-- aggiornato a ogni milestone: dove sono, ultimo problema, prossimo passo.
-     È la fonte dell'handoff per questa feature. -->
-```
-
-Stati ammessi nel frontmatter: `PLANNED` | `IN_PROGRESS` | `COMPLETED` | `CANCELLED`. `COMPLETED` richiede `data_fine`.
-
-## ai_docs/solutions/SPIKE_[tema].md
-
-```markdown
-# Spike: [tema]
-
-## Domanda da rispondere
-## Time-box
-## Cosa è stato provato
-## Risposta / Esito
-## Conseguenze
-<!-- max 1 pagina. Il codice dello spike NON è mergiabile: per produzione riclassificare L2/L3. -->
-```
-
-## ai_docs/audit/audit_plan.md (solo modalità Standalone)
-
-Il campo `Riferimento` (hash git o timestamp ISO UTC) è gestito da `sdlc_check.py mark` — non compilarlo a mano. La freschezza si verifica con `sdlc_check.py stale`.
-
-```markdown
-# Piano di Audit
-
-Stati: PENDING (da analizzare) | ANALYZED (analizzato, con riferimento) | SKIPPED (con motivo).
-
-| Percorso | Stato | Riferimento | Note |
-|---|---|---|---|
-| src/core/ | PENDING | - | |
-| vendor/ | SKIPPED | - | codice vendored |
-```
-
-## ai_docs/audit/handoff.md
-
-Solo un puntatore, ≤ 20 righe. Il dettaglio vive nel Diario di ciascuna ANALYSIS.
-
-```markdown
-# Handoff
-Data: 2026-06-11 (UTC)
-Branch: feature/sso-login
-Agente: Claude
-
-## Feature attive
-- F-001 — vedi solutions/ANALYSIS_login_sso.md (sezione Diario)
-
-## Prossimo passo
-<!-- una riga -->
-
-## Note di sessione
-<!-- vision lette in questa sessione? draft da far validare? -->
-```
-
-## ai_docs/strategic/architecture.md e existing_features.md
-
-Doc canonici: aprono con l'header (`description:`/`status:`) cosi' entrano puliti nel manifest `INDEX.md`.
-
-```markdown
----
-description: Stack, struttura directory e pattern architetturali del progetto.
-status: CURRENT
----
-# Architettura del Progetto
-## Stack Tecnologico
-## Struttura delle Directory
-## Pattern Architetturali
-```
-
-```markdown
----
-description: Catalogo sintetico delle funzionalità esistenti del progetto.
-status: CURRENT
----
-# Funzionalità Esistenti
-- [ID] **Nome Feature**: Descrizione
-```
-
-`ai_docs/strategic/features_history.md` e `ai_docs/INDEX.md` NON hanno template: sono generati da `sdlc_check.py index`.
+# Document templates — Agentic SDLC
+
+General rules:
+- Concise documents: ≤ ~80 lines each (handoff ≤ 20). If a document grows beyond that, split it, do not inflate it.
+- Template conformance is not the goal: if a section has no real content, state explicitly why it does not apply. Never filler text.
+- Dates always absolute, UTC where indicated.
+
+## Canonical document header (vision/ reference/ architecture/ functional/ strategic/)
+
+Every durable canonical document opens with this frontmatter: it feeds the generated manifest `ai_docs/INDEX.md` and gives an agent the freshness signal before it trusts the content.
+
+```markdown
+---
+description: One line — what the document is and when to read it.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: old_doc.md       # only if it replaces another canonical doc
+---
+# Document Title
+```
+
+When a doc replaces another: the new one declares `supersedes:`, the old one switches to `status: SUPERSEDED` (it stays as history, do not delete it). `sdlc_check.py validate` warns if `status` is missing or if a superseded doc is still `CURRENT`.
+
+## ai_docs/reference/GUIDE_[topic].md
+
+Operative guide distilled from USER-PROVIDED indications (never from model knowledge).
+The guide is a SYNTHESIS — the compact training a reader takes in whole before acting;
+the verbatim snapshot in `ai_docs/reference/.sources/<slug>-<hash8>.md` is the book,
+reached on demand. `source_hash` is the snapshot's SHA-256. Every `##` section carries
+a fidelity marker: `[source: <snapshot-file>#<anchor-or-line>]` for covered content
+(doubling as the detail-lookup pointer into the book), or a literal
+`[not covered by source]` for gaps. Sections are CHOSEN from the repertoire below —
+only those the source actually supports; never force empty ones. A guide approaching
+the source's own length is a paraphrase, not a synthesis.
+
+```markdown
+---
+description: One line, ≤160 chars — when to consult this guide.
+status: CURRENT
+source: Human-readable name of what the user provided.
+source_version: v1.2          # optional — only when the origin is versioned
+distilled_from: ai_docs/reference/.sources/topic-a1b2c3d4.md
+source_hash: <sha256 of the snapshot file>
+---
+# Guide: [Topic]
+
+## How to do [X]
+[source: topic-a1b2c3d4.md#setup]
+<!-- operative steps, imperative voice -->
+
+## How to verify it is done right
+[source: topic-a1b2c3d4.md#checks]
+
+## What NOT to do
+[not covered by source]
+<!-- the user's material does not address this: do not invent. -->
+```
+
+Section repertoire (pick what the source supports): How to do X / How to verify /
+What NOT to do / What to watch out for / Core principles / When this applies.
+
+## ai_docs/README.md
+
+Curated must-read index, by hand (it is NOT the generated manifest). Created at init, updated rarely, only for real must-reads.
+
+```markdown
+# ai_docs — reading guide
+
+Must-reads for this project, in order. The full manifest of canonical docs is
+`INDEX.md` (generated — regenerate with `sdlc_check.py index`, never edit by hand).
+
+1. `vision/project_vision.md` — why the project exists (check its Status first).
+2. `strategic/architecture.md` — how it is built.
+3. `audit/handoff.md` — where work stopped last session (if present).
+
+Directory purposes: `vision/` (project direction), `strategic/` (architecture and
+feature catalog), `reference/` (operative guides), `solutions/` (per-feature
+analyses, discovery-by-grep), `audit/` (audit plan and handoff).
+```
+
+## ai_docs/vision/project_vision.md
+
+```markdown
+# Project Vision
+Status: DRAFT
+<!-- Status: DRAFT (reconstructed by the agent, NOT a gating authority)
+     or APPROVED (by <who>, <date>) — only after the user's explicit confirmation -->
+
+## North Star
+## Target Users
+## Core Problem
+## Goals
+## Non-Goals
+## Success Signals
+```
+
+## ai_docs/vision/roadmap.md
+
+```markdown
+# Roadmap
+Status: DRAFT
+
+## Milestones
+<!-- for each: expected benefit, priority, progress indicator -->
+```
+
+## ai_docs/vision/principles.md
+
+```markdown
+# Decision Principles
+Status: DRAFT
+
+<!-- bullet list of the stable principles guiding trade-offs and scope, most critical first -->
+```
+
+## ai_docs/vision/features/VISION_[feature_name].md
+
+Only for features spanning multiple ANALYSIS documents or multiple milestones: otherwise the feature vision lives in the `## Feature Vision` section of the ANALYSIS.
+
+```markdown
+# Feature Vision: [Name]
+
+## Problem
+## Expected Benefit
+## Users or Stakeholders
+## Success Signals
+## Non-Goals / Out of Scope
+## Related Constraints and Principles
+```
+
+## ai_docs/solutions/ANALYSIS_[feature_name].md
+
+The frontmatter is the source of truth for the feature state (the `features_history.md` index is generated from it).
+
+```markdown
+---
+id: F-001
+feature: Feature Name
+status: PLANNED
+level: L3
+start_date: 2026-06-11
+end_date:
+---
+# Feature Analysis: [Name]
+
+## Objective
+<!-- what we want to achieve and which problems it solves -->
+
+## Feature Vision
+<!-- expected benefit and problem solved; alignment with the project vision
+     (cite the document and its DRAFT/APPROVED state); non-goals/out-of-scope
+     for this feature; success signals; stakeholders only if not obvious.
+     This is the single home of the feature vision: the separate file
+     VISION_[feature].md is created only if the feature spans multiple
+     ANALYSIS documents or multiple milestones. -->
+
+## Impact
+<!-- existing files touched, APIs/contracts, performance, new dependencies -->
+
+## Security and Threat Model
+<!-- ALWAYS mandatory, also in Standalone.
+     Surfaces touched: external input, authN/authZ, cryptography, network, personal data, filesystem.
+     Main threats and mitigations. "No security impact" must be justified, not declared. -->
+
+## Action Plan
+- [ ] ...
+
+## Test Strategy
+<!-- AAA unit tests, integration, examples. If the environment is not executable (firmware/HIL):
+     explicit alternative verification and reason. -->
+
+## Diary / Current State
+<!-- updated at every milestone: where I am, last problem, next step.
+     It is the handoff source for this feature. -->
+```
+
+Allowed frontmatter states: `PLANNED` | `IN_PROGRESS` | `COMPLETED` | `CANCELLED`. `COMPLETED` requires `end_date`. (The validator also accepts the deprecated Italian keys `stato`/`livello`/`data_inizio`/`data_fine` in existing projects.)
+
+## ai_docs/solutions/SPIKE_[topic].md
+
+```markdown
+# Spike: [topic]
+
+## Question to answer
+## Time-box
+## What was tried
+## Answer / Outcome
+## Consequences
+<!-- max 1 page. Spike code is NOT mergeable: for production reclassify L2/L3. -->
+```
+
+## ai_docs/audit/audit_plan.md (Standalone mode only)
+
+The `Reference` field (git hash or ISO UTC timestamp) is managed by `sdlc_check.py mark` — do not fill it by hand. Freshness is verified with `sdlc_check.py stale`.
+
+```markdown
+# Audit Plan
+
+States: PENDING (to analyze) | ANALYZED (analyzed, with reference) | SKIPPED (with reason).
+
+| Path | Status | Reference | Notes |
+|---|---|---|---|
+| src/core/ | PENDING | - | |
+| vendor/ | SKIPPED | - | vendored code |
+```
+
+## ai_docs/audit/handoff.md
+
+Just a pointer, ≤ 20 lines. The detail lives in the Diary of each ANALYSIS.
+
+```markdown
+# Handoff
+Date: 2026-06-11 (UTC)
+Branch: feature/sso-login
+Agent: Claude
+
+## Active features
+- F-001 — see solutions/ANALYSIS_login_sso.md (Diary section)
+
+## Next step
+<!-- one line -->
+
+## Session notes
+<!-- visions read this session? drafts to have validated? -->
+```
+
+## ai_docs/strategic/architecture.md and existing_features.md
+
+Canonical docs: they open with the header (`description:`/`status:`) so they enter the `INDEX.md` manifest cleanly.
+
+```markdown
+---
+description: Stack, directory structure and architectural patterns of the project.
+status: CURRENT
+---
+# Project Architecture
+## Technology Stack
+## Directory Structure
+## Architectural Patterns
+```
+
+```markdown
+---
+description: Concise catalog of the project's existing features.
+status: CURRENT
+---
+# Existing Features
+- [ID] **Feature Name**: Description
+```
+
+`ai_docs/strategic/features_history.md` and `ai_docs/INDEX.md` have NO template: they are generated by `sdlc_check.py index`.

package/references/analysis_template.md

@@ -1,44 +0,0 @@
----
-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

@@ -1,23 +0,0 @@
----
-description: Stack, struttura directory e pattern architetturali del progetto.
-status: CURRENT
----
-# Architettura del Progetto
-
-## Stack Tecnologico
-- **Linguaggio:** [es. TypeScript]
-- **Framework:** [es. React, Express]
-- **Database:** [es. PostgreSQL]
-- **Strumenti di Test:** [es. Jest, Vitest]
-
-## 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]
-- [es. Dependency Injection]

package/references/existing_features_template.md

@@ -1,8 +0,0 @@
----
-description: Catalogo sintetico delle funzionalità esistenti del progetto.
-status: CURRENT
----
-# Funzionalità Esistenti
-
-- [ID] **Nome Feature**: Descrizione sintetica della funzionalità.
-- [ID] **Altra Feature**: Dettagli su cosa permette di fare all'utente.

package/references/feature_vision_template.md

@@ -1,21 +0,0 @@
-# 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,5 +0,0 @@
-<!-- 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

@@ -1,13 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
-# 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

@@ -1,9 +0,0 @@
-# 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.