sync-docs

Keep CLAUDE.md, AGENTS.md, SKILL.md, and README.md accurate after new commits land: find the last docs-sync point, classify every commit since then, and write targeted edits. Syncing is bidirectional: add what is new, and remove or correct anything the current codebase contradicts.

Edit the docs that exist; never create a new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) during a sync. If one seems warranted, tell the user.

Audiences: CLAUDE.md is the dense agent reference (architecture, symbol and file names, file:line cues) and describes current behavior, never history. AGENTS.md mirrors it for other agent tools (step 5). SKILL.md is operator-facing and imperative (config keys, setup, CLI flows); no symbol or field names in its tables. README.md is the newcomer entry point and changes only when the public surface changes. CHANGELOG.md, when present, holds per-issue rationale and migration history.

Preconditions: gh auth status succeeds. Resolve DEFAULT=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name), run git fetch origin, record the range end T0=$(git rev-parse "origin/$DEFAULT"), and create a worktree off that tip with the harness branch prefix (cc/ on Claude Code): git worktree add .claude/worktrees/cc+sync-docs-<YYYY-MM-DD> -b cc/sync-docs-<YYYY-MM-DD> "$T0". Every range below ends at $T0, never at a later origin/$DEFAULT. When that branch already exists locally or on origin, never delete or reuse it: add the next free suffix to the branch and the worktree name (-2, then -3). Read, edit, and run every git command in that worktree (-C <worktree>), never in the main checkout.

Steps

1. Baseline. git log --oneline "origin/$DEFAULT" | grep -m1 -E '^[0-9a-f]+ ([Ss]ync docs\b|docs(\([^)]*\))?: sync\b|docs\(sync\):)'. A sync is a docs: or docs(<scope>): subject that begins with "sync", a docs(sync): scope, or a subject that begins with "sync docs"; a commit that mentions "sync docs" later in its subject is no sync, and a docs commit that only names CLAUDE.md or SKILL.md is no sync. The matched commit M is the baseline unless it records a range end: read git log -1 --format=%B <M> for a Docs-sync-range-end: <sha> line; when the body has none and the subject ends with (#N) (a squash merge), read gh pr view <N> --json body -q .body for that line. When a recorded <sha> exists and git merge-base --is-ancestor <sha> "origin/$DEFAULT" holds, the baseline is <sha>; otherwise it is M. If none, ask the user for the last-known-good tag or SHA, or use the initial commit for a first sync.
2. Range. git log <baseline>.."$T0" --oneline. Skip pure CI, workflow, and chore commits unless they change agent- or operator-facing behavior.
3. Classify each commit (an unrelated-areas commit is classified per area):

4. Audit docs near in-scope commits. Verify surrounding claims: paths exist, symbol names match, defaults and versions are current, CLI flags accept the documented args. Delete or correct what the code contradicts; grep first, and never remove a claim you haven't verified is wrong. Stay scoped; if the docs look broadly drifted, flag it instead of rewriting. Check "current/active/default" claims against the deciding switch (build target, feature-flag default, active-environment key), never against the doc's own prior text. When a commit touches a directory of pluggable items, ls it and diff against every catalog, index, and README list. When one item is promoted and another retired, confirm the active state (self-referencing URLs, indexing directives, flags, defaults) flipped on both; if that invariant is real but undocumented, add a short rule.
5. Edit CLAUDE.md, then mirror into AGENTS.md. Edit only changed sections; terse bullets, one behavioral change each; update any schema or config version constant a migration bumped; rewrite PR descriptions as imperative phrases. Then ls -l AGENTS.md: symlink to CLAUDE.md, skip it and never open it for writing; real file, apply every CLAUDE.md body edit verbatim, keep its own intro line, and audit it per step 4; absent, skip.
6. Edit SKILL.md (only if the repo has one). Add new keys to the settings table and the upgrade or post-update reference; update commands, reload scope, and safety-control sections when those surfaces change.
7. Edit README.md (only if the public surface changed). Default to no edit. Touch it only for a new supported feature or integration, a new public unit in an enumerated list, a new top-level CLI subcommand, a setup or install change, or a public config example the code now contradicts. Tutorial tone: no file:line cues, internals, or PR numbers; one line per list item in the existing format. Always check its enumerated lists for new public units.
8. Size check. wc -c CLAUDE.md. Above 35000 bytes, condense in place to under 30000; never split it. Keep symbol and file names, field lists, enum values, defaults, version numbers, gotchas, concurrency and ordering rules, live behavior, the Environment, Setup, Build & Deploy, and Testing blocks, lookup tables of IDs, paths, or prefixes, and repo-defined format conventions. Drop "why" prose where the rule alone is actionable, shipped-migration narrative, resolved-incident stories, duplicates, and examples that restate a rule; move history to CHANGELOG.md when it exists. Re-run wc -c and report old and new counts. Still over 40000, list the largest sections and ask the user which to cut.
9. Project notes file, if the repo keeps one with a Releases section and the range includes a version tag or release PR: append - **vX.Y.Z** — YYYY-MM-DD: <summary> (PRs #N, #M).
10. Land the edits through a PR. git status in the worktree. Stage only the doc files this sync changed, by name. Nothing staged: report "no doc changes", remove the worktree and delete its unpushed local branch (git branch -D <branch>), and stop. Otherwise commit with a subject that matches the step 1 baseline pattern (docs: sync <what> after <range>, or docs(sync): ...), a body line Docs-sync-range-end: $T0 (the full SHA), and the repo's commit footer, push the branch, open a PR against $DEFAULT whose title begins with that same subject (plus any title suffix the repo's PR convention requires, such as [C<score>, <model>, <effort>]) and whose body follows the repo's PR body rules and carries the same Docs-sync-range-end: $T0 line, and report its number and URL. A standalone run leaves the PR open for review; a caller such as sync-docs-release owns the merge decision.