Ccc Doc Sync

$ccc-doc-sync — Doc Count Synchronizer

Keeps every count reference (plugin_skills, specialist_agents, hook_handlers) and version string in sync across the entire project. One source of truth — never manually edit numbers in docs again.

What it does

Reads two canonical sources:

• commander/contract.json — plugin_skills, specialist_agents, hook_handlers
• package.json — version

Then applies surgical regex replacements across 20+ doc files, updating every occurrence of stale counts. Idempotent — running twice produces the same output.

How it works

1. Load values from contract.json + package.json
2. Read patterns.json — declarative per-file replacement rules
3. For each file: apply all patterns, compare before/after
4. --check: report drift, exit 1 if any file is stale (CI gate)
5. --apply: write changes, exit 0

The pattern engine uses ${plugin_skills}, ${specialist_agents}, ${hook_handlers}, ${version} template vars. Adding support for a new file is a JSON edit in patterns.json — no code change.

Files covered

Usage

# Dry-run — show what would change, exit 1 if drift detected
node commander/cowork-plugin/skills/ccc-doc-sync/sync.js --check

# Apply changes
node commander/cowork-plugin/skills/ccc-doc-sync/sync.js --apply

# Via npm scripts
npm run docs:sync:check   # CI gate (--check)
npm run docs:sync         # Apply all changes

When to run

• After bumping contract.json plugin_skills count (new skill added)
• After bumping contract.json specialist_agents count (new agent added)
• After bumping contract.json hook_handlers count (new handler added)
• After running npm version (updates package.json version)
• docs:sync:check runs automatically in prepublishOnly

Exit codes

Adding a new file

Edit patterns.json only — no JS changes needed:

{
  "file": "path/to/new-file.md",
  "replacements": [
    {
      "regex": "(Some prefix\\s*)\\d+( skills)",
      "flags": "g",
      "template": "$1${plugin_skills}$2"
    }
  ]
}

Architecture

sync.js          runner — args, output, exit codes
patterns.json    declarative replacements per file (the contract)
SKILL.md         this file

The .js file contains no hardcoded counts. All patterns live in patterns.json.

⚙️ Fable contract: plan before build · verifier ≠ worker · prove before alarm · loops need gates · leave durable state — rules/fable-method.md