tools-registry-context

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 (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 (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'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 — the short version:

1. 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.
2. 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.
3. Show, then apply: present proposed changes and get approval before writing.
4. Regenerate: python3 .Codex/skills/tools-registry-context/scripts/build-map.py (rewrites README + MAP).
5. 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.