lead
Skill0 starsChanged 15 days agoMITView on GitHub
Lead a workspace of several repositories: divide an epic into stories and tasks, agree the contracts between the repositories, give each task a new member session with a complete brief (or start it in the background, with the CLI), route the handoffs, and keep the progress, cross-repository tests and decisions in docs/workspace/. Use in a session started at a workspace root.
20 other projects use a version of this.
Adopted by
Most recently taken up by
- kchojn/claude-code-tradecrafttheir own version, first seen Nov 16, 2026
- rmyndharis/mandortheir own version, first seen Nov 15, 2026
- warrendeanlangeveldt/code-kittheir own version, first seen Nov 15, 2026
- igoroliveirg/claude-copytheir own version, first seen Nov 15, 2026
- Palatine-Labs/conisotheir own version, first seen Nov 15, 2026
- microsoft/vscode-documentdbtheir own version, first seen Nov 8, 2026
Used with
Projects with it also use reflect, technical-writing and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Microsoft AzureSkillreflect
Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md.
Also in 4 projects that use this
VercelSkilltechnical-writing
Write, edit, review, or audit user-facing documentation for the eve repository. Use for changes under docs/, documentation tied to eve APIs or CLI behavior, docs work based on Slack or support feedback, and requests to make eve docs clearer, more natural, or less AI-patterned while verifying claims against current source, tests, CLI help, public releases, and repository conventions.
Also in 3 projects that use this
Microsoft AzureSkilldesign
Design rules and conventions for the API Center Portal. Use when editing detail pages, card components, badges, layout, navigation, sidebars, or headers. Covers badge styling, metadata placement, page navigation patterns, and layout alignment.
Also in 3 projects that use this
photon-groveSkillunslop
Detects and rewrites generic, overly polished, or AI-sounding prose while preserving meaning. Use when the user asks to "unslop", humanize, de-AI, tighten, or review whether writing sounds generated.
Also in 3 projects that use this
GoogleSkilltdd
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
Also in 4 projects that use this
VercelSkillsetup
Set up Vercel CLI and project configuration. Use when the user says "set up Vercel", "configure Vercel", "link to Vercel", or "vercel init".
Also in 3 projects that use this
Other versions20 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 20
- Devolutions/IronRDP★ 3.3ksame name
- keli-wen/agy-staff★ 873same name
- robertguss/claude-code-toolkit★ 118same name
- microsoft/vscode-documentdb★ 33same name
- Palatine-Labs/coniso★ 17same name
- igoroliveirg/claude-copy★ 9same name
- Kripu77/software-factory★ 7same name
- xiebaiyuan/xiebaiyuan-skills★ 6same name
- alexnthnz/keel★ 5same name
- gao-xh/multi-agent-protocol★ 4same name
10 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/CLAUDE.mdCLAUDE.md
- a11y-auditSkill
- architecture-reviewSkill
- bootstrap-projectSkill
- capture-screenshotsSkill
- customizeSkill
- deliver-featureSkill
- design-reviewSkill
- docs-upkeepSkill
- fix-bugSkill
- handoffSkill
- implementSkill
- log-decisionSkill
- refine-requirementsSkill
- release-readinessSkill
- reproduce-in-worktreeSkill
- security-auditSkill
- ship-prSkill
- start-taskSkill
- sync-branchSkill
- threat-modelSkill
- verify-featureSkill
- vet-dependencySkill
- write-adrSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
77 rules. 0 are common, 35 are distinctive, and 42 are very specific to this project.
0
Common
Most of the 19 edited versions we read keep these.
35
Distinctive
This author's own choices. Worth a look.
42
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Do not change files in a member repository.
- Distinctive: line 43
Do not read a full diff, a full log or the full output of a test.
- Very specific: line 44
Read only the newest entries of HANDOFFS.md.
- Distinctive: line 45
Start again (section 6) at each of these points:
- Very specific: line 48
Do not use /compact. A new lead reads files that you wrote on purpose.
- Very specific: line 49
If your context was compacted, the summary can be wrong.
- Distinctive: line 55
Use the Read tool to read a file.
- Distinctive: line 57
Use one command for each repository.
- Very specific: line 67
Write the line Lead started: <YYYY-MM-DD HH:MM UTC> at the top of HANDOFFS.md.
- Very specific: line 68
Use ListAgents to find the sessions that run now.
- Very specific: line 69
If a task is in progress and its session does not run, ask the owner what happened to the session.
- Distinctive: line 75
If the epic file has a "Lead checkpoint", do its next steps.
- Very specific: line 76
If STATUS.md has open decisions, ask the owner about them (section 6, "Open decisions").
- Distinctive: line 80
Read the epic from its source: the ticket in the tracker, or the local file, list or description that the owner gives.
- Very specific: line 81
Do the steps of start-task for the full workspace: the assumptions, the possible meanings and the product questions.
- Very specific: line 82
If the request is not clear, do refine-requirements first.
- Distinctive: line 83
Ask the owner where to keep the briefs of the tasks.
- Distinctive: line 87
Ask the owner who starts the member sessions.
- Distinctive: line 90
Ask the owner the product questions, the question about the briefs and the question about the sessions in one message.
- Distinctive: line 98
If an unknown stops the plan of a story, make a scout task first.
- Very specific: line 104
Do not use max, unless the owner tells you to.
- Very specific: line 108
If a contract is difficult to change later, the member that owns it writes an ADR (write-adr) in its repository.
- Very specific: line 111
Write the epic file docs/workspace/epics/<epic id>.md from the template EPIC.md.
- Very specific: line 112
Add each task to STATUS.md, with the state planned and its checks.
- Distinctive: line 116
Do these steps for each task that can start now.
- Distinctive: line 131
Do not put secrets or private data in a brief.
- Very specific: line 133
Add the effort level of the task to the command: --effort <level>.
- Very specific: line 134
If the brief is in the tracker of the member repository (its AGENTS.md), the session reads the brief from the ticket.
- Very specific: line 136
If a different session works in the same repository at the same time, add -w <session name> to the command.
- Distinctive: line 138
Stop until the owner tells you that the session runs.
- Very specific: line 139
Use ListAgents to find the session.
- Very specific: line 141
If ListAgents does not show the session, and you started it, run claude agents to see that it runs.
- Very specific: line 142
If ListAgents still does not show the session, tell the owner to paste the text of the brief into the session.
- Distinctive: line 148
Do this only if the owner chose it (section 2).
- Very specific: line 151
Run the start command from section 3 step 2, with --bg and --permission-mode auto added.
- Very specific: line 156
Do not use --permission-mode bypassPermissions.
- Very specific: line 158
Ask for a notice when the session is idle (SendMessage with notify_when_idle).
- Very specific: line 160
If it waits for a permission or for the trust of its folder, tell the owner to open it: claude attach <id>.
- Distinctive: line 161
If it asks the owner a question, send the question to the owner.
- Very specific: line 162
When the task is complete, stop the session: claude stop <id>.
- Distinctive: line 168
Do not make a new sub-task.
- Very specific: line 170
Make sure that the old session of the task is closed.
- Very specific: line 172
If the owner chose that you start the sessions, do "Start the session yourself" in that folder.
- Distinctive: line 183
If the cause is the usage limit, wait until the reset time.
- Very specific: line 184
Use ListAgents. If the session is there, send it this message: "Your last turn stopped (<cause>).
- Very specific: line 185
If the session is not there, it cannot receive messages.
- Very specific: line 186
Write the stop and the recovery in HANDOFFS.md.
- Very specific: line 188
If you, the lead, stopped, you cannot do these steps.
- Distinctive: line 196
When a handoff comes:
- Very specific: line 198
Record it: Put the handoff at the top of HANDOFFS.md, as you received it.
- Distinctive: line 222
If the reply is not clear, ask the subagent one question.
- Very specific: line 223
If you cannot use a subagent, do the three steps yourself.
- Very specific: line 224
Compare it with the contract: If one side changed the contract, tell both sides to stop.
- Distinctive: line 231
If the task is complete, tell the owner how to deliver it.
- Very specific: line 240
If the task is complete and you started its session, stop the session (claude stop <id>).
- Distinctive: line 241
If a closed task needs more work later, continue the task (section 3, "Continue a task").
- Distinctive: line 242
Start the tasks that can start now (section 3).
- Distinctive: line 249
Write the findings that later tasks need under "Notes for the next task" in the epic file.
- Distinctive: line 250
If the report recommends work, record the recommendation as an open decision (section 6).
- Distinctive: line 251
When the owner agrees, plan the work as build tasks.
- Distinctive: line 252
Stop the session of the scout task, or tell the owner to close it.
- Very specific: line 258
Do these steps when all the tasks of a story are complete in their repositories.
- Very specific: line 260
Run the cross-repository checks of the story in STATUS.md.
- Distinctive: line 263
If a check fails, send it to the session of the task that owns the cause.
- Distinctive: line 264
After a fix, do the check again.
- Distinctive: line 273
Commit the records at each important point.
- Distinctive: line 274
Commit on the current branch of the workspace repository.
- Very specific: line 280
Write each question to the owner in STATUS.md, in "Open decisions": an id, the question, the options with the recommended option first, and …
- Distinctive: line 283
When the owner comes back, or when a new lead starts, ask the open decisions one at a time.
- Distinctive: line 287
Do this at each point in the section "Keep your own context small".
- Very specific: line 289
Make sure that STATUS.md, HANDOFFS.md and the epic file are up to date.
- Distinctive: line 290
Write the section "Lead checkpoint" in the epic file.
- Very specific: line 292
Do not copy the open decisions.
- Very specific: line 297
If this session runs in the background, the owner stops it with claude stop <id>.
- Very specific: line 303
Make sure that each story and each task is done in STATUS.md and in the epic file, with its PRs.
- Distinctive: line 304
Make sure that the cross-repository tests passed, with evidence.
- Distinctive: line 305
Put a summary handoff on each story ticket and on the epic ticket, or at the top of the epic file if there is no ticket: the changes in …
“Common” is measured: kept by at least 6 in 10 of the 19 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Lead a workspace
Playbook files named here: when the project has its own copy at
.playbook/local/<same path>, use that copy instead.
Request: $ARGUMENTS
You are the lead of the workspace. Your level is staff engineer for the full project. You start at the workspace root.
- You plan the work, give it to the member sessions, examine their results and keep the records.
- The member sessions build. Each member session works in its own repository, and obeys the
AGENTS.mdof that repository. - Do not change files in a member repository. Write only in the workspace repository: in
docs/workspace/, in the folder for the briefs that the owner chose, and in theAGENTS.mdof the workspace when the owner agrees. - Work in the workspace root, on its current branch. Do not make or enter a worktree for yourself (no
EnterWorktree, no-w). The rule inAGENTS.mdabout worktrees is for the sessions that change code. A new lead session and the owner read the records in the workspace root. In a worktree, the records are on a different branch, and the member repositories are not there.
Rules: AGENTS.md section 8 (members, sessions and workspace rules), and ${CLAUDE_PLUGIN_ROOT}/principles/15-agent-collaboration.md. Templates: ${CLAUDE_PLUGIN_ROOT}/templates/workspace/EPIC.md, ${CLAUDE_PLUGIN_ROOT}/templates/workspace/TASK.md and ${CLAUDE_PLUGIN_ROOT}/templates/handoff.md.
Words in this skill:
- Epic: a large request. It contains stories. If the request is one story, the epic contains only that story.
- Story: a change that a user can see and use. It has the acceptance criteria that the owner accepts. A story can need changes in more than one repository.
- Task: one part of a story. A task is one PR in one repository. One new member session does one task. A story can have many tasks.
- Scout task: a task that investigates a question and writes a report. It makes no PR. A report can recommend work, but it does not give approval for the work. Only the owner gives approval.
- Brief: the complete instructions for one task. The member session starts from the brief only.
- Contract: the agreed interface between two repositories, for example an endpoint, a payload, an event, a shared type or an error code.
- Route: give a task or a next step to a session, and record that you gave it.
Why one session for each task
A session that works for a long time collects a large context. Each new message sends all of it again, so it uses many tokens. A new session for each task starts small: the rules and the brief of the task.
Thus, keep the context in files, not in sessions:
- The epic file (
docs/workspace/epics/<epic id>.md) is your memory for the epic. - The brief of each task contains all the data that the task needs, and nothing more. Do not put the full epic in a brief.
Keep your own context small
Your context also grows. When it is large, your work becomes worse, and you cannot see that it becomes worse. Thus, obey these rules. Do not use your opinion to decide.
- Do not read a full diff, a full log or the full output of a test. A subagent examines each handoff and gives you a short result (section 4).
- Read only the newest entries of
HANDOFFS.md. - Start again (section 6) at each of these points:
- A story is
done. - You received 5 handoffs after the last Lead started line in
HANDOFFS.md.
- A story is
- Do not use
/compact. A new lead reads files that you wrote on purpose. A summary keeps only the data that it selects. - If your context was compacted, the summary can be wrong. Do section 1 again before you route a task. But in step 2, write the line
**Lead context compacted**: <YYYY-MM-DD HH:MM UTC>, not a Lead started line. Count the handoffs from this line also.
Commands that read files
Some machines block reads outside the working directories of a session (permissions.blockReadsOutsideWorkingDirectories). If the block cannot examine a command before it runs, it asks the person. A background session cannot show that question, so the session stops.
- Use the Read tool to read a file.
- In a shell command, write each path in full. Do not use loops, variables,
cdor command substitution in a command that reads files. - Use one command for each repository. Example:
git -C backend status --short --branch.
1. Find the current state
- Read these files:
AGENTS.mdsection 8.docs/workspace/STATUS.md.- The epic file
docs/workspace/epics/<epic id>.md, if it exists. If it exists, continue the epic from it. Do not plan again. Its section "Lead checkpoint" tells you what the last lead waited for and what to do next. - The newest entries in
docs/workspace/HANDOFFS.md, until the last Lead started line. - The entries in
docs/workspace/DECISIONS.mdthat apply to the request.
- Write the line
**Lead started**: <YYYY-MM-DD HH:MM UTC>at the top ofHANDOFFS.md. Section "Keep your own context small" counts the handoffs from this line. - Use
ListAgentsto find the sessions that run now. Compare them with the tasks that arein progressinSTATUS.md. - If a task is
in progressand its session does not run, ask the owner what happened to the session. If the session closed, continue the task (section 3, "Continue a task"). - If a task is
in progressand its session runs, the session possibly sent a handoff when no lead session ran. Send it this message: "The lead session started again. If you sent a handoff, send it again." Ask for a notice when it is idle (notify_when_idle). Also read the ticket of the task. - For each member repository, read the state. Do not change the repository:
git -C <repo> status --short --branchgit -C <repo> log --oneline -5git -C <repo> worktree list
- If the epic file has a "Lead checkpoint", do its next steps. If the checkpoint and the state that you found are different, use the state.
- If
STATUS.mdhas open decisions, ask the owner about them (section 6, "Open decisions").
2. Plan the epic (gate: owner)
- Read the epic from its source: the ticket in the tracker, or the local file, list or description that the owner gives.
- Do the steps of
start-taskfor the full workspace: the assumptions, the possible meanings and the product questions. - If the request is not clear, do
refine-requirementsfirst. - Ask the owner where to keep the briefs of the tasks. Give these options:
- The tracker in
AGENTS.md(recommended when there is one): one sub-task of the story for each task, with the brief in its description. If the tracker has no sub-tasks, use a child issue of the story. - A different tracker that the owner names. The member sessions cannot read it. Thus, you send each brief in a message, and you put each handoff on the ticket.
- Markdown files:
docs/workspace/tasks/, or a different folder in the workspace repository that the owner names. You send each brief in a message.
- The tracker in
- Ask the owner who starts the member sessions. Give these options:
- The owner (the default): you give the owner a start command for each task. This works in the desktop app and in a terminal.
- You, in the background: only if you run in the Claude Code CLI, and
claude --versionworks in your shell. The owner gives the maximum number of member sessions that run at the same time. The owner must trust each member repository folder once: the owner opens one normal session in that folder and accepts the trust question. A background session cannot show that question.
- Ask the owner the product questions, the question about the briefs and the question about the sessions in one message. Record each question as an open decision (section 6). Then stop until the owner answers.
- Get an id for the epic. Use its ticket id. If the epic has no ticket and the briefs go in a tracker, make the epic in the tracker first. If the briefs are Markdown files, use a short id, for example
E1. - Divide the epic into stories. If the epic has stories in the tracker or in the source file, use them. Do not make a copy of a story. Each story gets its acceptance criteria and the cross-repository checks that prove them.
Divide each story into tasks. Each task is one PR in one repository. Give each task its acceptance criteria and its checks. Make each task small enough for one session. Divide a task again if one of these is true:
- It has a data migration and also other changes.
- It makes a contract, and it also uses a different contract that is not complete.
- You expect more than approximately 400 changed lines. Do not count tests and generated files.
If an unknown stops the plan of a story, make a scout task first. Examples of unknowns: an area of the code that you do not understand, a risk, or a choice between approaches. The build tasks that need the answer wait for the report.
Give each task an effort level for its session:
low: a small task with a clear path.mediumorhigh: a usual task.xhigh: a task with an unclear design, and each scout task.- Do not use
max, unless the owner tells you to.
- Make the tasks independent. Two sessions must not change the same files at the same time.
- Write the contracts first. For each contract, write its shape, its errors, its version, and the repository that owns it.
- Record each contract with
log-decisionindocs/workspace/DECISIONS.md. - If a contract is difficult to change later, the member that owns it writes an ADR (
write-adr) in its repository. The owner must accept the ADR before a session builds on the contract. - Put the stories and the tasks in sequence. Finish one story before you start many others. Then the owner can examine each story early. Find the tasks that can run at the same time, and the tasks that must wait. For example, the frontend builds against the contract with a stub while the backend builds the endpoint.
- If the briefs go in a tracker, make each new story as a child of the epic. Make each task as a sub-task of its story. Write only a summary in the sub-task now. Write the full brief when the task starts (section 3), because earlier tasks add data to it.
- Write the epic file
docs/workspace/epics/<epic id>.mdfrom the templateEPIC.md. Write in it the place of the briefs and who starts the sessions, as the owner chose. - Add each task to
STATUS.md, with the stateplannedand its checks. Add the cross-repository checks of each story.
3. Start a task
Do these steps for each task that can start now.
Write the brief from the template
TASK.md:- In a tracker: put the brief in the description of the sub-task of the task.
- In Markdown files: write
<folder>/<task id>.md.
Make the brief complete. The member cannot see your conversation, and it cannot read the workspace files. Put in the brief:
- The owner's request for this work, in the words of the owner. Do not change it or make it wider. Your acceptance criteria come from it.
- The epic in one sentence, the story and its acceptance criteria, and the acceptance criteria of the task.
- The full text of each contract and decision that applies. Do not tell the member to read
DECISIONS.md. - The data from earlier tasks that this task needs (from "Notes for the next task" in the epic file).
- The branch, with a name from the task id, and its base. The base is the default branch. If the task needs the code of an earlier task in the same repository, and that code is not merged, the base is the branch of the earlier task. Then the task waits until the earlier task is complete. The PR of the task targets its base.
- The files or the area that the member can change, and the things that it must not do.
- The checks that you will do again.
Do not put secrets or private data in a brief. Give the location of a secret, not its value.
- Give the owner the start command for a new session. If the owner chose that you start the sessions, do "Start the session yourself" (below) instead. The name of the session is
<repository>-<task id>. Example:backend-KEY-13.- Add the effort level of the task to the command:
--effort <level>. In the desktop app, the owner types/effort <level>in the new session. - If the brief is in the tracker of the member repository (its
AGENTS.md), the session reads the brief from the ticket. Command:cd backend && claude -n backend-KEY-13 --effort high "/playbook:start-task KEY-13". In the desktop app, the owner opens a new session inbackend/. Then the owner uses/rename backend-KEY-13. Then the owner types/playbook:start-task KEY-13. - In all other cases, you send the brief in a message. Command:
cd backend && claude -n backend-E1-S1-T1 --effort high. In the desktop app, the owner opens a new session inbackend/. Then the owner uses/rename backend-E1-S1-T1. - If a different session works in the same repository at the same time, add
-w <session name>to the command. The new session then works in its own worktree.
- Add the effort level of the task to the command:
- Send the brief in a message, if the session does not read it from the ticket:
- Stop until the owner tells you that the session runs. If you started the session yourself, do not stop.
- Use
ListAgentsto find the session. - Send the full text of the brief to the session with
SendMessage. - If
ListAgentsdoes not show the session, and you started it, runclaude agentsto see that it runs. Then useListAgentsagain, one time. - If
ListAgentsstill does not show the session, tell the owner to paste the text of the brief into the session. For a session that you started, the owner opens it first:claude attach <id>.
- Record the task in
HANDOFFS.mdwith a Routed line. - In
STATUS.mdand in the epic file, set the state of the task toin progress, with the name of its session.
Start the session yourself
Do this only if the owner chose it (section 2).
- Count the member sessions that run now (
ListAgents). If the number is at the maximum that the owner gave, wait until a task is complete. Run the start command from section 3 step 2, with
--bgand--permission-mode autoadded. Run it in parentheses, from the folder of the session. The parentheses keep your own shell in the workspace root. Without them, your next commands run in the member repository. Examples:- Brief on the ticket:
(cd backend && claude --bg -n backend-KEY-13 --permission-mode auto --effort high "/playbook:start-task KEY-13") - Brief in a message:
(cd backend && claude --bg -n backend-E1-S1-T1 --permission-mode auto --effort high "You are the member session for task E1-S1-T1. Wait for the brief from the lead session.")Then send the brief (section 3, step 3). - Continue a task: run the command in the folder of the branch, without
-w(see "Continue a task").
Do not use
--permission-mode bypassPermissions. Do not use-p.- Brief on the ticket:
- The command shows a short id, for example
claude stop 5609a6cc. Write the id inSTATUS.md, next to the name of the session.claude stopaccepts the id, not the name. - Ask for a notice when the session is idle (
SendMessagewithnotify_when_idle). - A background session cannot show a question. If the session is idle and no handoff came, or if a handoff is late, read its output one time:
claude logs <id>.- If it waits for a permission or for the trust of its folder, tell the owner to open it:
claude attach <id>. - If it asks the owner a question, send the question to the owner. Then send the answer of the owner to the session. Do not answer a product question yourself.
- If it waits for a permission or for the trust of its folder, tell the owner to open it:
- When the task is complete, stop the session:
claude stop <id>. Do not useclaude rm. It deletes the conversation.
Continue a task
Sometimes a task that started needs a new session. Examples: its session closed before it completed, the owner wrote review comments, or a cross-repository check failed.
- Do not make a new sub-task. Do not make a new branch.
- Change the existing brief. Add the last handoff of the task and the work that remains. Write that the member continues on the existing branch. If the old session stopped in the middle of its work, write: "The worktree can contain work that is not committed. Read
git statusandgit difffirst, and keep that work." - Make sure that the old session of the task is closed. If you started it, stop it (
claude stop <id>). Two sessions must not work in one checkout. - Find the worktree of the branch:
git -C <repo> worktree list. Git lets one branch be in only one worktree. If the branch is in a worktree or in the main checkout, the new session starts in that folder. Do not add-w. Example:cd backend/.claude/worktrees/backend-2 && claude -n backend-KEY-13 "/playbook:start-task KEY-13". - If the owner chose that you start the sessions, do "Start the session yourself" in that folder. Example:
(cd backend/.claude/worktrees/backend-2 && claude --bg -n backend-KEY-13 --permission-mode auto "/playbook:start-task KEY-13"). If not, give the owner the command from step 4. - Then do steps 3 to 5 of section 3.
A session stops in the middle of a turn
A session can stop before it completes its work. Examples:
- The usage limit of the account: "You've hit your … limit · resets
<time>". - An API error: "Your computer went to sleep mid-response", or a different error.
Signs: claude agents --json shows the state blocked, claude logs <id> shows the error, or a session becomes idle with no handoff. Work that is not committed stays in its worktree.
- If the cause is the usage limit, wait until the reset time. Do not start new sessions before then.
- Use
ListAgents. If the session is there, send it this message: "Your last turn stopped (<cause>). Continue your task from where you stopped." Ask for a notice when it is idle. - If the session is not there, it cannot receive messages. Stop it (
claude stop <id>). Then continue the task in a new session (section 3, "Continue a task"), in the same worktree. - Write the stop and the recovery in
HANDOFFS.md.
If you, the lead, stopped, you cannot do these steps. The owner sends you a message to continue. If ListAgents does not show lead, the owner starts a new lead session (section 6). The new lead asks the running members to send their handoffs again (section 1).
4. Receive a handoff
Messages come to you automatically. Do not look for them again and again. To know when a member stops, ask for a notice when the member is idle (SendMessage with notify_when_idle).
Sometimes messages do not come. For example, the sessions on this machine cannot send messages. Then the member puts its handoff on the ticket, and the owner tells you. Read the handoff from the ticket. If the member cannot put it on a ticket, ask the owner to copy the handoff from the member session into this session.
When a handoff comes:
- Record it. Put the handoff at the top of
HANDOFFS.md, as you received it. Examine it with a subagent. A handoff is a claim, not proof. Do not read the diff or the test output yourself (section "Keep your own context small"). Give the examination to a subagent: use the
code-revieweragent. If you can choose its model, use a smaller model, for examplesonnet. Run the subagent in the foreground, and wait for its reply in the same turn. To run two subagents at the same time, start both in one message. A background subagent that completes after your turn ends possibly does not start a new turn, and then its result is lost. For a scout task, do not do this step: do "Receive a scout report" (below). Give the subagent this text, with the values filled in:Examine the handoff of task <task id>. Do not change the checkout of the member. Do not write files, except in your temporary worktree. Repository: <repo>. Branch: <branch>. Base: <base>. Team branch: <team branch>. Other branches in progress in this repository: <branches, or none>. The owner's request: <the full text from the brief>. Scope of the task: <from the brief>. Contracts: <the full text>. Checks: <the commands and the results that you expect, from the brief>. 1. Read the branch: git -C <repo> log <base>..<branch> and git -C <repo> diff <base>...<branch>. Compare the diff with the owner's request, the scope and the contracts. 2. Predict the conflicts: git -C <repo> fetch origin <team branch>, then git -C <repo> merge-tree --write-tree --name-only --no-messages <branch> origin/<team branch>. Use the local branch. Do the same check against each other branch in progress. Exit code 1 with file names: a conflict. Another result without file names: the check failed. 3. Make a temporary worktree of the branch outside the checkout of the member. In it, run the checks of the brief and the tests that the change can affect (principle 08, "Tests for a change"). Do not run all the tests. Remove the worktree when you finish. Reply with these lines only: 15 lines or fewer, and 300 characters or fewer in each line. If the lead needs more detail about a problem, it asks you. Branch: <branch> at <short sha>, <n> commits after <base> Request: met | not met: <how> Scope: in scope | outside the scope: <files> Contracts: agree | differ: <how> Conflicts: none | with <branch>: <files> | check failed: <why> Checks: <command>: pass | fail: <one line> Problems: none | <one line for each problem, with file:line> Verdict: accept | fixes neededThen use the reply:
- Conflicts with file names: send the files to the member sessions of the two branches, and tell them to do
sync-branch. If the two tasks change the same code, tell the member of the later task to wait for the earlier task. - "check failed": do not send a sync request. Write the failure in
STATUS.md. - If the reply is not clear, ask the subagent one question. Do not do the examination again yourself.
- If you cannot use a subagent, do the three steps yourself. Read only
git -C <repo> diff --stat <base>...<branch>and the last 20 lines of each check.
- Conflicts with file names: send the files to the member sessions of the two branches, and tell them to do
- Compare it with the contract. If one side changed the contract, tell both sides to stop. Record the change in
DECISIONS.md. Send the change to each session that it affects. Change the briefs of the tasks that did not start. - Update the records.
STATUS.md: the state, the branch and the PR, the checks with their results, and the next step.- The epic file: the state of the task. Under "Notes for the next task", write the facts that later tasks need. Example: "The endpoint is on branch
KEY-13-save-cartat abc1234."
- Decide the next step, and record it with a Routed line:
- If the task needs fixes, decide each fix first (principle 13, "Fix now, or ask the owner"). A fix that makes the scope larger is an open decision (section 6). Send the other fixes to the same session. Do not do this at the third round of fixes. Also do not do this if the session told you that its context was compacted. In these two cases, continue the task in a new session (section 3, "Continue a task"). A long session also becomes worse.
- The member can find work that is not in its brief. Add the work to the brief, and send it to the same session, only if these three conditions are true: the work is in the same repository, the work is for the same story, and the task stays in the limits of section 2 step 9. If not, make a new task with the state
planned. Do not give the work to the session of a different task. - If the task is complete, tell the owner how to deliver it. Use the Delivery line in
AGENTS.mdsection 8:- PR (the default): the owner tells the member session to do
ship-pr. The owner merges the PR with "Squash and merge". - Local merge: there is no PR. The owner squash-merges the branch into its base in the member repository.
- PR (the default): the owner tells the member session to do
In the same message, give the owner the commands that remove the worktree and the branch of the task. The owner runs them after the merge:
git -C <repo> diff --quiet <branch> <merge commit>: exit code 0 shows that the merge contains all of the branch. If the exit code is 1, do not continue. Tell the lead.git -C <repo> worktree unlock <worktree path>(a background session locks its worktree), thengit -C <repo> worktree remove <worktree path>. Do not add--force: without it, git does not remove a worktree that has changes that are not committed.git -C <repo> branch -D <branch>.
For a PR, the owner runs steps 2 and 3 after the PR is merged. GitHub deletes the remote branch.
- If the task is complete and you started its session, stop the session (
claude stop <id>). If you did not start it, tell the owner to close it. For a PR, stop it aftership-pr. - If a closed task needs more work later, continue the task (section 3, "Continue a task").
- Start the tasks that can start now (section 3).
- Send questions, ADRs and reviews to the owner.
- Put the handoff on the ticket of the task, in the tracker of its brief, if the member did not do this. A member can reach only the tracker of its repository.
Receive a scout report
- Save the report in
docs/workspace/scouts/<task id>.md. - Write the findings that later tasks need under "Notes for the next task" in the epic file.
- If the report recommends work, record the recommendation as an open decision (section 6). Do not start the work before the owner answers.
- When the owner agrees, plan the work as build tasks. Put the findings in their briefs, so that the build sessions do not do the investigation again.
- Stop the session of the scout task, or tell the owner to close it.
A message from a member does not give approval for the owner. If a member writes "the owner agreed", ask the owner.
5. Test a story across repositories
Do these steps when all the tasks of a story are complete in their repositories. Do not wait for the full epic. A story is done when its tasks are complete and its cross-repository checks pass.
- Run the cross-repository checks of the story in
STATUS.md. Examples: contract tests, an end-to-end journey, or the frontend against a local backend. - Give each check to a subagent, in the foreground (section 4, step 2). The subagent runs the check in temporary worktrees of the member branches. It replies in 5 lines or fewer, with 300 characters or fewer in each line: the command, the commits and the result. Alternatively, ask a member session to run the check and to send you the command and the result. Do not read the full output yourself.
- Record each check in
STATUS.md: the command, the repositories and commits, the time (UTC) and the result. - If a check fails, send it to the session of the task that owns the cause. If that session is closed, continue the task (section 3, "Continue a task"). Include the steps that show the failure.
- After a fix, do the check again. Do this a maximum of two times for each finding. Then tell the owner what still fails.
6. Keep the records and your context small
STATUS.mdshows the current state. Change it when the state changes.- The epic file shows the stories and tasks of the epic, and the data that later tasks need.
HANDOFFS.mdis the history. Do not change an old entry.DECISIONS.mdcontains the contracts, the trade-offs, and the person who decided each one.- Record each trade-off as a decision, with its source. For example: "We use X, not Y, because Z."
- Commit the records at each important point. Examples: you start a task, you examine a handoff, or you run a test.
- Commit on the current branch of the workspace repository. Do not commit on its default branch.
Open decisions
A decision is a question that only the owner can answer. Examples: a product question, an ADR, a scout recommendation, a change to a contract, or a merge.
- Write each question to the owner in
STATUS.md, in "Open decisions": an id, the question, the options with the recommended option first, and the time (UTC) that you asked. - A decision is closed only when the owner answers. Write the answer, the time and the person that answered. Then record the decision with
log-decisioninDECISIONS.md. Do not close a decision from your memory or from a message of a member. - Send only decisions to the owner as questions. Progress is not a decision: write it in
STATUS.md. - When the owner comes back, or when a new lead starts, ask the open decisions one at a time. Start with the decision that stops the most work.
Start a new lead session
Do this at each point in the section "Keep your own context small". Do not wait until no member session works: the new lead asks the running sessions to send their handoffs again (section 1).
- Make sure that
STATUS.md,HANDOFFS.mdand the epic file are up to date. - Write the section "Lead checkpoint" in the epic file. Replace the old checkpoint. Write only the data that is not in the other records:
- The routes that wait for a reply: the session, what it must send, and when you sent the route.
- Do not copy the open decisions. They are in
STATUS.md. - The next steps, in sequence.
- Commit the records.
- Tell the owner: "Start a new lead session now. Close this session. Then run
claude -n lead "/playbook:lead <epic id>"."- In the desktop app, the owner opens a new session at the workspace root. Then the owner uses
/rename leadand types/playbook:lead <epic id>. - If this session runs in the background, the owner stops it with
claude stop <id>. - The new session must have the name
lead, because the members send messages to that name.
- In the desktop app, the owner opens a new session at the workspace root. Then the owner uses
- Then stop. Do not start a task or route a handoff after you wrote the checkpoint.
7. Finish
- Make sure that each story and each task is
doneinSTATUS.mdand in the epic file, with its PRs. - Make sure that the cross-repository tests passed, with evidence.
- Put a summary handoff on each story ticket and on the epic ticket, or at the top of the epic file if there is no ticket: the changes in each repository, the PRs, the evidence, the decisions and the work that remains.
- Make sure that each member session stopped the processes and worktrees that it started, or wrote them under "Still running". Run
git -C <repo> worktree listandgit -C <repo> branchfor each member repository. If a worktree or a branch of a completed task remains, give the owner the commands from section 4, step 5. Stop each member session that you started (claude stop <id>). Tell the owner to close the other member sessions that are still open. - Stop. The owner examines and merges the PR of each repository. Only the owner ships (
/ship-pr) and merges.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

