docguard-cli 0.9.8 → 0.9.9

package/cli/commands/diagnose.mjs

@@ -16,6 +16,7 @@
 import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
+import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -35,23 +36,26 @@ const VALIDATOR_TO_DOC = {
   'Freshness':     null,       // freshness — maps to stale doc
 };
 
-// Actionable fix instructions per validator
+// Actionable fix instructions per validator (LLM-first: includes both skill and CLI commands)
 const FIX_INSTRUCTIONS = {
   'Structure': {
     action: 'Create missing files',
     command: 'docguard init',
+    llmCommand: '/docguard.init',
     description: 'Run init to create missing documentation templates.',
     autoFixable: true,
   },
   'Doc Sections': {
     action: 'Fill document sections',
     command: 'docguard fix --doc',
-    description: 'Documents exist but have missing or placeholder sections. Use fix --doc to generate AI content prompts.',
+    llmCommand: '/docguard.fix --doc',
+    description: 'Documents exist but have missing or placeholder sections. Use the docguard-fix skill to generate content.',
     autoFixable: false,
   },
   'Docs-Sync': {
     action: 'Sync documentation references',
     command: 'docguard fix --doc architecture',
+    llmCommand: '/docguard.fix --doc architecture',
     description: 'Documentation references are out of sync with code. Review and update component maps.',
     autoFixable: false,
   },
@@ -68,35 +72,44 @@ const FIX_INSTRUCTIONS = {
   'Test-Spec': {
     action: 'Update TEST-SPEC.md',
     command: 'docguard fix --doc test-spec',
+    llmCommand: '/docguard.fix --doc test-spec',
     description: 'Test documentation needs updating to match actual test structure.',
     autoFixable: false,
   },
   'Environment': {
     action: 'Update ENVIRONMENT.md',
     command: 'docguard fix --doc environment',
+    llmCommand: '/docguard.fix --doc environment',
     description: 'Environment documentation is missing or incomplete.',
     autoFixable: false,
   },
   'Security': {
     action: 'Update SECURITY.md',
     command: 'docguard fix --doc security',
+    llmCommand: '/docguard.fix --doc security',
     description: 'Security documentation needs updating.',
     autoFixable: false,
   },
   'Architecture': {
     action: 'Update ARCHITECTURE.md',
     command: 'docguard fix --doc architecture',
+    llmCommand: '/docguard.fix --doc architecture',
     description: 'Architecture documentation doesn\'t match the codebase.',
     autoFixable: false,
   },
   'Freshness': {
     action: 'Review stale documents',
+    command: 'docguard fix --doc',
+    llmCommand: '/docguard.fix --doc',
     description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
     autoFixable: false,
   },
 };
 
 export function runDiagnose(projectDir, config, flags) {
+  // ── Step 0: Detect agent mode (LLM-first) ──
+  const agentMode = detectAgentMode(projectDir);
+
   // ── Step 1: Run guard internally ──
   let guardData = runGuardInternal(projectDir, config);
   const scoreData = runScoreInternal(projectDir, config);
@@ -140,10 +153,15 @@ export function runDiagnose(projectDir, config, flags) {
         }
       }
     } else if (!shouldAutoFix && (hasStructural || autoFixable.length > 0) && (!flags.format || flags.format === 'text')) {
-      // Suggest-only mode: tell user what they can do
+      // Suggest-only mode: tell user what they can do (LLM-first)
       console.log(`  ${c.yellow}💡 ${autoFixable.length + (hasStructural ? 1 : 0)} issue(s) can be auto-fixed.${c.reset} Run with ${c.cyan}--auto${c.reset} to create/regenerate docs, or manually:`);
-      if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
-      if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+      if (agentMode === 'llm') {
+        if (hasStructural) console.log(`     ${c.dim}/docguard.init${c.reset}`);
+        if (autoFixable.length > 0) console.log(`     ${c.dim}/docguard.fix${c.reset}`);
+      } else {
+        if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
+        if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+      }
       console.log('');
     }
   }
@@ -157,7 +175,9 @@ export function runDiagnose(projectDir, config, flags) {
         const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
         issue.docTarget = docMap[docName] || null;
         if (issue.docTarget) {
-          issue.command = `docguard fix --doc ${issue.docTarget}`;
+          issue.command = agentMode === 'llm'
+            ? `/docguard.fix --doc ${issue.docTarget}`
+            : `docguard fix --doc ${issue.docTarget}`;
         }
       }
     }
@@ -167,9 +187,9 @@ export function runDiagnose(projectDir, config, flags) {
   if (flags.format === 'json') {
     outputJSON(guardData, scoreData, issues);
   } else if (flags.format === 'prompt') {
-    outputPrompt(projectDir, guardData, scoreData, issues, flags);
+    outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode);
   } else {
-    outputText(projectDir, guardData, scoreData, issues, flags);
+    outputText(projectDir, guardData, scoreData, issues, flags, agentMode);
   }
 }
 
@@ -191,6 +211,7 @@ function collectIssues(guardData) {
         message: err,
         action: fixInfo.action,
         command: fixInfo.command || null,
+        llmCommand: fixInfo.llmCommand || null,
         docTarget,
         autoFixable: fixInfo.autoFixable || false,
       });
@@ -202,6 +223,7 @@ function collectIssues(guardData) {
         message: warn,
         action: fixInfo.action,
         command: fixInfo.command || null,
+        llmCommand: fixInfo.llmCommand || null,
         docTarget,
         autoFixable: fixInfo.autoFixable || false,
       });
@@ -233,14 +255,18 @@ function outputJSON(guardData, scoreData, issues) {
   console.log(JSON.stringify(result, null, 2));
 }
 
