ref(docs): Move CLI command validation to review skill

Remove the automated docs:check script from CI, pre-commit, release, and project guidance. Use a dedicated review skill for changelog CLI command references instead, so historical migration examples can be judged with context.

Author: cameroncooke

.agents/skills/xcodebuildmcp-docs-command-review/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: xcodebuildmcp-docs-command-review
+description: Use when reviewing XcodeBuildMCP changelog CLI command references for invalid current guidance while allowing historical migration examples.
+allowed-tools: Read Grep Glob
+---
+
+# XcodeBuildMCP Docs Command Review
+
+Review changed changelog entries for CLI command references that would mislead users or agents.
+
+## What to inspect
+
+- `CHANGELOG.md`
+- `manifests/tools/*.yaml` and `manifests/workflows/*.yaml` when you need to verify current CLI workflow/tool names
+- `src/cli/**` only when command wiring is unclear from manifests
+
+## Issue criteria
+
+Report a finding only when a command reference is presented as current guidance and appears invalid for the current CLI surface.
+
+### High severity
+
+- A changelog bullet, example, or migration instruction tells users to run a removed or invalid `xcodebuildmcp` command as the current path.
+- A Breaking change mentions a removed command but does not give a valid replacement.
+- A command reference uses the wrong workflow/tool pairing in a way a user or agent would likely copy.
+
+### Medium severity
+
+- A command reference is ambiguous enough that users may not know whether it is historical or current.
+- A migration example gives the right replacement but does not clearly label the old command as "Before", "old", "removed", or equivalent.
+
+## Explicitly allowed
+
+Do not report removed commands when they are clearly historical context, especially in:
+
+- Breaking-change migration sections
+- "Before" examples paired with valid "After" examples
+- Already-released changelog sections describing past behavior
+
+Example that should not be reported:
+
+```markdown
+Before:
+xcodebuildmcp logging start-sim-log-cap
+
+After:
+xcodebuildmcp simulator build-and-run
+```
+
+## Output
+
+For each finding, include:
+
+- Severity
+- File and line
+- The command reference
+- Why it reads as current guidance
+- Suggested replacement wording or command
+
+If all command references are historical or valid, report no findings.

.agents/skills/xcodebuildmcp-docs-release-review/SKILL.md

@@ -16,7 +16,6 @@ Review guardrails for documentation, generated references, and release flow cons
 
 - `README.md`
 - `CHANGELOG.md` when present
-- `scripts/check-docs-cli-commands.js`
 - `scripts/build-website-manifest.mjs`
 - `scripts/generate-github-release-notes.mjs`
 - `scripts/release.sh`
@@ -33,11 +32,11 @@ Review guardrails for documentation, generated references, and release flow cons
 - Website manifest generation preserves expected normalized fields.
 - Docs explain runtime/contracts without deprecated patterns.
 - Keep docs-only work from introducing product behavior changes.
+- CLI command references in changelog entries are reviewed by `xcodebuildmcp-docs-command-review`.
 
 ## Validation
 
 - `npm run build`
-- `npm run docs:check`
 - Release notes check when touched:
   - `node scripts/generate-github-release-notes.mjs --version <version> --changelog CHANGELOG.md`
 - `npx skill-check .agents/skills/xcodebuildmcp-docs-release-review`

.agents/skills/xcodebuildmcp-packaging-resource-review/SKILL.md

@@ -37,7 +37,6 @@ Review guardrails for package/build/resource integrity and portable distribution
 ## Validation
 
 - `npm run build`
-- `npm run docs:check`
 - Packaging-specific when touched:
   - `npm run package:macos -- --help` (if supported)
   - `npm run verify:portable` after artifact creation

.agents/skills/xcodebuildmcp-runtime-boundary-review/SKILL.md

@@ -38,5 +38,4 @@ Review guardrails for runtime routing and invocation boundaries.
 
 - `npm test -- src/runtime/__tests__/tool-invoker.test.ts`
 - `npm run typecheck`
-- `npm run docs:check`
 - `npx skill-check .agents/skills/xcodebuildmcp-runtime-boundary-review`

.agents/skills/xcodebuildmcp-tool-contract-review/SKILL.md

@@ -37,7 +37,6 @@ Review guardrails for tool contract changes across implementation, manifests, an
 
 ## Validation
 
-- `npm run docs:check`
 - `npm run typecheck`
 - `npm test -- src/core/manifest/__tests__/schema.test.ts`
 - `npm test -- src/runtime/__tests__/tool-invoker.test.ts`

.githooks/pre-commit

@@ -27,16 +27,4 @@ if [ $? -ne 0 ]; then
   exit 1
 fi
 
-if [ "${XCODEBUILDMCP_DOCS_CHECK_WARN_ONLY:-}" = "1" ]; then
-  echo "Validating CLI command references in consumer docs (warnings only)..."
-  node scripts/check-docs-cli-commands.js --warn-only
-else
-  echo "Validating CLI command references in consumer docs..."
-  npm run docs:check
-  if [ $? -ne 0 ]; then
-    echo "${RED}Docs command validation failed. Aborting commit.${NC}"
-    exit 1
-  fi
-fi
-
 echo "Pre-commit checks passed."

.github/workflows/ci.yml

@@ -32,9 +32,6 @@ jobs:
       - name: Build
         run: npm run build
 
-      - name: Validate docs CLI command references
-        run: npm run docs:check
-
       - name: Lint
         run: npm run lint
 

AGENTS.md

@@ -7,7 +7,6 @@
 - `npm run lint` / `npm run lint:fix` - ESLint
 - `npm run format` / `npm run format:check` - Prettier
 - `npm run typecheck` - TypeScript type checking (src + test config)
-- `npm run docs:check` - Validate docs match CLI surface
 
 ## Architecture
 ESM TypeScript project (`type: module`). Key layers:
@@ -34,7 +33,6 @@ ESM TypeScript project (`type: module`). Key layers:
    npm run typecheck
    npm run format
    npm run build
-   npm run docs:check
    npm test
    ```
 4. Update `CHANGELOG.md` under `## [Unreleased]`

package.json

@@ -38,7 +38,6 @@
     "typecheck:tests": "npx tsc -p tsconfig.test.json",
     "inspect": "npx @modelcontextprotocol/inspector@latest node build/cli.js mcp",
     "doctor": "node build/doctor-cli.js",
-    "docs:check": "node scripts/check-docs-cli-commands.js",
     "bench:test-sim": "npx tsx scripts/benchmark-simulator-test.ts",
     "capture:xcodebuild": "npx tsx scripts/capture-xcodebuild-wrapper.ts",
     "license:report": "node scripts/generate-third-party-package-licenses.mjs",