Use when a task has a clear implementation plan and should be executed by a subagent in an isolated git worktree. Triggers on phrases like: dispatch this, send to a subagent, work on this in a worktree, dispatch to worktree, background task, isolated execution.
Packages a task with a clear plan, creates an isolated git worktree, and dispatches a subagent to implement, validate, verify, and commit in the background. The main session reviews, pushes, and creates the PR.
Core principle: Plan in the main session, execute in isolation, verify before pushing.
When NOT to use:
digraph dispatch {
rankdir=TB;
node [shape=box];
plan [label="1. Prepare implementation plan"];
worktree [label="2. Create git worktree\non new branch"];
dispatch [label="3. Dispatch subagent\n(implement, verify, commit)"];
review [label="4. Review diff,\npush + PR"];
cleanup [label="5. Remove worktree"];
plan -> worktree -> dispatch -> review -> cleanup;
}
Write a detailed plan that includes:
Before proceeding, confirm the plan includes all required sections:
If any section is missing or vague, fill it in before creating the worktree.
git worktree add .worktrees/<branch-name> -b <branch-name> main
Use .worktrees/ directory. Check that .worktrees/ is in .gitignore. If not, add it before creating the worktree. Branch name should match the work (e.g., fix/cache-lock-fs4).
Stale worktree/branch: If the branch or worktree already exists from a previous attempt, remove them first (
git worktree remove .worktrees/<branch-name>andgit branch -D <branch-name>) or reuse after verifying the worktree state is clean (git statusin the worktree).
Why manual worktrees instead of
isolation: "worktree"? The branch is the deliverable — it gets pushed and PR'd. You need a named branch you control. For fan-out/fan-in where you cherry-pick temporary commits back, seereview-and-fix.
Use the Agent tool with these settings:
| Parameter | Value |
|---|---|
subagent_type | general-purpose |
mode | bypassPermissions |
run_in_background | true |
Risk note: Unlike
isolation: "worktree"(which physically starts the agent in a separate directory),bypassPermissionshere applies while the agent is still in the parent's working directory. Thecdinstruction below is critical — without it, the agent operates on the main tree with no permission prompts. Always makecdthe first instruction in the prompt and never place other commands before it.
Prompt must include:
cd <worktree-absolute-path> as the subagent's FIRST action — before any other command. The Agent tool starts subagents in the parent's working directory, not the worktree.Subagent execution order:
On failure: If the implementation is incomplete, the plan doesn't match reality, or validation/reproduction fails — the subagent must NOT commit. Instead, report what happened: what was attempted, what failed, and what state the worktree is in. The main session will decide next steps.
If reproduction fails but the fix is otherwise correct, the subagent should fix the issue and re-verify. If it cannot fix it, do not commit — report the failure.
When the agent reports back:
git log main..<branch> --oneline and git diff --stat main..<branch>git push -u origin <branch>After the PR is created, remove the worktree:
git worktree remove .worktrees/<branch-name>
| Mistake | Fix |
|---|---|
| No reproduction command in prompt | Always include a command that exercises the original scenario |
| Reproduction command is just "run tests" | Tests verify correctness; reproduction verifies the original complaint is resolved |
| Reproduction command is destructive | Adapt for safety — use temp dirs, non-destructive variants — but verify the same behavior |
| Vague subagent prompt | Paste the full plan — subagents have no prior context |
| Not verifying the diff | Always read the key file diffs before creating the PR |
| Skipping pre-commit in prompt | Agent won't know to run validation unless told |
| Forgetting the PR | Always create or remind about PR after reviewing |