claude-brain: A Spec-Driven Workflow for AI Coding Agents
Program and Product
What is claude-brain?
claude-brain is the private workflow repository I use to run AI coding agents in my own repositories. Every piece of work gets a numbered roadmap entry, then three documents before any code is written: requirements, a design, and a task list. I approve each one, or I waive the approval and the waiver is recorded in the entry. A fourth document, the handoff, is what the implementing model actually receives. A strong model reviews a low-cost model’s work after every task, and a person reads the diffs before a merge unless that step was waived on the record.
The repository holds the stage definitions, the commands that drive them, the linters that enforce them, and one central roadmap. That roadmap has carried more than 500 entries since September 2026.
Why do unattended AI coding runs go wrong?
They go wrong when a decision is left for the run to make. A model working alone with an open question will answer it, and the answer will be plausible, and nobody will be there to notice that it was the wrong one. The workflow’s stated principle is to move all the thinking to before the run, so that the session doing the work has nothing left to decide.
The second cause is state. When small changes skip the process, the next session has to guess what was done and what was only discussed. So a three-line fix and a new module take the same path: an entry, a specification, and a handoff. The uniformity is what lets any session pick up any entry cold.
What is an EARS requirement?
EARS is the Easy Approach to Requirements Syntax, a small set of sentence patterns that make a requirement checkable instead of open to interpretation. The patterns cover properties that always hold, responses to an event, behavior during a state, optional features, and unwanted conditions. An event-driven requirement reads: WHEN <trigger> THE SYSTEM SHALL <response>.
In this workflow each requirement is numbered, and each task in the task list names the requirement numbers it satisfies and the exact command whose output is the evidence. A reviewer does not judge whether a task feels complete. The reviewer runs the command and reads whether the output demonstrates the numbered sentence.
What is a handoff document, and why is it a gate?
The handoff is the single message a fresh session can read with no other context and start working from. The implementing session has an isolated copy of the repository, the handoff, and nothing else. It has no chat history and no way to ask a question. If the handoff assumes anything outside itself and the files it points to, it is defective.
It contains the mission in two sentences, a block of ground rules that is pasted verbatim, the environment and the test baseline that has to pass before work starts, and the tasks in order. The rule attached to it has no exceptions: if the handoff is not written, the work is not ready to run. A linter checks the specification folder before a run is allowed to start, and a pre-commit hook has refused a handoff that failed it.
How do you use a low-cost model for code without losing quality?
By separating the model that writes from the model that judges, and by making the judge read real output. The implementer is a low-cost model called once per task with the handoff, a pointer to the task, and the current contents of the files that task touches. It returns complete files. The reviewing session, a stronger model, then does four things after every task.
Read the actual test output
The reviewer runs the evidence command itself. The implementer’s summary of a test run is not evidence.
Read the diff
Line by line for a small task, and every hunk for a large one.
Check scope
The files touched have to be exactly the files the task names. A drive-by fix, a reformatted file, or a dependency bump is reverted, not negotiated.
Give a verdict
A pass records the evidence and one commit for the task. Two failures on the same task stop the run, and the stopping point is written up for me.
A validation exercise ran this loop with DeepSeek V4 Pro as the implementer across five small projects. All 15 attempted tasks passed on the first attempt for about $0.20 in total. The one-call form cost about 1.2 cents per task, against about 2.2 cents for a full agent session doing the same work, because an agent session spends most of its tokens on its own tool traffic.
The default implementer today is a different low-cost model, GLM-5.3-Flash, and its record on real tasks is weaker. Of 9 recorded tasks, 2 were accepted without correction and 2 broke scope. That record is why the diff review is mandatory and why that model gets small, single-file tasks only.
What has the workflow caught, and what has it caused?
Its tooling has failed in ways that the process then recorded and closed. Each of these is an entry in the roadmap with its fix.
A model reply was cut off at its output limit, and the script that applies replies wrote the partial file as if it were whole. The file lost 60,507 of its 177,280 characters and still parsed as valid Python, so a syntax check would not have caught it. The applier now refuses any reply that did not finish normally.
The next ticket number was once a stored counter that concurrent sessions read and wrote back, and they collided repeatedly. The number is now derived fresh each time from the roadmap rows, the specification folders in every known checkout, and the branch names. That tool has itself reported a taken number twice, each time because a checkout was missing from its list.
The roadmap file was corrupted by a text-encoding fault three times in one week before a linter existed to catch the cause. A test fixture run from a git hook flipped a setting on the workflow repository itself, and it happened twice. The first repair did not remove the cause. The second time the commit was refused, the cause was fixed, and a regression test now covers it.
What are its limits?
The workflow was designed for overnight runs. Some recorded runs were autonomous batches under a standing authorization, with the stage approvals paused, and others were attended sessions. The rule is that a person reads the diffs before a merge. I have waived that rule for batches of work, and each waiver is written into the roadmap entry in plain words, so the record shows which work was reviewed and which was not.
A reviewing model does not make the low-cost model’s output correct. It makes defects visible at the task where they occur, and the record above shows that the tooling around both models has needed its own fixes. The repository is private.