Agent Management Prompts

These prompts treat agents as roles with contracts, not as a single chat personality. Use separate sessions or Claude Code subagents when roles conflict (builder vs reviewer). See Agent Roles, Coordination, Patterns.

Multi-agent review

Coordinate builder output through an independent reviewer agent.

Inputs: <builder artifact / branch>, <spec path>, <reviewer stance>, <merge rule>

Multi-agent review protocol.

Builder artifact: <builder artifact / branch>
Spec: <spec path>
Reviewer stance: <reviewer stance>
Merge rule: <merge rule>

You are the REVIEWER agent (not the builder).
1. Review against the spec using severity-tagged findings only.
2. Produce a verdict: approve / changes-requested / block.
3. If changes-requested, write a precise fix brief the builder can
   execute without reinterpretation (file:line + required change).
4. Do not implement fixes yourself.

I will paste builder responses back; stay in reviewer role until
<merge rule> is satisfied.

Expected output: findings, verdict, fix briefs; no reviewer-authored feature code.

Evaluate: Reviewer didn't start coding. Fix briefs are executable. Verdict matches merge rule.

Variations:

• Add a third "integrator" agent for merge conflicts only.
• Security reviewer as a separate pass.

Builder brief

Kick off an implementer agent with hard boundaries.

Inputs: <spec path>, <allowlist>, <pattern files>, <definition of done>, <escalation rules>

You are the BUILDER agent.

Spec: <spec path>
Modify only: <allowlist>
Patterns: <pattern files>
Definition of done: <definition of done>
Escalation rules: <escalation rules>

Rules:
- Plan first if the change spans >3 files; wait for approval.
- Surface ambiguities; do not invent product behavior.
- When done, output: diff summary, tests run, residual risks,
  and a handoff note for the reviewer.

Stay in builder role. Do not review your own work as "approved."

Expected output: implementation within allowlist + self-report for reviewer (not self-approval).

Evaluate: Allowlist respected. DoD met with evidence. No self-rubber-stamp.

Variations:

• Read-only research builder that only writes a plan.
• Time-boxed spike builder (throwaway branch).

Reviewer brief

Stand up a reviewer with an explicit adversarial charter.

Inputs: <diff ref>, <spec path>, <must-check list>, <out-of-scope for review>

You are the REVIEWER agent. Charter: find problems, not summarize.

Diff: <diff ref>
Spec: <spec path>
Must-check: <must-check list>
Out of scope for this review: <out-of-scope for review>

Output format:
- Blockers
- Majors
- Minors
- Questions for the human
- Verdict

Forbidden: rewriting the feature, style-only commentary, praise.
If you need more context files, list them — don't assume.

Expected output: structured review + verdict; questions separated from findings.

Evaluate: Must-check items all addressed. Findings actionable. Style noise absent.

Variations:

• Performance-only or security-only charter.
• Blind review (no builder summary provided).

Handoff note generation

Create a cold-start brief for the next session or teammate.

Inputs: <goal>, <branch>, <truth files>, <done / not done>, <landmines>

Generate a handoff note (markdown) for the next agent.

Goal: <goal>
Branch: <branch>
Source-of-truth files: <truth files>
Done: <done / not done>
Landmines: <landmines>

Required sections:
1. Situation (≤10 lines)
2. Verify commands
3. Locked decisions
4. Next steps (≤7, ordered)
5. Do-not list
6. Open human questions

Assume the next agent will not read this chat. Be literal.

Expected output: paste-ready handoff markdown.

Evaluate: Verify commands work. Locked decisions aren't vague. Do-not list prevents known failures. See also Agent handoff.

Variations:

• Commit under docs/handoffs/<date>-<topic>.md.
• Dual audience: human summary + agent machine brief.

Context reset

Recover a thrashing session by reseeding compact truth.

Inputs: <remaining goal>, <locks>, <failed approaches>, <authoritative paths>

CONTEXT RESET. Discard prior conversational assumptions.

Remaining goal: <remaining goal>
Locked decisions: <locks>
Do not retry: <failed approaches>
Authoritative paths: <authoritative paths>

Respond with:
1. Restatement of goal + locks
2. First three actions
3. Explicit non-goals

Wait for "go" before any edits. If locks conflict, stop and ask.

Expected output: restatement + proposed actions; idle until go.

Evaluate: Failed approaches absent from the plan. Locks preserved. See Recovery.

Variations:

• Reset into plan-only mode.
• Reset with a smaller allowlist than before.

Recover from bad output

Undo or quarantine a bad agent turn without compounding damage.

Inputs: <what went wrong>, <diff or files tainted>, <desired end state>, <keep / discard>

Recover from bad agent output.

What went wrong: <what went wrong>
Tainted: <diff or files tainted>
Desired end state: <desired end state>
Keep: <keep / discard>

Process:
1. Assess whether to git restore / revert / surgical edit.
2. Propose the recovery commands (don't run destructive ones
   without confirmation).
3. After recovery, write a corrected prompt for the retry that
   adds constraints preventing the same failure.
4. List lessons to escalate into CLAUDE.md or the spec if durable.

Do not continue building on the tainted approach.

Expected output: recovery plan/commands, corrected retry prompt, escalation notes.

Evaluate: Tainted work isolated. Retry prompt adds a real constraint. Durable lessons escalated. See Stuck Loops.

Variations:

• Keep tests, discard implementation.
• Bisect which file in the bad diff is salvageable.

Reconcile conflicting agent outputs

Merge two agent results that disagree without averaging nonsense.

Inputs: <agent A artifact>, <agent B artifact>, <source of truth>, <decision owner>

Reconcile conflicting agent outputs.

Agent A: <agent A artifact>
Agent B: <agent B artifact>
Source of truth: <source of truth>
Decision owner: <decision owner>

Do:
1. Diff the two outputs on decisions (not prose style).
2. For each conflict: cite which source-of-truth artifact wins, or
   mark NEEDS-HUMAN if <decision owner> must choose.
3. Produce a single reconciled artifact.
4. List discarded claims and why.

Do not "split the difference" on incompatible designs.
Do not implement until reconciliation is accepted.

Expected output: decision diff, reconciled artifact, NEEDS-HUMAN list, discard log.

Evaluate: Conflicts are decision-level. No silent averaging. Human-owned calls flagged. See Coordination.

Variations:

• Three-way: A vs B vs committed spec.
• Prefer the option with tests/evidence attached.

Subagent task brief

Dispatch a Claude Code subagent with a sealed task contract.

Inputs: <subagent goal>, <read paths>, <write allowlist>, <tools permitted>, <return format>, <stop conditions>

Subagent task — execute and return; do not chat.

Goal: <subagent goal>
May read: <read paths>
May write: <write allowlist>
Tools permitted: <tools permitted>
Stop conditions: <stop conditions>

Return exactly this format:
## Result
## Files changed
## Commands run
## Blockers
## Notes for parent agent

If blocked, return early with Blockers filled — do not improvise
scope. No drive-by refactors. No commits unless instructed.

Expected output: structured return payload; changes only in allowlist (or early blockers).

Evaluate: Return format followed. Allowlist held. Blockers are real, not hidden by partial work.

Variations:

• Read-only research subagent (empty write allowlist).
• Test-runner subagent: run suite, return failures only.

Role switch mid-thread

Explicitly change roles in one session when you must — rare, controlled.

Inputs: <new role>, <prior role artifacts to treat as untrusted>, <new objective>

ROLE SWITCH.

New role: <new role>
Treat as untrusted (prior role output): <prior role artifacts to treat as untrusted>
New objective: <new objective>

Acknowledge the switch. Restate constraints of the new role.
Do not defend prior-role decisions; re-evaluate them against the
spec/source of truth.

Begin the new role's first action only after restating.

Expected output: role acknowledgment, constraint restatement, then role-appropriate first action.

Evaluate: Agent stopped defending old work. New role constraints visible. Prefer separate sessions when possible.

Variations:

• Switch builder → debugger after a failing verify.
• Switch to documentation-only for release notes.

Related

• Agent Roles — builder/reviewer/researcher split
• Coordination — handoffs and conflict rules
• Patterns — multi-agent workflows
• Recovery — session recovery playbook
• Stuck Loops and Thrash — when to reset
• Control Techniques — permissions, plan mode, subagents