@antoneeo/agentic-sdlc-skill 1.6.0 → 1.8.0

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,
+};

package/scripts/postinstall.js

@@ -1,132 +1,36 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
-const { execSync } = require('child_process');
 const fs = require('fs');
-const path = require('path');
-const os = require('os');
+const { SKILL_SOURCE, CLIENTS, clientDetected, skillTarget, copyRecursive } = require('./lib');
 
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
-const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-const CLAUDE_SKILLS_DIR = path.join(CLAUDE_HOME, 'skills');
-const CLAUDE_SKILL_TARGET = path.join(CLAUDE_SKILLS_DIR, 'agentic-sdlc');
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-const CODEX_SKILLS_DIR = path.join(CODEX_HOME, 'skills');
-const CODEX_SKILL_TARGET = path.join(CODEX_SKILLS_DIR, 'agentic-sdlc');
-const GEMINI_HOME = process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini');
-const GEMINI_SKILLS_DIR = path.join(GEMINI_HOME, 'skills');
-const GEMINI_SKILL_TARGET = path.join(GEMINI_SKILLS_DIR, 'agentic-sdlc');
-
-function checkCommand(cmd) {
-  try {
-    execSync(`${cmd} --version`, { stdio: 'ignore' });
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-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);
-  }
-}
-
-function installClaudeSkill() {
-  if (!fs.existsSync(SKILL_SOURCE)) {
-    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Claude Code install.`);
-    return false;
-  }
-  try {
-    fs.mkdirSync(CLAUDE_SKILLS_DIR, { recursive: true });
-    copyRecursive(SKILL_SOURCE, CLAUDE_SKILL_TARGET);
-    console.log(`📦 Installed Claude Code skill at: ${CLAUDE_SKILL_TARGET}`);
-    console.log('   Restart Claude Code to load it. Invoke via Skill tool as "agentic-sdlc".');
-    return true;
-  } catch (err) {
-    console.log(`⚠️  Failed to install Claude Code skill: ${err.message}`);
-    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CLAUDE_SKILL_TARGET}".`);
-    return false;
-  }
-}
-
-function installCodexSkill() {
+function installSkill(client) {
   if (!fs.existsSync(SKILL_SOURCE)) {
-    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Codex install.`);
+    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping ${client.label} install.`);
     return false;
   }
+  const target = skillTarget(client);
   try {
-    fs.mkdirSync(CODEX_SKILLS_DIR, { recursive: true });
-    copyRecursive(SKILL_SOURCE, CODEX_SKILL_TARGET);
-    console.log(`📦 Installed Codex skill at: ${CODEX_SKILL_TARGET}`);
-    console.log('   Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.');
+    fs.mkdirSync(target, { recursive: true });
+    copyRecursive(SKILL_SOURCE, target);
+    console.log(`📦 Installed ${client.label} skill at: ${target}`);
+    console.log(`   ${client.reload}`);
     return true;
   } catch (err) {
-    console.log(`⚠️  Failed to install Codex skill: ${err.message}`);
-    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CODEX_SKILL_TARGET}".`);
+    console.log(`⚠️  Failed to install ${client.label} skill: ${err.message}`);
+    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${target}".`);
     return false;
   }
-}
-
-function installGeminiSkill() {
-  if (!fs.existsSync(SKILL_SOURCE)) {
-    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Gemini install.`);
-    return false;
-  }
-  try {
-    fs.mkdirSync(GEMINI_SKILLS_DIR, { recursive: true });
-    copyRecursive(SKILL_SOURCE, GEMINI_SKILL_TARGET);
-    console.log(`📦 Installed Gemini skill at: ${GEMINI_SKILL_TARGET}`);
-    console.log('   Run "gemini skills reload" or restart Gemini CLI to load it.');
-    return true;
-  } catch (err) {
-    console.log(`⚠️  Failed to install Gemini skill: ${err.message}`);
-    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${GEMINI_SKILL_TARGET}".`);
-    return false;
-  }
-}
-
-function hasCodexHome() {
-  return Boolean(process.env.CODEX_HOME) || fs.existsSync(CODEX_HOME);
 }
 
-function hasClaudeHome() {
-  return Boolean(process.env.CLAUDE_CONFIG_DIR) || fs.existsSync(CLAUDE_HOME);
-}
-
-function hasGeminiHome() {
-  return Boolean(process.env.GEMINI_HOME) || fs.existsSync(GEMINI_HOME);
-}
-
 console.log('\n--- Agentic SDLC Skill Discovery ---');
 
 let detected = false;
