@bastani/atomic 0.9.15 → 0.9.16-alpha.2

package/dist/builtin/subagents/README.md

@@ -127,12 +127,13 @@ There is no generic `reviewer` or `planner` agent; pick the specialist whose ang
 
 Builtin agents inherit your current Pi default model by default. This keeps new installs from depending on a provider you may not have configured. If you want a role to use a specific model, set an override instead of copying the bundled agent file.
 
-For one run, put the override in the command:
+For one run, pass `model` on the `subagent` call:
 
-```text
-/run codebase-analyzer[model=anthropic/claude-sonnet-4:high] "Review this diff"
+```typescript
+subagent({ agent: "codebase-analyzer", task: "Review this diff", model: "anthropic/claude-sonnet-4:high" })
 ```
 
+
 For a persistent override, edit settings. This example pins the codebase-analyzer everywhere, adds a backup model for provider failures, and keeps the other builtins on your normal default model:
 
 ```json
@@ -161,7 +162,7 @@ Workflow invocations receive a stable, non-`default` Intercom group automaticall
 
 ## Where running subagents show up
 
-Foreground runs stream progress in the conversation while they run. Parallel calls keep their grouped task shape in progress and results, and status/control actions can inspect or interrupt retained foreground children.
+Foreground runs stream progress in the conversation while they run. Parallel calls keep their grouped task shape in progress and results, and status/control actions can inspect or interrupt live foreground children.
 
 You can ask naturally:
 
@@ -169,18 +170,6 @@ You can ask naturally:
 Show me the current subagent status.
 ```
 
-If something feels misconfigured, run:
-
-```text
-/subagents-doctor
-```
-
-or ask:
-
-```text
-Check whether subagents and intercom are set up correctly.
-```
-
 ## Recommended orchestration pattern (scaffolding)
 
 Use orchestration as parent-agent guidance, not as a runtime workflow mode. For implementation work, the recommended loop is:
@@ -189,27 +178,13 @@ Use orchestration as parent-agent guidance, not as a runtime workflow mode. For
 clarify → gather context → worker → fresh reviewers → worker
 ```
 
-Use the optional prompt shortcuts below when you want the pattern to be repeatable.
 
-Packaged `worker` defaults to forked context when a launch omits `context`; every other builtin runs fresh. Pass `context: "fresh"` when you intentionally want a fresh `worker` run.
-
-Child-safety boundaries are enforced at runtime by typed admission policy. In-process child sessions load bundled extensions through normal discovery. The `subagent` tool may therefore be registered when the child's active tool selection permits it, including the default no-allowlist case; an explicit allowlist may omit it. Tool presence does not grant fanout: fanout is authorized only when the resolved builtin `tools` list includes `subagent`. Typed admission policy lets a non-fanout child use only `list`, `get`, `status`, and `doctor`; delegation, `resume`, and `interrupt` receive the fanout refusal. A management-restricted child is also refused `create`, `update`, and `delete`. The bundled `pi-subagents` skill remains parent-only and is stripped from child prompts, including fanout-authorized children. No admitted child may delegate: launches, `resume`, and `interrupt` are refused for every child regardless of its fanout authorization. Children receive boundary instructions that they are not the parent orchestrator and must complete their assigned task directly. Forked child context filtering also removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
 
-## Optional shortcuts
+Packaged `worker` defaults to forked context when a launch omits `context`; every other builtin runs fresh. Pass `context: "fresh"` when you intentionally want a fresh `worker` run.
 
-The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
+Child-safety boundaries are enforced at runtime by typed admission policy. In-process child sessions load bundled extensions through normal discovery. The `subagent` tool may therefore be registered when the child's active tool selection permits it, including the default no-allowlist case; an explicit allowlist may omit it. Tool presence does not grant fanout: fanout is authorized only when the resolved builtin `tools` list includes `subagent`. Typed admission policy lets a non-fanout child use only `list`, `get`, and `status`; delegation and `interrupt` receive the fanout refusal. A management-restricted child is also refused `create`, `update`, and `delete`. The bundled `pi-subagents` skill remains parent-only and is stripped from child prompts, including fanout-authorized children. No admitted child may delegate or control another child: launches and `interrupt` are refused for every child regardless of its fanout authorization. Children receive boundary instructions that they are not the parent orchestrator and must complete their assigned task directly. Forked child context filtering also removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
 
