The Code Builder Agent
Agents

The Code Builder Agent

Skip to main content
Table of Contents
< All Topics
Print

The Code Builder Agent

Last updated: November 20, 2026

The other agents in this series do editorial work. The code builder agent does engineering. It builds one change to the software that runs our publication, in a place where it cannot disturb anyone else’s work, with tests that prove its guards work. The same discipline applies: a written brief, hard limits, a report and a human who verifies.

What it is

The worktree code builder (worktree-code-builder) is an internal engineering agent. It implements exactly one step brief for our code in its own isolated copy of the repository (a git worktree) and reports in one results file. A step might be a script, a library, a test, a Makefile target or the definition of another agent. It is not an editorial tool and it never writes articles.

It works under a written build preamble that governs all code-building agents. Where the brief and the preamble disagree, the brief decides what to build and the preamble decides how.

When it runs

An orchestrating session dispatches it from a written step brief, in one sentence: read this brief and follow it exactly. The brief names the worktree and branch, the files it may touch and read, the spec, the tests that must pass, a tool-call budget, the commit message and the results-file path. The agent does not pick its own work.

What it does

  1. Reads the rules first: our agent-delegation rules and the build preamble, before any command.
  2. Works only in its own worktree. It never edits, stages or runs a writer in the main checkout, which belongs to the editing console and the content stream. The linked copy of our shared methodology repository is also off limits; a change there is a separate pull request the orchestrator opens.
  3. Touches only the files the brief lists. A fix needing another file becomes an open question in the results.
  4. Writes tests. Every new guard ships with a bite test: a test that seeds the fault and proves the guard fails on it. A guard without one is not done. New tests do not touch the network or write into the repository, and are fast and safe to run in parallel.
  5. Runs the named tests, then the full code suite (make test-code) once at the end.
  6. Measures instead of citing. Every count it reports carries the command that produced it.
  7. Commits once, when its gate is green: explicit file paths only, with the message the brief gives, on its own branch, respecting the lane guard that keeps content, docs and code in separate commits.
  8. Writes a results file of at most 350 words under fixed headings: status, done, not done, tests run with pass and fail counts, files touched, measured counts, open question and commit identifier.

It stops as “blocked” when a test selector collects zero tests, a test it did not touch turns red, it needs a file outside its list or a decision, or it reaches its tool-call budget.

Skills it applies

It applies no editorial skills. It applies the agent-delegation rules and the build preamble, both internal working documents that we describe and do not link.

Rules and gates it obeys

The engineering rules it follows are the ones described in Engineering and Change-Control Guards: tests as the gate, bite tests for every guard, separate commit lanes, and protected files that an agent never edits. The runtime limits shared by all agents are in AI and Research Runtime Guardrails.

Protected files are never edited by this agent: the project instruction files, the agent-instruction files that other tools read, the editor rule files, the other agent-tool workspace files and the Claude settings and hook files.

A separate test, tests/test_agent_definitions.py, checks every agent definition in the repository, including this one. It confirms that each definition is well formed, contains none of a list of forbidden instructions (such as pushing to a shared branch or reading the credentials file) and names only script paths that exist.

What it may never do

  • Push, merge, open or comment on a pull request, or run the GitHub tool.
  • Switch branches, stash, or touch another agent’s worktree.
  • Publish, deploy, or write to WordPress, the search index or a server.
  • Edit a protected file, any file its brief does not list, or anything in the main checkout.

Where a human decides

The orchestrator verifies the work itself; the results file points at what the agent did and is not evidence that it worked. Someone other than the agent reviews the commit, runs the checks and decides whether it ships. Shipping, meaning pushing, opening a pull request and merging, is never the agent’s step, and our main branch requires automated checks to pass before a change merges.

Team persona

This agent builds for the product and engineering side of the team, described on Jordan Calloway — Director of Product & Engineering. It does not mirror an editorial role. For the agents that do, see Agents and Automation: The AI That Works Here, and Its Limits and The Research Worker and the Document Auditor.

Factual correction requests: If you believe information in this page is incorrect, please contact factcheck@citizenanalyst.ai with your name (optional), the specific claim, and any supporting documentation. We review all submissions and correct verified errors promptly.

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
Please Share Your Feedback
How Can We Improve This Article?