Repository-Scale Coding Agent Governance

Teams using Claude Code or Cursor can treat token waste as a repo hygiene issue. agent-stack gives a concrete pattern: generate CLAUDE.md, AGENTS.md, .claudeignore, hooks, Cursor rules, skills, and .agent-stack/graph.md in one setup step, then log usage through a Stop hook into .agent-stack/usage.jsonl.

The most useful part is the code map. It indexes source files and exported symbols so an agent can search one compact file before opening source. The README example claims 142 files and 906 top-level symbols in the map, a CLAUDE.md capped at 800 startup tokens, and a measured drop from 12,340 to 7,180 input tokens per day. Those numbers are project claims, so the practical adoption test is simple: run the setup on one active repo, keep the baseline, and compare input tokens per day after a week of normal agent work.

Agent teams with repeated multi-step work can move the control flow into workflow files. BotCircuits stores each workflow as JSON under .botcircuits/workflows/; after loading, the workflow becomes a callable tool. The LLM still handles each agentAction, while the runtime follows start, next, and compiled branch conditions.

This is a fit for tasks where the sequence matters: release checks, support triage, file-generation jobs, or codebase audits that must stop early under known conditions. The README shows an 11-step example with an end_id argument controlling early termination, plus a /workflow add command that drafts, previews, writes, and registers a workflow without a restart. The missing check is measurement: teams should log task completion, branch accuracy, latency, and token use before calling it safer than a plain agent prompt.

Teams accepting LLM-generated code need review steps for names, boundaries, invariants, and tests. Martin Fowler’s essay frames code as machine instructions and as the conceptual model a team shares. For generated code, the risk is code that runs but introduces words, structures, or abstractions the team cannot explain during maintenance.

A practical change is to add a short generated-code section to pull request review: list any new domain terms, map them to existing bounded contexts or explain the new boundary, identify invariants in tests, and ask the author to remove names that only mirror the prompt. This gives the model better future context and gives reviewers a concrete way to catch cognitive debt before it spreads through the codebase.