Home

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.

Try “secrets”, “merge”, “handover” or “database”.