How I ship with AI agents

PROBLEM
[What's wrong or missing today. The facts, no solution yet.]

OUTCOME
[What's true once this ships, in a way I can check.]

OUT OF SCOPE
[What the agent must not touch: files, modules, behaviour, platforms.]

CONSTRAINTS
[Stack and conventions to follow.
What already exists and must be reused.
How we test. What to do if you get stuck.]

DONE WHEN
- [a check I can run or see]
- [a check I can run or see]
- Tests cover the new logic, failure cases included.

BEFORE YOU START
Research the codebase and the docs read-only. Don't write code yet.
Come back with a plan. Ask me about anything ambiguous. Don't guess.

Before anything gets built, argue against this plan.

Run it as a debate. The Author defends the plan.
The Reviewer thinks it's the wrong approach.

Stay on design: is this the right approach, what breaks first,
what simpler option got skipped. No bug hunting yet.

If the Author could answer a point with "I already knew that",
the round was too shallow. Run it again, deeper.

End with one verdict: keep the plan, change it (say exactly how),
or drop it.

The seven steps

1. Brief: I write the problem, the outcome and what's out of scope.
2. Research & plan: the agent reads the code read-only and drafts a plan.
3. Approve: I pick the plan and the pattern, and log the decision.
4. Execute: agents build it, tests first.
5. Verify: a fresh session checks it against the brief.
6. Review: I read every line and test it by hand.
7. Ship: small commits, a clear PR, then production.

The eight patterns

Pick one at Approve. Look at the shape, copy the prompt.

1. Single-shot

Small, clear question. One prompt, one answer.

[The question, with the exact context it needs: the file, the function, the error.]

Answer in [a diff / five bullets / one paragraph].
If you need more context to be sure, ask before you answer.

2. Chaining

Fixed order. You check each step before the next.

We'll do this in four steps. Stop after each one and wait for my go.

1. Understand: restate the task, the inputs and the constraints in your own words.
2. Outline: list the changes file by file. No code yet.
3. Build: implement the outline, tests first.
4. Refine: reread the diff against the brief and fix what doesn't match.

Start with step 1.

3. Routing

Mixed requests. One agent sorts them.

You're the router. Sort each item below into one kind:
bug, feature, refactor or question.

Reply with a table: item, kind, the reason in one line, the next step.
Bugs go to a debugging session, features to planning,
refactors wait for my approval, questions get answered here.
Only classify. Don't start any work.

Items:
[paste]

4. Orchestrator

Big plan. One agent splits it and combines the results.

You're the orchestrator for this approved plan:
[paste the plan]

Split it into independent tasks. Give each task to a subagent with only
the context it needs: the task, the files it may touch, the tests it must pass.

Don't write code yourself. Collect every subagent's report, check it
against the plan, then give me one summary: what changed, which files,
what's left and where it could break.

5. Evaluator

Clear bar to pass. A second agent sends it back until it passes.

You're the evaluator. The bar is the DONE WHEN list in this brief:
[paste the brief]

Check the output below against every item: pass or fail, with the exact reason.
If anything fails, write the fix request for the generator and stop.
Say "approved" only when every item passes.
After three rounds without approval, hand it back to me.

Output:
[paste]

6. Tools

The answer lives in files, logs or APIs.

Check the real system before you answer: [question]

Use the tools you have. Read the files, run the commands, call the API.
Show me every command you ran and what it returned.
Read-only. Don't change anything.

7. Parallel

Independent pieces run at the same time.

These tasks don't depend on each other:
1. [backend task]
2. [frontend task]

Run them as parallel subagents, each in its own scope.
The backend agent only touches [folder]. The frontend agent only touches [folder].

When both are done, start a third subagent that runs the Playwright
end-to-end tests on the full flow and reports what fails.

8. Autonomous loop

A goal the agent can check itself, inside limits you set.

Goal: [something you can check yourself, e.g. every test in /billing passes]

Work in a loop: plan the next step, do it, run the checks, look at the result, adjust.
After each round, write one line: what you tried and what happened.

Stop when the goal is met, after [10] rounds, or if you'd need to touch
anything outside [scope]. Then report back. Don't commit.

Verify in a fresh session

You didn't write this code and you have no context on how it was built.

The brief: [paste the brief]
The change: [branch, PR or diff]

1. Run the whole test suite, old tests included.
2. Go through every DONE WHEN item. Mark each one met, not met, or can't tell.
3. Check the new logic has real tests, failure cases included.
   A file that only tests the happy path doesn't count.
4. List anything in the change that's outside the brief.

Report only. I decide what gets fixed.

Log every decision

[date] CHOSE [x] OVER [y] | WHY: [the reason] | COST: [the trade-off]

Rules

• No code before "done" is written down.
• Tests come first.
• The session that wrote the code doesn't verify it.
• Critical code gets a second model.
• I review every line before it ships.