Dispatching Parallel Agents

Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.

Early Exit: When NOT to Dispatch

Before dispatching any subagent, classify the task:

• Simple (single file, <50 lines, clear path, no research needed): Controller handles inline. Dispatching overhead exceeds value. Signal: you can describe the change in one sentence and know the exact file.
• Medium (multiple files, needs some investigation, scoped changes): Dispatch a single subagent with the right profile.
• Complex (multi-system, needs research + design + implementation): Dispatch multiple subagents in sequence: researcher → architect → implementer → reviewer.

40-60% of tasks are simple enough for inline handling. Dispatching a subagent for a 10-line fix costs more in coordination overhead than it saves in context preservation. Reserve subagent dispatch for tasks where context isolation or parallelism genuinely helps.

Default stance — single agent beats orchestration for most coding

Parallel and multi-agent dispatch is for genuinely independent work only. For the common coding task — where steps depend on each other and share state — a single capable agent with tests and review beats a committee of subagents. The plan-execution loop below (5-round fix loops, task reviewers, re-reviews, breakers, ledgers) is heavy machinery; reach for it only when a plan is already written, its tasks are mostly independent, and the cost of context pollution across tasks is real.

Verified evidence (primary sources):

• Cognition, "Don't Build Multi-Agents" (2025-06-12): every action carries implicit decisions the other agents cannot see; subagents diverge even with shared context. https://cognition.com/blog/dont-build-multi-agents
• Anthropic multi-agent research (2025-06-13): multi-agent uses ~15x more tokens than chat; "most coding tasks involve fewer truly parallelizable tasks than research." https://www.anthropic.com/engineering/multi-agent-research-system
• MAP study (arXiv:2512.04123, ICML 2026 oral): 68% of 86 production agents across 26 domains execute at most 10 steps before human intervention — simple supervised loops, not orchestrated constellations. https://arxiv.org/abs/2512.04123

If the failures are related, or agents would edit the same files, or the task is a single cohesive build — stay inline. The plan-execution mode earns its cost only on a plan of mostly-independent tasks where each task's context would otherwise pollute the next.

When to Use

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

Use when:

• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between investigations

Don't use when:

• Failures are related (fix one might fix others)
• Need to understand full system state
• Agents would interfere with each other

The Pattern

1. Identify Independent Domains

Group failures by what's broken:

• File A tests: Tool approval flow
• File B tests: Batch completion behavior
• File C tests: Abort functionality

Each domain is independent - fixing tool approval doesn't affect abort tests.

2. Create Focused Agent Tasks

Each agent gets:

• Specific scope: One test file or subsystem
• Clear goal: Make these tests pass
• Constraints: Don't change other code
• Expected output: Summary of what you found and fixed

3. Dispatch in Parallel

Issue all three subagent dispatches in the same response — they run in parallel:

Subagent (subagent_general): "Fix agent-tool-abort.test.ts failures"
Subagent (subagent_general): "Fix batch-completion-behavior.test.ts failures"
Subagent (subagent_general): "Fix tool-approval-race-conditions.test.ts failures"
# All three run concurrently.

Multiple dispatch calls in one response = parallel execution. One per response = sequential.

4. Review and Integrate

When agents return:

• Read each summary
• Verify fixes don't conflict
• Run full test suite
• Integrate all changes

Profile Selection by Cost and Capability

When dispatching, match the profile to the task's capability needs AND cost sensitivity:

Don't dispatch implementer for a research task — researcher is 10x cheaper and read-only. Don't dispatch architect for a typo fix — handle inline.

Cost rule: if two profiles can handle the task, pick the cheaper one. The controller can override by switching the parent session model before dispatch when a task needs more capability than the profile's default model provides.

Agent Prompt Structure

Good agent prompts are:

1. Focused - One clear problem domain
2. Self-contained - All context needed to understand the problem
3. Specific about output - What should the agent return?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

