git:20260817.faa195b to git:20260901.c56ed4c

- Keep CLAUDE.md, AGENTS.md, SKILL.md, and README.md accurate after new commits land. Finds the last docs-sync point, classifies every commit since then, and writes targeted updates — no rewrite, no drift. Syncing is bidirectional: as well as adding what's new, **remove or correct anything the current codebase now contradicts** — stale paths, renamed symbols, removed fields, dead defaults. A doc that lies is worse than one that's merely incomplete.

- Adapt to the repo you're in. The doc set below is the common shape, not a requirement — a repo may have only a README, or add its own docs. Edit the files that exist; never create a new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) as part of a sync — if one seems warranted, surface it to the user instead.

- Audience split:

- - **CLAUDE.md** — agent-facing dense reference (architecture, symbol/file names, `file:line` cues). Describes **current behavior**; not a history log.

- - **AGENTS.md** *(only if the repo already has one — check `ls -l AGENTS.md` first)* — the counterpart agent doc for other tools (e.g. Codex). A repo keeps it in one of two shapes. As a symlink to CLAUDE.md it holds no content of its own, so it needs no edit. As a real file it carries the same body content (architecture, commands, conventions) with a tool-specific intro line, so every CLAUDE.md body edit gets mirrored into it — see step 5.

- - **SKILL.md** *(only if the repo has one)* — operator-facing imperative guide (config knobs, setup prompts, CLI flows).

- - **README.md** — public/newcomer-facing (setup, supported features, headline config). Lowest churn — update only when public surface changes.

- - **CHANGELOG.md** *(only if the repo already has one — check `ls CHANGELOG.md` first)* — per-issue/PR history, rationale, and migration archaeology. When present it is the home for the "why" and resolved-migration detail, so CLAUDE.md stays lean. Never create one as part of a sync.

- ```bash

- git log --oneline -5 # confirm you're on the right branch

- git status # must be clean before editing docs

- ```

- Note the SHA. If none found, ask the user for the last-known-good tag or SHA (or fall back to the initial commit for a first sync).

-

- ### 2. Get commits since last sync

- ```bash

- git log <last-sync-sha>..HEAD --oneline

- ```

- Exclude pure CI / workflow / chore commits (`.github/`, `scripts/`, version bumps) unless they affect agent- or operator-facing behavior.

- | New config field / flag / setting | CLAUDE.md config reference; SKILL.md settings table (if present); README.md **only if** it's a top-level/public-facing knob | Add field description + notes |

- | Changed default behavior | CLAUDE.md patterns section; SKILL.md (if present); README.md **only if** a documented default/example now contradicts the code | Update description; note old vs new |

- | New pluggable unit (plugin, command, integration, platform, strategy, theme, provider…) | CLAUDE.md structure + SKILL.md catalog (if present) + README.md feature list | Add entry to each doc that enumerates the set |

- | Bug fix (behavior change) | CLAUDE.md patterns (if pattern-level) | Update the relevant bullet |

- | New CLI command / flag | SKILL.md commands (if present); README.md Getting Started **only if** it's part of the setup/operator flow | Add usage |

- | Setup / install flow change | README.md Getting Started + SKILL.md (if operator-facing) | Update the relevant block |

- | Internal refactor / test | Skip (no docs change needed) | — |

- | New release milestone | Project memory/notes file **if one exists** (see step 9) | Append version entry |

- | Per-issue/PR history, rationale, or migration archaeology (*if CHANGELOG.md exists*) | CHANGELOG.md | Add a keyed entry there, not into CLAUDE.md; CLAUDE.md gets only the terse current-state invariant |

- | Existing doc claim contradicted by current code (stale path, renamed symbol, removed field, changed default) | Whichever doc carries the claim | Correct or delete the stale statement |

-

- ### 4. Audit existing docs against the codebase and prune outdated content

-

- Commit-driven updates catch what changed; they miss docs that silently went stale. Before writing new content, spot-check the existing docs against the actual code:

- - For each doc section in the area of an in-scope commit, verify the surrounding claims still hold — file paths exist, symbol names match, defaults and version numbers are current, CLI flags still accept the documented args.

- - Delete or correct any statement the codebase contradicts: removed fields, renamed symbols, dead file paths, stale defaults, deprecated flows, examples that no longer run.

- - Removing wrong content is as important as adding new content — treat a prune as a first-class edit, not an afterthought.

- - Stay scoped: audit the areas related to the in-scope commits, not the entire doc. If the docs look broadly drifted beyond that scope, flag it to the user rather than silently doing a full rewrite.

- - When unsure whether something is outdated, grep the code to confirm before deleting — never remove a claim you haven't verified is wrong.

- - **Cross-check "current/live/active/default" claims against the deciding variable, not the doc's own prior text.** Any doc that names which version/mode/config is currently in effect (a build script's target, a feature-flag default, an active-environment pointer) can go stale silently — the doc reads as self-consistent even after the underlying switch moved. Find the actual switch (grep for the assignment — `MAIN=`, `ACTIVE_*`, a default-branch config key, etc.) and confirm it still matches what the doc claims.

