cursor-composer-rules / rules

---
description: Subagents, plan mode, parallel workstreams, long-running tasks — when to delegate vs do inline
alwaysApply: false
---

# Composer orchestration

Use when work spans multiple files, parallel tracks, long-running commands, plan mode, or you need context isolation. For single-file edits, stay in the parent agent.

Companion rules: [composer-core](composer-core.mdc) (intent, confusion weight, handoff), [composer-reasoning](composer-reasoning.mdc) (tradeoffs on complex work), [composer-fullstack-delivery](composer-fullstack-delivery.mdc) (vertical slice + continue handoff), [composer-debugging](composer-debugging.mdc) (repro before fan-out), [composer-verification](composer-verification.mdc) (status labels).

## When to delegate

Delegate for **isolation or parallelism**, not because tools exist.

| Situation | Delegate to |
| --- | --- |
| Wide codebase search with noisy intermediate output | built-in **Explore** subagent |
| Long or verbose shell output | built-in **Bash** subagent or background shell |
| Browser/UI verification (DOM noise, screenshots) | built-in **Browser** subagent |
| Independent parallel tracks (API + docs, client + server read-only survey) | multiple subagents in one batch |
| Skeptical re-check before marking done | custom **verifier** (`.cursor/agents/verifier.md`) |
| Isolated debug with full stack context | custom **debugger** (`.cursor/agents/debugger.md`) |

## When not to delegate

- Single-file edit, one test run, one MCP call.
- One-shot tasks ("format imports", "generate changelog") — use a **skill** or do inline.
- Spawning many subagents for work one agent can finish in a few tool calls.
- Delegating because the model is tool-capable — prefer parent tools first.

Default: parent does the work unless isolation or parallelism clearly wins.

## Subagent prompt contract

Subagents start with a **clean context** — they do not see prior chat history. Every delegation prompt must include:

1. **Goal** — observable outcome.
2. **Constraints** — what not to change, style, scope limits.
3. **Pointers** — file paths, symbols, error messages, branch names.
4. **Definition of done** — what "finished" means for this handoff.
5. **Return shape** — summary format the parent needs (not raw logs).

Bad: "Look at the auth code."
Good: "Find where refresh tokens are validated in `src/auth/`; return file:line and the guard that rejects expired tokens."

## Parent owns the user message

- Children return **summaries** to the parent — not a substitute for the user-facing closeout.
- The **parent restates** findings, verdicts, and next steps in the final message ([composer-core](composer-core.mdc) § User-facing closeout).
- Do not dump child tool logs into the user message.
- A child's "done" is a **hypothesis** until the parent names evidence or runs a verifier — never auto-**verified**.

## Foreground vs background

| Mode | Use when |
| --- | --- |
| **Foreground** | Next step depends on the result (schema found, test output needed). |
| **Background** | Long explore, build, or survey; parent can continue other work. |

If you continue while a background subagent runs, **label assumptions** you are making. Reconcile when results arrive. Cloud or background completion does not change proof depth — same labels as the verification rule.

## Parallelism

- Batch **independent** subagents in one turn; do not serialize unnecessarily.
- Do not launch five agents to edit one file.
- Parent owns **integration**: merge findings, resolve conflicts, apply edits, run final verification.

## Nested subagents and resume

Subagents may spawn children for large trees (multi-file features, deep refactors). The **parent** still owns the final answer and conflict resolution.

- Children return **summaries**, not full tool logs.
- **Resume** with agent ID when continuing prior work on the same track — do not re-derive context from scratch with a new spawn.
- Start a **new** spawn when the goal, constraints, or return shape have changed enough that resume would confuse the child.
- Stopping the parent stops children; note this before aborting long runs.

## Plan mode

Enter plan mode (or honor user plan mode) when:

- Multiple valid designs exist and the choice changes architecture.
- Blast radius is large (migrations, auth, public API).
- User asked to plan first or enabled plan mode.

**In plan mode, deliver a structured plan.** For when to ask vs assume, see [clarify-first](clarify-first.mdc) plan-mode exception. For tradeoffs and one-way doors, [composer-reasoning](composer-reasoning.mdc) has the same judgment patterns — optional depth, not extra ceremony before you plan. When confusion weight was medium, name the **inferred intent** and **assumptions** so the user can correct them before implementation.

**Code change** (one module, a known bug, a local feature): use the short form. Filling the long list on a function change is the slow path.

| Section | Content |
| --- | --- |
| **Summary** | What changes; inferred intent and assumptions |
| **Files** | Path → create / modify / delete |
| **Approach** | The steps, in order |
| **Checks** | Command or action → expected result |
| **Assumptions** | What the user may correct |

**Architecture or multi-layer** (migrations, auth, public API, a new screen or endpoint): fill every section below; mark sections **N/A** when they genuinely do not apply.

| Section | Content |
| --- | --- |
| **Summary** | 2–4 sentences: what ships, what does not; inferred intent + assumptions if confusion was medium |
| **Current state** | What exists today (files, flows, pain) — cite paths |
| **Goals & non-goals** | Observable goals; explicit exclusions |
| **Constraints** | Backward compat, perf, security, timeline, deps |
| **Options** | 2–3 viable designs with **pros / cons / blast radius** |
| **Recommendation** | Pick one; **why** over alternatives |
| **Architecture** | Mermaid or bullet flow for data/control |
| **Change inventory** | Table: path → what changes (create/modify/delete) |
| **Contracts** | API shapes, types, events, config keys affected |
| **Phased rollout** | Ordered steps; which slice is MVP |
| **Risks & mitigations** | What could go wrong + guard |
| **Rollback** | How to undo if slice 1 fails |
| **Verification matrix** | Check \| command or action \| expected result |
| **Open questions** | Only blocking items (max 1–2); else state assumptions |
| **Style / tech-debt (optional)** | Separate from MVP unless user opts in |

**Plan depth (quality bar):**

- Every recommendation tied to **evidence** (file:line, doc, or command output from inspection).
- The file list (**Files**, or **Change inventory**) must be **actionable** (not "update auth").
- Checks must be **runnable** where possible.
- **Do not implement** until the user confirms — unless they explicitly ask to execute the plan.

After confirmation: execute; use status labels from the verification rule. **Build in Cloud** (if offered) is still subject to the same proof contract — cloud completion is not automatic **verified**.

## Long-running work

For tasks that span many steps:

1. Checkpoint with a **handoff** (done / next / run / wired / assumptions) — see [composer-core](composer-core.mdc).
2. Ship one **vertical slice** before widening (see fullstack delivery rule).
3. Prefer background subagents or shells for long builds; tell the user how to check output.
4. Defer polish until the slice is **verified** at the surface that matters.

## Anti-patterns

- Vague subagents with no definition of done.
- Parent and child both editing the same files without coordination.
- Marking **verified** because a subagent said "done."
- Delegating a 2-minute task and paying context startup cost.
- Dumping child logs into the user message instead of a structured summary.
- Vacuous polling of background children when the parent is not blocked on them.

## Skills vs subagents

| Use a **skill** when… | Use a **subagent** when… |
| --- | --- |
| Single-purpose, repeatable workflow | Long research or exploration |
| Fits in one context window | Parallel independent workstreams |
| No separate context needed | Specialized skepticism (verifier) or isolation |