Step 1 - Create the handoff template
# Agent handoff
Goal:
Current slice:
Files inspected:
Files changed:
Verification run:
Reviewer result:
Risks:
Next action:
This file should be updated after every meaningful cycle. Keep it short enough that the next agent will actually read it.
Step 2 - Define the planner role
The planner chooses the next slice. It should not edit code. Its output is a task card:
Task: Add the DB-GPT BM25 article.
Files likely needed:
- content/tutorials/dbgpt-bm25-elasticsearch-rag-guide.md
- src/lib/site-content.ts
Proof:
- article route builds
- blog card links to article
- lint passes
Stop if:
- content renderer cannot parse required Markdown
Good planner output makes the worker boring.
Step 3 - Define the worker role
The worker executes one task card. It should finish by updating the handoff:
Files changed:
- content/tutorials/dbgpt-bm25-elasticsearch-rag-guide.md
Verification run:
- pending
Risks:
- Need final lint after blog card updates.
Next action:
- Add blog card and run npm run lint.
The worker should not claim final success before verification.
Step 4 - Define the reviewer role
The reviewer has a narrow job:
- check the task card against the diff;
- identify missing proof;
- catch unrelated changes;
- request fixes;
- pass only when evidence exists.
Reviewer output should be blunt:
Result: fail
Reason: Article exists, but no blog card links to it.
Required fix: Add BLOG.posts entry and rerun lint.
The reviewer is not there to be encouraging. It is there to protect the loop.
Step 5 - Keep proof attached to each cycle
A handoff without proof is only a status update. Add the exact command or artifact:
Verification run:
- npm run lint: passed
- npm run build: passed
Evidence:
- /tutorials/dbgpt-bm25-elasticsearch-rag-guide generated by getTutorialEntries
- BLOG.posts links to /tutorials/dbgpt-bm25-elasticsearch-rag-guide
For UI work, include screenshots or route checks. For data work, include sampled query outputs. For code work, include tests.
Step 6 - Avoid the two common failure modes
First failure mode: every agent reads every document. Fix it by putting only the current contract and handoff in the default context.
Second failure mode: agents produce reports but nobody merges the reports into the next action. Fix it by making the handoff file the only active run state.
Step 7 - Scale the loop
After the simple loop works, add:
- a registry for multiple active tasks;
- agent-specific report folders;
- a script that checks handoff freshness;
- a final synthesis step;
- a policy that blocks finish when proof is missing.
Do not start with the large system. Start with one handoff file and one honest reviewer gate.