- - **Diff enumerable generated listings against the filesystem.** When an in-scope commit touches a directory holding a versioned or pluggable set of items (plugins, commands, integrations, themes, providers), list the actual directory entries (`ls`, `find`) and compare against every place that's supposed to enumerate them (index/chooser pages, catalog tables, README lists). A missing or orphaned entry is a silent drift the commit diff alone won't surface, because the commit that broke it may be several syncs back.

- - **Check promotion/demotion parity.** If the codebase has a "promote item to active, retire the previous one" pattern (a new default version, a new production config, a newly-active integration), verify that state encoding "this is the active one" — self-referencing URLs, indexing/discoverability directives, feature flags, config defaults — was flipped on BOTH the newly-promoted item and the newly-demoted item. A promotion is a two-sided edit; half-applied swaps (new item correct, old item still claiming to be active) are a common source of live bugs, not just doc drift, and won't show up in a diff of the promoting commit alone. If you find this pattern is real but undocumented as an explicit invariant, add a short rule for it to the project's own docs (e.g. CLAUDE.md patterns) so future promotions don't repeat the same half-applied swap.

- ### 5. Edit CLAUDE.md

- - Stay surgical: edit only the sections that changed.

- - Add new fields to the appropriate config or patterns section.

- - Keep bullets concise — CLAUDE.md is dense reference, not narrative.

- - Update any config/schema version constant the project maintains if a migration bumped it.

- - If a new opt-in field was added and the repo has a SKILL.md, add it to the relevant operator table there (see step 6).

- - **Mirror into AGENTS.md if it exists.** Run `ls -l AGENTS.md` and branch on what it is.