Common Mistakes

❌ Too broad: "Fix all the tests" - agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope

❌ No context: "Fix the race condition" - agent doesn't know where ✅ Context: Paste the error messages and test names

❌ No constraints: Agent might refactor everything ✅ Constraints: "Do NOT change production code" or "Fix tests only"

❌ Vague output: "Fix it" - you don't know what changed ✅ Specific: "Return summary of root cause and changes"

When NOT to Use

Related failures: Fixing one might fix others - investigate together first Need full context: Understanding requires seeing entire system Exploratory debugging: You don't know what's broken yet Shared state: Agents would interfere (editing same files, using same resources)

Real Example from Session

Scenario: 6 test failures across 3 files after major refactoring

Failures:

• agent-tool-abort.test.ts: 3 failures (timing issues)
• batch-completion-behavior.test.ts: 2 failures (tools not executing)
• tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Decision: Independent domains - abort logic separate from batch completion separate from race conditions

Dispatch:

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

Results:

• Agent 1: Replaced timeouts with event-based waiting
• Agent 2: Fixed event structure bug (threadId in wrong place)
• Agent 3: Added wait for async tool execution to complete

Integration: All fixes independent, no conflicts, full suite green

Verification

After agents return:

1. Review each summary - Understand what changed
2. Check for conflicts - Did agents edit same code?
3. Run full suite - Verify all fixes work together
4. Spot check - Agents can make systematic errors

Background subagent discipline

When dispatching with is_background=true, act as a scheduler, not a worker:

• Record each dispatch's agent ID and ownership boundary in the ledger, so background state survives compaction.
• Do not block the controller lane waiting on a background job. Pick the next independent task; if none remains, stop briefly and let the completion notification resume the workflow.
• Never advance a dependent phase while background jobs it consumes are still running or their results are unreconciled.
• When splitting work into phases, split on dependencies and natural delivery boundaries; never split merely to shrink a review's scope.

Cross-skills

• If fanning out many subagents, invoke context-hygiene to keep the parent context lean.
• If work spans sessions, invoke handoff to capture state before ending.
• For parallel implementation lanes, use git-workflows lane orchestration (per-lane worktrees + file ownership).

Plan execution mode

The sections above cover dispatching parallel agents for independent problems. This section covers a related but distinct mode: executing a multi-task plan by dispatching a fresh subagent per task, with a task review after each and a broad whole-branch review at the end. This is subagent-driven development.

Execute plan by dispatching a fresh subagent_general subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.

Devin CLI setup: Locate this skill's directory:

• Windows: %APPDATA%\devin\skills\dispatching-parallel-agents
• macOS/Linux: ~/.config/devin/skills/dispatching-parallel-agents

The helper scripts and prompt templates live there. If you cannot access that path, fall back to doing the equivalent steps with git, read, and write tools.

Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

Core principle: Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration

Narration: between tool calls, narrate at most one short line — the ledger and the tool results carry the record.

Continuous execution: Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.

When to Use (plan execution)

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "dispatching-parallel-agents (plan execution mode)" [shape=box];
    "execution" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "dispatching-parallel-agents (plan execution mode)" [label="yes"];
    "Stay in this session?" -> "execution" [label="no - parallel session"];
}

vs. Executing Plans (parallel session):

• Same session (no context switch)
• Fresh subagent per task (no context pollution)
• Review after each task (spec compliance + code quality), broad review at the end
• Faster iteration (no human-in-loop between tasks)