-function outputText(projectDir, guardData, scoreData, issues, flags) {
+function outputText(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm') {
   console.log(`${c.bold}🔍 DocGuard Diagnose — ${guardData.project}${c.reset}`);
-  console.log(`${c.dim}   Profile: ${guardData.profile} | Score: ${scoreData.score}/100 (${scoreData.grade})${c.reset}`);
+  console.log(`${c.dim}   Profile: ${guardData.profile} | Score: ${scoreData.score}/100 (${scoreData.grade}) | Mode: ${agentMode.toUpperCase()}${c.reset}`);
   console.log(`${c.dim}   Guard:   ${guardData.passed}/${guardData.total} passed | Status: ${guardData.status}${c.reset}\n`);
 
   if (issues.length === 0) {
     console.log(`  ${c.green}${c.bold}✅ All clear!${c.reset} No issues found.\n`);
-    console.log(`  ${c.dim}Your documentation is healthy. Run \`docguard score --tax\` to see maintenance estimate.${c.reset}\n`);
+    if (agentMode === 'llm') {
+      console.log(`  ${c.dim}Your documentation is healthy. Use ${c.cyan}/docguard.guard${c.dim} to re-validate after changes.${c.reset}\n`);
+    } else {
+      console.log(`  ${c.dim}Your documentation is healthy. Run \`docguard score --tax\` to see maintenance estimate.${c.reset}\n`);
+    }
     return;
   }
 
@@ -252,7 +278,8 @@ function outputText(projectDir, guardData, scoreData, issues, flags) {
     console.log(`  ${c.red}${c.bold}Errors (${errors.length}):${c.reset}`);
     for (const e of errors) {
       console.log(`  ${c.red}✗${c.reset} [${e.validator}] ${e.message}`);
-      if (e.command) console.log(`    ${c.dim}Fix: ${e.command}${c.reset}`);
+      const cmd = agentMode === 'llm' && e.llmCommand ? e.llmCommand : e.command;
+      if (cmd) console.log(`    ${c.dim}Fix: ${cmd}${c.reset}`);
     }
     console.log('');
   }
@@ -261,19 +288,21 @@ function outputText(projectDir, guardData, scoreData, issues, flags) {
     console.log(`  ${c.yellow}${c.bold}Warnings (${warnings.length}):${c.reset}`);
     for (const w of warnings) {
       console.log(`  ${c.yellow}⚠${c.reset} [${w.validator}] ${w.message}`);
-      if (w.command) console.log(`    ${c.dim}Fix: ${w.command}${c.reset}`);
+      const cmd = agentMode === 'llm' && w.llmCommand ? w.llmCommand : w.command;
+      if (cmd) console.log(`    ${c.dim}Fix: ${cmd}${c.reset}`);
     }
     console.log('');
   }
 
-  // ── Remediation Plan ──
+  // ── Remediation Plan (LLM-first) ──
   const commands = [...new Set(issues.filter(i => i.command).map(i => i.command))];
   if (commands.length > 0) {
     console.log(`  ${c.bold}📋 Remediation Plan:${c.reset}`);
     for (let i = 0; i < commands.length; i++) {
       console.log(`  ${c.cyan}${i + 1}. ${commands[i]}${c.reset}`);
     }
-    console.log(`  ${c.cyan}${commands.length + 1}. docguard guard${c.reset} ${c.dim}← verify fixes${c.reset}`);
+    const verifyCmd = agentMode === 'llm' ? '/docguard.guard' : 'docguard guard';
+    console.log(`  ${c.cyan}${commands.length + 1}. ${verifyCmd}${c.reset} ${c.dim}← verify fixes${c.reset}`);
     console.log('');
   }
 
@@ -282,15 +311,15 @@ function outputText(projectDir, guardData, scoreData, issues, flags) {
     // Multi-perspective debate prompts (AITPG/TRACE-inspired)
     console.log(`  ${c.bold}🤖 Multi-Perspective AI Debate Prompt:${c.reset}`);
     console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
-    outputDebatePrompt(projectDir, guardData, scoreData, issues);
+    outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode);
   } else {
     console.log(`  ${c.bold}🤖 AI-Ready Prompt:${c.reset}`);
     console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
-    outputPrompt(undefined, guardData, scoreData, issues, flags);
+    outputPrompt(undefined, guardData, scoreData, issues, flags, agentMode);
   }
 }
 
-function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
+function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm') {
   if (issues.length === 0) {
     console.log('No issues to fix. Documentation is healthy.');
     return;
@@ -345,7 +374,11 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
 
   lines.push('');
   lines.push('VALIDATION:');
-  lines.push('After making all fixes, run: docguard guard');
+  if (agentMode === 'llm') {
+    lines.push('After making all fixes, use the /docguard.guard skill to verify');
+  } else {
+    lines.push('After making all fixes, run: docguard guard');
+  }
   lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
   lines.push(`Target score: ≥${Math.min(scoreData.score + 5, 100)}/100`);
 
@@ -354,9 +387,15 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
     lines.push('');
     lines.push('VERIFICATION CHECKLIST (complete each step):');
     lines.push('□ Read each file in docs-canonical/ before editing');
-    lines.push('□ Run `docguard guard` after each file change');
-    lines.push('□ Confirm 0 errors before moving to next issue');
-    lines.push('□ Run `docguard score` to confirm improvement');
+    if (agentMode === 'llm') {
+      lines.push('□ Run /docguard.guard after each file change');
+      lines.push('□ Confirm 0 errors before moving to next issue');
+      lines.push('□ Run /docguard.score to confirm improvement');
+    } else {
+      lines.push('□ Run `docguard guard` after each file change');
+      lines.push('□ Confirm 0 errors before moving to next issue');
+      lines.push('□ Run `docguard score` to confirm improvement');
+    }
   }
 
   console.log(lines.join('\n'));
@@ -368,7 +407,7 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
  * and TRACE adversarial debate (Advocate/Challenger/Mediator/Explainer).
  * Lopez et al., IEEE TSE/TMLCN 2026.
  */