-| Prompt | Use it for |
-|--------|------------|
-| `/parallel-review` | Launch fresh-context reviewers with distinct angles, then synthesize what to fix. |
-| `/review-loop` | Run parent-controlled write, review, and fix cycles until clean or capped. `debugger` writes fixes for bugs, `code-simplifier` for cleanup. |
-| `/parallel-research` | Combine `codebase-online-researcher` with local code specialists for external evidence, local context, and practical tradeoffs. |
-| `/parallel-context-build` | Run local code and research specialists in parallel to produce handoff context and meta-prompts. |
-| `/parallel-handoff-plan` | Combine external research with local context passes into an implementation handoff plan and meta-prompt. |
-| `/gather-context-and-clarify` | Locate and analyze first, then ask the user the clarification questions that matter. |
-| `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
 
-Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the synthesized fixes worth doing now after reviewers return.
 
 ## Optional intercom companion
 
@@ -233,87 +208,28 @@ Ask codebase-analyzer to review this plan. If it sees a decision I need to make,
 
 The child can use one dedicated coordination tool:
 
-- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
-
-Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side Atomic sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per detached child completion. Intercom-confirmed delivery returns a compact receipt with artifact/session paths; without that confirmation, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
-When the companion is enabled and available, the bridge gives eligible children deterministic Intercom identities and coordination tools without connecting them automatically. Parent and child connections remain tool-driven: if a child may need live coordination, the parent model should invoke `intercom({ action: "status" })` before launch, and the child connects when it invokes `contact_supervisor` or `intercom`. Foreground launches and management-only actions do not force Intercom loading or broker startup.
-
-For foreground runs, Intercom uses a targeted probe/reservation before delivery: only the exact live child can claim its message. Atomic then commits detach for that child and waits for its acknowledgement before placing claimed asks, sends, decisions, interviews, and progress updates in the parent's model-visible steering queue, so cancellation between phases cannot surface an orphaned request. Blocking calls remain alive for an exact threaded reply and then resume; fire-and-forget calls create no waiter. The retained child later replaces its detached status and artifacts with the real result. Cancellation/replacement invalidates stale handshakes, duplicate delivery cannot recommit, and unmatched messages retain queued-until-idle behavior.
-
-If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
-
-If messages do not show up, run:
-
-```text
-/subagents-doctor
-```
-
-For normal use, you do not need to configure anything. Advanced users can tune the bridge with `intercomBridge` in the configuration section below.
-
-At this point, you know enough to use the plugin. The rest of this README is reference material for exact command syntax, custom agents, worktrees, and configuration.
-
-## Direct commands
-
-Skip this section until you want exact syntax.
+- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for a blocking decision, `reason: "interview_request"` for structured questions, and `reason: "progress_update"` for a short non-blocking update when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
 
-| Command | Description |
-|---------|-------------|
-| `/run <agent> [task]` | Run one agent; omit the task for self-contained agents |
-| `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel |
-| `/subagents-doctor` | Show read-only setup diagnostics |
+Child-side routine completion handoffs are still not expected. With the Intercom bridge active, a blocking decision or interview from the exact foreground child ends at the source before broker send or reply-waiter admission. The parent `subagent` call returns the verbatim question, ordered attachments with duplicates preserved, agent identity, terminal run ID, and a dynamic `[TASK_CONTEXT]` handoff. `intercom.ask` does the same only when its resolved target is the launching parent. The parent answers by launching a fresh child with a new run identity and the supervisor answer in its task.
 
-Commands validate agent names locally, support tab completion, and send results back into the conversation.
+For parallel runs, the claim interrupts every active sibling and prevents queued work from starting or requesting authorization. The sibling set, sessions, and worktrees are not retained for continuation. Any follow-up starts fresh SINGLE or PARALLEL children explicitly. `intercom.send`, progress updates, and asks to siblings or other peers retain the exact-child probe/commit detach and ordinary Intercom delivery paths.
 
-### Parallel tasks
+With the Intercom bridge active, the parent may load and connect its Intercom runtime before initial child execution to issue the exact child's broker capability. The child connection remains tool-driven. A claimed `contact_supervisor` decision or interview still yields before child send or reply-waiter admission; `intercom.ask` connects the child to resolve both targets.
 
-Use `->` to separate tasks and give each task its own prompt:
+Parent-side Atomic still sends grouped completion results through Intercom: one grouped message per foreground parent `subagent` run and one per detached child completion. Intercom-confirmed delivery returns a compact receipt with artifact/session paths; without that confirmation, the normal full output is preserved. Grouped messages include child Intercom targets and full child summaries.
 
