orchestrate-subagents

Files (1)

• SKILL.md

SKILL.md (first lines)

# Orchestrate Subagents

## Purpose

Use this skill when you are considering delegated work through the local orchestrator tools.

The orchestrator is useful, but delegation has a coordination cost. First decide whether separation actually helps. If it does, decide how to delegate.

## When to delegate

Use a subagent only when the task has a clear boundary and separation provides a concrete benefit.

Good reasons to delegate:
- **Parallelism**: independent areas can be investigated, implemented, validated, or compared at the same time.
- **Async progress**: broad or slow work can continue in the background instead of blocking the conversation.
- **Role specialism**: a `reviewer` can provide read-only critique focused on correctness, regressions, security, and maintainability.

Do the work yourself when it is small, sequential, needs clarification, depends on nuanced user intent, or is mainly synthesis and assessment. Do not delegate merely because a `scout` or `worker` could perform the same steps; without parallelism or async progress, the handoff overhead is usually not worth it.

The parent keeps final accountability. Subagents gather evidence, perform bounded parallel/background work, or review; the parent decides what it means and answers the user.

## Review economy

- `reviewer` is for one independent final code-diff review or an explicitly requested audit
- do not use `reviewer` as routine validation for plans, designs, documentation, or artifacts the parent just created
- do not review partial stages when one final diff review will cover the complete packet
- default to one reviewer invocation per user-requested packet
- after Medium/Low findings, fix and validate directly without another reviewer pass
- repeat review only for Critical/High remediation, security-sensitive changes, or an explicit user request
- never fan out multiple reviewers over the same change merely to increase confidence

## First how-choice: sync vs async

After deciding to delegate, choose whether the result is needed in this turn.

Prefer **sync** when the delegated task is bounded and you need the result before answering. Sync is best for small fan-outs, focused reviewer passes, and investigations where the default 40-second inactivity timeout is likely to be enough. If needed, set a longer `timeoutSeconds` deliberately.

Prefer **async** when the delegated task is broad, slow, long-running, or useful to start while the conversation continues. Long-running work is only a delegation reason when async progress helps; a long sync subagent often just moves the waiting elsewhere.

When `async: true`, do not add an assistant launch acknowledgment if the tool result already shows the run started. Wait for the orchestrator completion payload, then answer the original request naturally.

## Current orchestrator constraints

- Use only the mediated tools: `delegate_subagent` and `delegate_subagent_status`.
- Do not use raw `subagent` here.
- Available child agent types are known package/user subagents minus the current card's `banned_subagents`; depth and pi-gate lineage ceilings still apply.
- Child gate profile/env is assigned by the orchestrator, not by you.
- Child runs are unattended, so `clarify` is not available.
- Agent-driven continuation is explicit: use `context: "continue"` with a concrete `childSessionId`.
- For current or recent async work, use the orchestrator status tool rather than digging through files on disk.
- Read async artifacts on disk only for older runs outside the current/latest tree, or for low-level debugging.

## Choosing the subagent type

Use the subagent type that matches the actual reason for delegation.

- `scout`: reconnaissance when the work is parallelized, broad enough to benefit from async, or part of a chain that deliberately narrows a large search space.
- `worker`: bounded implementation or validation when it is not banned and the work can run in parallel or in the background.

  Keep worker assignments small and independently verifiable. If unsure, prefer smaller work packages and more workers, with non-overlapping ownership and explicit completion checks; sequence packages that depend on each other.

- `reviewer`: independent read-only critique of a design, plan, diff, or working tree. This is the main role-specialist subagent.

Do not use a scout or worker just to avoid doing ordinary parent-agent work. If the parent can inspect, decide, or edit directly with less coordination overhead, keep the work in the parent.

## Choosing task vs tasks vs chain

Use `task` for one bounded delegation, especially one reviewer pass, one async scout, or one explicit `continue` resume.

Use `tasks` for parallel work. Each task should stand on its own, have a distinct area or question, and avoid overlap unless the overlap is intentional.

Use `chain` when later steps should build on earlier child output. Prefer `tasks` when the work is independent.

Examples:
- `task`: review the current working tree diff.
- `tasks`: inspect frontend, backend, and configuration separately.
- `chain`: first map entry points, then inspect the most relevant paths.

## Choosing context

Use `context: "fresh"` when the child should work from a clean context and rely only on the delegated task plus files it reads. Prefer this for broad scans, neutral investigation, and avoiding unnecessary conversational baggage.

Use `context: "fork"` only when the current conversation branch contains important live context the child must inherit. Fork sparingly: subagents may use different models than the parent, and forking can require the current context to be processed without cache on that model, which can be slow and token-heavy.

Use `context: "continue"` when resuming one exact delegated child conversation. Use it only with single-task delegation, always supply `childSessionId`, and get that id from prior orchestration details or `delegate_subagent_status`.

## Tool reference

### `delegate_subagent`

Call exactly one of these shapes:

```json
{ "task": "...", "async": false, "context": "fresh", "showRunCard": false }
```

```json
{ "tasks": [{ "task": "..." }, { "task": "..." }], "async": false, "context": "fresh", "showRunCard": false }
```

```json
{ "chain": [{ "task": "..." }, { "task": "..." }], "async": false, "context": "fresh", "showRunCard": false }
```

Supported top-level options:
- `agent` — optional subagent type; defaults to `scout` when omitted
- `task` — one subagent
- `tasks` — multiple subagents in parallel
- `chain` — multiple subagents in sequence
- `async` — background execution when `true`
- `timeoutSeconds` — optional inactivity timeout for synchronous delegated runs; defaults to 40 seconds without child activity. Async runs do not use it, but if you provide it anyway it must still be valid.
- `context` — `fresh`, `fork`, or `continue`
- `childSessionId` — required when `context` is `continue`
- `showRunCard` — visible orchestrator run card message; keep this `false` unless the user explicitly wants that UI card

Not available: raw env/profile control, `cwd`, `clarify`, or implicit agent-side `continue latest`.

### `delegate_subagent_status`

From judepayne/picode, MIT.

More from judepayne/picode