--- title: "Inside LEGION: running agents like an engineering org" url: "https://toddpaulbrownjr.com/writing/inside-legion/" author: "Todd Paul Brown Jr." description: "LEGION is the control layer I run Adroit on — a generated state panel, human-triggered sessions, capability packages and agent governance, built after eight…" kind: "article" updated: "2026-09-26T02:50:32+00:00" --- # Inside LEGION: running agents like an engineering org I first tried to build LEGION in April 2025 and kept trying, by different means, without success, for most of a year. The idea never changed: I wanted to be able to have a discussion with the VP about strategic initiatives while the research, problem solving, asset acquisition and fulfillment were handled by the AI organization without further input from me. What was missing was operator skill and model capability, and I could tell which was which because I kept building other things in between. LEGION came together from late 2025 into early 2026, once I learned to work with coding agents and new models were released in December 2025. The first working files on disk are dated 2026-03-13. On 10 September 2026, roughly 18 months after I first described it, LEGION was actualized — powerful enough to rebuild Adroit's entire website within a couple of hours. This piece goes deeper than [LEGION's build page](/builds/legion/): what it is and how it works, the eight months of failed attempts, what broke and how I fixed it, and what the receipts show. ## What it is LEGION is the system I run Adroit on. It's a repository of instructions, state files, session prompts, skills and scripts that Claude Code sessions work from. When a session starts, the agent reads a generated status panel, the current strategy and my backlog, then executes the item I've pointed it at — deploying Adroit's apps, checking production health, running WordPress commands on the company website, writing product code and keeping its own records. It holds 64 capability packages across five folders, measured 2026-09-25, and it operates Adroit's hosted systems: Content Ops and Sadyr in production, and the company website. Status word: **live**. ## Where this sat against the frontier I started building LEGION in March 2025, in the same weeks OpenAI (11 March), Google (24 March) and Google again (9 April) publicly converged on orchestration as its own architectural layer. About eight months before Anthropic named it a harness (26 November 2025) and eleven before OpenAI published "harness engineering" as a discipline (11 February 2026), I was building around the same architectural insight while the industry was still naming it. The 2025 failures — state that doesn't survive a session, agents ignoring their instructions, agents editing things they shouldn't — are the problems the later harness writing is about. ## Eight months of not building it **March 2025: local scripts to a web app.** I had been working on adding features to my computer to allow AI APIs to interact with each other, but then I thought it might best serve our needs by making it a web app. The browser gave me a 404. **April 2025: Docker + FastAPI + LangChain task runner.** Agents would update files within the virtual environment, which would be deleted when the session ended. To overcome this we had to implement a specific mounting process. An early agent edited the look of the UI, which resulted in black text on a black background, and I went down a rabbit hole of editing various files. The agent didn't seem to believe it was capable of anything — the refusal was explicit. And it defaulted to not reading the onboarding handbook unless it was prompted to do so. That last one led to the fix: attach the file by tooling, and add a default prompt rule telling the agent to read it. In 2025 I already needed both layers — the file attached, and the prompt enforcing it. Same month, the README was already written for agents, not people. The primary audience for this README is AI agents; human users are intended to be a very minor part of this project, with the vast majority of the development being done by Legion agents. These are the earliest recorded evidence of me writing documentation for agents. **May 2025: LEGION v2.0 in Lovable.** I started getting errors as soon as I connected the Lovable code to my GitHub repo. It looked like the problem was that I was on a free account, which cannot update GitHub. I switched to a pro account, but the build was still unsuccessful and gave me more errors. Three attempts, three different failure types: tooling friction (a 404, a free-tier GitHub limit), environment design (work lost in ephemeral containers), and agent behavior (self-edits that broke the UI, refusals, ignored instructions). ## How it works: tiered authority, no standing autonomy LEGION runs on four rules, and the important part is where they live — in the tool's own contract, not just in a policy document I have to remember: - **Observe freely.** Reading logs, checking health, listing what's deployed: any time, no gate. - **Change only with a flag.** A deploy or a write to production needs the explicit flag the script demands (`--yes`, `--confirm`). - **Destructive is mine.** Delete, reset, rotate a secret, push a database to live: never run by an agent. It hands me the exact command instead. - **No standing autonomy.** Sessions run the backlog I set. LEGION documents and operationalizes strategy I have approved; it doesn't author strategy, and when direction is unclear it stops and asks. This was tested by accident, not by design. On 2026-09-21, a LEGION session needed both hosted operator consoles and found them signed out. It did not attempt to sign in — it works inside a browser tab I have already signed into. It finished every other item on the backlog and handed me one line: log in here. Put the boundary in the tool's contract, not just in a policy document — a flag the script literally requires, or a login screen with no session to reuse, stops an agent whether or not it remembers the rule that day. ## What broke and how I fixed it ### Documentation drift Agents trust whatever the docs say, so a stale fact can make a long unattended run confidently wrong for hours. LEGION's fix keeps machine-derivable facts — versions, test counts, git state, whether a file exists — in one generated file, regenerated by a small deterministic script. Judgment stays in files only a person edits. A second run of the sync script has to print "already in sync." The fix still has a limit: it only protects what it actually derives. On 2026-09-21, while cross-checking numbers for an unrelated batch of content, I found that the hand-typed source file the generated panel quotes from had drifted — it declared Sadyr at 1,175 tests when the deployed commit actually had 1,334. The generated panel's own Test Inventory section doesn't track a Sadyr number at all, since Sadyr is an independent repo observed read-only, so the stale figure was sitting one level up, in a hand-written source the generator trusts without re-verifying. I caught it by hand. Every stale test count I have found this year undercounts. Not once has a project's documentation claimed more tests than the repo actually holds. What makes it worse with an agent in the loop, not better: a person skimming a stale doc usually notices the number feels old and checks it; an agent reading the same doc treats the number as a fact and reasons from it confidently for the rest of the task, with no instinct that a document's number can simply be wrong. If a document in your repo states a number instead of deriving it, assume it is already behind. The fix is not writing better summaries. It is writing fewer of them, and building something that regenerates the ones that are just facts. ### A rule the tooling had to enforce My own instructions ban shell heredocs, because they had repeatedly mangled scripts. In one session on 2026-09-21 the coding agent used a heredoc three separate times anyway, apologizing each time. Awareness didn't change the behavior, so I had the agent write a 40-line pre-execution hook wired as a global PreToolUse check on the Bash tool; it denies any shell command containing a heredoc pattern before the command runs. The next deliberate heredoc attempt was refused before execution. A rule an agent has to remember is a suggestion, even when it's written down, even when the agent agrees with it. A rule the tooling checks before the action is a boundary. ### Logged work that wasn't logged In a job-search pipeline I built for a family member — status word **parked** — the audit log held exactly 1 entry for 31 tracked jobs because the state-initialization code never logged its own actions. Fixed, and the log grew to 208 entries in the same session. Separately, the pipeline's own status view reported 26 of 31 jobs as fully tracked when they had not yet cleared human approval, because a step was marked done whenever its output file existed on disk without checking whether its upstream dependency had actually cleared its own gate. Fixed with an explicit post-hoc dependency-enforcement pass and 6 new tests. ### Three unrelated projects, one identical undercount An on-device interactive fiction engine's README stated 610 deterministic tests while its own roadmap, one milestone earlier, had already recorded 1,010 tests green — the highest figure, used per my rule, and the two numbers are unreconciled anywhere in that repo. A proofreading app's last written summary said 309 backend tests; the repo held 368, a figure true only as of 2026-07-15 before the suite kept growing. A Godot game's implementation notes claimed eight test scripts when there were ten, caught by a same-project refinement audit rather than any documentation discipline. ## The receipts Here's what LEGION operates, with the numbers re-pulled at generation time from their live sources: - **Content Ops** v5.12.0: 839 of 839 TypeScript tests and 57 of 57 Python tests passing on the last full run (measured). - **Sadyr** v1.0.0: 2,816 automated tests on its last recorded suite run (measured, 2026-09-23). - **LEGION** itself: 64 capability packages across five capability folders (filesystem count). Every one of those numbers comes from a generated file, not from memory. The full list, with sources, is on the [receipts page](/receipts/). LEGION's own complexity is governed the same way it governs everything else: a generated state panel, capability packages with explicit contracts, and documentation that derives its numbers instead of typing them. The second run of the doc-sync script prints "already in sync." Full receipts — build pages, commits, test counts, dates — are at [/receipts/](/receipts/). ## What's next LEGION is live, operating production systems. The work now is the work it was built for: delegating more of the backlog, catching drift before it compounds, and adding capability packages where the work justifies the tooling. The vision from March 2025 is actualized. The systems it runs are in production. The eight months of failed attempts taught me what had to be true before it could work: the tooling enforces the boundaries, the docs derive their facts, and the agent writes the code while I direct, decide and validate.