Skip to content

vt-c-doc-sync

Audit and synchronize documentation with actual toolkit state. Checks component counts, terminology, version references, and maintains What's New via the change ledger. Run after adding/removing components or version bumps.

Plugin: core-standards
Category: Documentation Pipeline
Command: /vt-c-doc-sync

/vt-c-doc-sync — Documentation Synchronization Audit

Keeps documentation honest. Compares documented state against filesystem reality, maintains the change ledger, and generates What's New content.

Purpose

Prevents documentation drift by auditing: - Component counts across 6 sources (README, docs, plugin.json, macros) - Terminology consistency (deprecated terms still in use) - Version references against plugins/registry.json - MkDocs macro definitions vs usage - Change ledger completeness (undocumented specs/changes) - What's New section currency

When to Use

  • After adding/removing skills, agents, or commands
  • After version bumps (registry.json changes)
  • After completing a spec — run --log to capture the story
  • Before merging to main — run --fix to ensure docs are current
  • On demand — --report-only to check drift without changing anything

Invocation

/vt-c-doc-sync                    # Audit report only (default)
/vt-c-doc-sync --report-only      # Same as above, explicit
/vt-c-doc-sync --fix              # Audit + apply all mechanical fixes
/vt-c-doc-sync --log              # Interactively capture a change ledger entry
/vt-c-doc-sync --whats-new-only   # Regenerate What's New from ledger + CHANGELOG

Execution Steps

Step 0: Parse Arguments

Determine mode from the user's invocation:

Argument Mode Writes Files?
(none) Report only No
--report-only Report only No
--fix Report + apply fixes Yes
--log Change ledger capture Yes (append only)
--whats-new-only Regenerate What's New Yes

