// Blog / definition
How .knowledge routes coding agents to the right files
.knowledge starts with a clearly defined task and builds a focused path to the files and tests that matter before the agent explores the repository more broadly.
// direct answer
Short answer
A task route is a repository-owned map to the modules and files relevant to one job. .knowledge compares that focused starting set with a repository-wide starting set and reports whether it is smaller, larger, about the same, or cannot be measured reliably. This is a local file-size estimate, not provider-reported model-token usage.
Understand how task routing selects a focused set of starting files and how to interpret the resulting local comparison without confusing it with provider usage.
// the problem
Broad repository scans repeat work
A new coding-agent session starts by sampling README files, package manifests, source folders, tests, and old notes.
The agent may find useful context, but it has no stable signal for which summary is current, which module is risky, or which files must be checked before behavior changes.
The result is repeated orientation work and a higher chance of trusting prose that should have been rechecked against code.
// focused task
Start with a clearly defined task
The Routing Bundle is a compact starting map. Focused work begins with the task text and the repository areas that actually contain the change.
The route can include a direct dependency, but it should not expand into sibling repositories or unrelated files because a generic task word happened to match.
The resulting task map points to current source, tests, and supporting checks. Current code and tests remain the source of truth.
// local comparison
Compare repository-wide and task-specific starting sets
The comparison uses a repository-wide starting set and the smaller set selected for one task. Those two views are intentionally different.
The result is calculated from local file sizes. It is not tokenizer telemetry, model speed, accuracy, error reduction, or provider-reported usage.
The result says whether the task-specific set is smaller, larger, about the same, or cannot be measured reliably. Missing or outdated inputs are reported as unavailable rather than as zero savings.
// concrete example
A focused runtime task
If routing_bundle.json is not present after downloading .knowledge, run the setup flow first. The file is created inside the repository so it can describe that project accurately.
The task names the relevant module and path. The task map then directs the agent to the current implementation and tests.
A larger repository-wide starting set produces a smaller-context result. Tiny repositories can produce a larger result, similar sets can be about the same, and missing or outdated inputs make the result unavailable.
If a module summary is marked as needing review or out of date, use it only to find files. Confirm behavior in current source and tests.
// files you can inspect
Files that explain task routing
Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.
.knowledge/maintenance/routing_bundle.json
This is the compact route into modules, trust state, stale items, and the next files to inspect.
- Choosing the first source files to read
- Finding the relevant module boundary
- Claiming runtime behavior
- Skipping source and tests
.knowledge/modules/*.json
Module summaries describe ownership, confidence, and important paths, while their current status shows how much weight they deserve.
- Planning a targeted read
- Spotting low-confidence areas
- Treating old summaries as current
- Making security or billing claims without code
.knowledge/evidence/*.json
Evidence ties claims back to commands, files, or observed checks so the agent can avoid free-floating prose.
- Finding supporting checks
- Reviewing source-of-truth references
- Assuming passing evidence is permanent
- Ignoring stale timestamps
.knowledge/maintenance/repair_queue.json
Outdated or unverified context becomes visible work instead of hidden uncertainty inside the prompt.
- Prioritizing rechecks
- Surfacing stale or suspect areas
- Blocking every edit
- Replacing engineering judgment
// commands to try
Commands and expected checks
node .knowledge/tools/install-agent-integrations.js - what it does
- Agent entrypoints are installed or refreshed for Codex, Claude Code, OpenCode, and local commands.
- where to look
- .agents/skills/*/SKILL.md and .knowledge/agent-integrations/
node .knowledge/tools/flow.js import - what it does
- The repository is ingested without overwriting curated knowledge.
- where to look
- .knowledge/project_index.json and .knowledge/modules/*.json
- before you run it
- Use this when bootstrapping or refreshing an existing repository.
node .knowledge/tools/task-routing.js create --task="<explicit task>" --scope-module=<module> --scope-path=<path> --json - what it does
- A current task map, repository-wide starting set, and local comparison are created for the chosen task.
- where to look
- .knowledge/routing/tasks/<task_scope_hash>/current.json
- before you run it
- Use real repository modules and paths; do not broaden the scope to manufacture a larger narrowing percentage.
node .knowledge/tools/flow.js release --no-color - what it does
- Routing, trust, freshness, search, metrics, Inspector, and current task comparisons are rebuilt.
- where to look
- .knowledge/maintenance/pr_summary.md and the current task routing snapshot
From cold start to targeted source review
// practical reference
How to read the local comparison
| State | What it means |
|---|---|
| Smaller task context | The task-specific starting set is smaller than the repository-wide starting set. |
| Larger task context | The task route includes more local content than the repository-wide starting set. |
| About the same | There is no meaningful local size difference between the two starting sets. |
| Cannot measure reliably | Required files are missing or outdated, so no percentage is reported. |
// quick FAQ
FAQ
Is repo-local routing the same as RAG?
No. RAG retrieves chunks. Repo-local routing is a maintained starting map that tells an agent what to inspect and how much confidence to place in each repository file.
Can an agent edit code based only on routing_bundle.json?
No. The routing bundle should point the agent to source, tests, evidence, and stale areas. Current code and tests still decide behavior.
Is the workspace-to-task percentage actual model-token usage?
No. It is a local estimate based on the size of the selected starting files. It is not provider-reported usage.
Why can a task route report overhead or unavailable?
Routing has fixed structure cost, so small tasks can show overhead or no material difference. Missing, stale, inaccessible, or invalid comparison inputs make the estimate unavailable rather than zero.
Why is routing_bundle.json not visible in the fresh GitHub archive?
It is created during setup inside your repository so it can describe the project’s current modules and files.
// next step
Use task routing before broad repository exploration
Start with the routing bundle as the agent's map, then require source and test reads before behavior-changing edits. That keeps the workflow concrete without pretending the knowledge layer is magic.