feat(rules): add subagents.md — when, how, and when not to delegate

Cross-cutting rule covering subagent hygiene:

- Decision table: parallel-safe (read-only investigation, independent
  test failures, multi-domain research) vs sequential-with-review
  (plan execution, coupled edits) vs never-parallel (concurrent writes)
  vs don't-subagent-at-all (target known, work fits in ~10 tool calls).
- Prompt contract: scope / pasted context / explicit 'do NOT' list /
  required output format. Missing any field yields shallow work.
- Context-pollution rule: subagents absorb noise the main thread
  shouldn't carry. When one fails, dispatch a fix-agent with the
  failure report — do not retry in the orchestrator.
- Review-gate cadence: after each sequential task, or every ~3 in
  parallel batches.
- Anti-patterns including parallel implementation on overlapping
  files, broad 'fix all the tests' prompts, timeout-tuning to mask
  flakes, and letting the agent decide scope.

Added one-line cross-references to subagents.md from debug/,
review-code/, and finish-branch/ SKILL.md — the skills that most
rely on delegation.

Clean-room synthesis from NeoLabHQ/context-engineering-kit's
subagent-driven-development pattern (MIT).

1 files changed, 126 insertions, 0 deletions

diff --git a/claude-rules/subagents.md b/claude-rules/subagents.md
new file mode 100644
index 0000000..310f979
--- /dev/null
+++ b/claude-rules/subagents.md
@@ -0,0 +1,126 @@
+# Subagents — When, How, and When Not To
+
+Applies to: `**/*`
+
+Subagents exist to protect the main thread's context and parallelize
+independent work. They are not free — every spawn pays a prompt-construction
+cost and breaks the chain of context from the current conversation. Use them
+deliberately, not reflexively.
+
+## When to Spawn a Subagent
+
+### Parallel-safe (spawn multiple in parallel)
+
+- **Read-only investigation across independent domains** — "what uses
+  function X?", "what are the three logging libraries in this repo?", etc.
+  spread across different subsystems.
+- **N independent test-file failures** where each is its own diagnosis.
+- **Library/API research across unrelated topics** — doc fan-out.
+- **Analysis scans over different parts of a codebase** — e.g. C4 diagram
+  generation scanning distinct services.
+
+### Sequential-with-review (one at a time, review between)
+
+- **Plan-task execution** where each task may depend on the last.
+- **Coupled edits** — related files that must stay in sync (schema + migration
+  + seed script).
+- **Anything where mid-course correction is likely** — the review gate is
+  where course correction happens.
+
+### Never Parallel
+
+- **Concurrent writes to the same files or directories** — race conditions,
+  conflicting edits, lost work.
+- **Ordered edits where sequence matters** — e.g. add a config flag, then
+  read it in code; don't fan these out.
+
+### Don't Subagent At All
+
+- **The target is already known** and the work fits in under ~10 tool calls.
+- **Single-function logic** — one Read + one Edit is faster than briefing
+  an agent.
+- **You can see the answer from context** — don't spawn a researcher for
+  something already on screen.
+
+## Prompt Contract
+
+Every Agent spawn must include four fields. Missing any one produces
+shallow, generic work:
+
+1. **Scope** — one bounded task, named file or domain. Not "fix the bugs"
+   but "find the root cause of the NPE in `order_service.py:process_refund`."
+2. **Context** — paste the relevant output, error, or prior finding. The
+   subagent cannot see this conversation. If you learned something from an
+   earlier turn, include it verbatim; don't paraphrase.
+3. **Constraints** — explicit "do NOT" list. "Do not refactor surrounding
+   code." "Do not add tests." "Do not touch files outside `src/billing/`."
+4. **Output format** — what to return and in what shape. "Report root cause
+   + file:line + proposed fix in under 200 words" beats "investigate this."
+
+If you can't fill all four fields, you don't yet understand the task well
+enough to delegate it. Do it yourself, or think more before dispatching.
+
+## Context-Pollution Rule
+
+Subagents exist to absorb noise the main thread shouldn't carry. When one
+fails or produces unexpected results:
+
+- **Do not retry the task manually in the orchestrator context.** That
+  re-imports the exact noise the subagent was meant to contain — failed
+  approaches, dead ends, irrelevant exploration.
+- **Dispatch a fix subagent** with the failure report as its context
+  (paste the subagent's output verbatim). New scope, fresh context.
+- **If two fix attempts fail**, stop and surface the problem to the user.
+  Don't keep spawning.
+
+The corollary: if you're tempted to "just quickly fix it myself after the
+agent failed," you are about to pollute your context. Dispatch.
+
+## Review-Gate Cadence
+
+Subagent output is not verified work — it's a claim about what was done.
+Review before moving on:
+
+- **Sequential execution** — review after each task completes. Read the
+  diff, run the relevant tests, confirm the claim matches reality (see
+  `verification.md`). Then spawn the next task.
+- **Parallel execution** — review after every batch of ~3 tasks. Larger
+  batches compound bugs; smaller batches make review overhead dominate.
+- **Never chain subagents past a failed review.** If the review finds a
+  problem, dispatch a fix subagent before continuing the plan.
+
+## Delegation vs Understanding
+
+Subagents execute; they do not understand *for you*. Never write prompts
+like:
+
+- "Based on your findings, fix the bug" — synthesis pushed onto the agent
+- "Investigate and implement" — scope too broad, no contract
+
+Do the understanding step yourself (read the agent's report, decide the
+fix), then dispatch the fix with a specific contract.
+
+## Anti-Patterns
+
+- **Parallel implementation agents on overlapping files** — they will
+  conflict. Fan-out is for investigation, not concurrent writes.
+- **Broad prompts** — "fix the failing tests" sends the agent exploring;
+  "fix the assertion at `test_cart.py:142`" gets a diff.
+- **Timeout-tuning to quiet flaky tests** — the flake is usually a race
+  condition. Diagnose, don't mask.
+- **Retrying a failed subagent task in the orchestrator** — pollutes
+  context. Dispatch a fix agent instead.
+- **Subagenting trivial work** — one Read + one Edit doesn't need an
+  agent; spawn overhead exceeds benefit.
+- **Skipping review between tasks** — compounding bugs are much harder to
+  unwind than any single bug.
+- **Letting the agent decide scope** — "figure out what needs changing"
+  produces sprawling, unfocused work. You decide scope; the agent
+  executes it.
+
+## Cross-References
+
+- Completion claims must be verified regardless of who produced them —
+  see `verification.md`.
+- Testing discipline applies to subagent-produced tests too — see
+  `testing.md`.