1. Set up
About 5 minutes
Install Cursor from cursor.com/download and sign in.
Claude models sit in the Other models pool on paid plans, Pro and up. Several are hidden by default; if a Claude model is missing from the model picker, turn it on in Cursor's model settings. Cursor models and pricing
Pick one Claude model in the picker and leave it there; every step after this runs on it.
Open the project folder in Cursor. If the folder is not a git repo yet, run this in Cursor's terminal. Agents edit files in place, so git diff shows what they changed and git restore undoes it.
git initOptional, with a Claude plan: search Extensions for Claude Code and pick the one published by Anthropic. Claude Code in VS Code and Cursor
2. Install the kit
About 5 minutes
Read https://tools.islandlab.dev/start/kit and create every file it lists,
at the path it names, with exactly the content between its markers.
If a file already exists, show me the difference and ask before changing it.This prompt does it in one step. Or copy each file by hand.
Cursor reads AGENTS.md as a project rule. Claude Code reads CLAUDE.md, and the one line in it pulls AGENTS.md in. Cursor rules docs Claude Code memory docs
# How to work in this repo
Cursor and Claude Code both read this file. Keep it short: every line here is
read on every request.
## The project
- What it is:
- Run it locally:
- Test it:
## Rules
- Before saying a change to a page works, open it with the Playwright tools,
take a screenshot, and look at it. "It should work" is not a check.
- Make the smallest change that does the job, and leave untouched what was not asked.
- When unsure what is wanted, ask one question rather than guessing in code.
- Commit in small steps with plain messages. Never commit secrets or .env files.
- Work bigger than one file goes through the dispatch agent first (see Agents).
## Agents
Agents live in .claude/agents/: dispatch, scout, hand, builder, verifier.
They are roles, and every one runs on whatever model this session uses. When
a result is wrong, the fix is a clearer brief or a better check.
## Checks
<!-- Every check that proves the work, as a command. -->
- (none yet)
## Lessons
<!-- When the agent gets something wrong, add one line here:
date, what happened, the rule that would have prevented it.
The same lesson twice: move it up into Rules.
A rule a command can check: write the check, list it under Checks. -->Both tools read the same rules.
@AGENTS.mdTwo MCP servers, Playwright and Context7, each described under Tools.
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
},
"context7": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
}3. Tell it how to test
Test it
Open the MCP list in Cursor's settings and turn on playwright and context7 if they are waiting for approval.
Open https://example.com with the Playwright tools, take a screenshot, and tell me the page heading.A screenshot and the heading "Example Domain" mean the agent can see pages. The agent can run and test the project once AGENTS.md, under The project, says how.
4. Hand over a task
Whenever a job is bigger than one file
One file of change: ask in chat. Anything bigger goes through dispatch.
Use the dispatch agent to split this: <what you want>.It hands back the briefs.
Run those briefs with the agents they name, in parallel where Depends on allows, then run the verifier.Cursor reads subagents from .claude/agents/, and model: inherit runs each one on whatever model the chat uses. Cursor subagents docs
.claude/agents/dispatch.mdSplits a request into ten-minute briefs, each with its agent and its check.
---
name: dispatch
description: Splits one request into briefs that each finish in ten minutes or less, names the agent for each, and the check that proves it done. Writes nothing and builds nothing. Use it first on any request that touches more than one file.
model: inherit
readonly: true
tools: Read, Glob, Grep, Bash
---
You are the dispatcher. You do not do the work. Read the request, read enough
of the repo to know what it touches, and return the split.
Return a numbered list of briefs, each in this shape:
### N. <a few words naming the piece>
Agent: scout | hand | builder | verifier
Scope: one file, or one block in one file, by path
Contract: names, ids and file paths the piece must match so the pieces fit
Deliverable: the smallest thing that counts as done
Check: the command that proves it, and what a pass prints
Budget: minutes, 10 or less
Depends on: brief numbers, or "nothing"
Then a short "Integration" block: what to do after the briefs land, and any
decision only the person can make.
Rules:
1. A piece that cannot finish in ten minutes is two pieces.
2. Each brief owns its files: one file or one block for hand, a few files for
builder. No file belongs to two briefs that run at the same time; if two
pieces must change one file, chain them with Depends on.
3. The check comes first. If nothing can prove a piece done, brief 1 writes
that check and the others depend on it. Take checks from the Checks
section of AGENTS.md.
4. You decide the names, once, and copy them into every brief that uses them.
An agent that has to invent a name was briefed badly.
5. Every brief runs on the session's model. Never choose models. If a piece
fails its check twice, say so in Integration: it needs a smaller piece,
more information, or the person, not another try..claude/agents/scout.mdFinds where something lives and answers with paths and line numbers.
---
name: scout
description: Read-only lookup. Finds where something lives, what a file does, or what a name refers to, and answers with paths and line numbers. Use it whenever the answer is in the repo and the only cost is looking.
model: inherit
readonly: true
tools: Read, Glob, Grep, Bash
---
You find things. You do not judge them, propose changes, or write files.
Answer with a short list: path:line, then one line saying what is there.
If you cannot find it, say where you looked. Stop as soon as the question is
answered..claude/agents/hand.mdChanges one file, or one block of it, exactly as its brief says.
---
name: hand
description: Changes one file, or one block of one file, exactly as its brief says, matching the names and paths the brief gives. Use it for the small pieces a dispatch split produces.
model: inherit
tools: Read, Glob, Grep, Bash, Edit, Write
---
You make one change to one file, against a brief.
- Do what the brief says and nothing else. No extra cleanup, no renames.
- Use the names, ids and paths in the brief's Contract exactly.
- Run the brief's Check. Report: what changed, the check's output, pass or fail.
- If the brief is unclear or the check cannot pass, stop and say why.
- If the piece grows past its brief, stop and report what you have and where you stopped..claude/agents/builder.mdBuilds one piece that spans a few files, against a brief.
---
name: builder
description: One piece of work that spans a few files and needs judgment inside it, built against a brief. Use it only when a piece is too tangled to split into single-file briefs.
model: inherit
tools: Read, Glob, Grep, Bash, Edit, Write
---
You build one piece that touches several files, against a brief.
- Keep to the brief's Scope. Use the Contract's names exactly.
- Build the Deliverable first, the smallest version that counts as done,
and run the Check before adding anything.
- Report: files changed, the check's output, pass or fail, and anything you
had to decide that the brief did not settle.
- Two failed attempts at the same check: stop and report. Do not try a third
time without new information.
- If the piece grows past its brief, stop and report what you have and where you stopped..claude/agents/verifier.mdRuns the checks on finished work and reports pass or fail with evidence.
---
name: verifier
description: Checks finished work against its brief and the repo's checks, and reports pass or fail with the evidence. Reads and runs, changes nothing. Use it after agents report done, before believing them.
model: inherit
readonly: true
tools: Read, Glob, Grep, Bash
---
You are the check between an agent saying "done" and anyone believing it.
You verify; you do not fix.
1. Read the brief. List what it promised.
2. Run every check named in the brief and in the Checks section of AGENTS.md.
3. For any page or UI change, open it with the Playwright tools and take a
screenshot. Say what you see, not what the code implies.
4. Report a table: promise, evidence, PASS or FAIL. Then one line overall.
Never mark something PASS because the code looks right. If you could not run
a check, the row says NOT RUN and why.When a check fails twice
Two failures on the same check means stop and add information: a log, a smaller case, or a question to the developer.
About models
When a result is wrong, the fix is a clearer brief or a better check. More tries help only when a check picks the winner.
5. Run the loop
A minute each time something goes wrong, ten minutes a week
- When the agent gets something wrong, ask:
Agent chat
Add a line to Lessons in AGENTS.md: today's date, what went wrong, and the rule that would have prevented it. - The same lesson twice moves up into Rules.
- A rule a command can check becomes a check: a test, a lint, a Playwright script. The verifier runs every check, every time.
- Once a week, for ten minutes, ask:
Agent chat
Read Lessons in AGENTS.md and propose edits to Rules and Checks. Show me the diff and wait for my yes.
6. Grow it
The docs advise watching the first few runs of anything new before trusting it unattended. best practices
The loop: four moves that make a fix last
A mistake corrected in chat comes back next session; the loop writes it down so the fix outlives the session. It is plan, do, study, act applied to the setup itself (IHI, PDSA): the session is the Do, reading what went wrong is the Study, and each move below is an Act.
Each mistake climbs as far as it needs: a lesson, then a rule if it repeats, then a check once a command can test it; decisions are recorded on the side, and rules come back out once their mistake stops.
| Move | Trigger | What the person writes | Where it lives | Established practice |
|---|---|---|---|---|
| 1. A failure becomes a lesson | The agent gets something wrong | One line, the same day: the date, what happened, the rule that would have prevented it | Lessons in AGENTS.md | A written postmortem "after any significant undesirable event", blameless, with "follow-up actions to prevent the incident from recurring" (Google SRE); Toyota's jidoka, "stopping immediately when abnormalities are detected" (Toyota) |
| 2. A lesson seen twice becomes a rule | The same lesson a second time | A standing rule, one line | Rules in AGENTS.md | The docs list anything corrected twice already as belonging in the rules file (Claude Code best practices); "There can be no kaizen without a standard", Taiichi Ohno (Lean Enterprise Institute) |
| 3. A checkable rule becomes a check | A command could tell whether the rule held | A test, a lint, a script, or a hook for what must always hold | Checks in AGENTS.md; hooks in the tool's settings | A rules-file line "works most of the time, not every time" (best practices); "failures become test cases, test cases prevent regressions" (Anthropic, evals for agents); poka-yoke, devices that "help operators avoid mistakes" (LEI) |
| 4. A shaping decision becomes a record | A choice a later reader might undo without knowing why | A dated entry: context, decision, consequences; a reversed one is marked superseded, never deleted | A decisions file beside AGENTS.md | "a short text file" per decision, kept to avoid "blind acceptance or blind reversal" (Nygard, 2011) |
The loop also runs backwards. Every rule costs "a little of Claude's attention on every task", and "from there the work is mostly removing lines" (best practices). Delete a rule once the mistake it prevents has stopped happening.
Since May 2026, Sean's own setup has run this loop across his projects: 68 incident write-ups, 28 decision records, about 250 mistakes logged where a review caught an agent's error before Sean saw it, and about 20 hooks that enforce the rules that must always hold.
The system the person wants
A system is built from the person's own questions, one part at a time, in the order the parts pay off. Anthropic's advice holds throughout: "finding the simplest solution possible, and only increasing complexity when needed" (building effective agents).
| Order | The person's question | What to add | Where it lives | Source |
|---|---|---|---|---|
| 1 | What does the person keep telling it? | A rule | Rules in AGENTS.md, kept short: CLAUDE.md is best "under 200 lines" | memory docs |
| 2 | How would anyone know it is done? | A check | Checks in AGENTS.md, as a command that says pass or fail | best practices |
| 3 | What does it need to see or touch? | A tool, one at a time | An MCP server in .cursor/mcp.json, trusted before it is connected | MCP docs |
| 4 | Which jobs come round again in the same shape? | A workflow or an agent role | Fixed steps first; an agent file in .claude/agents/ only where the steps cannot be predicted | building effective agents, subagents |
| 5 | What must never happen, whatever the model decides? | A hook or a deny rule | The tool's hook settings; a rule file is "context, not enforced configuration" | hooks guide, memory docs |
| 6 | What should run while nobody is there? | A scheduled run | claude -p in a scheduled job or CI, watched for its first few runs | headless mode |
| 7 | What was decided, and why? | A decision record | A dated entry in a decisions file beside AGENTS.md | Nygard, 2011 |
One limit sits on every row: an agent holding private data, reading untrusted content and able to send data out can be tricked into leaking it, so no single agent gets all three (Willison, the lethal trifecta).
Tools worth having
As needed
| Tool | What it gives the agent | How to get it |
|---|---|---|
| Playwright MCP | Opens, clicks and screenshots pages, so the agent checks its own UI work. | In the kit's mcp.json. playwright-mcp |
| Context7 MCP | Current library docs, so the agent writes this year's API. | In the kit's mcp.json. |
| GitHub CLI | Branches, pull requests and issues from the agent's terminal. | brew install gh, then gh auth login |
| Claude Code extension | Claude Code inside Cursor, reading the same AGENTS.md. | Optional, see Set up. |
| Cursor Marketplace | More plugins and MCP servers, in the Customize panel. | Customize Cursor |
The kit
The kit at /start/kit holds these files; each names the step that uses it.
| File | What it does | Used in step |
|---|---|---|
| AGENTS.md | The rules every session reads: The project, Rules, Agents, Checks, Lessons | 2, then 3 (The project), 5 (Lessons, Rules, Checks) |
| CLAUDE.md | One line, @AGENTS.md, so Claude Code reads the same rules | 2 |
| .cursor/mcp.json | Two tools: Playwright to open and screenshot pages, Context7 for current library docs | 2, tested at the end of 2 |
| .claude/agents/dispatch.md | Splits a request into ten-minute briefs, each with its agent and its check | 4 |
| .claude/agents/scout.md | Finds where something lives, with paths and line numbers | 4 |
| .claude/agents/hand.md | Changes one file, or one block of it, exactly as its brief says | 4 |
| .claude/agents/builder.md | Builds one piece that spans a few files, against a brief | 4 |
| .claude/agents/verifier.md | Runs the checks on finished work and reports pass or fail with evidence | 4, 5 |
The kit carries three of the loop's four moves in its Lessons comment; the decision record is kept in a separate dated file.
One car, any engine
Before building
The same engine posts different scores in different cars: the SWE-agent study found the interface built around a model significantly improves its code edits. SWE-agent paper MindStudio on engine and car
A car for any engine
Rules in AGENTS.md, read by more than 20 coding tools; tools over MCP, an open protocol under the Linux Foundation; agents set to model: inherit; a router reaching hundreds of models through one API; checks that judge any model's output alike. Its cost: only the features the shared formats cover, and more files to keep. AGENTS.md MCP governance OpenRouter
A car for one engine
A tighter fit, one vendor's features first, such as hooks and subagent permissions, and less to set up. Its cost: rules, tools and agents to rebuild when the engine changes, since tuning for one model may not carry over. Subagents docs
The kit takes the first path, adding one vendor's extras where they pay.
Sources
Sources opened 2026-11-01: IHI PDSA worksheet; Lean Enterprise Institute on kaizen and poka-yoke; Toyota Production System; Google SRE postmortem culture; Nygard, 2011; Anthropic, Demystifying evals for AI agents; Willison, the lethal trifecta. Every other source is linked beside its claim.