@antoneeo/agentic-sdlc-skill 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,30 +1,74 @@
 # Changelog - Agentic SDLC Skill
 
-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.
+Tutte le modifiche significative a questa skill saranno documentate in questo file.
+
+## [1.7.0] - 2026-07-02 (Phases 0-1 of the evolution roadmap)
+### Changed (breaking-soft)
+- **English is now the canonical language of the skill**: `SKILL.md`, `templates.md`, `ENFORCEMENT.md`, validator messages, generated indexes and the project protocol are in English. New ANALYSIS documents use English frontmatter keys (`status`, `level`, `start_date`, `end_date`) and English section headings. **Existing projects keep working**: the validator silently accepts the deprecated Italian keys (`stato`, `livello`, `data_inizio`, `data_fine`) and Italian headings.
+- The generated project protocol (`CLAUDE.md`/`GEMINI.md`/`AGENTS.md`/`.cursorrules`) is now a **thin pointer** to the skill (triage summary + where things live + closure gate) instead of a condensed copy of its rules, which had drifted from `SKILL.md`.
+- `init.js` now seeds `ai_docs/` from `templates.md` (single template source) instead of inline boilerplates; it creates `ai_docs/reference/` and the curated `ai_docs/README.md`, no longer seeds the generated `features_history.md`, and generates `INDEX.md` via the validator when Python is available, so the very first `sdlc_check.py check` on a fresh project is CLEAN.
+- Client detection unified between `init.js` and `postinstall.js` (`scripts/lib.js`): CLI on PATH **or** config home present (covers Claude Desktop with integrated Claude Code).
+
+### Added
+- `sdlc_check.py validate --strict` / `check --strict`: warnings and a missing `ai_docs/` become failures (for CI).
+- **Coexistence with devPNT (Phase 1, the Hybrid seam)**: new SKILL.md section with the ownership matrix (who is master per artifact in Standalone vs Hybrid), the triage equivalence table (one significance threshold, two vocabularies), the ANALYSIS↔plan-node state mapping and the shadow discipline (`SHADOW_[doc_key]_vX.Y.md`, exported BEFORE implementation; never saved under an `ANALYSIS_*` name).
+- `sdlc_check.py --hybrid` (explicit, never auto-detected) on `check`/`stale` (audit-plan staleness delegated to devPNT/KL) and on `gate` (an approved E-TDD shadow in `solutions/` authorizes writes on protected paths).
+- devPNT MCP doctrine (`mcp_system_prompt.md`, devPNT repo) slimmed accordingly: process (triage, phases, lifecycle, closure) deferred to the skill; `ai_docs/` layout aligned (adds `vision/` and `reference/`); shadow naming and shadow-before-implementation rule; checklist items for methodology, shadow export and hybrid closure gate.
+- Evolution roadmap for v1.7.0 in `ai_docs/vision/roadmap_evoluzione_agenti.md` (subagent execution, operative guides + agent-level knowledge base, devPNT seam, open-core positioning).
+
+### Fixed
+- Shadow detection is structural (filename `SHADOW_*` or `<!-- SHADOW` marker on the first line): an ANALYSIS merely *mentioning* shadows is no longer silently skipped from index and validation.
+- `mark`/`index` fail fast when `ai_docs/` is missing instead of silently creating a second documentation root in the wrong directory.
+
+### Removed
+- Divergent `agentic-sdlc-v2/` copy (integrated in 1.5.0, the leftover risked edits on the wrong files).
+- `references/*_template.md` (duplicated `templates.md` and had already diverged).
+
+## [1.6.0] - 2026-06-15
+### Added
+- **Manifest generato dei documenti canonici** (`ai_docs/INDEX.md`): `sdlc_check.py index` ora produce, oltre a `features_history.md`, un indice completo di tutti i doc in `vision/`, `reference/`, `architecture/`, `functional/`, `strategic/`, con descrizione e stato letti dall'header. Si rigenera, quindi non drifta.
+- **Lifecycle dei documenti canonici**: convenzione header `status: CURRENT|SUPERSEDED|DRAFT|DEPRECATED` + `supersedes:`. `validate` avvisa se `status` manca/è invalido o se un doc superseduto è ancora `CURRENT`. Stop ai grep che riportano a guide obsolete.
+- **Modello a due indici** documentato nella sezione "Documenti ai_docs" di `SKILL.md`: `README.md` curato (must-read, a mano) vs `INDEX.md` generato (completo, meccanico) — ruoli separati, prima confusi in un unico README che driftava.
+
+### Changed
+- §1 Audit: leggere `README.md` + `INDEX.md` all'avvio per sapere cosa esiste prima di esplorare il codice.
+- §3 Analisi: cercare con glob/grep un'ANALYSIS esistente prima di crearne una nuova (anti-duplicazione).
+- §5 Chiusura: gate "Indici allineati" — rigenerare `INDEX.md`, aggiornare il `README.md` curato per i must-read, marcare lo `status`; doc canonico non indicizzato o senza `status` = chiusura sporca.
+- `templates.md`: aggiunto il template dell'header dei documenti canonici.
+
+### Fixed
+- `sdlc_check.py` legge ora i file con `utf-8-sig`: un BOM iniziale (file autorati su Windows) non impedisce più il riconoscimento del frontmatter `---`.
+- L'estrattore dell'header riconosce sia il frontmatter `status:` sia la riga in corpo `**Status:**`/`Stato:`, e gli stati di tutte le convenzioni in uso (canonici `CURRENT/SUPERSEDED/DRAFT/DEPRECATED`, vision `DRAFT/APPROVED`, ADR `Accepted/Proposed/Rejected`) — niente più falsi avvisi "status non riconosciuto" su `APPROVED`/`Accepted`.
+- La descrizione del manifest salta righe di metadati (`Date`, `Created`, `Task ref`, ...) e i commenti HTML, così non finiscono come descrizione del documento.
+- `index` non genera più un `INDEX.md` vuoto su progetti senza documenti canonici (solo `solutions/`+`audit/`).
+
+### Migrazione (da 1.5.x)
+- Al primo `sdlc_check.py check`/`validate` dopo l'upgrade, un progetto con documenti canonici darà **un errore** `ai_docs/INDEX.md mancante`: è atteso — esegui **una volta** `sdlc_check.py index` per generarlo. Da lì in poi resta allineato.
+- I documenti canonici preesistenti senza `status:` produrranno **avvisi** (non errori): aggiungi l'header `description:`/`status:` per silenziarli. I nuovi progetti nascono già compatibili (template aggiornati).
+
+## [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/gemini-extension.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "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.",
+  "version": "1.7.0",
+  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",
     "claude-skill",