- - **A symlink to CLAUDE.md** (this repo's shape): skip it. The CLAUDE.md edits you just made are already the AGENTS.md content. Never open AGENTS.md for writing here — the write resolves through the link and edits CLAUDE.md, so a tool-specific intro line would land in the canonical file.

- - **A real file**: apply every body edit you just made to CLAUDE.md to AGENTS.md verbatim (architecture, commands, conventions, schema — same content). The only thing that differs is the intro/header line, which stays tool-specific — do not overwrite it with CLAUDE.md's Claude-facing line. Also audit AGENTS.md for the same staleness patterns as step 4: it drifts silently because commit-driven edits target CLAUDE.md by name.

- - **Absent**: skip it — never create one during a sync.

- ### 6. Edit SKILL.md (only if the repo has one)

- Keep SKILL.md operator-facing and imperative; avoid code internals. Common targets, depending on what the repo's SKILL.md documents:

- - **Settings / configuration table** — add new global or per-unit keys.

- - **Post-update / upgrade reference** — add the change as a default, opt-in, or auto-migration row so operators get prompted on upgrade.

- - **Commands / reconfiguration section** — if a CLI surface or reload scope changed.

- - **Operator safety controls** — if guard/circuit-breaker/limit behavior changed.

- ### 7. Edit README.md (only if public surface changed)

- README is the entry point for newcomers and the public face of the project. Default to **no edit** — only touch when one of these is true:

- - **New supported feature/platform/integration** → add to the relevant feature or catalog section.

- - **New public-facing unit** (plugin, command, provider, theme) → add to the list that enumerates them, one line each, matching the existing format.

- - **New top-level CLI subcommand** that users run by hand → add to the appropriate Getting Started block or a dedicated section.

- - **Setup / install / build flow change** → update the relevant setup block.

- - **Public-facing config knob change** that contradicts a documented example → update the affected config sub-block only.

- Skip README for: bug fixes, internal refactors, parameter tweaks, symbol renames, schema migrations (those go in SKILL.md if present), and cosmetic changes.

- When editing:

- - Keep the tone tutorial-clean — no `file:line` cues, no code internals, no PR numbers in body text (PR numbers only in changelog-style sections that already use them).

- - Don't grow lists into prose — each item gets one line / one bullet matching the existing format.

- - If a section already has version/PR references, follow the same convention; otherwise omit them.

- Claude Code warns when CLAUDE.md exceeds 40k chars ("Large CLAUDE.md will impact performance"). Run after step 5:

-

- ```bash

- wc -c CLAUDE.md

- ```

-

- If the byte count exceeds **35000**, condense in-place before finishing the sync. Target: bring the file back under 30000 chars (leaves headroom for the next sync). Do NOT split into multiple files — agents only auto-load the root CLAUDE.md.

-

- **If a CHANGELOG.md exists, relocate rather than delete.** Before dropping completed-migration prose, resolved-incident narrative, or per-issue "why" detail (passes 2 and 5 below), move it into CHANGELOG.md keyed by issue/PR instead of discarding it — the history stays available without loading into agent context every turn. Only outright-delete history when the repo has no CHANGELOG.md to receive it. Never create a CHANGELOG.md solely to offload bytes during a sync; if CLAUDE.md is oversized and no CHANGELOG.md exists, surface that to the user as an option rather than introducing the file unilaterally.

-

- **Condensation rules — preserve agent-critical signal, drop narrative:**

-

- | Keep | Trim / drop |

- |------|-------------|

- | Symbol / file names and `file:line` cues | Prose explaining *why* a pattern exists when the rule alone is actionable |

- | Field-name lists, enum values, default values, version numbers (thresholds, timeouts, schema versions) | Historical migration notes once the migration has shipped and stabilized (>2 versions old) |

- | Non-obvious gotchas, race conditions, lock order, ordering constraints | Restated information that's already in another bullet |

- | Active "new X requires Y" instructions | Examples that duplicate a rule already stated tersely |

- | Currently-live behavior | Deprecated behavior, legacy field aliases that no caller uses |

-

- **Mechanical passes — apply in order, stop when under target:**

-

- 1. **Collapse duplicated phrasing** — same fact stated twice in different bullets → merge into one bullet.

- 2. **Drop completed-migration prose** — if a migration is ≥2 versions behind the current schema/config version AND the legacy field is no longer read, delete the migration narrative; keep the field rename only if code still references the old name.

- 3. **Compress example-laden bullets** — `e.g.` lists with 3+ items → keep the first 1–2 + `…` if the pattern is obvious.

- 4. **Inline single-line sub-bullets** — `- foo:\n - bar` where bar is one short clause → `- foo: bar`.

- 5. **Remove resolved-incident narrative** — "fixed because X happened in prod" becomes "X — see <symbol>" or is dropped if the rule stands on its own.

- 6. **Shorten reference-table cells** — multi-clause descriptions → one clause + symbol name; agents resolve details from code.

-

- **Forbidden — never trim these even if oversized:**

- - The `## Environment`, `## Setup`, `## Build & Deploy`, `## Testing` blocks (operator-load-bearing).

- - Lookup tables — lists of IDs, type names, prefixes, file paths (losing one row corrupts dispatch).

- - Concurrency-hazard rules (state-locking, lock-order, skip-reason/live-exec guards).

- - Any PR/commit footer or format convention the repo's own CLAUDE.md defines.

-

- After condensing, re-run `wc -c CLAUDE.md` and report old → new byte counts. If still over 40k after all six passes, surface to the user with a list of the largest sections and ask which to cut further — don't unilaterally remove load-bearing content.

- ### 9. Update the project memory/notes file if one exists

- Some repos keep a running notes or memory file (e.g. `MEMORY.md`, `NOTES.md`, `docs/CHANGELOG`-style log) with a Releases section. If one exists **and** the in-scope commits include a version tag or release PR, append:

- ```

- - **vX.Y.Z** — YYYY-MM-DD: <one-line summary> (PRs #N, #M)

- ```

- Only append if such a file already exists — never create one during a sync.

- | `git status` is dirty before you start | Stash or commit pending work first |

- | Commit touches multiple unrelated areas | Split classification carefully; don't conflate |

- | A field was *removed* | Delete the row/bullet — don't leave stale docs |

- | Behavior reversal (bug was fixed back to original) | Note the revert explicitly, don't just silently restore |

- | A sync seems to warrant a brand-new top-level doc (AGENTS.md, CHANGELOG.md, SKILL.md) | Surface it to the user — never create one as part of a sync |

-

- ## Common Mistakes

-

- - **Over-documenting internals** — CLAUDE.md is for agent-relevant patterns; SKILL.md is for operators. Symbol/field names belong in CLAUDE.md, not SKILL.md operator tables.

- - **Under-documenting opt-in fields** — when the repo has a SKILL.md, every new opt-in field needs a row in its settings table and its upgrade reference so operators get prompted on upgrade.

- - **Copying PR descriptions verbatim** — translate to concise imperative phrases the reader can act on.

- - **Bundling multiple unrelated changes into one bullet** — one bullet per behavioral change.

- - **Treating README like CLAUDE.md** — don't dump code internals, symbol names, or PR-by-PR changelog entries into README. If a change doesn't affect what a newcomer needs to install/run/configure, it doesn't belong there.

- - **Forgetting README on new public units** — new features/plugins/integrations are the highest-signal README updates and the easiest to miss because CLAUDE.md and SKILL.md updates feel "complete." Always check the enumerated lists.

- - **Trusting a doc's own history instead of re-deriving current state from code** — a "currently active" claim is only correct as of when it was written. Always re-check it against the actual deciding switch (config default, build-script variable, feature flag) rather than assuming a prior sync got it right.

- - **Creating a new top-level doc during a sync** — AGENTS.md, CHANGELOG.md, and SKILL.md are only edited when they already exist; introducing one is a user decision, not a sync side effect.