2026-09-12
The Foundation · Part 4 of 4
The Constitution and the Dashboard: What Lives in the Repository and What Lives in the Tool
Context routing, session continuity, cost tracking — the tool ecosystem ships all of it. The question is which layer each concern belongs to, and what breaks when you put it in the wrong one.
The Foundation · Part 4 of 4 · ~6 min read · prev: Part 3 — The Language of Control · next shelf: The Orchestrator Mindset — The Coder Isn't Dead
"Context routing? There's a plugin for that. Session continuity? A plugin for that too. Cost tracking, context dashboards, execution traces — the ecosystem already ships all of it. Why are you building this in the repository?"
It is a fair question with a precise answer, because the assumption underneath it is a category error: a repository pattern and a tool plugin are not competing solutions to one problem, and confusing the two is how a team ends up with governance that dies the moment it switches tools. Every plugin solves a real problem and is a stopgap for a question the repository should eventually answer itself — this is a statement about architecture, not competence.
The Category Error
When a plugin "does context routing" and a repository pattern also "does context routing", it looks like duplication. It is not. The plugin decides what the runtime loads right now — one session, one tool. The repository declares what any agent must load, for any task, in any tool, from now on. One is a behaviour of a running process; the other is a contract that outlives the process. They share a verb, not a layer.
| The tool answers | The repository answers |
|---|---|
| "What is happening right now?" | "What must always be true?" |
| "What did this session load?" | "What should every session load?" |
| "How much did this cost?" | "What is allowed to enter the prompt?" |
| "Where is this task?" | "What are the steps, and where are the gates?" |
The tool is a lens. The repository is a law. A lens shows what is happening; a law says what must hold — and you would not put a live chart into a constitution, or a constitutional rule into a dashboard that will one day be replaced.
The Boundary Rule
If removing the tool changes what the agent must do, the concern belongs in the repository. If removing it only changes what the human sees, the concern belongs in the tool.
Sharpen it one step further, because there are three categories rather than two:
| Category | The test | Where it lives |
|---|---|---|
| Rule | Must the agent obey this? | Repository — portable, versioned, reviewed |
| Mechanism | Does something execute this? | Tool — indexing, execution, sandboxing, caching |
| View | Does a human look at this? | Tool — dashboards, panels, diffs, dialogs |
The common mistake is thinking in two buckets when there are three. A mechanism and a view belong in the tool, and neither is lesser for it — a repository cannot index a codebase, and it should never try. The practical form is the deletion test: delete the plugin. If the agent now does the wrong thing, the rule belonged in the repository; if it merely becomes less visible, it was a view.
Where the deletion test gets subtle
Two cases are genuinely ambiguous, so run the test rather than sorting by instinct.
Memory and project-context features. Delete the tool's memory: does the agent lose the rule or the fast path to it? If the map also lives in the repository, only the fast path is lost — a mechanism, and fine. If the tool held the only copy, the agent now does the wrong thing: a rule in the wrong place.
Saved prompts. Delete them: the agent loses a convenient wrapper, not a constraint — provided the constraints inside those prompts are written down elsewhere. A saved prompt carrying the only statement of a rule is governance in a tool-specific format, and it will not survive the next tool.
What breaks in each direction
A rule in the tool works beautifully until you migrate runtimes, a teammate uses another editor, or the plugin is abandoned — and then the agent loads whatever it wants, because the rule was never in the repository: invisible, unversioned, unreviewable. This is tool lock-in wearing a productivity costume. A view in the repository is the mirror failure: a dashboard definition in the always-loaded files is read on every request, updated by nobody, and meaningless to a reader using another tool. Context economy is not a slogan here — every kilobyte of always-loaded rules competes with the task itself.
Sorting the Concerns That Get Conflated
| Concern | Rule → repository | Mechanism → tool | View → tool |
|---|---|---|---|
| Context routing | The table of rules: "for API tasks, load endpoints, auth, data model" | Reading the rule and loading those sections | The panel showing what loaded, and what it cost |
| Session continuity | The session artifact schema — task, status, files read, decisions, next step, gate status | The lifecycle: auto-resume, session identity, crash recovery | The timeline |
| Workflow orchestration | The named, gated procedure: step → action → gate → approval | The engine that runs steps and stops at gates | The board showing where each procedure stands |
| Escalation boundaries | The declared conditions under which the agent must stop | The permission layer that enforces the sandbox | The approval dialog |
| Context economy | What is allowed to load, by task scope | Token metering, compression, window management | The cost dashboard |
| Execution transparency | The execution-log schema: timestamp, task, files read, rules applied, gates run, outcome, next step | Tracing, telemetry, request capture | The trace viewer and replay |
Two rows carry the subtlety. Escalation boundaries: a permission system can only enforce permissions — "stop and report, because this change touches the law" is a behavioural rule, and those live in the repository. Execution transparency: the repository log proves whether the rules were followed; the runtime trace proves what calls were made — collapsing them loses the one an auditor needs.
Sorting Real Tool Features
| Feature | What it really is | Where it belongs |
|---|---|---|
| Project instruction file | A rule — already repository-native | Repository (canonical) + thin per-tool adapter |
| Custom slash commands / saved prompts | A rule wrapped in tool syntax | Repository content; tool-format shim |
| Glob-scoped rules files | A rule, with tool-specific scoping | Canonical rule in the repository; scoping in the tool |
| Memory / project-context features | A rule the tool happens to persist | Repository (the map); tool memory is the fast path |
| Tab completion, inline suggestions | A mechanism | Tool. Never the repository. |
| Codebase indexing, semantic search | A mechanism | Tool. Never the repository. |
| Agent mode, plan mode, tool execution | A mechanism | Tool. The plan artifact can be repository-owned. |
| Hooks, sandboxing, permissions | A mechanism | Tool. The escalation conditions are repository-owned. |
| Dashboards, diffs, cost meters, trace viewers | A view | Tool. Never the repository. |
| Model routing, temperature, context caching | A mechanism | Tool. Never the repository. |
Most rule-like features in these tools are a tool-specific expression of something the repository should own — the tools compensating for the absence of a standard governance layer, which is why a team that writes its rules in five formats ends up with five rules that drift apart.
The Posture Is Symmetric
"Rules belong in the repository" is easy to hear as "repository good, tool bad" — the opposite failure. Over-correcting looks like reimplementing codebase indexing in shell scripts, rebuilding the editor's panel as a dashboard, and writing token metering into the repository: waste in the other direction, spent on mechanisms and views the tool already ships well.
One canonical source of truth for every rule. Adopt every mechanism and view the tool offers. Write thin adapters, never duplicates.
This is not AI-specific: networking keeps its routing rules in config rather than in the network dashboard, infrastructure keeps declarative state out of the provisioning console, and observability decides what must be measured separately from the chart that shows it. The separation is the best practice, and this is that same separation applied to AI-assisted work.
The Decision Procedure
1. Ask: is this a rule, a mechanism, or a view?
2. If a rule -> state it once in the repository (plain markdown).
If the tool needs its own format, write a thin adapter
that points at the repository rule. One source of truth.
3. If a mechanism -> adopt the tool feature. Do not rebuild it.
4. If a view -> adopt the tool feature. Do not rebuild it.
5. Never write the same rule twice, in two tools' formats.
Step 5 saves the money: drift between duplicated rules is the silent failure, invisible until two tools answer the same task differently. A rule changes the way everything else in the repository changes — by pull request, reviewed, with its reason recorded. If a rule changes constantly, it may really be a mechanism wearing a rule's clothes.
The Orchestrator's Takeaway
Sort every concern with one question: rules to the repository, mechanisms and views to the tool. Write each rule once, keep the always-loaded set small enough that it does not compete with the task, and run the deletion test before rebuilding anything the tool already does well.
Where the Foundation Ends
The vocabulary exists, the principles are named, and the boundary is drawn — the whole of the foundation this framework stands on. What remains is the engineering judgement an engineer applies on top of it when the work is delegated rather than typed: the work of the Orchestrator Mindset series, which opens with The Coder Isn't Dead.
For the full method, see The DevOps Engineer's Guide to Effective AI Usage.