The Process

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer implements, tests, commits, self-reviews" [shape=box];
        "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
        "Spec ✅ and quality approved?" [shape=diamond];
        "Finding conflicts with plan text?" [shape=diamond];
        "Ask human partner which governs" [shape=box];
        "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
        "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
        "All findings addressed?" [shape=diamond];
        "R = 5?" [shape=diamond];
        "Adjudicate each open finding" [shape=box];
        "Any load-bearing finding?" [shape=diamond];
        "STOP: report BLOCKED to human partner" [shape=box];
        "Park findings in ledger with rulings" [shape=box];
        "Append completion to ledger, mark todo complete" [shape=box];
    }

    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer (../code-review/code-reviewer.md)" [shape=box];
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
    "Final review clean: delete this plan's workspace" [shape=box];
    "Use /finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
    "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
    "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
    "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
    "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
    "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
    "Finding conflicts with plan text?" -> "Ask human partner which governs" [label="yes"];
    "Ask human partner which governs" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
    "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
    "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
    "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
    "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
    "All findings addressed?" -> "R = 5?" [label="no"];
    "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
    "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
    "Adjudicate each open finding" -> "Any load-bearing finding?";
    "Any load-bearing finding?" -> "STOP: report BLOCKED to human partner" [label="yes"];
    "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
    "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
    "Append completion to ledger, mark todo complete" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer (../code-review/code-reviewer.md)" [label="no"];
    "Dispatch final code reviewer (../code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
    "Final review clean: delete this plan's workspace" -> "Use /finishing-a-development-branch";
}

Setup

Ensure the work happens in an isolated workspace: use /git-workflows to create one or verify the existing one. Never start implementation on a main/master branch without your human partner's explicit consent.

Conversation memory does not survive compaction. In real sessions, controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed. Track progress in a ledger file, not only in todos.

• Each plan owns a workspace: at skill start, run this skill's <skill-dir>/scripts/sdd-workspace.py (or run the equivalent with git/read/write if the skill directory is not accessible) PLAN_FILE — it prints the plan's git-ignored directory (<repo-root>/.devin/sdd/<plan-basename>/), home to every artifact for THIS plan: ledger, briefs, reports, review packages. Another plan's directory is never yours to read or write.
• Check for this plan's ledger at <workspace>/progress.md. If its first line names your plan file, tasks with a Task <N>: complete line are DONE — do not re-dispatch them; resume at the first task without one. A task whose last line is a fix round is mid-loop: resume the loop at the next round. A ledger whose first line names a different plan file — or a stray ledger at the old flat path .devin/sdd/progress.md — is another plan's progress: leave it in place and start your own, fresh.

• Create the ledger with its identity as the first line: # SDD ledger — plan: <plan file path>. Structure it with an Index section at the top for fast context reconstruction after compaction, and a Commit Boundaries section marking safe recovery points:

  # SDD ledger — plan: <plan file path>
  
  ## Index
  - Task 1: complete (commits a1b..d4e, review clean)
  - Task 2: fix round 1/5 → complete (commits d4e..b7c, 2 addressed)
  - Task 3: in progress (dispatched, awaiting review)
  
  ## Commit Boundaries
  - a1b2c3d: Task 1 complete — safe recovery point
  - d4e5f6a: Task 2 fix round 1 — safe recovery point
  
  ## Detail Log
  Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)
  Task 2: fix round 1/5 (2 addressed, 0 open — magic number, missing progress; commits d4e5f6a..b7c8d9e)
  Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)

  The Index lets you reconstruct task status at a glance after compaction. Commit Boundaries mark points where git reset --hard <SHA> is safe. The Detail Log is the append-only record of every action.

