subagent

What this skill does

# 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 the parent orchestrator needs to launch a specialized subagent, compose multiple specialists into a workflow, or create/edit agents and chains on demand.

## 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` to reproduce, diagnose, and patch failing behavior with `tdd` and `browser` support.
- **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.
- **Long-running work**: launch async/background runs and inspect them later.
- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked.
- **Agent authoring**: create, update, or override agents and chains 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
- `/chain` — launch a chain of steps
- `/parallel` — launch top-level parallel tasks
- `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow
- `/subagents-doctor` — diagnose setup, discovery, async paths, 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 async writer (`debugger` for correctness-shaped work, `code-simplifier` for refinement-shaped work), fresh-context specialist reviewers inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async writer applies them. The parent can express the sequence up front as an async/background chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless the user explicitly wants the foreground clarify UI. Treat an async writer handoff as an intermediate state, not final completion, unless the user explicitly asked for writer-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.

### Parallel research technique

Use this when the question needs both external evidence and local implications. Combine `codebase-online-researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `codebase-locator`/`codebase-analyzer` for repository files and current behavior, `codebase-pattern-finder` for analogous conventions, and `codebase-research-locator` + `codebase-research-analyzer` for prior decisions. Give each child a distinct angle: external evidence, local code context, local conventions, prior decisions. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit — none of them should write in this pass.

### Parallel context-build technique

Use this before planning or implementation when a stronger handoff is needed. Run a chain with one parallel step of codebase specialists rather than top-level parallel tasks, so relative output files live under the temporary chain directory. Give every task a distinct output path such as `context-build/where-it-lives.md`, `context-build/how-it-works.md`, `context-build/existing-patterns.md`, and `context-build/prior-research.md`. Choose two to four specialists by angle: `codebase-locator` for the file map, `codebase-analyzer` for current behavior, `codebase-pattern-finder` for conventions, and `codebase-research-locator` → `codebase-research-analyzer` for history when the topic has prior docs. The parent synthesizes the outputs into important context, a recommended next meta-prompt, open questions, assumptions, and artifact paths.

Example shape:

```typescript
subagen