-function outputDebatePrompt(projectDir, guardData, scoreData, issues) {
+function outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode = 'llm') {
   const lines = [];
 
   lines.push('═══════════════════════════════════════════════════════');
@@ -427,7 +466,8 @@ function outputDebatePrompt(projectDir, guardData, scoreData, issues) {
   lines.push('   a. Which file to edit');
   lines.push('   b. What section to add or modify');
   lines.push('   c. What content to write (be specific, not vague)');
-  lines.push('4. After all fixes, verify with: docguard guard');
+  const verifyCmd = agentMode === 'llm' ? '/docguard.guard' : 'docguard guard';
+  lines.push(`4. After all fixes, verify with: ${verifyCmd}`);
   lines.push(`5. Target score: ≥${Math.min(scoreData.score + 10, 100)}/100`);
   lines.push('');
   lines.push('═══════════════════════════════════════════════════════');

package/cli/commands/fix.mjs

@@ -453,7 +453,7 @@ function generateDocPrompt(projectDir, config, docName) {
 
   console.log(expectations.aiResearchInstructions.trim());
 
-  console.log(`\nVALIDATION: After writing, run \`npx docguard guard\` to verify the document passes all checks.`);
+  console.log(`\nVALIDATION: After writing, run \`npx docguard-cli guard\` to verify the document passes all checks.`);
   console.log(`The document should have NO <!-- TODO --> or <!-- e.g. --> placeholders.`);
   console.log(`Set the docguard:status header to 'active' (not 'draft').`);
 }

package/cli/commands/guard.mjs

@@ -8,6 +8,7 @@
  */
 
 import { c } from '../shared.mjs';
+import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -197,7 +198,12 @@ export function runGuard(projectDir, config, flags) {
 
   // Next step hint — always point to diagnose when issues exist
   if (data.status !== 'PASS') {
-    console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${c.reset}`);
+    const agentMode = detectAgentMode(projectDir);
+    if (agentMode === 'llm') {
+      console.log(`  ${c.dim}Use ${c.cyan}/docguard.diagnose${c.dim} to get AI fix prompts.${c.reset}`);
+    } else {
+      console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${c.reset}`);
+    }
   }
 
   // Badge snippet
@@ -206,6 +212,11 @@ export function runGuard(projectDir, config, flags) {
   const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
   console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
 
+  // Spec-kit reminder — persistent nudge if not initialized
+  if (!isSpecKitInitialized(projectDir)) {
+    console.log(`\n  ${c.yellow}💡${c.reset} ${c.dim}Enhance DocGuard with Spec Kit: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
+  }
+
   console.log('');
 
   if (data.errors > 0) process.exit(1);

package/cli/commands/hooks.mjs

@@ -20,7 +20,7 @@ echo "🛡️  Running DocGuard guard..."
 
 # Check if docguard is available
 if command -v npx &> /dev/null; then
-  npx docguard guard
+  npx docguard-cli guard
   EXIT_CODE=$?
 elif command -v docguard &> /dev/null; then
   docguard guard
@@ -60,7 +60,7 @@ echo "📊 Running DocGuard score check (minimum: $MIN_SCORE)..."
 
 # Get score as JSON
 if command -v npx &> /dev/null; then
-  RESULT=$(npx docguard score --format json 2>/dev/null)
+  RESULT=$(npx docguard-cli score --format json 2>/dev/null)
 elif command -v docguard &> /dev/null; then
   RESULT=$(docguard score --format json 2>/dev/null)
 else

package/cli/commands/init.mjs

@@ -1,14 +1,21 @@
 /**
  * Init Command — Initialize CDD documentation from templates
- * Interactive setup: asks which docs the user needs + suggests hooks.
+ *
+ * Extension-First: When `specify` CLI is available, DocGuard delegates
+ * LLM/IDE detection and spec-kit skill installation to spec-kit.
+ * DocGuard then layers CDD-specific docs on top.
+ *
+ * Fallback: When `specify` is not available, DocGuard runs standalone
+ * with a warning suggesting spec-kit installation.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
 import { c, PROFILES } from '../shared.mjs';
-import { ensureSkills } from '../ensure-skills.mjs';
+import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
@@ -189,61 +196,57 @@ export async function runInit(projectDir, config, flags) {
     console.log(`  ${c.yellow}⏭️${c.reset}  .docguard.json ${c.dim}(already exists)${c.reset}`);
   }
 
-  // ── Slash commands for AI agents ───────────────────────────────────────
-  const commandsSourceDir = resolve(TEMPLATES_DIR, 'commands');
-  if (existsSync(commandsSourceDir)) {
-    const commandFiles = readdirSync(commandsSourceDir).filter(f => f.endsWith('.md'));
-
-    const agentDirs = [
-      { name: 'GitHub Copilot', path: '.github/commands' },
-      { name: 'Cursor', path: '.cursor/rules' },
-      { name: 'Google Gemini', path: '.gemini/commands' },
-      { name: 'Claude Code', path: '.claude/commands' },
-      { name: 'Antigravity', path: '.agents/workflows' },
-    ];
-
-    const detected = agentDirs.filter(a =>
-      existsSync(resolve(projectDir, a.path.split('/')[0]))
-    );
-
-    const targets = detected.length > 0
-      ? detected
-      : [{ name: 'GitHub (default)', path: '.github/commands' }];
-
-    let totalCreated = 0;
-    const installedLocations = [];
-
-    for (const target of targets) {
-      const destDir = resolve(projectDir, target.path);
-      if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-      }
+  // ── Spec-Kit Integration (Extension-First) ────────────────────────────
+  // Delegate LLM/IDE detection and spec-kit skill install to `specify init`
+  const specKitAvailable = isSpecKitAvailable();
+  const specKitInitialized = isSpecKitInitialized(projectDir);
 
-      let dirCreated = 0;
-      for (const file of commandFiles) {
-        const destPath = resolve(destDir, file);
-        if (!existsSync(destPath)) {
-          const content = readFileSync(resolve(commandsSourceDir, file), 'utf-8');
-          writeFileSync(destPath, content, 'utf-8');
-          dirCreated++;
-        }
-      }
+  if (specKitAvailable && !specKitInitialized) {
+    console.log(`\n  ${c.bold}🌱 Spec Kit Integration${c.reset}`);
 
-      if (dirCreated > 0) {
-        totalCreated += dirCreated;
-        installedLocations.push(`${target.path}/ (${target.name})`);
-      }
-    }
+    // Detect which AI agent is in use (matches spec-kit's --ai flag)
+    const detectedAgent = detectAIAgent(projectDir);
+    const aiFlag = detectedAgent
+      ? `--ai ${detectedAgent}`
+      : '--ai generic --ai-commands-dir .agent/commands/';
 
-    if (totalCreated > 0) {
-      created.push(`slash commands (${installedLocations.length} location(s))`);
-      console.log(`  ${c.green}✅${c.reset} Installed ${c.cyan}slash commands${c.reset} for AI agents:`);
-      for (const loc of installedLocations) {
-        console.log(`     ${c.dim}→ ${loc}${c.reset}`);
-      }
-    } else {
-      console.log(`  ${c.yellow}⏭️${c.reset}  Slash commands ${c.dim}(already installed)${c.reset}`);
+    console.log(`  ${c.dim}Running specify init (agent: ${detectedAgent || 'generic'})...${c.reset}`);
+    try {
+      const scriptFlag = process.platform === 'win32' ? '--script ps' : '--script sh';
+      execSync(
+        `specify init --here --force ${aiFlag} --ai-skills --ignore-agent-tools --no-git ${scriptFlag}`,
+        { cwd: projectDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30000 }
+      );
+      console.log(`  ${c.green}✅${c.reset} Spec Kit initialized ${c.dim}(.specify/, spec-kit skills, agent: ${detectedAgent || 'generic'})${c.reset}`);
+      created.push('.specify/ (spec-kit foundation)');
+    } catch (err) {
+      console.log(`  ${c.yellow}⚠️${c.reset}  Spec Kit init had issues ${c.dim}(continuing with DocGuard standalone)${c.reset}`);
+      if (flags.debug) console.log(`     ${c.dim}${err.message}${c.reset}`);
     }
+  } else if (specKitInitialized) {
+    const agent = getDetectedAgent(projectDir);
+    console.log(`\n  ${c.green}✅${c.reset} Spec Kit already initialized${agent ? ` ${c.dim}(agent: ${agent})${c.reset}` : ''}`);
+  } else {
+    console.log(`\n  ${c.red}┌─────────────────────────────────────────────────────────────┐${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.bold}⚠️  Spec Kit not installed — running in standalone mode${c.reset}     ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}                                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  DocGuard is designed as a Spec Kit extension.               ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  Without Spec Kit, you get ${c.bold}4 skills${c.reset}. With it: ${c.bold}13 skills${c.reset}.    ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}                                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.bold}What you're missing:${c.reset}                                       ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}   • 9 Spec Kit AI skills (specify, plan, tasks, implement)  ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}   • Project constitution (${c.cyan}constitution.md${c.reset})                 ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}   • Full SDD + CDD integrated workflow                     ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}   • AI agent auto-detection and config                     ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}                                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.bold}Install with:${c.reset}                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.cyan}uv tool install specify-cli \\${c.reset}                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.cyan}  --from git+https://github.com/github/spec-kit.git${c.reset}       ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}                                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.dim}Alternative: ${c.cyan}pip install specify-cli${c.reset}                       ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}                                                              ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}│${c.reset}  ${c.dim}Then re-run: ${c.cyan}docguard init${c.reset}                                 ${c.red}│${c.reset}`);
+    console.log(`  ${c.red}└─────────────────────────────────────────────────────────────┘${c.reset}`);
   }
 
   // ── Summary ────────────────────────────────────────────────────────────
