@antoneeo/agentic-sdlc-skill 1.10.0 → 1.12.0

package/README.md

@@ -1,87 +1,88 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
-
-`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Cursor/Windsurf-style project instructions, and optional devPNT governance.
-
-## Key Features
-
-- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
-- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
-- **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
-- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer.
-- **Installed support files**: Claude, Codex, and Gemini receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`; an agent-global KB at `~/.agentic-sdlc` shares the same engine cross-project.
-- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
-
-## Installation
-
-### Via npm
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill@latest
-agentic-sdlc-install-skill
-```
-
-The installer copies `skills/agentic-sdlc-skill/` recursively into native skill locations:
-
-- Claude Code: `~/.claude/skills/agentic-sdlc/`
-- Codex: `~/.codex/skills/agentic-sdlc/`
-- Gemini CLI: `~/.gemini/skills/agentic-sdlc/`
-
-Restart the relevant agent, or reload skills where the CLI supports it.
-
-The global package also exposes:
-
-```bash
-agentic-sdlc-init
-```
-
-Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
-
-## Runtime Shape
-
-The actual runtime skill is the folder:
-
-```text
-skills/agentic-sdlc-skill/
-├── SKILL.md
-├── templates.md
-├── guides.md
-├── tdd.md
-├── debugging.md
-├── elicitation.md
-├── review.md
-├── dispatch.md
-├── ENFORCEMENT.md
-└── scripts/
-    └── sdlc_check.py
-```
-
-`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
-
-## Standalone vs Hybrid
-
-Standalone:
-
-- `ai_docs/` is the source of truth.
-- Vision, analysis, audit, handoff, test strategy, and feature history are maintained locally.
-
-Hybrid/devPNT:
-
-- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
-- `ai_docs/` remains useful as readable context, fallback, handoff, or shadow copy.
-- Divergence between user request, local Vision, and devPNT `M-VISION` must be surfaced before implementation.
-
-## Gemini Extension Alternative
-
-You can still install this folder as a Gemini extension:
-
-```bash
-gemini extensions install .
-```
-
-For native Gemini Agent Skills, the npm installer now copies the skill folder into `~/.gemini/skills/agentic-sdlc/`.
-
-## Created By
-
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
-
-(c) 2026 Antonio Pinto. All rights reserved.
+# Agentic SDLC Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
+
+`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+
+## Key Features
+
+- **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
+- **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
+- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer.
+- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`; an agent-global KB at `~/.agentic-sdlc` shares the same engine cross-project.
+- **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
+
+## Installation
+
+### Via npm
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
+```
+
+The installer copies `skills/agentic-sdlc-skill/` recursively into native skill locations:
+
+- Claude Code: `~/.claude/skills/agentic-sdlc/`
+- Codex: `~/.codex/skills/agentic-sdlc/`
+- Gemini CLI: `~/.gemini/skills/agentic-sdlc/`
+- Google Antigravity: `~/.gemini/config/skills/agentic-sdlc/` (detected distinctly from Gemini CLI; override the home with `ANTIGRAVITY_HOME`)
+
+Restart the relevant agent, or reload skills where the CLI supports it.
+
+The global package also exposes:
+
+```bash
+agentic-sdlc-init
+```
+
+Run it inside a project to create `ai_docs/`, Vision documents, strategic docs, audit plan, and agent protocol files (`AGENTS.md` — also the Antigravity CLI surface, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
+
+## Runtime Shape
+
+The actual runtime skill is the folder:
+
+```text
+skills/agentic-sdlc-skill/
+├── SKILL.md
+├── templates.md
+├── guides.md
+├── tdd.md
+├── debugging.md
+├── elicitation.md
+├── review.md
+├── dispatch.md
+├── ENFORCEMENT.md
+└── scripts/
+    └── sdlc_check.py
+```
+
+`SKILL.md` is the entrypoint. Supporting files are loaded or executed only when the agent needs them.
+
+## Standalone vs Hybrid
+
+Standalone:
+
+- `ai_docs/` is the source of truth.
+- Vision, analysis, audit, handoff, test strategy, and feature history are maintained locally.
+
+Hybrid/devPNT:
+
+- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
+- `ai_docs/` remains useful as readable context, fallback, handoff, or shadow copy.
+- Divergence between user request, local Vision, and devPNT `M-VISION` must be surfaced before implementation.
+
+## Gemini Extension Alternative
+
+You can still install this folder as a Gemini extension:
+
+```bash
+gemini extensions install .
+```
+
+For native Gemini Agent Skills, the npm installer now copies the skill folder into `~/.gemini/skills/agentic-sdlc/`.
+
+## Created By
+
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo)).
+
+(c) 2026 Antonio Pinto. All rights reserved.

package/gemini-extension.json

@@ -1,6 +1,6 @@
-{
-  "name": "agentic-sdlc-skill",
-  "version": "1.10.0",
-  "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
-  "author": "Antonio Pinto (https://github.com/Antoneeo)"
-}
+{
+  "name": "agentic-sdlc-skill",
+  "version": "1.12.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,43 +1,46 @@
-{
-  "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.10.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",
-    "gemini-cli",
-    "skill",
-    "sdlc",
-    "documentation",
-    "ai-agent"
-  ],
-  "author": "Antonio Pinto (https://github.com/Antoneeo)",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "agentic-sdlc-init": "scripts/init.js",
-    "agentic-sdlc-install-skill": "scripts/postinstall.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "preuninstall": "node scripts/preuninstall.js"
-  },
-  "files": [
-    "skills/agentic-sdlc-skill/SKILL.md",
-    "skills/agentic-sdlc-skill/templates.md",
-    "skills/agentic-sdlc-skill/guides.md",
-    "skills/agentic-sdlc-skill/tdd.md",
-    "skills/agentic-sdlc-skill/debugging.md",
-    "skills/agentic-sdlc-skill/elicitation.md",
-    "skills/agentic-sdlc-skill/review.md",
-    "skills/agentic-sdlc-skill/dispatch.md",
-    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
-    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
-    "gemini-extension.json",
-    "README.md",
-    "CHANGELOG.md",
-    "scripts"
-  ]
-}
+{
+  "name": "@antoneeo/agentic-sdlc-skill",
+  "version": "1.12.0",
+  "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "gemini-cli",
+    "skill",
+    "sdlc",
+    "documentation",
+    "ai-agent"
+  ],
+  "author": "Antonio Pinto (https://github.com/Antoneeo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agentic-sdlc-init": "scripts/init.js",
+    "agentic-sdlc-install-skill": "scripts/postinstall.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  },
+  "files": [
+    "skills/agentic-sdlc-skill/SKILL.md",
+    "skills/agentic-sdlc-skill/templates.md",
+    "skills/agentic-sdlc-skill/guides.md",
+    "skills/agentic-sdlc-skill/tdd.md",
+    "skills/agentic-sdlc-skill/debugging.md",
+    "skills/agentic-sdlc-skill/elicitation.md",
+    "skills/agentic-sdlc-skill/review.md",
+    "skills/agentic-sdlc-skill/dispatch.md",
+    "skills/agentic-sdlc-skill/ENFORCEMENT.md",
+    "skills/agentic-sdlc-skill/scripts/sdlc_check.py",
+    "gemini-extension.json",
+    "README.md",
+    "CHANGELOG.md",
+    "scripts/lib.js",
+    "scripts/init.js",
+    "scripts/postinstall.js",
+    "scripts/preuninstall.js"
+  ]
+}

package/scripts/init.js

@@ -1,153 +1,154 @@
-#!/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();
-
-// 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);
-}
-
-// 4. Create directories
-directories.forEach((dir) => {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
-  }
-});
-
-// 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: ${relPath}${description ? ` (${description})` : ''}`);
-    return true;
-  }
-  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 ---');
-
-const protocolFiles = {
-  claude: 'CLAUDE.md',
-  gemini: 'GEMINI.md',
-  codex: 'AGENTS.md',
-};
-
-for (const client of CLIENTS) {
-  if (clientDetected(client)) {
-    console.log(`✅ ${client.label} detected.`);
-    writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
-  }
-}
-
-// Cursor/Windsurf (always recommended)
-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. 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.');
+#!/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();
+
+// 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);
+}
+
+// 4. Create directories
+directories.forEach((dir) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    console.log(`📁 Created directory: ${path.relative(cwd, dir)}`);
+  }
+});
+
+// 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: ${relPath}${description ? ` (${description})` : ''}`);
+    return true;
+  }
+  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 ---');
+
+const protocolFiles = {
+  claude: 'CLAUDE.md',
+  gemini: 'GEMINI.md',
+  codex: 'AGENTS.md',
+  antigravity: 'AGENTS.md', // Antigravity CLI reads AGENTS.md; single protocolContent reused.
+};
+
+for (const client of CLIENTS) {
+  if (clientDetected(client)) {
+    console.log(`✅ ${client.label} detected.`);
+    writeIfNotExists(protocolFiles[client.key], protocolContent, `${client.label} protocol pointer`);
+  }
+}
+
+// Cursor/Windsurf (always recommended)
+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. 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.');