Rook

What it is

Rook is the runner that builds Trellis. It takes each story from a queue and moves it through fixed stages:

1. Journey tests. A builder agent writes one failing journey test for each acceptance criterion, then stops. A journey test checks a step that a person takes through the product, not a line of code.
2. Test agreement. Rook checks that each test fails for the right reason. A checker agent confirms that the tests match the criteria. Only then does the builder write code.
3. Build. The builder writes the code and says “ready”.
4. Gate. Rook runs the full gate and mutation testing on the changed lines, in a clean copy of the code.
5. Audit. The checker reads the criteria, the diff, the gate record and the mutation report. It answers one question: would each test catch a wrong implementation?
6. Release. Rook opens the pull request. A person merges.

A failed step sends the story back to the builder, in the same session. The message holds the exact facts: the failing test names, the mutants that survived, or the checker’s findings.

How it grew

The start: rules and two agents. I began with a set of written rules and two agents in separate sessions. One built a ticket, and the other reviewed it. Because they never shared a session, the review stayed independent. A small meter showed what each session cost and how much the cache saved.

A weekly retro drives each change. Each week, I look at the runs and fix what slowed them down most. Three changes shaped it.

At first, agents did everything. A runner moved tickets between the two agents. The agents also ran the gate, waited for locks, cleaned up and released. I measured it, and the model did useful work for only a small part of the time. Most stops came from the setup, not the model:

• a gate that gave two agents different answers,
• commands that a safety check refused,
• a watchdog that stopped an agent while it waited for a lock.

The model was not the bottleneck. The setup was.

So agents judge, and code runs the rest. I moved every step with a fixed answer into code. Tests come first, and they must be agreed before any code. Then I tuned it on real stories. Two stories run at once, and an hourly cap limits launches. A guard stops code until each criterion has a red test.

Then features ship whole. When each story released alone, the shared gate was often red for reasons outside the story. The live journey then found one bug per run. Feature mode changes the unit from a story to a feature. The full journey, live, then gates the release.

One design decision

Agents judge. Code does everything else.

An agent writes code, writes tests and reads code. Any step with a fixed answer is a script that Rook runs. Scripts run the gate, wait for locks, order the queue, run mutation testing and open the release. A script gives the same answer every time, so nobody runs it twice.

The rules it keeps today

• One gate result per code tree. The builder, the checker and the release all read the same record.
• Tests first, agreed first. A missed criterion is caught in minutes, not after a full build.
• Mutation testing is the evidence. Rook breaks the changed code on purpose. Each break that the tests miss goes back to the builder as a list.
• One warm session per story. Every round of a story resumes the same session, so the cache stays warm. A second check reads only what changed.
• Cost on every run. A ledger records the cost and the cache hit rate of each stage and story. Budget caps can stop a story, a stage or a day.

Feature mode: done means the journey passes

Feature mode is built. Switching it on is on the roadmap.

The tests prove that a person can use the product, not only that the code runs. The journey is the set of steps a person takes through the live product, from start to end.

• Each story owns one journey step. The first test of a story checks that step, and it fails at first. The story is done when the step passes on the local stack.
• Failures go to the owner. A failing step goes back to the side and the story that own it.
• The whole journey gates the release. It runs once, live, before the pull request. A green gate alone ships nothing.
• A failing main branch stops all new work. While the main branch fails, Rook starts only the stories that fix it.

Feature mode: a warm cache for the whole feature

Most of the cost of an agent is reading its context again. Feature mode keeps more of that context in the cache.

• One agent per side. One agent owns the front end and one owns the back end, for the whole feature.
• One fixed prefix. The prompt, the rules and the contract are the same, byte for byte, for every session. Each new session reads them from cache.
• Short notes, not long history. Between stories, an agent starts again from the fixed prefix and a short note that it wrote.
• A steward agrees the plan. A steward agent agrees each feature before the work starts.

Status

Rook is in use on my own projects, and a weekly retro improves it. Feature mode is built, and switching it on is on the roadmap. The code is private for now.