@antoneeo/agentic-sdlc-skill 1.3.1 → 1.5.0

package/scripts/init.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const fs = require('fs');
 const path = require('path');
@@ -17,63 +17,133 @@ function checkCommand(cmd) {
 }
 
 // 1. Path definitions
-const directories = [
-  path.join(cwd, 'ai_docs'),
-  path.join(cwd, 'ai_docs', 'strategic'),
-  path.join(cwd, 'ai_docs', 'audit'),
-  path.join(cwd, 'ai_docs', 'solutions')
-];
-
-const files = {
-  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'),
+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')
-};
+  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 strictly following a "Documentation-First" process. NEVER implement code without completing the preceding documentation steps. Use your tools (file read/write, shell execution) to adhere to the following phases.
-
-## 1. Audit and Alignment Phase
-Before responding to any operational request:
-- Check for the existence of the \`ai_docs/\` folder.
-- If \`ai_docs/\` is missing or essential documents are absent, create them by analyzing the source code:
-    1. \`ai_docs/strategic/architecture.md\`: Tech Stack, Directory Structure, Architecture Patterns.
-    2. \`ai_docs/strategic/existing_features.md\`: List of current features.
-    3. \`ai_docs/strategic/features_history.md\`: Feature history table (ID, Name, Status, Dates).
-    4. \`ai_docs/audit/audit_plan.md\`: Codebase analysis plan in batches.
-
-## 2. Request Analysis Phase
-For every new feature request:
-- Create \`ai_docs/solutions/ANALYSIS_[feature_name].md\` (Objective, Impact, Action Plan, Test Strategy).
-- Add an entry in \`ai_docs/strategic/features_history.md\` with status \`[PLANNED]\`.
-
-## 3. Development and Testing Phase
-Only after Phase 2 is complete:
-1. Update feature status to \`[IN_PROGRESS]\` in \`ai_docs/strategic/features_history.md\`.
-2. Implement code surgically following the plan.
-3. **Mandatory:** Write automated tests following the **AAA (Arrange, Act, Assert)** pattern.
-4. Execute tests. If they fail, fix and re-run until Exit Code is 0.
-
-## 4. Closing Phase
-Upon feature completion:
-- Update \`ai_docs/strategic/architecture.md\` and \`ai_docs/strategic/existing_features.md\` if necessary.
-- Update \`ai_docs/strategic/features_history.md\` setting status to \`[COMPLETED]\`.
-`;
-
-const historyBoilerplate = `# Feature History
-
-| ID | Feature Name | Status | Start Date | End Date | Analysis Doc | Notes |
-|:---|:---|:---|:---|:---|:---|:---|
-| 000 | Project Init | [COMPLETED] | - | - | - | Automatic initialization |
-`;
+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)...');
 
@@ -95,12 +165,15 @@ const writeIfNotExists = (filePath, content, description) => {
     console.log(`⏭️  Skipped: ${path.relative(cwd, filePath)} already exists.`);
     return false;
   }
-};
-
-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\n| Directory/File | Status | Notes |\n|:---|:---|:---|\n| / | [PENDING] | Initial analysis |\n', 'Audit Plan');
+};
+
+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('\n--- Environment Analysis ---');
@@ -115,17 +188,17 @@ if (checkCommand('gemini')) {
   writeIfNotExists(files.geminiConfig, protocolContent, 'Gemini Configuration');
 }
 
-if (checkCommand('codex')) {
-  console.log('✅ Codex AI detected.');
-  writeIfNotExists(files.codexAgents, protocolContent, 'Codex AGENTS.md');
-}
+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');
 
 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. 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.');

package/scripts/postinstall.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { execSync } = require('child_process');
 const fs = require('fs');
@@ -10,9 +10,12 @@ 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 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 {
@@ -56,7 +59,7 @@ function installClaudeSkill() {
   }
 }
 
-function installCodexSkill() {
+function installCodexSkill() {
   if (!fs.existsSync(SKILL_SOURCE)) {
     console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Codex install.`);
     return false;
@@ -72,15 +75,37 @@ function installCodexSkill() {
     console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CODEX_SKILL_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 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 ---');
 
@@ -92,10 +117,11 @@ if (checkCommand('claude') || hasClaudeHome()) {
   installClaudeSkill();
 }
 
-if (checkCommand('gemini')) {
-  console.log(`✅ Detected: Gemini CLI`);
-  detected = true;
-}
+if (checkCommand('gemini') || hasGeminiHome()) {
+  console.log(`✅ Detected: Gemini CLI`);
+  detected = true;
+  installGeminiSkill();
+}
 
 if (checkCommand('codex') || hasCodexHome()) {
   console.log(`✅ Detected: Codex AI`);

package/scripts/preuninstall.js

@@ -6,8 +6,10 @@ const os = require('os');
 
 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 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) {
   if (!fs.existsSync(target)) return;
@@ -19,5 +21,6 @@ function removeSkill(target, label) {
   }
 }
 
-removeSkill(CLAUDE_SKILL_TARGET, 'Claude Code');
-removeSkill(CODEX_SKILL_TARGET, 'Codex');
+removeSkill(CLAUDE_SKILL_TARGET, 'Claude Code');
+removeSkill(CODEX_SKILL_TARGET, 'Codex');
+removeSkill(GEMINI_SKILL_TARGET, 'Gemini');

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).