If --log: Skip to Step 7b (Log Mode). If --whats-new-only: Skip to Step 6 then Step 8 (only What's New generation and apply).

Step 0b: Branch Guard (write modes only)

If the mode writes files (--fix, --log, or --whats-new-only):

  1. Check the current branch with git branch --show-current
  2. If already on a docs/doc-sync-* branch, skip — reuse the existing branch
  3. Otherwise, create and checkout: git checkout -b docs/doc-sync-YYYY-MM-DD
  4. Print: Created branch docs/doc-sync-YYYY-MM-DD

If --report-only or default: Skip this step entirely.

Step 1: Component Count Audit

Count actual components per plugin by scanning the filesystem:

For each directory in plugins/:
  skills  = count subdirectories containing SKILL.md
  agents  = count .md files in agents/**/ (excluding README.md, index.md)
  commands = count .md files in commands/ (excluding README.md, index.md)

Compare actual counts against documented values in these sources:

Source Where counts appear
README.md "What's Included" table, plugin tree comment
docs/index.md "What's Included" table
docs/plugins/{name}.md Component count table
plugins/{name}/.claude-plugin/plugin.json components object
scripts/docs-gen/macros.py Hardcoded return values in skill_count(), agent_count()

Output format:

Component Count Audit
─────────────────────────────────────────────────────────────────
core-standards:
  Skills:   92 actual | plugin.json: 60 | README: 87 | docs: 65 | macros: 87
  Agents:   43 actual | plugin.json: 36 | README: 47 | docs: 42 | macros: 47
  Commands: 33 actual | plugin.json: 47 | README: 32 | docs: 47

Totals (all plugins):
  Skills: 99 | Agents: 50 | Commands: 37
─────────────────────────────────────────────────────────────────
Mismatches: N fields need updating

Step 2: Terminology Audit

Grep for deprecated terms across documentation files.

Deprecated terms:

Pattern Replacement
Three Workflows (case-insensitive) Two Workflows
three-workflow (case-insensitive) two-workflow
Three-Workflow Two-Workflow

Files to scan: README.md, docs/**/*.md, plugins/*/.claude-plugin/plugin.json

Exclusions (do not flag): - CHANGELOG.md (historical references are correct) - specs/ directory (frozen spec content) - Lines containing "previously", "harmonized from", "later changed to", or "was renamed"

Output format:

Terminology Audit
─────────────────────────────────────────────────────────────────
STALE: README.md:33 — "## Three Workflows" → "## Two Workflows"
STALE: README.md:27 — "Three-workflow phases" → "Two-workflow phases"
STALE: docs/plugins/core-standards.md:26 — "all three workflows" → "both workflows"
─────────────────────────────────────────────────────────────────
N terminology issues found

Step 3: Version Consistency Audit

Read plugins/registry.json as the authoritative version source. Compare against:

File Field to check
plugins/{name}/.claude-plugin/plugin.json version
docs/plugins/{name}.md Version row in overview table
scripts/docs-gen/macros.py toolkit_version() return value

Output format:

Version Consistency Audit
─────────────────────────────────────────────────────────────────
core-standards:
  registry.json: 3.2.0
  plugin.json:   3.2.0  OK
  docs/plugins:  3.0.0  STALE
  macros.py:     1.0.0  STALE
─────────────────────────────────────────────────────────────────
N version mismatches

Step 4: Macros Completeness Audit

Check scripts/docs-gen/macros.py:

  1. Grep docs/**/*.md for {{ ... }} macro calls
  2. For each macro found, check if it is defined in macros.py
  3. For each defined macro, check if the return value matches reality

Known issues to detect: - {{ command_count }} used in docs/reference/index.md but not defined - skill_count() and agent_count() return hardcoded stale values

Output format:

Macros Audit
─────────────────────────────────────────────────────────────────
skill_count():    returns "87" — actual: 99 (all plugins)  STALE
agent_count():    returns "47" — actual: 50 (all plugins)  STALE
toolkit_version(): returns "1.0.0" — registry: 3.2.0       STALE
command_count():  NOT DEFINED — used in docs/reference/index.md  MISSING
─────────────────────────────────────────────────────────────────
N macro issues

Step 5: Change Ledger Audit

Check docs/change-ledger.md:

  1. Exists? If not, flag as missing.
  2. Coverage check: Read recent git log for completed specs (branches matching feature/spec-* merged to main). For each, check if a corresponding ledger entry exists (search for SPEC-NNN in the ledger).
  3. Well-formed? Each entry should have **Discovery:** and **Fix:** fields. Flag entries missing these.

Output format:

Change Ledger Audit
─────────────────────────────────────────────────────────────────
Ledger: docs/change-ledger.md EXISTS
Entries: 5 total
Coverage:
  SPEC-024: No ledger entry  MISSING
  SPEC-023: Entry found       OK
  SPEC-022: Entry found       OK
  SPEC-021: Entry found       OK
  SPEC-020: Entry found       OK
─────────────────────────────────────────────────────────────────
N undocumented changes

Step 6: What's New Audit & Generation

Check for docs/whats-new.md and the What's New section in README.md.

If generating (in --fix or --whats-new-only mode):

  1. Primary source: Read docs/change-ledger.md for narrative entries.
  2. Fallback: Read plugins/core-standards/CHANGELOG.md for bullet points.
  3. For each ledger entry: Produce a narrative paragraph: bold title, then "We discovered [Discovery], so we [Fix]."
  4. Cross-reference: Check CHANGELOG for items not in the ledger — include as bullet points under "Also in this release."
  5. Generate two outputs:
  6. docs/whats-new.md — Full page with narrative entries per version
  7. README.md section — Condensed 3-5 bullet summary for the latest version

Step 7: Combined Report

Display the audit summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Doc-Sync Audit Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Component Counts:    N mismatches
Terminology:         N stale references
Version Consistency: N mismatches
Macros:              N issues
Change Ledger:       N undocumented changes
What's New:          Present / Missing

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: N issues found | M auto-fixable

Next: Run /vt-c-doc-sync --fix to apply corrections
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If --report-only: Stop here.

Step 7b: Log Mode (--log only)

Interactive change ledger capture. Skip all audit steps.

  1. Auto-detect context:
  2. Read current git branch name for spec reference (e.g., feature/spec-024-* → SPEC-024)

  3. Run git diff --name-only HEAD~5..HEAD to suggest affected files

  4. Ask the user:

  5. "What did you discover or what triggered this change?"
  6. "What fix or change did you apply?"
  7. "Related spec, fix, or PR?" (pre-fill from branch name if detected)

  8. "Key files affected?" (show auto-detected list, let user confirm or edit)

  9. Append to docs/change-ledger.md:

  10. Under today's date header (create if not present)

  11. Using the structured format: ### SPEC-NNN: Title / **Discovery:** / **Fix:** / **Files:**

  12. Confirm: 

    Ledger entry added to docs/change-ledger.md
TIP: Run /vt-c-doc-sync --fix to regenerate What's New from the ledger

  13. Done — no audit, no fixes.

Step 8: Apply Fixes (--fix mode only)

Apply corrections in this order:

  1. scripts/docs-gen/macros.py — Update hardcoded counts to actual values. Add missing command_count() macro. Update toolkit_version() to match registry.
  2. plugins/{name}/.claude-plugin/plugin.json — Update components counts to match filesystem.
  3. README.md — Fix "What's Included" table counts. Fix "Three Workflows" → "Two Workflows" header and body. Add or update "What's New" section after "Quick Install".
  4. docs/index.md — Fix component count table.
  5. docs/plugins/core-standards.md — Fix version, component counts, terminology.
  6. docs/whats-new.md — Create or update from change ledger + CHANGELOG.
  7. mkdocs.yml — Add whats-new.md to nav (under Getting Started or top-level) if not present. Add change-ledger.md to nav if not present.
  8. Remaining terminology — Fix all flagged stale term occurrences.

After applying: Re-run Steps 1-6 as a verification pass. Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fixes Applied
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Updated: N files
  - macros.py (counts + version + command_count macro)
  - plugin.json (component counts)
  - README.md (counts, terminology, What's New)
  - docs/index.md (counts)
  - docs/plugins/core-standards.md (version, counts, terminology)
  - docs/whats-new.md (created/updated)
  - mkdocs.yml (nav entries)

Verification: All checks PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 9: Commit and Offer Merge

After all fixes are applied and verified:

  1. Stage all modified files
  2. Commit with message: docs: sync documentation with vX.Y.Z toolkit state
  3. Ask the user: "Merge to main and push?"
  4. If yes: git checkout main && git merge docs/doc-sync-YYYY-MM-DD --no-edit && git push origin main

Change Ledger Format Reference

The change ledger at docs/change-ledger.md uses this structure:

# Change Ledger

Structured record of toolkit changes — the "why" behind the "what".
Read by `/vt-c-doc-sync` to generate rich What's New content.

---

## YYYY-MM-DD

### SPEC-NNN: Title
**Discovery:** What was found, observed, or reported that triggered this change.
**Fix:** What was changed, added, or removed to address it.
**Files:** Comma-separated list of key files affected.

### FIX: Short Description
**Discovery:** Description of the bug or gap.
**Fix:** What was done to fix it.
**Files:** Key files affected.

Entry types: - ### SPEC-NNN: Title — Spec-driven changes (features, enhancements) - ### FIX: Title — Bug fixes and corrections - ### BREAKING: Title — Breaking changes requiring migration

Integration Points

  • /vt-c-5-finalize checks for a ledger entry matching the current spec. Advisory prompt if missing.
  • /vt-c-4-review Step 7e can reference doc-sync for documentation completeness.
  • This skill is never a gate — all prompts are advisory only.