-
-if (checkCommand('claude') || hasClaudeHome()) {
-  console.log(`✅ Detected: Claude Code`);
-  detected = true;
-  installClaudeSkill();
-}
-
-if (checkCommand('gemini') || hasGeminiHome()) {
-  console.log(`✅ Detected: Gemini CLI`);
-  detected = true;
-  installGeminiSkill();
-}
-
-if (checkCommand('codex') || hasCodexHome()) {
-  console.log(`✅ Detected: Codex AI`);
-  detected = true;
-  installCodexSkill();
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ Detected: ${client.label}`);
+    detected = true;
+    installSkill(client);
+  }
 }
 
 if (!detected) {

package/scripts/preuninstall.js

@@ -1,26 +1,17 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
-const path = require('path');
-const os = require('os');
+const { CLIENTS, skillTarget } = require('./lib');
 
-const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-const CLAUDE_SKILL_TARGET = path.join(CLAUDE_HOME, 'skills', 'agentic-sdlc');
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-const CODEX_SKILL_TARGET = path.join(CODEX_HOME, 'skills', 'agentic-sdlc');
-const GEMINI_HOME = process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini');
-const GEMINI_SKILL_TARGET = path.join(GEMINI_HOME, 'skills', 'agentic-sdlc');
-
-function removeSkill(target, label) {
+function removeSkill(client) {
+  const target = skillTarget(client);
   if (!fs.existsSync(target)) return;
   try {
     fs.rmSync(target, { recursive: true, force: true });
-    console.log(`🧹 Removed ${label} skill at: ${target}`);
+    console.log(`🧹 Removed ${client.label} skill at: ${target}`);
   } catch (err) {
     console.log(`⚠️  Could not remove ${target}: ${err.message}`);
   }
 }
 
-removeSkill(CLAUDE_SKILL_TARGET, 'Claude Code');
-removeSkill(CODEX_SKILL_TARGET, 'Codex');
-removeSkill(GEMINI_SKILL_TARGET, 'Gemini');
+CLIENTS.forEach(removeSkill);

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

@@ -1,55 +1,56 @@
-# 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).
+# Mechanical enforcement (optional, recommended for teams)
+
+Prompt-level rules depend on the model's discipline and degrade with long contexts, compaction and competing instructions. Three levels of increasing guarantee:
+
+## 1. Interactive validation (default, no setup)
+
+The agent runs a single gate at closure (Phase 5):
+
+```
+python "<skill_dir>/scripts/sdlc_check.py" check
+```
+
+(`check` = validate + stale in one command.) Exit code ≠ 0 ⇒ the feature is not declared closed. This is the minimum level the skill expects.
+
+## 2. Check in CI (recommended for teams)
+
+Copy `scripts/sdlc_check.py` into the repository (e.g. `tools/sdlc_check.py`) and add to the pipeline:
+
+```
+python tools/sdlc_check.py validate --strict
+```
+
+Effect: an unregenerated index, invalid frontmatter, a missing security section or incoherent states **block the pipeline** instead of relying on the agent's memory. `--strict` also fails on warnings and on a missing `ai_docs/`, so a wrong working directory cannot produce a green pipeline. This works because documents travel in the same PR as the code (Phase 5 rule).
+
+Note: the copy in the repo is the authoritative one for CI; update it when you update the skill.
+
+## 3. PreToolUse hook (gate on writes)
+
+Blocks Edit/Write on protected paths when no `ANALYSIS_*.md` is `IN_PROGRESS`. In the project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\<user>\\.claude\\skills\\agentic-sdlc\\scripts\\sdlc_check.py\" gate --hook --protected \"src/auth;src/crypto\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Semantics: exit code 2 + message on stderr ⇒ the write is blocked and the message is shown to the agent, which must create the ANALYSIS (Phase 3) before retrying.
+
+**Usage warnings:**
+- The gate is deliberately coarse: applied to all of `src/` it would also block the legitimate L1/L2 tasks foreseen by the Triage. Use it **only on security-critical directories** (`--protected "src/auth;src/crypto"`), where "never without analysis" is the desired policy.
+- The paths in `--protected` are prefixes relative to the project root, separated by `;`.
+- `ai_docs/`, `tests/` and `test/` are always excluded from blocking.
+- The hook assumes the working directory is the project root (standard behavior of Claude Code hooks).
+- **Hybrid/devPNT projects**: add `--hybrid` to the gate command. Governed designs live in the devPNT DB, so the gate also unlocks when an approved E-TDD shadow (`ai_docs/solutions/SHADOW_*tdd*.md`, exported before implementation — see the SKILL.md shadow discipline) is present. Without the flag the gate would block legitimate governed work. The flag is deliberately explicit: never auto-detected.