• The ledger is your recovery map: the commits it names exist in git even when your context no longer remembers creating them. After compaction, trust the ledger and git log over your own recollection.
• git clean -fdx will destroy the workspace (it's git-ignored scratch); if that happens, recover from git log.

Read the plan once, note its context and Global Constraints, and create a todo per task.

Before dispatching Task 1, scan the plan once for conflicts:

• tasks that contradict each other or the plan's Global Constraints
• anything the plan explicitly mandates that the review rubric treats as a defect (a test that asserts nothing, verbatim duplication of a logic block)

Present everything you find to your human partner as one batched question — each finding beside the plan text that mandates it, asking which governs — before execution begins, not one interrupt per discovery mid-plan. If the scan is clean, proceed without comment. The review loop remains the net for conflicts that only emerge from implementation.

Model Selection

In Devin CLI, a subagent_general subagent inherits the parent session's model (BUNDLE_DEFAULT_MODEL / data/bundle-models.json, free by default). The built-in subagent_explore runs on the CLI default router (possibly paid). When parent is FREE (default): never use subagent_explore — use the custom researcher profile (agents/researcher.md, model: swe-2-max, free) instead. When parent is PAID (user switched via /model), subagent_explore is permitted. You cannot name a model directly in a run_subagent call; the profile determines the model. Custom profiles in agents/*.md pin SWE-2 effort variants to stay within the bundle's free tier.

Effort-level routing: pick the effort level that matches the task shape (see context-hygiene): Medium (swe-2-medium) for simple/bounded execution, High (swe-2-high) for multi-file work, Max (swe-2-max) for open-ended or judgment-heavy work.

Use subagent_general (inherits parent BUNDLE_DEFAULT_MODEL / data/bundle-models.json, free) for:

• Final whole-branch review — the judgment task that needs the most capability.
• High-stakes architecture that needs the parent model's reasoning (routine architecture → architect at Max effort).
• Rounds 4-5 fix-loop escalation (the parent can switch effort via /model before dispatching).
• Complex reasoning tasks that benefit from context isolation but need the parent model's effort level.

Use custom profiles (free, context per data/bundle-models.json) for:

• researcher — codebase research and fact-finding (read-only, swe-2-max).
• implementer — bounded coding tasks (swe-2-medium).
• debugger — root cause analysis and debugging (swe-2-medium).
• architect — routine architecture and trade-off analysis (read-only, swe-2-max).
• reviewer — code review and spec compliance (read-only + exec for tests, swe-2-max).

To run a different model for a subagent:

1. Switch the parent session model with /model <model> before dispatching (affects all subagent_general dispatches from this session).
2. Or create a custom subagent profile in ~/.config/devin/agents/ or %APPDATA%\devin\agents\ with a model: field, and pass that profile name as profile in run_subagent.

Turn count beats token price. Wall-clock and context cost scale with how many turns a subagent takes. SWE-2 variants are fast enough that turn count rarely causes wall-clock issues. When the task's plan text contains the complete code to write, the implementation is transcription plus testing, and Medium effort is sufficient. For rounds 4-5 escalation, switch to subagent_general (inherits the parent model from BUNDLE_DEFAULT_MODEL) or raise the parent's effort via /model.

Task complexity signals (implementation tasks):

• Touches 1-2 files with a complete spec → implementer (Medium effort)
• Touches multiple files with integration concerns → implementer (Medium effort)
• Requires design judgment or broad codebase understanding → architect (Max effort) for design, then implementer (Medium effort) for code
• Rounds 4-5 fix-loop failure → subagent_general (parent BUNDLE_DEFAULT_MODEL) for fresh eyes + reasoning

The Task Loop

Everything you paste into a dispatch prompt — and everything a subagent prints back — stays resident in your context for the rest of the session and is re-read on every later turn. Hand artifacts over as files.

1. use run_subagent with profile: "implementer" and the filled implementer prompt as task

Record BASE (git rev-parse HEAD) before dispatching — the review package and fix-round diffs need it.

• Task brief: before dispatching an implementer, run this skill's <skill-dir>/scripts/task-brief.py PLAN_FILE N — it extracts the task's full text to a uniquely named file and prints the path. Compose the dispatch so the brief stays the single source of requirements. Your dispatch should contain: (1) one line on where this task fits in the project; (2) the brief path, introduced as "read this first — it is your requirements, with the exact values to use verbatim"; (3) interfaces and decisions from earlier tasks that the brief cannot know; (4) your resolution of any ambiguity you noticed in the brief; (5) the report-file path and report contract. Exact values (numbers, magic strings, signatures, test cases) appear only in the brief. Never make a subagent read the whole plan file.
• Report file: name the implementer's report file after the brief (brief …/task-N-brief.md → report …/task-N-report.md) and put it in the dispatch prompt. The implementer writes the full report there and returns only status, commits, a one-line test summary, and concerns.
• A dispatch prompt describes one task, not the session's history. Do not paste accumulated prior-task summaries ("state after Tasks 1-3") into later dispatches — a real session's dispatch hit 42k chars of which 99% was pasted history. A fresh subagent needs its task, the interfaces it touches, and the global constraints. Nothing else.
• If an earlier task parked a finding in the area this task touches, carry a pointer to that ledger entry in the dispatch.
• Record the implementer's agent identity from the dispatch result — fix-loop rounds 1-3 resume this agent.
• Never dispatch multiple implementation subagents in parallel (conflicts).

Template: implementer-prompt.md

2. Handle the report

Implementer subagents report one of four statuses. Handle each appropriately:

DONE: Generate the review package (<skill-dir>/scripts/review-package.py PLAN_FILE BASE HEAD, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never HEAD~1, which silently drops all but the last commit of a multi-commit task), then use run_subagent with profile: "reviewer" and the filled task-reviewer prompt as task with the printed path.

DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.

NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.

BLOCKED: The implementer cannot complete the task. Assess the blocker:

1. If it's a context problem, provide more context and re-dispatch with the same model
2. If the task requires more reasoning, re-dispatch with a more capable model
3. If the task is too large, break it into smaller pieces
4. If the plan itself is wrong, escalate to the human
5. If a specific subtask within the task failed (not the whole task), re-dispatch ONLY the failed subtask with targeted context. Don't re-run the entire task pipeline when one piece failed — this wastes 50-70% of retry cost.

Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.

If the implementer asks questions — before starting or mid-task — answer clearly and completely, provide additional context if needed, and don't rush it into implementation.

3. Review the task

Per-task reviews are task-scoped gates. The broad review happens once, at the final whole-branch review. Never skip the task review, and never accept a report missing either verdict — spec compliance AND task quality are both required. Implementer self-review never replaces the task review; both are needed.

• Hand the reviewer its diff as a file: run this skill's <skill-dir>/scripts/review-package.py PLAN_FILE BASE HEAD and pass the reviewer the file path it prints (or, without bash: git log --oneline, git diff --stat, and git diff -U10 for the range, redirected to one uniquely named file). The output never enters your own context, and the reviewer sees the commit list, stat summary, and full diff with context in one Read call. Use the BASE you recorded before dispatching the implementer — never HEAD~1, which silently truncates multi-commit tasks. Never use run_subagent for a task reviewer without a diff file.
• Reviewer inputs: the task reviewer gets three paths — the same brief file, the report file, and the review package — plus the global constraints that bind the task.
• The global-constraints block you hand the reviewer is its attention lens. Copy the binding requirements verbatim from the plan's Global Constraints section or the spec: exact values, exact formats, and the stated relationships between components ("same layout as X", "matches Y"). The reviewer's template already carries the process rules (YAGNI, test hygiene, review method) — the constraints block is for what THIS project's spec demands.
• Do not add open-ended directives like "check all uses" or "run race tests if useful" without a concrete, task-specific reason
• Do not ask a reviewer to re-run tests the implementer already ran on the same code — the implementer's report carries the test evidence
• Do not pre-judge findings for the reviewer — never instruct a reviewer to ignore or not flag a specific issue. If you believe a finding would be a false positive, let the reviewer raise it and adjudicate it in the review loop. If the prompt you are writing contains "do not flag," "don't treat X as a defect," "at most Minor," or "the plan chose" — stop: you are pre-judging, usually to spare yourself a review loop. The task reviewer may report "⚠️ Cannot verify from diff" items — requirements that live in unchanged code or span tasks. These do not block the rest of the review, but you must resolve each one yourself before marking the task complete: you hold the plan and cross-task context the reviewer lacks. If you confirm an item is a real gap, treat it as a failed spec review — it enters the fix loop with the other findings.

Template: task-reviewer-prompt.md

4. The fix loop

The loop triggers when the review reports spec ❌, any Critical or Important finding, or a ⚠️ item you confirmed as a real gap.

Before the loop starts, two routes leave it immediately:

• Record Minor findings in the progress ledger as you go (Task <N>: minor (deferred): <one-liner>), and point the final whole-branch review at that list so it can triage which must be fixed before merge. A roll-up nobody reads is a silent discard. Minor findings never enter the loop.
• A finding labeled plan-mandated — or any finding that conflicts with what the plan's text requires — is the human's decision, like any plan contradiction: present the finding and the plan text, ask which governs. Do not dismiss the finding because the plan mandates it, and do not run a fix via run_subagent that contradicts the plan without asking. Everything else enters the loop. A fix round is one run_subagent fix dispatch plus one scoped re-review. Exit conditions (checked in order after each re-review):

1. PRIMARY: zero Critical/Important findings remain → exit clean
2. SECONDARY: convergence — no new findings for 2 consecutive rounds → exit clean
3. HARD CAP: 5 rounds (safety net — adjudicate as below)
4. ESCALATION: not converged after round 3 → switch to more capable model (rounds 4-5 already do this)

Rounds 1-3 — resume the original implementer. Send it the open findings verbatim. Its context is intact: it knows the task, the code, and its own choices. If you prefer a fresh context over resuming the same subagent, use run_subagent with profile: "implementer" for a fresh implementer carrying the brief path, the report-file path, and the findings — the report file is the persistent memory either way.

Rounds 4-5 — use run_subagent with profile: "implementer" for a fresh implementer on a more capable model (per Model Selection), with the brief path, the report-file path, the open findings, and this framing: "A prior implementer attempted this task [N] times; you own it now. Read the report file for what was tried." A loop that survives three resumes usually means the implementer cannot see its own problem — fresh eyes and a capability bump in one move.

Every round, either way: the implementer fixes, re-runs the tests covering the amended code, appends its fix report to the same report file, and returns the short contract. Before re-dispatching the reviewer, confirm the fix report contains the covering tests, the command run, and the output; use run_subagent with profile: "reviewer" for the re-review once all three are present. Name the covering test files in the fix message — a one-line fix does not need the whole suite.

The re-review is scoped. Run <skill-dir>/scripts/review-package.py PLAN_FILE FIX_BASE HEAD where FIX_BASE is the head the previous review saw, and dispatch re-review-prompt.md with the findings list, the brief, the report file, and the printed diff path. The re-reviewer verdicts each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix diff only. New Critical/Important breakage in the fix diff joins the open findings list. Out-of-scope observations go to the ledger as deferred minors — they never extend the loop.

After each round, append to the ledger: Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)

Never fix findings yourself in the controller session — your context stays clean for coordination, and controller fixes skip review.

The breaker. When round 5's re-review still leaves findings open, stop dispatching. Adjudicate each open finding yourself — you hold the plan and the cross-task context the reviewer lacks:

• The reviewer is wrong, or the point is contestable: park it — Task <N>: parked — <finding> — ruling: <why the code stands>. The final review sees both sides.
• Real, but nothing downstream builds on it: park it the same way, with a ruling that says it's real and deferred.
• Real and load-bearing — a later task builds on it, or it reveals a plan defect: STOP. Append Task <N>: BLOCKED — <reason> and report to your human partner with the finding, the plan text it collides with, and the fix history. Parking a structural failure lets every dependent task build on it and hands the final review a problem it cannot fix either.

Adjudicate only at the cap. Adjudicating earlier to end a loop is pre-judging with a different name. Every adjudication is a ledger entry — a silent discard is forbidden.

5. Complete the task

When the review comes back clean — or every open finding is parked with a ruling at the cap — append the completion line to the ledger in the same message as your other bookkeeping:

• Task <N>: complete (commits <base7>..<head7>, review clean)
• Task <N>: complete (commits <base7>..<head7>, <K> parked) after a tripped breaker

Then mark the todo complete and move on. Never move to the next task while the review has open Critical/Important issues that are neither fixed nor parked-with-ruling at the cap.

Final Review

The final whole-branch review gets a package too: run <skill-dir>/scripts/review-package.py PLAN_FILE MERGE_BASE HEAD (MERGE_BASE = the commit the branch started from, e.g. git merge-base main HEAD) and include the printed path in the final review dispatch, so the final reviewer reads one file instead of re-deriving the branch diff with git commands. Dispatch on the most capable available model (see Model Selection), using /code-review's code-reviewer.md. Point it at the ledger's deferred-minor and parked lines so it can triage which must be fixed before merge.

If the final whole-branch review returns findings, use run_subagent with profile: "implementer" to dispatch one fix subagent with the complete findings list — not one fixer per finding. Per-finding fixers each rebuild context and re-run suites; a real session's final-review fix wave cost more than all its tasks combined. Then run exactly one scoped re-review of the fix wave (<skill-dir>/scripts/review-package.py PLAN_FILE FIX_BASE HEAD over the fix range, re-review-prompt.md). Adjudicate any residual findings as in the task loop's breaker: park with rulings, or stop on load-bearing ones. There is no second fix wave — residual load-bearing findings surface to your human partner when finishing-a-development-branch presents the options.

Finish

When the final whole-branch review is clean and its fixes are merged, delete this plan's workspace (rm -rf <workspace>) — the git history is the record now. Sibling directories belong to other plans; leave them alone.

Use /finishing-a-development-branch.

Common Rationalizations

Example Workflow

You: I'm using Subagent-Driven Development to execute this plan.

[Setup: worktree verified]
[Read plan file once: .devin/plans/feature-plan.md]
[Resolve workspace: <skill-dir>/scripts/sdd-workspace.py (or run the equivalent with git/read/write if the skill directory is not accessible) .devin/plans/feature-plan.md — no ledger inside, fresh start]
[Create todos for all tasks]

Task 1: Hook installation script

[Run python scripts/task-brief.py for Task 1; dispatch implementer with brief + report paths + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/devin/hooks/)"

Implementer: [Later]
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Run python scripts/review-package.py PLAN_FILE BASE HEAD; use `run_subagent` with `profile: "reviewer"` and the task-reviewer prompt for the printed path]
Task reviewer: Spec ✅ - all requirements met, nothing extra.
  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.

[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]

Task 2: Recovery modes

[Run python scripts/task-brief.py for Task 2; dispatch implementer with brief + report paths + context]

Implementer: [No questions]
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed

[Run python scripts/review-package.py PLAN_FILE BASE HEAD; use `run_subagent` with `profile: "reviewer"` and the task-reviewer prompt for the printed path]
Task reviewer: Spec ❌:
  - Missing: Progress reporting (spec says "report every 100 items")
  Issues (Important): Magic number (100)

[Fix round 1: resume the implementer with both findings]
Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
  Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.

[Run python scripts/review-package.py PLAN_FILE FIX_BASE HEAD; use `run_subagent` with `profile: "reviewer"` and the re-review prompt]
Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
  Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
  Verdict: all findings addressed.

[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]

...

[After all tasks]
[Run python scripts/review-package.py PLAN_FILE MERGE_BASE HEAD; use `run_subagent` with `profile: "reviewer"` and the code-review template]
Final reviewer: All requirements met. Deferred minors triaged: none block merge.

[Delete this plan's workspace — the record now lives in git]

Done! Using /finishing-a-development-branch.