subagent

# 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 kill only when a delegated run is genuinely blocked. - **Agent authoring**: create, update, or override agents for a project. ## Tool Use the `subagent(...)` tool for execution, management, status, and control. There is no bundled slash-command launcher. When the user asks for research, context-build, or cleanup shapes, apply the same pattern directly with `subagent(...)`. ## Applying Prompt Techniques 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 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 one top-level parallel call with codebase specialists, giving each 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` plus `codebase-research-analyzer` for history. The parent reads the outputs and synthesizes the important context, a recommended next meta-prompt, open questions, assumptions, and artifact paths. Example shape: ```typescript subagent({ tasks: [ { agent: "codebase-locator", task: "Map files, tests, fixtures, and configs that touch: ...", output: "context-build/where-it-lives.md" }, { agent: "codebase-analyzer", task: "Trace how this currently works with file:line refs: ...", output: "context-build/how-it-works.md" }, { agent: "codebase-pattern-finder", task: "Surface analogous patterns to model after: ...", output: "context-build/existing-patterns.md" } ], context: "fresh" }) ``` ### Parallel cleanup technique Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `codebase-analyzer` scouts with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that scout; otherwise inline the criteria. Both scouts are read-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized. When the user opts to autofix, the parent launches one foreground `code-simplifier` writer with the synthesized fixes as its explicit scope. ## Builtin Agents Builtin agents load at the lowest priority. Project agents override user agents, and user/project agents override builtins with the same name. | Agent | Purpose | Tools | Notes | | --- | --- | --- | --- | | `codebase-locator` | Locate files, directories, tests, and configs relevant to a topic | read, search, find, ls, intercom | Read-only finder. Returns a categorized file map; no analysis. | | `codebase-analyzer` | Explain how specific code currently works | read, search, find, ls, todo, intercom | Read-only. Traces flow with `file:line` references; does not critique. | | `codebase-pattern-finder` | Find similar implementations or conventions | read, search, find, ls, intercom | Read-only. Returns code snippets with `file:line` references. | | `codebase-research-locator` | Discover prior `research/` and `specs/` docs | read, search, find, ls, intercom | Read-only. Sorts by date, tiers by recency, flags supersession. | | `codebase-research-analyzer` | Extract decisions and constraints from prior docs | read, search, find, ls, todo, intercom | Read-only. Filters aggressively for what still applies today. | | `codebase-online-researcher` | Web research with authoritative sources | read, search, find, ls, bash, web_search, fetch_content, get_search_content, todo, intercom | Has the `agent-browser` skill. Returns cited findings. | | `code-simplifier` | Clean up recently changed code without changing behavior | read, edit, write, search, find, ls, bash, todo, intercom | **Writer.** Scopes to recently modified code by default; preserves all observable behavior. | | `debugger` | Reproduce, diagnose, and fix failing behavior | read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo | **Writer.** Has the `tdd`, `agent-browser`, and `tmux` skills. Can coordinate with the parent; inspect-only mode requires an explicit instruction. | | `worker` | Implement normal tasks and approved orchestrator handoffs | read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo | **Writer.** Has the `tdd`, `agent-browser`, and `tmux` skills. Defaults to forked context; escalates unapproved decisions instead of guessing. | Each builtin defaults to `model: "auto"`, with no pinned fallback chain. The router selects a model and effort before launch. Inspect effective configuration with `subagent({ action: "get", agent: "debugger" })`. Normal execution fallback remains subject to routing constraints and does not change the main-chat model. Override per run with a concrete model: ```typescript subagent({ agent: "codebase-analyzer", task: "Trace the auth flow", model: "anthropic/claude-sonnet-4" }) ``` For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Every builtin agent declares `intercom` for live coordination with the supervisor and with same-group peers; `debugger` and `worker` also declare `contact_supervisor`. Parent tool restrictions and disabled Intercom still apply. Custom agents can coordinate when they declare `intercom` or when the runtime bridge supplies `contact_supervisor`; see [Subagent + Intercom Coordination](#subagent--intercom-coordination). ## Prompting specialist subagents Specialist agents are narrow on purpose. Write the task prompt as a compact contract that names the agent's specific job — do not duplicate the agent's own system-prompt instructions. Let the role choose the efficient path. A strong subagent prompt usually includes: - **Goal**: the concrete outcome the child should produce. - **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved. - **Success criteria**: what must be true before the child can finish. - **Hard constraints**: true invariants only — for example, "inspect and report only, do not edit" when using `debugger` as a reviewer, or "do not invent issues" for `codebase-analyzer` in a review pass. - **Validation**: targeted checks to run, or the next-best check when validation is impossible. - **Output**: the expected summary shape, artifact path, or finding format. - **Stop rules**: when to stop after enough evidence, and when not to keep searching. Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell `codebase-analyzer` to trace the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell `codebase-online-researcher` the retrieval budget: start with broad targeted searches, fetch the strongest sources via `fetch_content`, fall back to `agent-browser` only when JS execution is required, and stop when the question is answered. For implementation handoffs to `debugger` or `code-simplifier`, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation. Settings locations: - User scope: `~/.atomic/agent/settings.json` (legacy: `~/.pi/agent/settings.json`) - Project scope: `.atomic/settings.json` (legacy: `.pi/settings.json`) Direct settings example: ```json { "subagents": { "agentOverrides": { "codebase-analyzer": { "model": "anthropic/claude-sonnet-4", "thinking": "high", "fallbackModels": ["openai/gpt-5-mini"] } } } } ``` Useful override fields: `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `disabled`, `skills`, `tools`, and `systemPrompt`. Create a user or project agent with the same name only when you want a substantially different agent. ## Discovery and Scope Rules Agent files can live in: - `~/.atomic/agent/agents/**/*.md` — user scope - `.atomic/agents/**/*.md` — canonical project scope - legacy `.agents/**/*.md` and `.pi/agents/**/*.md` — still read for compatibility, but `.atomic/agents/` wins on conflicts Discovery is recursive. Agents can set optional frontmatter/package metadata; `name: codebase-analyzer` plus `package: code-analysis` registers as runtime name `code-analysis.codebase-analyzer` while serialization keeps `name` and `package` separate. Precedence is by parsed runtime name: 1. project scope 2. user scope 3. builtin agents ## Running Subagents ### Single agent ```typescript subagent({ agent: "codebase-analyzer", task: "Trace the auth flow from the route handler through token verification, with file:line refs." }) ``` Enable file-based progress tracking for foreground single-agent runs with `progress: true`. The child maintains a run-scoped `progress.md` under isolated subagent artifact storage without writing it into its effective `cwd`; `progress: false` disables an agent's `defaultProgress`. Omission inherits that default except for read-only tasks, and `artifacts: false` removes foreground storage after the child exits. This is distinct from `includeProgress: true`, which only returns detailed runtime progress data in the final foreground result. ```typescript subagent({ agent: "debugger", task: "Implement the approved fix and validate it.", progress: true, }) ``` ### Forked context ```typescript subagent({ agent: "debugger", task: "Reproduce the failing test in test/unit/foo.test.ts and propose a fix.", context: "fork" }) ``` `context: "fork"` creates a branched child session from the current persisted parent session. It does **not** create a fresh minimal review context or filter history down to only the relevant parts. Use it when you want a separate writer thread that can still reference the parent session history. For adversarial review, prefer fresh context so the specialist inspects the repo directly. ### Parallel execution ```typescript subagent({ tasks: [ { agent: "codebase-locator", task: "Find every file in the auth module" }, { agent: "codebase-pattern-finder", task: "Find existing API-key validation patterns" } ] }) ``` Top-level parallel tasks can override per-task behavior: ```typescript subagent({ tasks: [ { agent: "codebase-locator", task: "Map auth files", output: "auth-files.md", progress: true }, { agent: "codebase-online-researcher", task: "Research OAuth 2.1 changes", output: "oauth-research.md" }, { agent: "codebase-analyzer", task: "Trace the token-refresh flow", model: "anthropic/claude-sonnet-4" } ], concurrency: 3 }) ``` Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file. For large saved outputs, set `outputMode: "file-only"` together with an `output` path. The parent result then contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` instead of the full saved content. Do not use `output: false` for this; `output: false` means no file output. Failed runs and save errors still return inline details for debugging. Concurrent writers conflict. `code-simplifier` and `debugger` change files. Do not run two writers in parallel against the same worktree unless you isolate them with `worktree: true`. ### Foreground, background, and automatic yielding Keep immediately blocking work local unless specialist expertise, context isolation, or an explicit user request justifies delegation. Prefer independent tasks you can overlap with useful parent work. Do not spawn a child merely to wait immediately, or duplicate its assigned work while it runs. Choose the observation mode for each authorized task. No extra user confirmation is needed merely to choose foreground or background. In owner-bound main and workflow-stage sessions, omitted `wait` or `wait: { kind: "background" }` returns after admission. Use `wait: { kind: "foreground", budgetMs: 30000 }` when the result is needed next. If the observation budget expires, the same child keeps running in the background; do not relaunch it. This applies to single and parallel calls. Use `subagent({ action: "wait", id: taskId })` to observe an existing task with the owner's budget, `status` to inspect its state, or `kill` to terminally stop it. Wait when the result becomes a dependency; otherwise rely on completion notices. Avoid repeated short waits or status polls; override the budget only for a concrete responsiveness need. A yielded receipt is not a terminal result. Background counts stay below the prompt; `/tasks` opens inspection only on command. A shaded completion notification reaches the owning chat without requiring a model reply. A later wait does not extend the owner's lifetime. Intercom `ask` cannot revive a completed, failed, interrupted, or cancelled noninteractive child, even if its retained registration says `idle`. New asks fail immediately, and termination fails an already-admitted ask that has not received a reply. Use a fresh child for follow-up work. Live interactive idle sessions and workflow post-mortem conversations remain separate reply-capable cases; `send` transport behavior is unchanged. Completed, killed, interrupted, and parent-question children are terminal for continuation. Do not address a prior child or sibling set by run ID. Start follow-up work with the normal launch form and an explicit handoff: ```typescript subagent({ agent: "worker", task: "[TASK_CONTEXT] Continue with this supervisor answer: ..." }) ``` A parent-ask handoff supplies the original question, ordered attachments, previous agent identity, and dynamic task context. The fresh launch receives a new run identity. ### Subagent control Subagent control is the runtime visibility and intervention layer for delegated runs. Lifecycle status distinguishes queued and running children from terminal completed, failed, killed, or cancelled results. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs push this as a `subagent:control-event` event, and notification-worthy control events are inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `kill` options. Visible notifications fire once per child run and attention state. Use kill when a child is clearly blocked or drifting and the parent needs to terminally stop it: ```typescript subagent({ action: "kill", id: taskId }) ``` Pass `id` when targeting a specific controllable run: ```typescript subagent({ action: "kill", id: "abc123" }) ``` Kill terminally stops the child and records it as killed. It cannot be resumed and does not mean the delegated task succeeded. Decide the next explicit action: launch a fresh child with the relevant task context, replace the task, ask the user, or stop the workflow. Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual: ```typescript subagent({ agent: "debugger", task: "Run the slow migration test suite", control: { needsAttentionAfterMs: 300000, notifyOn: ["needs_attention"] } }) ``` If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists. Every builtin specialist declares `intercom`; coordination still depends on the effective tools and an active route. ## Non-Interactive Execution Every supported subagent launch starts immediately without a preview/editor prompt or terminal input. This applies to single, parallel, forked, fanout, and prompt-template execution. Resolve questions in the parent conversation before launching children. Use `interview` when the user must answer a question, then put the resolved scope and validation contract in the child task. ## Worktree Isolation When multiple writers might run concurrently, use worktrees instead of letting them share one filesystem view. ```typescript subagent({ tasks: [ { agent: "debugger", task: "Fix the failing test in package A" }, { agent: "code-simplifier", task: "Clean up recent changes in package B" } ], worktree: true }) ```