Two classes of tools, two different roles. Context tools give the agent cheap, accurate understanding of the code — without reading the repository file by file. Authoritative systems hold the truth and the evidence: stage, code, tests, design. And every system has three possible integration paths — chosen deliberately, case by case.
The agent walks down the ladder from the cheapest accurate tool and stops at the first one that answers the question. Two cost filters run in parallel: rtk trims command output before it reaches the model, and caveman compresses the model's own communication.
A local knowledge graph of the code: symbols, calls, flows. One query returns a function's source together with who calls it — from a precomputed index, not from reading files. Available to agents as MCP and as a CLI.
npm i -g @colbymchenry/codegraph
github.com/colbymchenry/codegraph
Semantic search over code and documents: "where is the payment retry logic" — without knowing function or file names. The best first entry into an unfamiliar repository.
uv tool install semble
github.com/MinishLab/semble
A blazing-fast next-generation grep: exact matches, regular expressions, final verification of hypotheses from the two previous rungs of the ladder.
brew install ripgrep
github.com/BurntSushi/ripgrep
A CLI proxy that filters the output of developer commands (git, builds, tests) before it reaches the model. A hook rewrites the calls transparently — the agent does not need to know about it.
brew install rtk
rtk-ai.app
A plugin that enforces an ultra-compressed model speaking style — "talk like a smart caveman": no ornament, no pleasantries, full technical substance. Works on reports, statuses, and handoffs between agents; three compression levels (lite / full / ultra).
/plugin marketplace add JuliusBrussee/caveman
github.com/JuliusBrussee/caveman
These systems are not for "reading code" — they hold state and evidence. The agent's context may be ephemeral, but the truth about stage, code, tests, and design lives in authoritative systems and can be reconstructed after a restart. What binds is the role in the process, not the product name — below is our set; at a customer, their equivalents take these places.
Lifecycle statuses, gate entries (ANALYSIS GATE: PASS 8f3c21ab), decisions, and the full audit history of every issue.
Pull requests, reviews, merges only through the gate. CI on a self-hosted runner pool builds the evidence: tests, lint, scans — pinned to a specific SHA.
Test results from CI land in test cycles — coverage and regression history does not vanish in build logs; it has its own auditable register.
Browser tests: login flows, route smoke, screenshot comparisons. The artifacts become UI verification evidence at the gate.
The agent reads and annotates designs directly: component specifications and design tokens feed Analysis and Architecture without manual transcription.
Self-hosted flow orchestration: approval gates, retries, integrations between systems — where automation does not require a full agent.
Four categories: dependency scanning, static analysis, dynamic testing, container image scanning — for us cargo audit, clippy, OWASP ZAP and Trivy respectively. Results pinned to a specific SHA become security evidence at the verification gate.
Three roads with different properties lead to every system. A mature process does not pick a single "best" one — it matches the path to the character of the work: deterministic, interactive, or governed by policy.
| Path | When | Strengths | Limitations |
|---|---|---|---|
| Script / CLI | delivery tracks: gates, status transitions, merges — everything that must be repeatable and accountable | ✚ deterministic and fail-closed ✚ cheap in tokens ✚ runs headless and in cron |
✖ your own code to maintain ✖ a rigid set of operations |
| MCP | interactive work: exploring issues, working with the design file, sessions with a human | ✚ full operation schemas without shell glue ✚ rich, two-way interaction |
✖ per-session authentication — can vanish in headless runs ✖ token overhead of the tool schemas |
| Skill / wrapper | when access must carry policy: preflight auth, a uniform error contract, a double-work lock | ✚ rules enforced in one place ✚ consistent error messages across the whole role system |
✖ an extra layer and latency ✖ one more artifact to maintain |
The rule: the path is chosen per case, not per fashion. Delivery tracks run on scripts (determinism + audit), interactive work on MCP, and a skill steps in where policy is needed — not access alone. One thing is constant: evidence always lands in the authoritative system, never in the agent's memory.
Process roles are definitions — an agent runtime executes them. We use two, deliberately different ones: an interactive runtime for orchestration and decisions, and a headless one for high-volume implementation. The third element is the model ladder: simple tasks go to the cheapest model that passes the gates.
Anthropic's interactive runtime (also runs headless). In our stack: the Director layer — delivery orchestration, decisions, operator collaboration — plus agent subtasks wherever the job needs a strong model.
npm i -g @anthropic-ai/claude-code
claude.com/claude-code
OpenAI's execution runtime. In our stack: the main implementation line — a Director sends a task package, the runtime executes it autonomously in a sandbox and returns a branch with evidence.
npm i -g @openai/codex
github.com/openai/codex
Models with token costs orders of magnitude lower, OpenAI-API compatible. Role on the ladder: mechanical, well-defined tasks go to the cheap model; escalation to a stronger one happens only after a gate failure.
platform.deepseek.com
api-docs.deepseek.com
Division of labour: decisions and orchestration — the interactive runtime; high-volume implementation — the headless runtime; mechanical changes — the cheapest model that passes the gates. Whatever the runtime, the same gates and the same evidence apply. On top of that, every PR revision is reviewed by an independent AI bot on GitHub — a voice from outside both ecosystems, treated as an opinion, not a gate verdict.