-```text
-/parallel codebase-pattern-finder "find security issues" -> codebase-analyzer "check code style"
-```
-
-Both double and single quotes work. You can also use `--` as a delimiter:
-
-```text
-/parallel codebase-locator codebase-analyzer -- check for security issues
-```
-
-Tasks without a prompt use the first available task as a fallback.
-
-### Inline per-step config
-
-Append `[key=value,...]` to an agent name to override defaults for that step:
-
-```text
-/run codebase-locator[model=anthropic/claude-sonnet-4] summarize this codebase
-/parallel codebase-analyzer[skills=code-review+security] "review backend" -> codebase-analyzer[model=openai/gpt-5-mini] "review frontend"
-```
-
-| Key | Example | Description |
-|-----|---------|-------------|
-| `output` | `output=context.md` | Write results to a file. For `/parallel`, relative paths resolve against the child working directory; for `/run`, relative paths resolve against cwd. |
-| `outputMode` | `outputMode=file-only` | Return only a concise file reference for saved output instead of the full saved content. Requires `output`; default is `inline`. |
-| `reads` | `reads=a.md+b.md` | Read files before executing. `+` separates multiple paths. `/run` forwards these through the same resolver as tool-based foreground launches, so relative paths use the effective child working directory. |
-| `model` | `model=anthropic/claude-sonnet-4` | Override model for this step. |
-| `skills` | `skills=planning+review` | Override injected skills. `+` separates multiple skills. |
-| `progress` | `progress` | Enable progress tracking. |
-
-Set `output=false`, `reads=false`, or `skills=false` to disable that behavior explicitly. Do not use `output=false` for file-only returns; use `outputMode=file-only` with an `output` path.
-
-### Forked runs
+If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
 
-Add `--fork` to start each child from a real branched session created from the parent’s current leaf:
+If messages do not show up, check the bridge from the intercom side with `intercom({ action: "status" })`.
 
-```text
-/run codebase-analyzer "review this diff" --fork
-/parallel codebase-locator "audit frontend" -> codebase-analyzer "audit backend" --fork
-```
+For normal use, you do not need to configure anything. Advanced users can tune the bridge with `intercomBridge` in the configuration section below.
 
-`worker` is designed for an explicit decision loop. A typical pattern is to ask a read-only specialist such as `codebase-analyzer` or `debugger` for diagnosis and a recommended execution prompt, then only run `worker` after the main agent approves that direction.
+At this point, you know enough to use the plugin. The rest of this README is reference material for custom agents, worktrees, and configuration.
 
 ## Non-interactive execution
 
-Every supported subagent launch starts immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, forked, fanout, prompt-template, and human-entered `/run` and `/parallel` execution. Gather any needed context and ask the user questions in the parent conversation before launching.
+Every supported subagent launch starts immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, forked, fanout, and prompt-template execution. Gather any needed context and ask the user questions in the parent conversation before launching.
+
 
 ## Agents
 
@@ -405,7 +321,7 @@ interactive: true
 Your system prompt goes here.
 ```
 
-Frontmatter is parsed with a real YAML parser, so it must be valid YAML: a file whose frontmatter does not parse (for example a colon-space inside an unquoted scalar like `description: Deploy: fast`, duplicate keys, or tab-indented block lists) is skipped during discovery. `subagent({ action: "doctor" })` lists every skipped file with the parser's message, so a bad file never disappears silently.
+Frontmatter is parsed with a real YAML parser, so it must be valid YAML: a file whose frontmatter does not parse (for example a colon-space inside an unquoted scalar like `description: Deploy: fast`, duplicate keys, or tab-indented block lists) is skipped during discovery. Discovery records the parser's message for every skipped file, so a bad file never disappears silently.
 
 Important fields:
 
@@ -496,11 +412,11 @@ The package bundles a `subagent` skill that is automatically available to the pa
 
 What the bundled skill covers:
 - **Delegation patterns**: when to launch which agent, whether to use single or parallel mode, and whether to use fresh or forked context
-- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup
+- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel research, parallel context-build, and parallel cleanup
 - **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers
 - **Safety boundaries**: child agents must not run subagents, must not invent intercom targets, and must escalate unapproved decisions
 - **Intercom conventions**: when to ask vs send, and how parent-side result delivery works with `pi-intercom`
-- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action
+- **Control signals**: attention signals, soft interrupts, and status
 
 If you are writing an agent that orchestrates subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it directly; the README and prompt shortcuts encode the same workflows in user-facing form.
 
@@ -537,6 +453,16 @@ These are the parameters the LLM passes when it calls the `subagent` tool. Most
 ], worktree: true }
 ```
 
+### Sibling execution calls
+
+If one assistant response emits several sibling execution-mode `subagent` calls, Atomic collects the synchronous burst before any child starts and runs it through one indexed parallel set. Each original tool call receives only its own children in source order, and its live result, progress, control, and artifact updates are projected to that same route without sibling data. The TUI redraws the shared run as one aggregate parallel widget rather than retaining one widget per original call. A solitary call keeps its original mode, sequential awaited calls stay independent, and management actions bypass collection. A call that arrives after a child has started still gets the existing in-progress rejection. Prefer one explicit `{ tasks: [...] }` call when you intend parallel work; burst collection handles model-emitted sibling calls.
+
+In a collected burst, a call's top-level `agent` task comes first, followed by its `tasks` array. Duplicates and array order are preserved, and `count` expands in place. The task cap applies after all calls are flattened and counts are expanded, with the same hard maximum of 50. Each call-level `cwd` selects that call's agent-discovery scope and child base directory. A task-level `cwd` stays relative to that base and affects child execution, not agent discovery. This per-origin rule applies only to collected sibling calls; an ordinary explicit `{ tasks: [...] }` call keeps one discovery scope from its top-level `cwd`. Per-call and per-task `group` values also remain attached to their children, and a task-level group wins.
+
+For a collected `worktree: true` burst, every call-level `cwd` must resolve to the same path. That common path becomes the shared worktree root; differing origins reject the burst before launch, and any task-level `cwd` must still resolve to that root. Each projected caller result keeps shared worktree diff text and terminal control guidance while its child results and standard child-output sections remain route-local.
+
+One parallel run also needs one value for each run-wide option. Sibling calls must agree on `concurrency`, `worktree`, `context`, `share`, `control`, `sessionDir`, `maxOutput`, `artifacts`, `includeProgress`, and `agentScope`. If any value differs, Atomic rejects the full burst before launch and names the field instead of mixing settings.
+
 ### Management actions
 
 Agent definitions are not loaded into context by default. Management actions let the LLM discover, inspect, create, update, and delete agents at runtime.
@@ -580,7 +506,7 @@ Agent definitions are not loaded into context by default. Management actions let
 |-------|------|---------|-------------|
 | `agent` | string | - | Agent name for single mode, or target for management actions. |
 | `task` | string | - | Task string for single mode. |
-| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, `interrupt`, `resume`, or `doctor`. |
+| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, or `interrupt`. |
 | `config` | object/string | - | Agent config for create/update. |
 | `output` | `string \| false` | agent default | Override single-agent output file. |
 | `outputMode` | `"inline" \| "file-only"` | `inline` | Return saved output inline or as a concise saved-file reference. `file-only` requires an `output` path. |
@@ -611,12 +537,9 @@ Status and control actions:
 subagent({ action: "status" })
 subagent({ action: "status", id: "<run-id>" })
 subagent({ action: "interrupt", id: "<run-id>" })
-subagent({ action: "resume", id: "<run-id>", message: "follow-up question" })
-subagent({ action: "resume", id: "<run-id>", index: 1, message: "follow-up for child 2" })
-subagent({ action: "doctor" })
 ```
 
-`resume` sends the follow-up directly when a child is still reachable. After completion or eviction, it cold-reloads the same canonical child identity from the stored session file. Remembered foreground single or parallel runs can be revived by passing `index` to choose the child; no new OS process is created.
+Completed, interrupted, and parent-question children are terminal for continuation. A prior run ID cannot revive a child or parallel sibling set. Start a fresh subagent call with an explicit context handoff for follow-up work.
 
 ## Worktree isolation
 
@@ -640,7 +563,7 @@ Requirements:
 - the main repository's Husky or populated `.git/hooks` directory is shared through `core.hooksPath`
 - gitignored files matched by `.worktreeinclude` are copied into the worktree
 
-After a worktree parallel step completes, per-agent diff stats are appended to the output and full patch files are written to artifacts. Cleanup forcibly removes each worktree, waits briefly for Git's lock release, and deletes its `worktree-*` branch; the same cleanup runs after post-creation setup failures.
+After a worktree parallel step reaches any terminal result, per-agent diff stats are appended to the output and full patch files are written to artifacts. A parent-directed ask terminally ends the active set, captures its staged and unstaged changes in the same handoff result, and then cleans up every worktree and `worktree-*` branch after a brief Git lock-release wait. The same cleanup runs after post-creation setup failures.
 
 ## Configuration
 
@@ -772,7 +695,7 @@ This is disabled by default. Session data may contain source code, paths, enviro
 
 ## Delegation boundary
 
-Delegation is exactly one level deep, and nothing configures it. A top-level session — main chat or a workflow stage — may call `subagent`. A session that was itself admitted as a subagent child may not: every launch, `resume`, and `interrupt` it attempts is refused with guidance to complete its assigned task directly. The observing actions `list`, `get`, `status`, and `doctor` stay available to a child.
+Delegation is exactly one level deep, and nothing configures it. A top-level session — main chat or a workflow stage — may call `subagent`. A session that was itself admitted as a subagent child may not: every launch and `interrupt` it attempts is refused with guidance to complete its assigned task directly. The observing actions `list`, `get`, and `status` stay available to a child.
 
 There is no configuration option, agent frontmatter field, or tool parameter for the delegation level. The rule is enforced twice: the subagent executor refuses a child before any run starts, and the Rust `SubagentControl` admission door refuses a child deeper than the single permitted level. Admitted depth is typed admission state and is not inherited through an environment variable.
 
@@ -829,13 +752,13 @@ The main runtime files are:
 |------|---------|
 | `src/extension/index.ts` | Extension registration, tool registration, message/render wiring. |
 | `src/agents/agents.ts` | Agent discovery and frontmatter parsing. |
-| `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, management, status, interrupt, and doctor actions. |
+| `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, management, status, and interrupt actions. |
 | `src/runs/foreground/execution.ts` | Core foreground `runSync` handling. |
 | `src/runs/foreground/notify.ts` | Completion-notification delivery for a detached Intercom child. |
 | `src/runs/foreground/completion-notification.ts` | Local completion acknowledgement and ordering barrier for detached children. |
 | `src/shared/settings.ts` | Shared task behavior, instructions, and config helpers. |
 | `src/runs/shared/worktree.ts` | Git worktree isolation. |
-| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
+| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions. |
 | `src/extension/schemas.ts` / `src/shared/types.ts` | Tool schemas, shared types, and event constants. |
 | `test/unit/` / `test/integration/` | Unit and loader-based integration tests. |
 

package/dist/builtin/subagents/agents/worker.md

@@ -20,9 +20,9 @@ Treat an approved handoff or execution plan as the contract. Inspect inherited c
 
 ## Decision and escalation contract
 
-Do not silently make a new product, architecture, or scope decision. When implementation reveals an unapproved decision required to continue safely, pause and use the live coordination route supplied at runtime. Use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for a concise, non-blocking update when helpful or explicitly requested. Fall back to `intercom` only when `contact_supervisor` is unavailable.
+Do not silently make a new product, architecture, or scope decision. When implementation reveals an unapproved decision required to continue safely, use the live coordination route supplied at runtime. Use `contact_supervisor` with `reason: "need_decision"`; a claimed request ends this child and gives the supervisor a fresh-subagent handoff, so do not wait for a reply in this run. Use `reason: "progress_update"` only for a concise, non-blocking update when helpful or explicitly requested. Fall back to `intercom` only when `contact_supervisor` is unavailable.
 
-Do not end with a question requiring the supervisor to choose before work can continue. Do not send routine completion handoffs; return the normal task result when coordination is unnecessary. If you sent a blocked or progress update through `contact_supervisor`, keep it short and still provide the full structured result.
+Do not end with a question requiring the supervisor to choose before work can continue. Do not send routine completion handoffs; return the normal task result when coordination is unnecessary. If you sent a progress update through `contact_supervisor`, keep it short and still provide the full structured result.
 
 ## Work and validation
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.15",
+  "version": "0.9.16-alpha.2",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [
@@ -21,7 +21,6 @@
     "src/**/*.ts",
     "agents/",
     "skills/**/*",
-    "prompts/**/*",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -31,9 +30,6 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "prompts": [
-      "./prompts"
     ]
   },
   "peerDependencies": {

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -25,38 +25,16 @@ Use this skill when bounded specialist delegation adds value and the parent shou
 - **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
+## Tool
 
-Agents can use the `subagent(...)` tool directly for execution, management, status, and control.
-Humans often use the slash-command layer instead:
+Use the `subagent(...)` tool for execution, management, status, and control. There is no bundled slash-command launcher.
 
-- `/run` — launch a single agent
-- `/parallel` — launch top-level parallel tasks
-- `/subagents-doctor` — diagnose setup, execution paths, current session, and intercom bridge state
+When the user asks for research, context-build, or cleanup shapes, apply the same pattern directly with `subagent(...)`.
 
-Prefer the tool when you are writing agent logic. Prefer the slash commands when you are guiding a human through an interactive flow.
+## Applying Prompt Techniques
 
-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(...)`:
+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` — 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 resolve only material unanswered questions before launching. Treat a 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 I set another cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
 
 ### Parallel research technique
 
@@ -79,29 +57,6 @@ subagent({
 })
 ```
 
