docguard-cli 0.9.8 → 0.9.10

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);
 }