@@ -25,15 +25,13 @@
     "preuninstall": "node scripts/preuninstall.js"
   },
   "files": [
-    "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",
+    "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",
     "CHANGELOG.md",
-    "assets",
     "scripts"
   ]
 }

package/scripts/init.js

@@ -1,204 +1,153 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { SKILL_SOURCE, CLIENTS, clientDetected, loadTemplates, templateFor } = require('./lib');
 
 const cwd = process.cwd();
 
-// Helper for command checking
-function checkCommand(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
-  } catch (e) {
-    return false;
-  }
+// 1. Directory layout (canonical ai_docs structure, including reference/)
+const directories = [
+  'ai_docs',
+  'ai_docs/vision',
+  'ai_docs/vision/features',
+  'ai_docs/reference',
+  'ai_docs/strategic',
+  'ai_docs/audit',
+  'ai_docs/solutions',
+].map((d) => path.join(cwd, d));
+
+// 2. Project protocol (thin pointer — the operating contract is the skill).
+// Deliberately short: duplicating the skill's rules here made them drift.
+const protocolContent = `# Agentic SDLC — Project Protocol (pointer)
+
+This project follows the Agentic SDLC Documentation-First process. The full
+operating contract is the \`agentic-sdlc\` skill (installed in your agent's
+skills directory); this file is only the minimal always-on pointer.
+
+## Rule Zero — Triage every request
+- L1 Trivial: ~10 lines, 1-2 files, no API/dependency/behavior change. Implement + run existing tests; no docs.
+- L2 Small: clear root cause, at most 3 files, low risk. Mini-analysis in the reply; tests mandatory.
+- L3 Significant: >3 files, APIs/contracts, new dependency, user-visible behavior, security-sensitive area, or architectural change. Full workflow via the skill: Vision Gate -> ANALYSIS -> plan -> implement -> test -> closure.
+- Spike: time-boxed exploration; outcome in \`ai_docs/solutions/SPIKE_[topic].md\`; reclassify for production.
+- Security-sensitive areas (external input parsing, authN/authZ, crypto, network, personal data, filesystem) are never L1.
+- When in doubt, pick the higher level. Declare the chosen level when starting.
+
+## Where things live
+- Vision (gate for L3): \`ai_docs/vision/\` — \`Status: DRAFT\` informs, \`Status: APPROVED\` binds.
+- Feature analyses: \`ai_docs/solutions/ANALYSIS_[feature].md\` (frontmatter = feature state).
+- Must-reads: \`ai_docs/README.md\`; full generated manifest: \`ai_docs/INDEX.md\`.
+- If devPNT is available for this project, its M-VISION / plans / governed artifacts take over (Hybrid mode — see the skill).
+
+## Closure gate
+Docs travel in the same commit/PR as the code they describe. If the project
+adopts the validator, \`python <skill_dir>/scripts/sdlc_check.py check\` must be
+CLEAN before declaring work done.
+
+If the agentic-sdlc skill is not available in this client, ask the user to install it:
+\`npm i -g @antoneeo/agentic-sdlc-skill && agentic-sdlc-install-skill\`
+`;
+
+console.log('🚀 Initializing Agentic SDLC workflow...');
+
+// 3. Load templates from the single source (skill's templates.md)
+let sections;
+try {
+  sections = loadTemplates();
+} catch (err) {
+  console.error(`❌ Cannot load templates: ${err.message}`);
+  process.exit(1);
+}
+
+// audit_plan: the template block carries illustrative rows; a fresh project
+// starts from a single root PENDING row instead.
+function initialAuditPlan() {
+  const tpl = templateFor(sections, 'audit_plan.md');
+  const lines = tpl.split('\n');
+  const sepIdx = lines.findIndex((l) => /^\|[-\s|:]+\|$/.test(l.trim()));
+  if (sepIdx === -1) return tpl; // unexpected shape: keep the template as-is
+  return lines.slice(0, sepIdx + 1).join('\n') + '\n| / | PENDING | - | Initial analysis |\n';
+}
+
+let seedFiles;
+try {
+  seedFiles = [
+    ['ai_docs/README.md', templateFor(sections, 'ai_docs/README.md')],
+    ['ai_docs/vision/project_vision.md', templateFor(sections, 'project_vision.md')],
+    ['ai_docs/vision/roadmap.md', templateFor(sections, 'vision/roadmap.md')],
+    ['ai_docs/vision/principles.md', templateFor(sections, 'principles.md')],
+    ['ai_docs/strategic/architecture.md', templateFor(sections, 'architecture.md and existing_features.md', 0)],
+    ['ai_docs/strategic/existing_features.md', templateFor(sections, 'architecture.md and existing_features.md', 1)],
+    ['ai_docs/audit/audit_plan.md', initialAuditPlan()],
+    // NOTE: features_history.md and INDEX.md are NOT seeded — they are
+    // generated by `sdlc_check.py index` and would immediately fail validate.
+  ];
+} catch (err) {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
 }
 
-// 1. Path definitions
-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')
-};
-
-// 2. Operational Protocol (System Prompt)
-const protocolContent = `# "Agentic SDLC" Operational Protocol
-
-You are a senior software engineer following a Documentation-First and Vision-Guided process. The process is proportional to risk: do not apply heavyweight governance to trivial work, but never bypass Vision, security, or design gates for significant changes.
-
-## 0. Triage First
-Classify every operational request:
-- L1 Trivial: small local fix, no API/dependency/behavior expansion. Implement with relevant tests; no new docs.
-- L2 Small: clear root cause, up to 3 files, low risk. Provide mini-analysis in the response; test.
-- L3 Significant: public contract, user-visible behavior, security-sensitive area, new dependency, architectural impact, or more than 3 files. Use the full workflow below.
-- Spike: time-boxed exploration; document result in \`ai_docs/solutions/SPIKE_[topic].md\`; production work must be reclassified.
-
-Security-sensitive areas are never L1.
-
-## 1. Mode Selection
-- Standalone: if devPNT is unavailable, use \`ai_docs/\` as the complete source of truth.
-- Hybrid/devPNT: if devPNT is available and configured for this project, use it for governed state. The devPNT M-VISION is the milestone north star, Master Plan is strategic roadmap, Action Plan is tactical execution, and governed artifacts live in devPNT.
-- Do not create silent double truth. In Hybrid, \`ai_docs/\` is human-readable context, fallback, handoff, or shadow; devPNT governs plans and versioned artifacts.
-
-## 2. Audit and Alignment
-For L3 or explicit audit requests:
-- Check \`ai_docs/\`, \`ai_docs/vision/\`, \`ai_docs/strategic/\`, \`ai_docs/audit/\`, and \`ai_docs/solutions/\`.
-- If missing, create them by analyzing the codebase in batches.
-- Never treat architecture or feature history as a substitute for Vision.
-
-## 3. Vision Gate
-Standalone:
-- Read \`ai_docs/vision/project_vision.md\`, \`roadmap.md\`, and \`principles.md\`.
-- Vision documents start as \`Stato: DRAFT\`; DRAFT informs but does not block an explicit user request.
-- \`Stato: APPROVED\` is binding: surface conflicts before implementation.
-
-Hybrid/devPNT:
-- Read the active M-VISION before design or code.
-- Verify the request advances a stated benefit or success signal.
-- If request, local Vision, and M-VISION diverge, stop and surface the conflict.
-
-## 4. Request Analysis
-For L3 in Standalone:
-- Create or update \`ai_docs/solutions/ANALYSIS_[feature].md\`.
-- Include Objective, Feature Vision, Impact, Security and Threat Model, Action Plan, Test Strategy, and Diary/Current State.
-
-For L3 in Hybrid:
-- Restore Master Plan, Action Plan, and related devPNT artifacts.
-- Use devPNT for D-UC, P-TM, E-ISP, E-TDD, E-TP, ADR, and plan updates.
-- Use Markdown shadows only as readable mirrors, never as the authoritative source over devPNT.
-
-## 5. Development and Testing
-Only after the required gate for the triage level:
-1. Implement surgically following the plan.
-2. Write or update automated tests where possible, using AAA for unit tests.
-3. Run tests/lint/smoke checks. If the environment cannot run them, document the alternative verification.
-4. After 3 consecutive test runs without progress, stop and ask for guidance.
-
-## 6. Closing
-- Verify the result against local Vision or devPNT M-VISION.
-- Update only documents actually impacted.
-- In Hybrid, propose ADR/KL updates when architectural facts changed.
-- Keep docs and code in the same commit/PR.
-`;
-
-const projectVisionBoilerplate = `# Project Vision
-Stato: DRAFT
-
-## North Star
-- TBD
-
-## Target Users
-- TBD
-
-## Goals
-- TBD
-
-## Non-Goals
-- TBD
-
-## Success Signals
-- TBD
-`;
-
-const roadmapBoilerplate = `# Vision Roadmap
-Stato: DRAFT
-
-| Milestone | Expected Benefit | Priority | Success Signal | Status |
-|:---|:---|:---|:---|:---|
-| M1 | - | - | - | [PLANNED] |
-`;
-
-const principlesBoilerplate = `# Vision Principles
-Stato: DRAFT
-
-## Principles
-- TBD
-
-## Strategic Anti-Patterns
-- TBD
-`;
-
-const historyBoilerplate = `<!-- 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 |
-|:---|:---|:---|:---|:---|:---|:---|
-`;
-
-console.log('🚀 Initializing Agentic SDLC workflow (Discovery Mode)...');
-
-// 3. Directory creation
-directories.forEach(dir => {
+// 4. Create directories
+directories.forEach((dir) => {
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
     console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
   }
 });
 
-// 4. Basic file writing
-const writeIfNotExists = (filePath, content, description) => {
+// 5. Write seed files (never overwrite)
+const writeIfNotExists = (relPath, content, description) => {
+  const filePath = path.join(cwd, relPath);
   if (!fs.existsSync(filePath)) {
     fs.writeFileSync(filePath, content, 'utf8');
-    console.log(`📄 Created file: ${path.relative(cwd, filePath)} (${description})`);
+    console.log(`📄 Created file: ${relPath}${description ? ` (${description})` : ''}`);
     return true;
-  } else {
-    console.log(`⏭️  Skipped: ${path.relative(cwd, filePath)} already exists.`);
-    return false;
   }
-};
-
-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\nStates: PENDING | ANALYZED | SKIPPED.\n\n| Percorso | Stato | Riferimento | Note |\n|---|---|---|---|\n| / | PENDING | - | Initial analysis |\n', 'Audit Plan');
-
-// 5. Client Discovery and Configuration
+  console.log(`⏭️  Skipped: ${relPath} already exists.`);
+  return false;
+};
+
+seedFiles.forEach(([relPath, content]) => writeIfNotExists(relPath, content));
+
+// 6. Client discovery and protocol pointers
 console.log('\n--- Environment Analysis ---');
 
-if (checkCommand('claude')) {
-  console.log('✅ Claude Code detected.');
-  writeIfNotExists(files.claudeConfig, protocolContent, 'Claude Configuration');
-}
+const protocolFiles = {
+  claude: 'CLAUDE.md',
+  gemini: 'GEMINI.md',
+  codex: 'AGENTS.md',
+};
 
-if (checkCommand('gemini')) {
-  console.log('✅ Gemini CLI detected.');
-  writeIfNotExists(files.geminiConfig, protocolContent, 'Gemini Configuration');
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ ${client.label} detected.`);
+    writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
+  }
 }
 
-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');
+writeIfNotExists('.cursorrules', protocolContent, 'Cursor/Windsurf rules');
+
+// 7. Generate ai_docs/INDEX.md so the very first `validate` is already clean.
+// The manifest is generated, never seeded: delegate to the validator if Python is available.
+const validator = path.join(SKILL_SOURCE, 'scripts', 'sdlc_check.py');
+let indexed = false;
+for (const py of ['python', 'python3', 'py']) {
+  try {
+    execSync(`${py} "${validator}" index --root "${cwd}"`, { stdio: 'ignore' });
+    console.log('📇 Generated ai_docs/INDEX.md (document manifest).');
+    indexed = true;
+    break;
+  } catch (e) { /* try the next interpreter */ }
+}
+if (!indexed) {
+  console.log('ℹ️  Python not found: generate the manifest later with '
+    + '"python <skill_dir>/scripts/sdlc_check.py index" (validate reports it until then).');
+}
 
 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. Make sure the agentic-sdlc skill is installed (agentic-sdlc-install-skill).');
+console.log('   2. Restart/open the project in your AI client so it reads the protocol pointer.');
+console.log('   3. Start with an audit following ai_docs/audit/audit_plan.md.');

package/scripts/lib.js

@@ -0,0 +1,138 @@
+// Shared helpers for the Agentic SDLC npm scripts (init / postinstall / preuninstall).
+// Single source for client detection and skill-target paths: init and postinstall
+// must never disagree on what "Claude Code is installed" means.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
+const TEMPLATES_PATH = path.join(SKILL_SOURCE, 'templates.md');
+
+// One entry per supported AI client. `home` may be overridden by an env var
+// (Claude Desktop / portable installs); presence of the home dir counts as
+// detection even when the CLI is not on PATH.
+const CLIENTS = [
+  {
+    key: 'claude',
+    label: 'Claude Code',
+    cmd: 'claude',
+    home: process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    envVar: 'CLAUDE_CONFIG_DIR',
+    reload: 'Restart Claude Code to load it. Invoke via Skill tool as "agentic-sdlc".',
+  },
+  {
+    key: 'gemini',
+    label: 'Gemini CLI',
+    cmd: 'gemini',
+    home: process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini'),
+    envVar: 'GEMINI_HOME',
+    reload: 'Run "gemini skills reload" or restart Gemini CLI to load it.',
+  },
+  {
+    key: 'codex',
+    label: 'Codex AI',
+    cmd: 'codex',
+    home: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+    envVar: 'CODEX_HOME',
+    reload: 'Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.',
+  },
+];
+
+function commandExists(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function clientDetected(client) {
+  return commandExists(client.cmd)
+    || Boolean(process.env[client.envVar])
+    || fs.existsSync(client.home);
+}
+
+function skillTarget(client) {
+  return path.join(client.home, 'skills', 'agentic-sdlc');
+}
+
+function copyRecursive(src, dest) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true, force: true });
+    return;
+  }
+  // Fallback for Node < 16.7
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyRecursive(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Parse templates.md into { headingText: [fencedBlock, ...] }.
+ * Templates are single-sourced there: the init script must extract them
+ * instead of carrying its own inline copies (which historically drifted).
+ */
+function loadTemplates() {
+  const text = fs.readFileSync(TEMPLATES_PATH, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const sections = {};
+  let heading = null;
+  let block = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h && block === null) {
+      heading = h[1].trim();
+      sections[heading] = sections[heading] || [];
+      continue;
+    }
+    if (/^```/.test(line)) {
+      if (block === null) {
+        block = [];
+      } else {
+        if (heading) sections[heading].push(block.join('\n') + '\n');
+        block = null;
+      }
+      continue;
+    }
+    if (block !== null) block.push(line);
+  }
+  return sections;
+}
+
+/**
+ * Return the Nth fenced block of the section whose heading contains `needle`.
+ * Throws with a clear message when missing: writing a wrong or empty
+ * boilerplate silently would be worse than failing the init.
+ */
+function templateFor(sections, needle, index = 0) {
+  const heading = Object.keys(sections).find((h) => h.includes(needle));
+  const blocks = heading ? sections[heading] : undefined;
+  if (!blocks || !blocks[index]) {
+    throw new Error(
+      `Template section containing "${needle}" (block ${index}) not found in ${TEMPLATES_PATH}. ` +
+      'The package is corrupted or templates.md was restructured: fix templates.md, do not improvise content.'
+    );
+  }
+  return blocks[index];
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  SKILL_SOURCE,
+  TEMPLATES_PATH,
+  CLIENTS,
+  commandExists,
+  clientDetected,
+  skillTarget,
+  copyRecursive,
+  loadTemplates,
+  templateFor,
+};