-### Parallel handoff-plan technique
-
-Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context. Run one top-level parallel discovery call; the parent synthesizes the final handoff afterward. The discovery group usually includes `codebase-online-researcher` for external projects/docs/prompt guidance, `codebase-locator` and `codebase-analyzer` for local code, and optionally `codebase-pattern-finder` and `codebase-research-*` for transferable conventions and prior decisions. Use distinct output paths under `handoff/`, then write `handoff/final-handoff-plan.md` yourself with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact implementation-ready meta-prompt.
-
-Example shape:
-
-```typescript
-subagent({
-  tasks: [
-    { agent: "codebase-online-researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
-    { agent: "codebase-locator", task: "Map local files that would change for: ...", output: "handoff/local-files.md" },
-    { agent: "codebase-analyzer", task: "Trace current behavior of those files: ...", output: "handoff/local-flow.md" },
-    { agent: "codebase-pattern-finder", task: "Find analogous local patterns for: ...", output: "handoff/local-patterns.md" }
-  ],
-  context: "fresh"
-})
-// Parent then writes handoff/final-handoff-plan.md from the outputs.
-```
-
-### Gather-context-and-clarify technique
-
-Use this when unresolved requirements and genuinely missing repository context justify a discovery pass. Launch `codebase-locator` and `codebase-analyzer` for local context, `codebase-pattern-finder` when conventions matter, `codebase-research-locator` + `codebase-research-analyzer` when prior docs likely apply, and `codebase-online-researcher` only when external docs would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
-
 ### 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.
@@ -124,10 +79,11 @@ Builtin agents load at the lowest priority. Project agents override user agents,
 
 Each builtin declares an explicit `model` and `fallbackModels` sequence (typically `github-copilot/<same>`, then `anthropic/claude-opus-4-8`, then `github-copilot/claude-opus-4.7`). The current user-selected model is automatically appended as the last fallback and de-duplicated. Override per run with inline config:
 
-```text
-/run codebase-analyzer[model=anthropic/claude-sonnet-4] "Trace the auth flow"
+```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.
 
 The builtin `debugger` and `worker` agents declare both `intercom` and `contact_supervisor`, so they can send progress or ask the parent for a decision when the bridge is active. Other builtin specialists finish their pass and return without live coordination. Custom agents can coordinate when they declare `intercom` or when the runtime bridge injects `contact_supervisor`; see [Subagent + Intercom Coordination](#subagent--intercom-coordination).
@@ -251,36 +207,21 @@ Avoid duplicate output paths in parallel tasks. Concurrent children should not w
 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 execution and resume
+### Foreground execution and fresh follow-ups
 
 All subagent execution runs in the foreground and returns its result to the parent call. Parallel tasks may still run concurrently within one foreground invocation, and forked context still creates branched child sessions.
 
-Use `resume` for a follow-up on a retained child:
-
-```typescript
-subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
-subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." })
-```
-
-Resume behavior:
-
-- If a child is still running and reachable, `resume` sends the follow-up through its intercom route when available.
-- Completed foreground single and parallel runs can be revived by `index` while their run metadata remains in extension state.
-- A revived child starts a new in-process attempt from its persisted session file.
-- Multi-child runs require `index` unless only one child is selectable.
-- If the chosen child has no persisted `.jsonl` session file, resume fails and reports that directly.
-
-Use diagnostics when setup or child startup looks wrong:
+Completed, 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({ action: "doctor" })
+subagent({ agent: "worker", task: "[TASK_CONTEXT] Continue with this supervisor answer: ..." })
 ```
 
-Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, current session context, and intercom bridge state.
+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. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. 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.
+Subagent control is the runtime visibility and intervention layer for delegated runs. Lifecycle status distinguishes queued and running children from terminal completed, failed, or interrupted 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 `interrupt` options. Visible notifications fire once per child run and attention state.
 
@@ -296,7 +237,7 @@ Pass `id` when targeting a specific controllable run:
 subagent({ action: "interrupt", id: "abc123" })
 ```
 
-A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the delegated task succeeded or failed. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow.
+A soft interrupt cancels the current child turn and terminally records the child as interrupted. It 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:
 
@@ -315,9 +256,10 @@ If the run already has an active intercom bridge target, needs-attention notific
 
 ## Non-Interactive Execution
 
-Every supported subagent launch starts immediately without a preview/editor prompt or terminal input. This applies to single, parallel, forked, fanout, prompt-template, and human-entered `/run` and `/parallel` 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.
 
-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. Human slash commands retain their separate parsing and event-bridge path.
 
 ## Worktree Isolation
 
@@ -339,7 +281,7 @@ subagent({
 
 Atomic subagents work without intercom. When Atomic's bundled intercom companion or upstream `pi-intercom` is installed and enabled, the bridge can give eligible child agents a private coordination tool back to the parent session without connecting either session automatically. If a child may need live coordination, invoke `intercom({ action: "status" })` in the parent before launching it; the child connects when it first invokes `contact_supervisor` or `intercom`.
 
-The builtin `debugger` and `worker` agents declare `intercom` and `contact_supervisor`. With an active bridge route, they can send progress or pause to ask the parent for a decision. Other builtin specialists finish their pass and return without live coordination; use a custom agent with bridge tools when another role needs that ability.
+The builtin `debugger` and `worker` agents declare `intercom` and `contact_supervisor`. With an active bridge route, they can send progress or terminally hand a parent-directed question back to the supervisor. Other builtin specialists finish their pass and return without live coordination; use a custom agent with bridge tools when another role needs that ability.
 
 Custom agents that do have the bridge tool can ask the parent for a decision:
 
@@ -369,7 +311,7 @@ Message conventions:
 
 Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target.
 
-If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
+If intercom messages do not show up, check the bridge from the intercom side with `intercom({ action: "status" })`.
 
 ## Management Mode
 
@@ -451,18 +393,15 @@ That is only a starting point. Omit `package` for the traditional unqualified ru
 
 For many customizations, builtin overrides in settings are lower-friction than copying a full builtin file.
 
-## Prompt Template Integration
+If a prompt-template extension is installed, additional user prompt templates can delegate into subagents.
 
-The package includes prompt shortcuts for common workflows: `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`, `/gather-context-and-clarify`, and `/parallel-cleanup`. Use them when the user wants repeatable review, review/fix loops, research, context handoff, implementation handoff, clarification, or cleanup-review patterns. `/parallel-review autofix` launches a `debugger` or `code-simplifier` writer (depending on feedback shape) to apply the synthesized fixes worth doing now. `/parallel-cleanup autofix` launches one `code-simplifier` writer to apply the synthesized cleanup fixes. Parent agents can also apply the same recipes directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command.
-
-If a prompt-template extension is installed, additional user prompt templates can delegate into subagents. This is useful when a slash command should always run through a particular agent or with forked context.
 
 ## Important Constraints
 
 - **Forking requires a persisted parent session.** If the current session does not have a persisted session file, forked runs fail.
 - **Forked runs inherit parent history.** They are branched threads, not fresh filtered contexts. Use fresh context for adversarial review unless the user explicitly asks for forked context.
-- **Delegation is one level deep and not configurable.** A subagent cannot call `subagent`: every launch, `resume`, and `interrupt` from inside a child is refused. Only `list`, `get`, `status`, and `doctor` stay available to a child.
-- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
+- **Delegation is one level deep and not configurable.** A subagent cannot call `subagent`: every launch and `interrupt` from inside a child is refused. Only `list`, `get`, and `status` stay available to a child.
+- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `interrupted` means the child turn ended before completion; it is terminal for continuation and is not the same as `failed`.
 - **Builtin coordination varies by agent.** `debugger` and `worker` declare `intercom` and `contact_supervisor`; the other builtin specialists do not. For agents without bridge tools, decide the task up front or use a custom agent when mid-run coordination is required.
 - **Intercom asks are blocking.** A session can only maintain one pending outbound ask wait state at a time.
 - **Keep conversational authority clear.** Advisory specialists should not silently become second decision-makers.
@@ -522,19 +461,10 @@ await subagent({ agent: "debugger", task: "Reproduce the failure and patch the r
 
 ### Clarify → Discover → Implement → Review (self-orchestrated workflow)
 
-When the user requests one of these bounded orchestration shapes, factor in the packaged prompt recipes without literally invoking slash commands. Use the same patterns through tools and subagents.
-
-Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override. Do not add overrides just because you are orchestrating; the defaults encode the intended role behavior.
+When the user requests a bounded orchestration shape, apply it through the `subagent` tool. Keep builtin agent defaults unless the user explicitly asks for a different model, thinking level, skills, output behavior, context mode, or other override.
 
 When the user approves launching a subagent to carry out a workflow, treat that as approval to generate a proper role-specific meta prompt for that subagent. Include the approved plan path or summary, clarified requirements, non-goals, relevant context, role boundaries, files or areas to inspect, completion criteria, expected output, and validation expectations. Do not pass vague instructions like "implement the change fully" or "review this" by themselves.
 
-- `/gather-context-and-clarify` maps to: launch locator/analyzer/research specialists; synthesize findings; then use `interview` to ask every clarification question needed for shared understanding.
-- `/parallel-review` maps to: launch fresh-context specialist reviewers with distinct review angles; synthesize the feedback before applying anything.
-- `/review-loop` maps to: keep the parent in charge of writer → fresh specialist reviewers → synthesized fix writer cycles until no fixes worth doing now remain, an unapproved decision appears, or the review-round cap is reached.
-- `/parallel-research` maps to: combine local locator/analyzer/pattern-finder/research-analyzer context with external `codebase-online-researcher` evidence when current docs, ecosystem behavior, or API details matter.
-- `/parallel-context-build` maps to: run a top-level parallel group of codebase specialists with distinct output paths, then synthesize their context and meta-prompt sections.
-- `/parallel-handoff-plan` maps to: run external `codebase-online-researcher` plus local locator/analyzer/pattern-finder/research passes, then synthesize the final handoff plan and implementation-ready meta-prompt yourself.
-- `/parallel-cleanup` maps to: read-only `codebase-analyzer` scouts (deslop + verbosity) followed by an optional `code-simplifier` writer when the user authorizes autofix.
 
 For feature work, use this sequence as scaffolding for parent-agent behavior:
 
@@ -550,7 +480,7 @@ For complex or risky changes, increase review and validation fanout when user in
 
 For very large work, split into serial milestones instead of launching a swarm of writers. Each milestone gets one writer, a validation contract, fresh-context review, a fix pass, and parent approval before the next milestone starts. Use parallel subagents inside a milestone for read-only context, research, and review only.
 
-Keep orchestration authority in the parent session. Child subagents cannot launch more subagents or run their own orchestration loops: delegation is one level deep and nothing configures it. This skill is parent-only and is stripped from every child prompt. A child may still have the `subagent` extension tool registered, because bundled extensions load through normal discovery; registration is not authority. Typed admission policy lets a child use only `list`, `get`, `status`, and `doctor`, and refuses delegation, `resume`, and `interrupt`. Spawned children also do not receive parent-only status/control/slash messages or prior parent `subagent` tool-call/tool-result artifacts, and child context filtering strips old hidden orchestration-instruction messages when they appear in inherited history. Every child also receives a boundary instruction that says the parent owns orchestration, that the `subagent` tool refuses every launch, `resume`, and `interrupt` from inside a subagent, and that writer children must call real edit/write tools instead of printing pseudo tool calls. Pass children concrete role-specific work instead.
+Keep orchestration authority in the parent session. Child subagents cannot launch more subagents or run their own orchestration loops: delegation is one level deep and nothing configures it. This skill is parent-only and is stripped from every child prompt. A child may still have the `subagent` extension tool registered, because bundled extensions load through normal discovery; registration is not authority. Typed admission policy lets a child use only `list`, `get`, and `status`, and refuses delegation and `interrupt`. Spawned children also do not receive parent-only status/control/slash messages or prior parent `subagent` tool-call/tool-result artifacts, and child context filtering strips old hidden orchestration-instruction messages when they appear in inherited history. Every child also receives a boundary instruction that says the parent owns orchestration, that the `subagent` tool refuses every launch and `interrupt` from inside a subagent, and that writer children must call real edit/write tools instead of printing pseudo tool calls. Pass children concrete role-specific work instead.
 
 1. Clarify only when needed. Use existing context first; gather missing code or research context selectively, then ask only unresolved questions that materially affect scope, completion criteria, constraints, or non-goals.
 2. Define the validation contract. State completion expectations before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the writer handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
@@ -600,7 +530,7 @@ When implementation review is part of the requested shape, do not treat the firs
 
 When a writer completes, treat its handoff as an intermediate state when review is part of the requested shape. The next parent action is bounded review, then synthesis, then a fix writer if reviewers found fixes worth doing now. Keep these calls in the foreground so each handoff is available before the next action.
 
-For explicit review-loop requests, repeat writer → fresh-specialist-reviewers → synthesized-fix-writer cycles until reviewers find no blockers or fixes worth doing now, remaining feedback is optional or intentionally deferred, an unapproved product/scope/architecture decision needs the user, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap.
+When the user explicitly asks to keep reviewing until the work is clean, repeat writer → fresh-specialist-reviewers → synthesized-fix-writer cycles until reviewers find no blockers or fixes worth doing now, remaining feedback is optional or intentionally deferred, an unapproved product/scope/architecture decision needs the user, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap.
 
 ### Parallel non-conflicting analysis
 
@@ -623,13 +553,6 @@ subagent({ action: "list" })
 // Check available agents, then confirm scope and precedence.
 ```
 
-**Setup, discovery, or intercom confusion**
-
-```typescript
-subagent({ action: "doctor" })
-// Check runtime paths, execution support, discovery counts, current session, and intercom bridge state.
-```
-
 **"Subagent delegation is not available inside a subagent"**
 
 ```typescript
@@ -666,7 +589,7 @@ subagent({ action: "doctor" })
 **Child fails before starting**
 
 ```typescript
-// Inspect `subagent({ action: "status", id: "..." })`, artifact metadata/output logs, and run doctor. Extension loader errors usually appear in child output logs.
+// Inspect `subagent({ action: "status", id: "..." })` plus artifact metadata and output logs. Extension loader errors usually appear in child output logs.
 ```
 
 ## Suffix-first reasoning levels