Who it's for
Engineers who want agents to build real changes, not demos.
You'll be able to
Walk one change from idea to merge, and say who decides at each step.
Agents type fast. The way of working decides what they type, and who says yes before it reaches main.
Five steps, one owner each
Every change takes the same path. Each step has an owner and a result you can point at.
| Step | Who | Result |
|---|---|---|
| Spec | A person, with an agent's help | A short document: what to build, and how we know it is done |
| Plan | An agent; a person approves | A list of small tasks, each with its test |
| Build | Agents | Code, with a test written first for each task |
| Check | Scripts, then AI checkers | The automatic checks pass; a person reads the checker report |
| Review and merge | A person | The change is on the main branch |
Three rules hold it together:
- No code before an approved spec.
- One task, one commit or a few. Each commit names its step.
- If a check fails, fix the cause. Do not weaken the check.
People decide, agents build, checks guard main.
A task is one pull request
Tasks live as issues in your tracker, and the issues are the only copy of the task list. One issue is one piece of work, small enough for one pull request.
A small change needs no separate spec: the issue is the spec. A bigger piece of work gets a spec file first, and several issues that link to it.
Two parts of each task decide how it gets built:
- How we know it is done. A command that says "done" or "not done": a test, or a score with a limit. With one, an agent can work alone for a long time, because it can see how far it is. Without one, a person stays close.
- Kind of work. A person marks it
routineorjudgment. Routine is a known kind of work with a "done" command. Judgment is a new idea or a design choice, and gets a written design first. An agent never sets this mark on its own task.
From task to merge
- A person writes the issue and adds a label that says "an agent may build this". Agents never add that label.
- An agent builds it on a branch, with a test first.
- The pull request closes the issue and names its step.
- A person reviews and merges.
The person is at both ends. An agent can't start work nobody approved, and its work can't land without someone reading it.
Try it
Take the next change you were going to hand to an agent. Before it starts, write the issue:
- What to build, in one or two sentences.
- Two or three acceptance points, each answerable with yes or no.
- The command that says "done" or "not done", or "none" if there isn't one yet.
routineorjudgment, chosen by you.
If you can't fill in step 3, plan to stay close while the agent works.