tools-registry-context — load the right design fragment, keep docs honest
tools-registry's design docs are fragments under docs/context/ (one per subsystem), each declaring the source files it covers in frontmatter. [MAP.md](MAP.md) (next to this file) is the generated reverse index: source file → the fragment that documents it. This skill has two modes.
Mode A — LOAD context (default). Adapt to when you're called:
Cold start (a fresh session, little/no prior context) → warm up. Read [docs/context/README.md](../../../docs/context/README.md) (the index), then the fragments that matter (the foundation-style overview fragments plus whichever subsystems the query or repo state points at). Run git log --oneline -15 and git status to catch recent commits + uncommitted work. Then give a short orientation — what tools-registry is, the subsystems in play, what changed recently — and say you're ready.
Mid-chat (a task/topic is already in play) → stay targeted. Map the artifacts/topic at hand via [MAP.md](MAP.md)'s "Source file → fragment(s)" table, read just those fragment(s), and proceed. Don't re-warm the whole tree.
A focus query (/tools-registry-context <query>) always wins — use it to pick the fragment(s) and focus the warm-up on that area, in either case.
Always: read the data model / behavior / RCAs / symbol anchors before changing anything; load only what's relevant (never dump the whole tree); if an artifact you touch has no fragment, note it as a gap for Mode B.
Mode B — SYNC docs (/tools-registry-context sync, or before a push)
Before a push to the main branch, remind the user to run this; proceed only on their yes. Then follow [MAINTAINING.md](MAINTAINING.md) — the short version:
- Detect drift:
bash .Codex/skills/tools-registry-context/scripts/drift.sh (defaults to
origin/main..HEAD). It prints, per changed source, which fragment(s) document it — plus gaps.
- Draft updates: for each affected fragment, read it + the diff; update prose to match changed
behavior and verify cited symbols still exist (no line-number chasing — symbols don't drift). New subsystem with no fragment → draft a new fragment from fragment.md.tmpl.
- Show, then apply: present proposed changes and get approval before writing.
- Regenerate:
python3 .Codex/skills/tools-registry-context/scripts/build-map.py (rewrites README + MAP).
- Commit together: doc updates ride with the code in the same commit/push.
Invariants
- Docs are the source of truth; this skill is a lens. Fragments live in
docs/context/; never
duplicate them into the skill. The skill holds only the generated MAP.md + scripts + config.
- Frontmatter drives everything. A fragment's
sources: feeds the index, the MAP, and drift. When a
fragment starts covering a new file, add it to sources: and rerun build-map.py.
- Cite stable symbols, not line numbers. Anchor every claim to a grep-able symbol; bare line
numbers drift on every edit and slow sync. Describe what shipped, not intent.
- No automation behind the user's back. Sync is reminder → approve → apply. There is no git hook.
- Handoffs and plans are NOT documentation. They live outside
docs/context/ (e.g. .context/) and
are out of scope — never read, fold in, or scan them as fragment input.
