/subagent

name: subagent
description: |
  Delegate work to builtin or custom subagents with single-agent,
  parallel, forked-context, and intercom-coordinated runs.
  Use for bounded specialist delegation where a single parent agent stays in
  control while subagents contribute locate, analyze, pattern-find, research,
  debug, or simplify passes.

Subagent

This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final writer launches; child subagents should receive concrete role-specific tasks and should not run their own subagent workflows.

Use this skill when bounded specialist delegation adds value and the parent should remain in control. Keep interactive, exploratory, conceptual, and conversation-led work inline. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow; use a durable workflow for clearly delegated long-running autonomous jobs that materially need its lifecycle features.

When to Use

• **Parallel codebase discovery**: combine `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` to map where code lives, how it works, and what existing conventions look like — concurrently, with fresh context per child.
• **Local research mining**: pair `codebase-research-locator` with `codebase-research-analyzer` to surface prior decisions in `research/` and `specs/` and extract what still applies.
• **External research**: use `codebase-online-researcher` for authoritative web sources, with persisted findings in `research/web/`.
• **Debug and fix**: use `debugger` for actual failures that need reproduction, root-cause diagnosis, and a validated patch; conceptual or exploratory debugging can stay inline.
• **Refinement**: use `code-simplifier` to clean up recently changed code without altering behavior.
• **Adversarial review**: compose read-only specialists (`codebase-analyzer`, `codebase-pattern-finder`, `debugger` in inspect-only mode, `codebase-online-researcher`) into a parallel review pass — there is no generic `reviewer` agent.
• **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked.
• **Agent authoring**: create, update, or override agents for a project.

Tool vs Slash Commands

Agents can use the `subagent(...)` tool directly for execution, management, status, and control. Humans often use the slash-command layer instead:

• `/run` — launch a single agent
• `/parallel` — launch top-level parallel tasks
• `/subagents-doctor` — diagnose setup, execution paths, current session, and intercom bridge state

Prefer the tool when you are writing agent logic. Prefer the slash commands when you are guiding a human through an interactive flow.

Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)`:

• `/parallel-review` — fresh-context specialists (analyzer, debugger inspect-only, pattern-finder) with distinct review angles, then parent synthesis
• `/review-loop` — parent-orchestrated writer (`debugger` or `code-simplifier`) + specialist reviewer cycles until clean or capped
• `/parallel-research` — combine `codebase-online-researcher` with local locator/analyzer/pattern-finder/research-analyzer specialists
• `/parallel-context-build` — parallel codebase specialist passes that produce planning handoff context
• `/parallel-handoff-plan` — external-reference research plus local specialist passes, followed by a parent-side handoff plan and implementation-ready meta-prompt
• `/gather-context-and-clarify` — locate/analyze/research first, then ask the user clarifying questions with `interview`
• `/parallel-cleanup` — two read-only specialist scouts (deslop + verbosity) followed by an optional `code-simplifier` writer pass

Applying Prompt Techniques Without Slash Commands

The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. Do not depend on the parent conversation history when the recipe calls for fresh context.

Parallel review technique

Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. There is no generic `reviewer` agent — assemble the review from read-only specialists with distinct angles. Common angles: correctness/regressions (`codebase-analyzer`), failure-mode hunt (`debugger` in inspect-only mode), pattern fit (`codebase-pattern-finder`), prior decisions (`codebase-research-locator` + `codebase-research-analyzer`), and external-spec conformance (`codebase-online-researcher`). Specialists inspect files and diffs directly from `git diff`/`git status` and return concise evidence-backed findings with file/line references. They must not edit files — even `debugger`, which can write, must be told to inspect and report only in this pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.

Review-loop technique

Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one writer (`debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work), fresh-context specialist reviewers inspect the actual repo and diff, the parent synthesizes accepted fixes, and one writer applies them. Run each bounded call in the foreground so the parent receives the result before the next step. Programmatic runs are non-interactive, so r