@@ -258,35 +261,53 @@ export async function runInit(projectDir, config, flags) {
   console.log(`  ${c.dim}Auto-guard on commit:${c.reset}  ${c.cyan}docguard hooks --type pre-commit${c.reset}`);
   console.log(`  ${c.dim}Auto-guard on push:${c.reset}   ${c.cyan}docguard hooks --type pre-push${c.reset}`);
 
-  // ── Next steps ─────────────────────────────────────────────────────────
+  // ── Next Steps (LLM-First) ─────────────────────────────────────────────
+  const agentMode = detectAgentMode(projectDir);
   const createdDocs = created.filter(f => f.startsWith('docs-canonical/'));
 
   if (createdDocs.length > 0) {
-    console.log(`\n  ${c.bold}🤖 AI Auto-Populate${c.reset}`);
+    console.log(`\n  ${c.bold}🤖 Next Steps${c.reset} ${c.dim}(${agentMode === 'llm' ? 'LLM mode' : 'CLI mode'})${c.reset}`);
     console.log(`  ${c.dim}The files above are skeleton templates. Your AI agent should fill them.${c.reset}`);
-    console.log(`  ${c.dim}Run this single command to get a full remediation plan:${c.reset}\n`);
-    console.log(`  ${c.cyan}${c.bold}docguard diagnose${c.reset}\n`);
-    console.log(`  ${c.dim}Or generate prompts for individual docs:${c.reset}`);
-
-    const docNameMap = {
-      'docs-canonical/ARCHITECTURE.md': 'architecture',
-      'docs-canonical/DATA-MODEL.md': 'data-model',
-      'docs-canonical/SECURITY.md': 'security',
-      'docs-canonical/TEST-SPEC.md': 'test-spec',
-      'docs-canonical/ENVIRONMENT.md': 'environment',
-    };
 
-    for (const doc of createdDocs) {
-      const target = docNameMap[doc];
-      if (target) {
-        console.log(`  ${c.cyan}docguard fix --doc ${target}${c.reset}`);
+    if (agentMode === 'llm') {
+      // LLM-first: show skill commands
+      console.log(`\n  ${c.bold}Use these skills in your AI agent:${c.reset}`);
+      if (isSpecKitInitialized(projectDir)) {
+        console.log(`  ${c.cyan}1. /speckit.constitution${c.reset} ${c.dim}← establish project principles${c.reset}`);
+      }
+      console.log(`  ${c.cyan}${isSpecKitInitialized(projectDir) ? '2' : '1'}. /docguard.guard${c.reset}    ${c.dim}← validate documentation${c.reset}`);
+
+      const docNameMap = {
+        'docs-canonical/ARCHITECTURE.md': 'architecture',
+        'docs-canonical/DATA-MODEL.md': 'data-model',
+        'docs-canonical/SECURITY.md': 'security',
+        'docs-canonical/TEST-SPEC.md': 'test-spec',
+        'docs-canonical/ENVIRONMENT.md': 'environment',
+      };
+
+      const fixTargets = createdDocs.map(d => docNameMap[d]).filter(Boolean);
+      if (fixTargets.length > 0) {
+        console.log(`\n  ${c.dim}Fix individual docs with the docguard-fix skill:${c.reset}`);
+        for (const target of fixTargets) {
+          console.log(`  ${c.cyan}/docguard.fix --doc ${target}${c.reset}`);
+        }
       }
+      console.log(`\n  ${c.dim}Then verify:${c.reset} ${c.cyan}/docguard.guard${c.reset}`);
+    } else {
+      // CLI fallback
+      console.log(`\n  ${c.dim}Get a full remediation plan:${c.reset}`);
+      console.log(`  ${c.cyan}${c.bold}docguard diagnose${c.reset}\n`);
+      console.log(`  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}`);
     }
-    console.log(`\n  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
+    console.log('');
   } else {
-    console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
+    if (agentMode === 'llm') {
+      console.log(`\n  ${c.dim}Use${c.reset} ${c.cyan}/docguard.guard${c.reset} ${c.dim}in your AI agent to check for issues.${c.reset}\n`);
+    } else {
+      console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
+    }
   }
 
-  // Auto-install skills and commands
+  // Auto-install DocGuard skills and commands (spec-kit skills handled by specify init)
   ensureSkills(projectDir, flags);
 }

package/cli/commands/setup.mjs

@@ -13,7 +13,8 @@
  * Each step shows current status (✅/⚠️) and offers to fix what's missing.
  * Supports --skip-prompts for non-interactive CI mode.
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ * Framework dependency: spec-kit (convention, not code).
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
@@ -22,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
 import { c } from '../shared.mjs';
-import { ensureSkills } from '../ensure-skills.mjs';
+import { ensureSkills, detectAgentMode, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -211,11 +212,17 @@ export async function runSetup(projectDir, config, flags) {
 
   console.log(`  ${c.bold}Step 3/7: AI Skills${c.reset}`);
 
-  const skillNames = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const docguardSkills = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const speckitSkills = [
+    'speckit-specify', 'speckit-plan', 'speckit-tasks', 'speckit-implement',
+    'speckit-analyze', 'speckit-clarify', 'speckit-checklist', 'speckit-constitution',
+    'speckit-taskstoissues',
+  ];
+  const allSkillNames = [...docguardSkills, ...speckitSkills];
   const skillsDest = resolve(projectDir, '.agent/skills');
   let missingSkills = [];
 
-  for (const skill of skillNames) {
+  for (const skill of allSkillNames) {
     const skillPath = resolve(skillsDest, skill, 'SKILL.md');
     if (existsSync(skillPath)) {
       console.log(`  ${c.green}✅${c.reset} ${skill}`);
@@ -227,19 +234,28 @@ export async function runSetup(projectDir, config, flags) {
   }
 
   if (missingSkills.length > 0) {
-    const install = interactive
-      ? await askYesNo(`     → Install ${missingSkills.length} AI skill(s) to .agent/skills/?`)
-      : true;
+    const hasSpeckitMissing = missingSkills.some(s => s.startsWith('speckit-'));
+    const hasDocguardMissing = missingSkills.some(s => s.startsWith('docguard-'));
 
-    if (install) {
-      for (const skill of missingSkills) {
-        const srcSkill = resolve(SKILLS_SOURCE, skill, 'SKILL.md');
-        const destDir = resolve(skillsDest, skill);
-        if (existsSync(srcSkill)) {
-          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
-          writeFileSync(resolve(destDir, 'SKILL.md'), readFileSync(srcSkill, 'utf-8'), 'utf-8');
-          console.log(`     ${c.green}✅ Installed ${skill}${c.reset}`);
-          configured++;
+    if (hasSpeckitMissing) {
+      console.log(`  ${c.dim}   Spec-kit skills installed via: ${c.cyan}specify init --here --force --ai-skills${c.reset}`);
+    }
+
+    if (hasDocguardMissing) {
+      const install = interactive
+        ? await askYesNo(`     → Install ${missingSkills.filter(s => s.startsWith('docguard-')).length} DocGuard skill(s) to .agent/skills/?`)
+        : true;
+
+      if (install) {
+        for (const skill of missingSkills.filter(s => s.startsWith('docguard-'))) {
+          const srcSkill = resolve(SKILLS_SOURCE, skill, 'SKILL.md');
+          const destDir = resolve(skillsDest, skill);
+          if (existsSync(srcSkill)) {
+            if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+            writeFileSync(resolve(destDir, 'SKILL.md'), readFileSync(srcSkill, 'utf-8'), 'utf-8');
+            console.log(`     ${c.green}✅ Installed ${skill}${c.reset}`);
+            configured++;
+          }
         }
       }
     }
@@ -354,16 +370,20 @@ export async function runSetup(projectDir, config, flags) {
 
   console.log(`  ${c.bold}Step 6/7: Integrations${c.reset}`);
 
-  // Check spec-kit framework
-  const speckitDir = resolve(projectDir, '.speckit');
-  const hasSpeckit = existsSync(speckitDir) || existsSync(resolve(projectDir, 'spec.md'));
-  if (hasSpeckit) {
-    console.log(`  ${c.green}✅${c.reset} spec-kit ${c.dim}(spec-driven development configured)${c.reset}`);
+  // Check spec-kit framework (Extension-First: detect .specify/ directory)
+  const specKitInitialized = isSpecKitInitialized(projectDir);
+  const specifyDir = resolve(projectDir, '.specify');
+  if (specKitInitialized) {
+    const agent = getDetectedAgent(projectDir);
+    console.log(`  ${c.green}✅${c.reset} spec-kit ${c.dim}(SDD configured${agent ? `, agent: ${agent}` : ''})${c.reset}`);
     alreadyGood++;
+  } else if (existsSync(specifyDir)) {
+    console.log(`  ${c.yellow}⚠️${c.reset}  spec-kit ${c.dim}(.specify/ exists but not fully initialized)${c.reset}`);
+    console.log(`  ${c.dim}     Run: ${c.cyan}specify init --here --force --ai-skills${c.reset}`);
   } else {
-    console.log(`  ${c.dim}──${c.reset}  spec-kit ${c.dim}(not configured — optional)${c.reset}`);
-    console.log(`  ${c.dim}     Spec Kit enables spec-driven development with AI agents${c.reset}`);
-    console.log(`  ${c.dim}     See: ${c.cyan}https://github.com/github/spec-kit${c.reset}`);
+    console.log(`  ${c.dim}──${c.reset}  spec-kit ${c.dim}(not configured — recommended for full SDD+CDD workflow)${c.reset}`);
+    console.log(`  ${c.dim}     Install: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
+    console.log(`  ${c.dim}     Then: ${c.cyan}docguard init${c.reset} ${c.dim}(will auto-run specify init)${c.reset}`);
   }
 
   // Check for spec-kit extensions
@@ -421,8 +441,8 @@ export async function runSetup(projectDir, config, flags) {
             if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
 
             const hookContent = existsSync(preCommitHook)
-              ? readFileSync(preCommitHook, 'utf-8') + '\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n'
-              : '#!/bin/sh\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n';
+              ? readFileSync(preCommitHook, 'utf-8') + '\n\n# DocGuard CDD validation\nnpx docguard-cli guard --fail-on-warning\n'
+              : '#!/bin/sh\n\n# DocGuard CDD validation\nnpx docguard-cli guard --fail-on-warning\n';
 
             writeFileSync(preCommitHook, hookContent, { mode: 0o755 });
             console.log(`     ${c.green}✅ Pre-commit hook installed${c.reset}`);
@@ -447,9 +467,19 @@ export async function runSetup(projectDir, config, flags) {
     console.log(`  ${c.dim}No changes made.${c.reset}`);
   }
 
-  console.log(`\n  ${c.bold}Next steps:${c.reset}`);
-  console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}docguard diagnose${c.reset}`);
-  console.log(`  ${c.dim}Validate:${c.reset}       ${c.cyan}docguard guard${c.reset}`);
-  console.log(`  ${c.dim}Check score:${c.reset}    ${c.cyan}docguard score${c.reset}`);
+  const agentMode = detectAgentMode(projectDir);
+  console.log(`\n  ${c.bold}Next steps:${c.reset} ${c.dim}(${agentMode === 'llm' ? 'LLM mode' : 'CLI mode'})${c.reset}`);
+  if (agentMode === 'llm') {
+    if (!isSpecKitInitialized(projectDir)) {
+      console.log(`  ${c.dim}Bootstrap:${c.reset}      ${c.cyan}/speckit.constitution${c.reset}`);
+    }
+    console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}/docguard.guard${c.reset}`);
+    console.log(`  ${c.dim}Fix issues:${c.reset}     ${c.cyan}/docguard.fix${c.reset}`);
+    console.log(`  ${c.dim}Review:${c.reset}         ${c.cyan}/docguard.review${c.reset}`);
+  } else {
+    console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}docguard diagnose${c.reset}`);
+    console.log(`  ${c.dim}Validate:${c.reset}       ${c.cyan}docguard guard${c.reset}`);
+    console.log(`  ${c.dim}Check score:${c.reset}    ${c.cyan}docguard score${c.reset}`);
+  }
   console.log('');
 }

package/cli/docguard.mjs

@@ -3,13 +3,13 @@
 /**
  * DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD)
  * 
- * Zero dependencies. Pure Node.js.
+ * Zero NPM runtime dependencies. Pure Node.js.
  * 
  * Usage:
- *   npx docguard audit     — Scan project, report what docs exist/missing
- *   npx docguard init      — Initialize CDD docs from templates
- *   npx docguard guard     — Validate project against its canonical docs
- *   npx docguard --help    — Show help
+ *   npx docguard-cli audit     — Scan project, report what docs exist/missing
+ *   npx docguard-cli init      — Initialize CDD docs from templates
+ *   npx docguard-cli guard     — Validate project against its canonical docs
+ *   npx docguard-cli --help    — Show help
  * 
  * @see https://github.com/raccioly/docguard
  */

package/cli/ensure-skills.mjs

@@ -4,12 +4,16 @@
  * Called before every command execution. If skills or commands are missing,
  * copies them from the package's bundled assets into the project directory.
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Also provides agent mode detection (LLM vs CLI) and spec-kit availability.
+ *
+ * Zero npm dependencies — pure Node.js built-ins only.
+ * Framework dependency: spec-kit (convention, not code).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, cpSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
 import { c } from './shared.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -23,23 +27,224 @@ const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
 const SKILLS_DEST = '.agent/skills';
 const COMMANDS_DEST = 'commands';
 
+// ── Agent Mode Detection ────────────────────────────────────────────────
+
+/**
+ * Detect if user is in LLM mode (AI agent) or CLI mode (terminal).
+ * DocGuard is LLM-first — defaults to 'llm' when any agent signal detected.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {'llm' | 'cli'}
+ */
+export function detectAgentMode(projectDir) {
+  // First check .specify/init-options.json for explicit AI agent selection
+  const initOptions = resolve(projectDir, '.specify', 'init-options.json');
+  if (existsSync(initOptions)) {
+    try {
+      const opts = JSON.parse(readFileSync(initOptions, 'utf-8'));
+      if (opts.ai) return 'llm'; // spec-kit was initialized with an AI agent
+    } catch { /* ignore */ }
+  }
+
+  // Check for LLM signal directories/files
+  const llmSignals = [
+    '.agent/skills',
+    '.cursor',
+    '.claude',
+    '.specify',
+    '.github/copilot-instructions.md',
+    'CLAUDE.md',
+    '.gemini',
+    '.agents',
+  ];
+
+  for (const signal of llmSignals) {
+    if (existsSync(resolve(projectDir, signal))) return 'llm';
+  }
+
+  return 'cli';
+}
+
+/**
+ * Get the detected AI agent name from spec-kit init options.
+ * Returns null if spec-kit hasn't been initialized.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {string | null}
+ */
+export function getDetectedAgent(projectDir) {
+  const initOptions = resolve(projectDir, '.specify', 'init-options.json');
+  if (existsSync(initOptions)) {
+    try {
+      const opts = JSON.parse(readFileSync(initOptions, 'utf-8'));
+      return opts.ai || null;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+/**
+ * Detect which AI agent is in use, returning the spec-kit --ai flag value.
+ * Matches spec-kit's supported agents: agy, claude, copilot, cursor-agent,
+ * gemini, windsurf, codex, roo, etc.
+ *
+ * Priority: .specify/init-options.json > filesystem signals > null
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {string | null} - spec-kit --ai flag value, or null if unknown
+ */
+export function detectAIAgent(projectDir) {
+  // 1. Check spec-kit init options (already initialized — trust it)
+  const existing = getDetectedAgent(projectDir);
+  if (existing) return existing;
+
+  // 2. Map filesystem signals to spec-kit agent IDs
+  // Order matters: more specific signals first
+  const agentSignals = [
+    { signal: '.cursor',                        agent: 'cursor-agent' },
+    { signal: '.claude',                        agent: 'claude' },
+    { signal: 'CLAUDE.md',                      agent: 'claude' },
+    { signal: '.gemini',                        agent: 'gemini' },
+    { signal: '.agents',                        agent: 'agy' },         // Antigravity
+    { signal: '.github/copilot-instructions.md', agent: 'copilot' },
+    { signal: '.windsurf',                      agent: 'windsurf' },
+    { signal: '.codex',                         agent: 'codex' },
+    { signal: '.roo',                           agent: 'roo' },
+    { signal: '.amp',                           agent: 'amp' },
+    { signal: '.kiro',                          agent: 'kiro-cli' },
+    { signal: '.tabnine',                       agent: 'tabnine' },
+  ];
+
+  for (const { signal, agent } of agentSignals) {
+    if (existsSync(resolve(projectDir, signal))) return agent;
+  }
+
+  // 3. No signal found — return null (caller decides: interactive vs generic)
+  return null;
+}
+
+/**
+ * Check if the specify CLI (spec-kit) is available on PATH.
+ *
+ * @returns {boolean}
+ */
+export function isSpecKitAvailable() {
+  try {
+    const cmd = process.platform === 'win32' ? 'where specify' : 'which specify';
+    execSync(cmd, { encoding: 'utf-8', stdio: 'pipe', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Silently ensure skills and commands are installed in the project.
+ * Check if spec-kit has been initialized in this project.
+ *
+ * @param {string} projectDir - The project root directory
+ * @returns {boolean}
+ */
+export function isSpecKitInitialized(projectDir) {
+  return existsSync(resolve(projectDir, '.specify', 'init-options.json'));
+}
+
+// ── Spec-Kit Integration Gate ───────────────────────────────────────────
+
+// Read DocGuard package version (for skill auto-update)
+const PKG_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch { return '0.0.0'; }
+})();
+
+const SPEC_KIT_INSTALL_CMD = 'uv tool install specify-cli --from git+https://github.com/github/spec-kit.git';
+
+/**
+ * Ensure spec-kit is initialized in the project.
+ * Called on every command run — this is the persistent nudge.
+ *
+ * - If .specify/ exists → do nothing
+ * - If specify CLI available → auto-run specify init with detected agent
+ * - If specify CLI not available → show prominent install reminder (every time)
+ *
+ * @param {string} projectDir - The project root directory
+ * @param {object} flags - CLI flags
+ * @returns {{ specKitReady: boolean }}
+ */
+export function ensureSpecKit(projectDir, flags = {}) {
+  const silent = flags.format === 'json';
+
+  // Already initialized — nothing to do
+  if (isSpecKitInitialized(projectDir)) {
+    return { specKitReady: true };
+  }
+
+  // Spec-kit CLI available — auto-initialize
+  if (isSpecKitAvailable()) {
+    if (!silent) {
+      console.log(`  ${c.cyan}🌱 Spec Kit detected — auto-initializing SDD workflow...${c.reset}`);
+    }
+    try {
+      const detectedAgent = detectAIAgent(projectDir);
+      const aiFlag = detectedAgent
+        ? `--ai ${detectedAgent}`
+        : '--ai generic --ai-commands-dir .agent/commands/';
+      const scriptFlag = process.platform === 'win32' ? '--script ps' : '--script sh';
+      execSync(
+        `specify init --here --force ${aiFlag} --ai-skills --ignore-agent-tools --no-git ${scriptFlag}`,
+        { cwd: projectDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30000 }
+      );
+      if (!silent) {
+        console.log(`  ${c.green}✅ Spec Kit initialized${c.reset} ${c.dim}(agent: ${detectedAgent || 'generic'}, 9 skills installed)${c.reset}\n`);
+      }
+      return { specKitReady: true };
+    } catch {
+      // Failed silently — will show reminder instead
+    }
+  }
+
+  // No specify CLI — show prominent reminder (every time, no dismiss)
+  if (!silent) {
+    console.log(`  ${c.yellow}┌─────────────────────────────────────────────────────────┐${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.bold}💡 Spec Kit not installed${c.reset}                                ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  DocGuard is a Spec Kit extension. Install Spec Kit      ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  for the full experience: 13 AI skills, SDD workflow,    ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  project constitution, and seamless agent integration.   ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.cyan}${SPEC_KIT_INSTALL_CMD}${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}                                                          ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}│${c.reset}  ${c.dim}Then run: ${c.cyan}docguard init${c.reset}                                ${c.yellow}│${c.reset}`);
+    console.log(`  ${c.yellow}└─────────────────────────────────────────────────────────┘${c.reset}\n`);
+  }
+
+  return { specKitReady: false };
+}
+
+// ── Skill Installation ──────────────────────────────────────────────────
+
+/**
+ * Silently ensure DocGuard skills and commands are installed in the project.
+ * Also checks spec-kit integration and auto-updates stale skills.
  *
  * @param {string} projectDir - The project root directory
  * @param {object} flags - CLI flags (format, etc.)
- * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean }}
+ * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean, specKitReady: boolean }}
  */
 export function ensureSkills(projectDir, flags = {}) {
-  const result = { skillsInstalled: false, commandsInstalled: false };
+  const result = { skillsInstalled: false, commandsInstalled: false, specKitReady: false };
   const silent = flags.format === 'json';
 
-  // ── Skills ────────────────────────────────────────────────────────────
-  const skillsCheck = resolve(projectDir, SKILLS_DEST, 'docguard-guard', 'SKILL.md');
-  if (!existsSync(skillsCheck) && existsSync(SKILLS_SOURCE)) {
+  // ── Spec-Kit Gate (runs on every command) ─────────────────────────────
+  const specKitResult = ensureSpecKit(projectDir, flags);
+  result.specKitReady = specKitResult.specKitReady;
+
+  // ── DocGuard Skills (install + auto-update) ───────────────────────────
+  if (existsSync(SKILLS_SOURCE)) {
     try {
       const skillDirs = readdirSync(SKILLS_SOURCE).filter(d =>
-        existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
+        d.startsWith('docguard-') && existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
       );
 
       for (const skillDir of skillDirs) {
@@ -49,14 +254,26 @@ export function ensureSkills(projectDir, flags = {}) {
         }
         const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
         const destSkill = resolve(destDir, 'SKILL.md');
+
         if (!existsSync(destSkill)) {
+          // New install
           writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+          result.skillsInstalled = true;
+        } else {
+          // Auto-update: check if package version is newer than installed
+          const installedContent = readFileSync(destSkill, 'utf-8');
+          const versionMatch = installedContent.match(/docguard:version:\s*(\S+)/);
+          const installedVersion = versionMatch ? versionMatch[1] : '0.0.0';
+
+          if (installedVersion !== PKG_VERSION) {
+            writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+            result.skillsInstalled = true;
+          }
         }
       }
 
-      result.skillsInstalled = true;
-      if (!silent) {
-        console.log(`  ${c.cyan}✨ DocGuard AI skills installed → ${SKILLS_DEST}/${c.reset}`);
+      if (result.skillsInstalled && !silent) {
+        console.log(`  ${c.cyan}✨ DocGuard AI skills installed/updated → ${SKILLS_DEST}/${c.reset}`);
       }
     } catch {
       // Silent failure — skills are optional enhancement
@@ -94,3 +311,4 @@ export function ensureSkills(projectDir, flags = {}) {
 
   return result;
 }
+

package/cli/scanners/speckit.mjs

@@ -19,7 +19,7 @@
  * Credit: Integration with GitHub's Spec Kit framework
  *         (github.com/github/spec-kit)
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync } from 'node:fs';

package/cli/validators/doc-quality.mjs

@@ -18,7 +18,7 @@
  *
  * Optional: If `understanding` CLI is installed, runs a full 31-metric deep scan.
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';

package/cli/validators/schema-sync.mjs

@@ -6,7 +6,7 @@
  *
  * Supported: Prisma, Drizzle, Sequelize, TypeORM, Knex, Django, Rails
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';

package/cli/validators/todo-tracking.mjs

@@ -9,7 +9,7 @@
  * Inspired by spec-kit-cleanup (github.com/dsrednicki/spec-kit-cleanup)
  * which uses tiered issue classification for code hygiene.
  *
- * Zero dependencies — pure Node.js built-ins only.
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';

package/extensions/spec-kit-docguard/extension.yml

@@ -3,8 +3,8 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.9.8"
-  description: "Canonical-Driven Development enforcement with enterprise-grade AI skills. 19 automated validators, structured research workflows, quality validation loops, and spec-kit integration hooks. Zero dependencies."
+  version: "0.9.9"
+  description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"
   license: "MIT"
@@ -12,12 +12,16 @@ extension:
 
 requires:
   speckit_version: ">=0.1.0"
+  framework: "spec-kit"  # DocGuard builds on spec-kit conventions (.specify/, skills, constitution)
   tools:
     - name: "node"
       required: true
       version: ">=18.0.0"
     - name: "npx"
       required: true
+    - name: "specify"
+      required: false
+      description: "Spec Kit CLI — enables auto-initialization of SDD workflow during docguard init"
 
 provides:
   commands:

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,9 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.5
+  version: 0.9.9
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
+<!-- docguard:version: 0.9.9 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md

@@ -7,9 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.5
+  version: 0.9.9
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
+<!-- docguard:version: 0.9.9 -->
 
 # DocGuard Guard Skill
 
@@ -155,12 +156,16 @@ Present the user with options:
 - **Track progress** — if user runs guard multiple times, compare before/after
 - If user provides `$ARGUMENTS` like "just structure" or "only security", filter report to those validators
 
-## Integration with Spec Kit
+## Integration with Spec Kit (Extension-First)
 
-If this project has `.specify/` directory (spec-kit enabled):
+DocGuard is a spec-kit extension. When this project has a `.specify/` directory:
+- Read `.specify/memory/constitution.md` for project principles that constrain documentation
 - Include Spec-Kit validator results in the triage
 - Cross-reference spec quality issues with `specs/*/spec.md` file paths
-- Suggest `/speckit.analyze` if spec-related findings exceed 3
+- When specification issues found → suggest `/speckit.specify` or `/speckit.clarify`
+- When architecture gaps found → suggest `/speckit.plan`
+- When cross-artifact inconsistencies exceed 3 → suggest `/speckit.analyze`
+- When no constitution exists → suggest `/speckit.constitution` as first step
 
 ## Context
 

package/extensions/spec-kit-docguard/skills/docguard-review/SKILL.md

@@ -6,9 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.5
+  version: 0.9.9
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
+<!-- docguard:version: 0.9.9 -->
 
 # DocGuard Review Skill
 
@@ -163,7 +164,10 @@ Output a structured markdown report (do NOT write to disk):
 
 Based on findings:
 - **If CRITICAL issues**: "Run `/docguard.fix --doc [name]` to resolve blocking issues"
+- **If spec-related gaps**: "Run `/speckit.specify` to update specifications" or "/speckit.clarify to resolve ambiguities"
+- **If architecture drift**: "Run `/speckit.plan` to realign implementation plan with codebase"
 - **If only LOW/MEDIUM**: "Documentation is healthy. Consider `/docguard.fix` for polish"
+- **If constitution missing**: "Run `/speckit.constitution` to establish project principles"
 - **If all clean**: "Documentation is excellent. No action needed."
 
 Ask: "Would you like me to fix the top N issues? (I'll show you what I plan to change before applying)"

package/extensions/spec-kit-docguard/skills/docguard-score/SKILL.md

@@ -6,9 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.9.5
+  version: 0.9.9
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
+<!-- docguard:version: 0.9.9 -->
 
 # DocGuard Score Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {