Add a shared instruction kernel and byte-budgeted topic router so agents load only task-relevant repository guidance. Wire drift checks into local and CI workflows and point project skills at the routed topics.
3.1 KiB
AI Context Router
This page is the complete in-repository manual for maintaining agent documentation routing without an external skill. Load it with python3 scripts/ai-context.py ai-context.
Layers
- Kernel: root
AGENTS.md, loaded for every task. It contains only universal rules and topic triggers. - Scoped instructions: package- or app-specific nested
AGENTS.mdfiles. Every scoped file must be loaded by at least one topic. - Topics:
docs/ai-context.jsonmaps topics to complete files or exact headings.scripts/ai-context.py <topic>prints only those sections. - History:
wiki/history/stores milestone logs in their original language. History is not loaded by default and is indexed inwiki/README.md.
docs/ai-context.json is the single source of truth. The tables in AGENTS.md and wiki/README.md are discovery mirrors.
When Documentation Must Change
Update documentation in the same change that makes it stale:
| Change | Update |
|---|---|
| Changed behavior described by a topic | That topic page |
| Found documentation that contradicts code | Verify the code, fix the documentation, and mention it in the handoff |
| Learned a cross-task lesson from a failure | A one-line behavior rule in the kernel plus the procedure in its topic |
| Finished a milestone | wiki/history/<milestone>.md and the wiki/README.md history index |
| Added a recurring kind of task | A new topic, JSON entry, and both topic tables |
Added a nested AGENTS.md |
Map it to a topic |
Do not put volatile state in the wiki, including progress counts, current owners, or today's blocker. Keep that information in the tracker.
Adding or Changing a Topic
- Put the content in
wiki/<page>.md. A topic should represent a recognizable kind of work, not one ticket or file. - Map it in
docs/ai-context.jsonusing a complete file or exact heading. - Add it to the tables in
AGENTS.mdandwiki/README.md. - Run
python3 scripts/ai-context.py check. - Render the topic and read it as an agent would; it must be sufficient on its own for the task.
Heading references must be unique and exact. A section ends at the next heading of the same or higher level. Never use line ranges.
What Check Enforces
- Every path stays inside the repository and exists, and every heading matches exactly once.
AGENTS.mdand every topic stay within byte budgets. Split an over-budget topic instead of raising its cap.- Every JSON topic appears in
AGENTS.md. - There are no orphans:
- every non-history wiki page is loaded by a topic;
- every history file is indexed in
wiki/README.md; - every nested
AGENTS.mdis loaded by a topic.
Only genuine human-only exceptions belong in the JSON unrouted map, and every exception requires a reason.
Skills and CI
Skills retain workflow phases, report templates, and helper invocation. They load the applicable topic before acting; repository rules must not exist only in a skill.
The router check runs through the Makefile docs-check/check targets and the test and website workflows. After changing the router, run:
python3 scripts/ai-context.py check