docs-sync-check

docs-sync-check — Living Docs Verification

Verify that CLAUDE.md and README.md reflect the actual state of commands, skills, and hooks on disk. Called by /retro and /release as a parallel fork.

Input

$ARGUMENTS (optional JSON from caller):

{
  "changed_files": ["commands/zie-foo.md", "skills/bar/SKILL.md"]
}

If empty or unparseable: run full check across all commands/skills/hooks.

Steps

1. Read CLAUDE.md (project root) — extract lines mentioning commands/, skills/, hooks/. If missing → note in details, set claude_md_stale: false.

2. Read README.md (project root) — extract commands table if present. If missing → note in details, set readme_stale: false.

3. Enumerate actual state:

   • Glob commands/*.md → extract base filenames (strip .md).
   • Glob skills/*/SKILL.md → extract parent directory names.
   • Glob hooks/*.py → extract base filenames (exclude utils.py).

3b. Read PROJECT.md — parse Commands and Skills tables: - Read PROJECT.md at the project root. If missing → set project_md_stale: false, append "PROJECT.md not found — skipped" to details, skip cross-reference. - Extract Commands table: every | /command | row. Skip header rows (| Command |, | --- |). Strip the leading / from each command name. Strip .md suffix from disk basenames before comparing. - Extract Skills table: every | skill-name | row. Skip header rows (| Skill |, | --- |). Skill names are bare (no path prefix). - If a Commands or Skills table is absent from PROJECT.md, treat as empty (all disk items → missing_from_project_md). - Cross-reference: - missing_from_project_md: commands/skills on disk NOT in PROJECT.md tables. - extra_in_project_md: entries in PROJECT.md tables NOT found on disk. - Set project_md_stale: true if either list is non-empty; false otherwise.

4. Compare each category: docs vs. actual.

   • missing_from_docs: items on disk not mentioned in the doc.
   • extra_in_docs: items mentioned in doc but not on disk.

5. Return JSON:

{
  "claude_md_stale": false,
  "readme_stale": false,
  "project_md_stale": false,
  "missing_from_docs": [],
  "extra_in_docs": [],
  "missing_from_project_md": [],
  "extra_in_project_md": [],
  "details": "CLAUDE.md in sync | README.md in sync | PROJECT.md in sync"
}

Set claude_md_stale: true if missing_from_docs or extra_in_docs has entries relating to CLAUDE.md; readme_stale: true for README.md entries.