Tools
The papers I use when I run agents, in the order a run needs them. Fill one in here and copy it out. What you type stays in this browser. They are cut down from mine. What I would skip and keep in a smaller system.
Download all of it10 files for your repository.
before the project
The opening interview
Paste this at the start of a project. The agent reads first, settles what it can, then asks what is left in one go. Lesson 1
Before you write any code, interview me.
1. Read everything that already exists in this project first: the code, the documents and any earlier decisions. Do not ask me anything those already answer.
2. Work out which open decisions would change what you build. Settle every one you can from what you read, and say which those are. Bring me only the ones that need an owner.
3. Ask me all of those together, in one batch. Do not drip them one at a time.
4. For each question, put your recommended option first, and say what it would cost me if that choice turned out wrong.
5. When I have answered, write my answers into the project as recorded decisions, in a file, in my own words. Mark each one "do not re-open".
6. If nothing is left open, say so. Then tell me what you will build first, and wait for my go-ahead.
A template written for this site from the practice in the talk. The skill I use for this is longer.
before the project
The PRD
One document says what the product is, who it is for and which decisions are yours. Every agent starts from it. The three decisions ticked are mine. Lesson 2
PRD:
Sources:
1. Summary
2. Problem
3. Goals
System invariants. Each one is a test.
4. Who it is for
5. User stories
6. Out of scope
7. Open questions
8. Decisions that stay with me
9. Slice map
Each slice is one thing a user can do, through every layer it needs. Each gets its own spec.
Amendments
Every agent reads this before starting work. It is kept under version control. Changes are added as dated notes and the old text stays.
Sections 1 to 7 follow my own PRDs, in order and cut down. The decisions and the slice map are added.
before a run
The slice spec
The plan for one slice, written before any agent starts. It says what is in, what must not be touched, what is already decided and what proves it is done. The five fences ticked are mine. Untick what does not apply and add your own. Lesson 11
Spec:
Kill criteria: when to stop
Goal
Scope
In:
Out, untouched:
Decisions already made. Do not re-open.
Build order
Exit tests
Hands-on proof
To delete
Risks
Fences: stop and wait for me if the next step would
Budget
This is the plan. Where it and the kickoff prompt disagree, this wins.
The first nine sections follow my own slice specs, in order. Mine run longer. Fences and budget are added here. In mine they sit in the kickoff prompt.
before a run
The kickoff prompt
What you paste into a fresh chat to start the run. It points at the spec and adds what only this run needs. The part about what you have approved ahead of time is yours to fill in, never the agent. Lesson 11
Build . Run to completion without me.
Branch: , from
The plan is . Where this prompt and the spec disagree, the spec wins.
READ FIRST, IN THIS ORDER
RULES FROM LAST TIME THAT NO LONGER APPLY
RULES THAT ALWAYS APPLY
One slice per chat.
The fences in the spec hold for the whole run.
Secrets by name only, never by value.
KNOWN GAPS AND RISKS
DECISIONS
Already made, do not re-open:
BUILD ORDER
QUESTIONS
If anything still blocks you, ask all of it now, in one batch, recommended option first. After that, work without interrupting me unless it is something only I can decide.
WHAT I HAVE APPROVED AHEAD OF TIME
If this is empty, nothing in this run merges, deploys or publishes. One approval never implies another.
DONE WHEN
The parts and their order are the ones in my own kickoff prompts.
handing over
The state file
Where the work stands, kept by one agent. Commit it after every write. With the PRD, the spec and the kickoff prompt, it is what a fresh agent needs to pick up cold. Lesson 5
State:
Only the lead agent writes this file. Builders and checkers send it their updates. Commit it after every write.
Shipped
Decided but not landed
Waiting on me
In progress
Environment
Known proof gaps
Next
The sections follow my own state files. I lost one that was not committed.
when it comes back
Evidence pack
What a claim of done has to come with before I will read it. Lesson 14
Evidence:
Verdict:
Commit:
Branch:
Captured:
Environment:
Why not the real environment:
1. Seen failing first
2. Results
Passed
Failed
Not verified
Inconclusive
3. What the operator sees
4. Human gates
Not satisfied by this pack. No merge, no production database change, no publication.
Not done here
A skip is never written up as a pass. New results go at the top. Old results are never edited.
The sections follow the proof notes and test reports from my own work.
when it comes back
Can this check fail?
Paste this into your agent. It goes through every test and check, says what each could catch, and lists the ones that cannot fail. A check that cannot fail tells you nothing when it passes. Lesson 22
Audit the checks that guard this work. Do not change any code.
Scope:
A check that cannot fail tells me nothing when it passes. For every test, automated check and review step:
1. Say in one line what failure it is meant to catch.
2. Say whether it could go red where it runs. Look at that place: does it have what the failure needs, such as real keys, real data, a real browser or the real service? If the failure cannot happen there, the check cannot fail.
3. Say what it observes. Does it assert something a user can see or do, or only that nothing errored?
4. Say whether it would still pass if the feature it guards were deleted.
5. If it expects an error, say whether it passes on any error or only on the one it names.
6. If it is new, say whether it fails on the commit before the change.
7. Say whether an empty result looks the same to it as a result that could not be read.
8. Say whether anything is skipped and counted as passed.
Then give me three lists:
Checks that can fail and that observe a real result.
Checks that cannot fail where they run, and what would have to change for them to be able to.
Things a user depends on that no check observes at all.
Quote the file and line for each check. Do not guess. If you cannot tell whether a check can fail, say so, and say what you would have to run to find out. Do not suggest loosening a check to make it pass.
Written for this site from the first chapter of the essay. Questions 5 to 8 come from my own failures.
after a failure
From failure to rule
One page to fill in after something breaks, so the lesson ends up somewhere it cannot be skipped. Lesson 24
What went wrong:
Symptom
Root cause
Checks that passed for the wrong reason
Smallest safe fix
How to check the fix
Do not
The rule, in one line
Where must this live?
If it is critical to safety, it must end up in the last row. A lesson that only lives in prose can be skipped.
How the next agent meets it
The sections up to the rule follow my own write-ups. The four places are the ones in the talk.
to learn all of it
Get walked through all of it
Give this to ChatGPT or Claude with pages from this site, and it will walk you through them. All 27 lessons
Act as my guide to the attached Chief of Agents materials.
Start by asking about my technical background and what I want to do with AI coding agents. Then offer a 10-minute overview, a 30-minute walkthrough, or a 60-minute working session.
Explain unfamiliar terms before using them. For every section, separate:
1. the general engineering principle.
2. the implementation used in the example project.
3. the failure or evidence that motivated it.
4. the decision I would need to make for my own project.
Do not assume that the named tools or models are required. Do not invent project details, costs, incidents, or results. If two sources disagree, point out the disagreement instead of guessing.
Pause after each part so I can ask questions. At the end, help me fill in a spec for the first slice of my own project: its scope, what it must not touch, its exit tests and its fences.
From the written guide to the talk, shortened, with the last step changed.