docguard-cli 0.9.8__tar.gz → 0.9.9__tar.gz

{docguard_cli-0.9.8/extensions/spec-kit-docguard → docguard_cli-0.9.9/.agent}/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
 

{docguard_cli-0.9.8/extensions/spec-kit-docguard → docguard_cli-0.9.9/.agent}/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
 

{docguard_cli-0.9.8/extensions/spec-kit-docguard → docguard_cli-0.9.9/.agent}/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)"

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/.agent/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
 

docguard_cli-0.9.9/.specify/memory/constitution.md

@@ -0,0 +1,76 @@
+<!-- Sync Impact Report
+  Version change: 0.0.0 → 1.0.0
+  Modified principles: N/A (initial creation)
+  Added sections: Core Principles (7), Technology Constraints, Extension & Spec Kit Compliance, Governance
+  Removed sections: N/A
+  Templates requiring updates: ✅ constitution-template.md (reference only, not modified)
+  Follow-up TODOs: None
+-->
+
+# DocGuard Constitution
+
+## Core Principles
+
+### I. LLM-First, CLI-Second
+
+DocGuard is built for AI coding agents. Every feature MUST be designed for LLM consumption first, with CLI as a secondary interface. Skills (behavior protocols) take priority over CLI commands (step-lists). When DocGuard detects an AI agent environment, it MUST surface skill-based instructions. CLI output MUST be machine-parseable (JSON mode) alongside human-readable text.
+
+### II. Zero NPM Runtime Dependencies (NON-NEGOTIABLE)
+
+DocGuard has zero `node_modules` at runtime. All Node.js functionality uses built-in modules only (`node:fs`, `node:path`, `node:child_process`, `node:test`, `node:url`, `node:readline`, `node:os`, `node:assert`). This maximizes portability, eliminates supply chain risk, and ensures instant `npx` usage. Dev dependencies are also zero — tests use `node:test`. DocGuard depends on spec-kit as a **framework convention** (`.specify/` directory structure, skill architecture, constitution pattern). This is an integration, not a code dependency. When the `specify` CLI is available, DocGuard MUST leverage it for initialization and skill management.
+
+### III. Documentation as Source of Truth
+
+Canonical-Driven Development means documentation drives code, not the other way around. DocGuard enforces this by validating code against `docs-canonical/` and detecting drift. Any deviation from canonical docs MUST be logged in `DRIFT-LOG.md` with `// DRIFT: reason` inline comments. The `docguard guard` command is the enforcement gate.
+
+### IV. Validator Isolation
+
+Each of the 19 validators is a pure, self-contained function. Validators receive `projectDir` and `config`, then return results. No validator may import another validator or depend on command-level logic. This ensures adding or modifying validators never breaks existing ones.
+
+### V. AI as Author, CLI as Orchestrator
+
+The CLI detects problems and generates structured prompts. The AI agent writes the actual documentation. DocGuard MUST NOT generate final documentation content itself — it provides research instructions, templates, and validation. The `fix`, `diagnose`, and `generate` commands produce AI-actionable output, not finished documents.
+
+### VI. Safe Writes
+
+All file write operations MUST use defensive patterns. Before overwriting any file, DocGuard creates backups. The `--force` flag is required to overwrite existing files. Init and setup commands skip files that already exist unless explicitly forced.
+
+### VII. Spec Kit Extension Compliance
+
+DocGuard is a community extension of GitHub Spec Kit. It MUST follow spec-kit conventions: `extension.yml` schema, skill architecture (`SKILL.md` files with YAML frontmatter), workflow hooks (`after_implement`, `before_tasks`, `after_tasks`), and the `.specify/` directory structure. DocGuard MUST always install spec-kit core skills alongside its own skills so users get the complete spec-driven development workflow.
+
+## Technology Constraints
+
+- **Language**: JavaScript (ES Modules only, no CommonJS)
+- **Runtime**: Node.js ≥ 18 (for native `node:test` and ES module support)
+- **Dependencies**: None. Zero. Ever. This is a hard constraint.
+- **Distribution**: npm (`docguard-cli`) + PyPI (`docguard`)
+- **Testing**: `node:test` + `node:assert` (built-in, no framework)
+- **Extension**: VS Code Extension API for editor integration
+- **Config**: `.docguard.json` for project-level customization
+- **Profiles**: starter, standard, enterprise compliance levels
+- **Output**: Text (human) + JSON (machine) dual output for all commands
+
+## Extension & Spec Kit Compliance
+
+- DocGuard MUST declare all skills, scripts, hooks, and commands in `extension.yml`
+- DocGuard MUST bundle spec-kit core skills so users don't need a separate install
+- All 4 DocGuard skills (`docguard-guard`, `docguard-fix`, `docguard-review`, `docguard-score`) MUST follow spec-kit skill architecture: YAML frontmatter with `name`, `description`, `compatibility`, `metadata`
+- Workflow hooks MUST be optional (never force execution)
+- The `ensureSkills()` function MUST auto-detect and install both DocGuard skills AND spec-kit core skills
+- DocGuard MUST detect agent environment (LLM vs CLI) and adapt its output accordingly
+
+## Governance
+
+This constitution supersedes all ad-hoc practices. Amendments require:
+1. Documentation of the change in `DRIFT-LOG.md` if deviating
+2. Update this constitution with a version bump
+3. Update `CHANGELOG.md` with the change
+4. All PRs MUST pass `docguard guard` before merge
+
+Versioning follows semantic versioning:
+- **MAJOR**: Principle removal or backward-incompatible redefinition
+- **MINOR**: New principle added or materially expanded guidance
+- **PATCH**: Clarification, wording, typo fix
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-17 | **Last Amended**: 2026-03-17

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.9] - 2026-03-17
+
+### Added — Extension-First Architecture & Spec-Kit Integration Gate
+
+#### Spec-Kit Integration Gate
+- **`ensureSpecKit()`** — Runs on every command. Auto-initializes spec-kit when `specify` CLI is available. Shows a prominent yellow-box reminder every time when spec-kit is not installed (persistent, no dismiss).
+- **`detectAIAgent(projectDir)`** — Maps 12 filesystem signals to spec-kit `--ai` flag values: `.cursor/` → `cursor-agent`, `.claude/` or `CLAUDE.md` → `claude`, `.gemini/` → `gemini`, `.agents/` → `agy` (Antigravity), `.github/copilot-instructions.md` → `copilot`, `.windsurf/` → `windsurf`, `.codex/` → `codex`, `.roo/` → `roo`, `.amp/` → `amp`, `.kiro/` → `kiro-cli`, `.tabnine/` → `tabnine`. Falls back to `--ai generic` when no agent detected.
+- **Strong init push** — `docguard init` now shows a prominent red-bordered box when spec-kit is missing, listing exactly what users miss: 9 AI skills, constitution, SDD workflow, agent detection. Provides both `uv` and `pip` install commands.
+- **Guard footer reminder** — `docguard guard` shows a 1-line spec-kit install nudge after results when not initialized.
+- **Skill auto-update** — `ensureSkills()` now compares installed SKILL.md `docguard:version` against package version. Automatically overwrites stale skills on DocGuard update.
+
+#### LLM-First Output
+- **`detectAgentMode(projectDir)`** — Returns `'llm'` or `'cli'` based on filesystem signals and `.specify/init-options.json`. All adaptive commands check this.
+- **`diagnose.mjs`** — All `FIX_INSTRUCTIONS` now include `llmCommand` fields (e.g., `/docguard.fix --doc architecture`). Issue collection propagates `llmCommand` to output. Remediation plan, verification checklist, and debate prompts all adapt to agent mode.
+- **`guard.mjs`** — "Next step" hint now shows `/docguard.diagnose` in LLM mode.
+- **`init.mjs`** — Next steps show skill commands (`/docguard.guard`, `/docguard.fix`) in LLM mode, CLI commands (`docguard diagnose`) in CLI mode.
+- **`setup.mjs`** — Next steps adapt to agent mode.
+
+#### Spec-Kit Skill Chaining
+- **`docguard-guard` SKILL.md** — Now chains to `/speckit.specify`, `/speckit.plan`, `/speckit.clarify`, and checks `constitution.md`.
+- **`docguard-review` SKILL.md** — Offers spec-kit skills for specification-level issues.
+- **`extension.yml`** — Declares `framework: spec-kit` and `specify` as optional tool.
+
+### Fixed
+- **`npx docguard guard`** → `npx docguard-cli guard` — The npm package name is `docguard-cli`, not `docguard`. Fixed in `hooks.mjs`, `setup.mjs`, `fix.mjs`, `docguard.mjs` (pre-existing bug).
+- **Hardcoded `--ai agy`** → Dynamic `detectAIAgent()` — `init.mjs` and `setup.mjs` no longer hardcode Antigravity as the agent.
+- **`llmCommand` never propagated** — `collectIssues()` in `diagnose.mjs` was not copying `llmCommand` from `FIX_INSTRUCTIONS` to issue objects, so LLM-first fix hints silently fell back to CLI commands.
+- **Debate prompt not LLM-aware** — `outputDebatePrompt()` now receives `agentMode` and adapts verification commands.
+- **Basic-tier checklist hardcoded** — Verification checklist for basic-tier agents now adapts to LLM/CLI mode.
+- **Stale "Zero dependencies" doc comments** — Updated 6 files to "Zero NPM runtime dependencies" matching the constitution.
+- **Platform-aware `--script`** — `specify init` now uses `--script ps` on Windows, `--script sh` on Unix.
+
+### Changed
+- **Constitution** — Principle II amended from "Zero Dependencies" to "Zero NPM Runtime Dependencies" (spec-kit is a framework convention, not a code dependency).
+- **SKILL.md metadata** — All 4 skills updated from `0.9.5`/`0.9.8` to `0.9.9`. Added `docguard:version` comment for auto-update mechanism.
+- **`ensure-skills.mjs`** — Full rewrite: 6 exports (`ensureSkills`, `ensureSpecKit`, `detectAgentMode`, `detectAIAgent`, `getDetectedAgent`, `isSpecKitAvailable`, `isSpecKitInitialized`).
+- **22 files changed**, +567/−203 lines.
+
 ## [0.9.6] - 2026-03-14
 
 ### Added — Enterprise AI Skills Architecture

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.9.8
+Version: 0.9.9
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/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('═══════════════════════════════════════════════════════');

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/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').`);
 }

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/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);

{docguard_cli-0.9.8 → docguard_cli-0.9.9}/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