Start here: set it up, then make it better

/start/intro explains what AI is and how the levels work; this page is where a person does it. Every step says what the person is doing, what it changes in their work, and how they know it worked. Then comes the loop that improves the setup each week, and how to grow it into the system the person wants.

The levels and the key terms are in the intro at /start/intro.

Already in an editor: go straight to Install the kit.

A mistake ends as a check the next session runs under A working session, where the agent does the job, is the Do. When it goes wrong, the Study, the person writes 1. Lesson, one line under Lessons the same day. The same lesson a second time becomes 2. Rule, one line under Rules in AGENTS.md, deleted once its mistake stops. When a command can tell if it held, it becomes 3. Check, a test, lint, script or hook that always runs, the one accented mark. The next session runs under the new rule and check: the Act, drawn as an arc back to the session. A choice that shapes the setup goes to the side as 4. Decision record: a dated entry beside AGENTS.md holding context, decision and consequences. A working sessionthe agent does the job: the Do it goes wrong: the Study 1. Lessonone line under Lessons, the same day the same lesson a second time 2. Ruleone line under Rules in AGENTS.md deleted once its mistake stops a command can tell if it held 3. Checka test, lint, script or hookthat always runs the next session runs under the newrule and check: the Act a choice that shapes the setup 4. Decision recorda dated entry beside AGENTS.mdcontext, decision, consequences

What the person is doing, step by step

Six steps, from an empty folder to a setup that improves itself.

StepDoingWhat changesDone when
1. Set upGiving the model a folder to work in, with git as the undoThe work lives in files the model reads and changesgit status answers in Cursor's terminal, and git restore undoes a test edit
2. Install the kitWriting the house rules once, where every session reads themInstructions stop being retyped; Cursor and Claude Code read the same AGENTS.md (Claude Code memory, agents.md)The test prompt returns a screenshot and the heading "Example Domain"
3. Tell it how to testFilling in The project in AGENTS.md: what it is, how to run it, how to test itThe agent checks its own work; without a check, the person ends up as the test suite (Claude Code best practices)The agent runs the test command and reports pass or fail without being asked
4. Hand over a taskDirecting and reviewing: a brief in, a diff and a report back; one file in chat, anything larger through dispatchThe person writes the brief and reads the diff instead of typing the codeThe verifier reports pass with its evidence, and the person has read the diff
5. Run the loopTurning each mistake into a lesson, a lesson seen twice into a rule, a checkable rule into a checkThe same mistake stops coming backA week's Lessons holds a line or two, and at least one rule has become a check
6. Grow itMaking rules that must always hold into hooks; moving proven tasks onto a clockThe setup keeps working while nobody types (hooks guide, headless mode)A hook has blocked something once, and the first few scheduled reports have been read

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.

Terminal
git init

Optional, 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

Install: paste into Agent chat
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

AGENTS.md
# 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.

CLAUDE.md
@AGENTS.md

Two MCP servers, Playwright and Context7, each described under Tools.

.cursor/mcp.json
{
  "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.

Agent chat
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.

Agent chat
Use the dispatch agent to split this: <what you want>.

It hands back the briefs.

Agent chat
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

  1. 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.
  2. The same lesson twice moves up into Rules.
  3. A rule a command can check becomes a check: a test, a lint, a Playwright script. The verifier runs every check, every time.
  4. 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.

MoveTriggerWhat the person writesWhere it livesEstablished practice
1. A failure becomes a lessonThe agent gets something wrongOne line, the same day: the date, what happened, the rule that would have prevented itLessons in AGENTS.mdA 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 ruleThe same lesson a second timeA standing rule, one lineRules in AGENTS.mdThe 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 checkA command could tell whether the rule heldA test, a lint, a script, or a hook for what must always holdChecks in AGENTS.md; hooks in the tool's settingsA 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 recordA choice a later reader might undo without knowing whyA dated entry: context, decision, consequences; a reversed one is marked superseded, never deletedA 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).

OrderThe person's questionWhat to addWhere it livesSource
1What does the person keep telling it?A ruleRules in AGENTS.md, kept short: CLAUDE.md is best "under 200 lines"memory docs
2How would anyone know it is done?A checkChecks in AGENTS.md, as a command that says pass or failbest practices
3What does it need to see or touch?A tool, one at a timeAn MCP server in .cursor/mcp.json, trusted before it is connectedMCP docs
4Which jobs come round again in the same shape?A workflow or an agent roleFixed steps first; an agent file in .claude/agents/ only where the steps cannot be predictedbuilding effective agents, subagents
5What must never happen, whatever the model decides?A hook or a deny ruleThe tool's hook settings; a rule file is "context, not enforced configuration"hooks guide, memory docs
6What should run while nobody is there?A scheduled runclaude -p in a scheduled job or CI, watched for its first few runsheadless mode
7What was decided, and why?A decision recordA dated entry in a decisions file beside AGENTS.mdNygard, 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

ToolWhat it gives the agentHow to get it
Playwright MCPOpens, clicks and screenshots pages, so the agent checks its own UI work.In the kit's mcp.json. playwright-mcp
Context7 MCPCurrent library docs, so the agent writes this year's API.In the kit's mcp.json.
GitHub CLIBranches, pull requests and issues from the agent's terminal.brew install gh, then gh auth login
Claude Code extensionClaude Code inside Cursor, reading the same AGENTS.md.Optional, see Set up.
Cursor MarketplaceMore 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.

FileWhat it doesUsed in step
AGENTS.mdThe rules every session reads: The project, Rules, Agents, Checks, Lessons2, then 3 (The project), 5 (Lessons, Rules, Checks)
CLAUDE.mdOne line, @AGENTS.md, so Claude Code reads the same rules2
.cursor/mcp.jsonTwo tools: Playwright to open and screenshot pages, Context7 for current library docs2, tested at the end of 2
.claude/agents/dispatch.mdSplits a request into ten-minute briefs, each with its agent and its check4
.claude/agents/scout.mdFinds where something lives, with paths and line numbers4
.claude/agents/hand.mdChanges one file, or one block of it, exactly as its brief says4
.claude/agents/builder.mdBuilds one piece that spans a few files, against a brief4
.claude/agents/verifier.mdRuns the checks on finished work and reports pass or fail with evidence4, 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.