Delegation Skill
Dispatch implementation tasks to subagents with proper context, worktree isolation, and TDD requirements. This skill follows a three-step flow: Prepare, Dispatch, Monitor.
Triggers
Activate this skill when:
- User runs command
- Implementation plan is ready with extractable tasks
- User wants to parallelize work across subagents
Exception — oneshot workflows skip delegation entirely. The oneshot playbook runs an in-session TDD loop in the main agent's context, with no subagent dispatch or review phase. If
workflowType === "oneshot"
, do not call this skill — see
for the lightweight path.
Core Principles
Fresh Context Per Task (MANDATORY)
Each subagent MUST start with a clean, self-contained context. As established in the Anthropic best practices for multi-agent coordination:
- No shared state assumptions. Every subagent prompt must contain the full task description, file paths, TDD requirements, and acceptance criteria. Never say "see the plan" or "as discussed earlier."
- No cross-agent references. Subagent A must not depend on output from Subagent B unless explicitly sequenced with a dependency edge in the plan.
- Isolated worktrees. Each subagent operates in its own . Parallel agents in the same worktree will corrupt branch state.
Rationalization patterns that violate this principle are catalogued in
references/rationalization-refutation.md
.
Delegation Modes
The default
mode dispatches each task using the runtime's spawn primitive:
.
Use the
from
task classifications when available. If no classification exists (e.g., fixer dispatch), omit
to inherit the session default.
Pre-Dispatch Schema Discovery
Before dispatching, query decision runbooks to classify the work and select the right strategy:
- Task complexity:
exarchos_orchestrate({ action: "runbook", id: "task-classification" })
to get the cognitive complexity classification tree. Low-complexity tasks can use the scaffolder agent spec for faster execution.
- Dispatch strategy:
exarchos_orchestrate({ action: "runbook", id: "dispatch-decision" })
for dispatch strategy (parallel vs sequential, team sizing, isolation mode).
Step 1: Prepare
Use the
composite action to validate readiness in a single call. This replaces manual script invocations and individual checks.
Authoritative spec: the canonical list of preconditions, blockers, and arguments for
lives in the runtime — query it with
exarchos_orchestrate({ action: "describe", actions: ["prepare_delegation"] })
if anything in this skill drifts from observed behavior. Treat the runtime
output as the source of truth.
Step 0 — Pre-emit (required before )
Before calling
, the workflow stream must contain a
event for each task. The readiness view counts these events to populate
; without them,
returns
{ ready: false, blockers: ["no task.assigned events found ..."] }
.
typescript
exarchos_event({
action: "batch_append",
stream: "<featureId>",
events: tasks.map((t) => ({
type: "task.assigned",
data: { taskId: t.id, title: t.title, branch: t.branch },
})),
})
Step 1 — Prepare (readiness check)
typescript
exarchos_orchestrate({
action: "prepare_delegation",
featureId: "<featureId>",
planPath: "docs/specs/<the-decomposition-spec>.md",
tasks: [{ id: "task-001", title: "...", modules: [...] }, ...]
})
Pass . It points
at the decomposition markdown so it lifts each task's
/
stamp automatically (deterministic parse — no hand-transcription). The stamp is what selects the per-task verification depth below; without
(and without an explicit
/
on a task) every task falls back to a keyword/glob heuristic that under-provisions planner-
/boundary tasks (#1636). You may still set
/
explicitly on a
entry to override the plan for one task; an explicit value always wins.
The composite action is
read-only — it queries delegation readiness and
assembles quality hints. It does
not create worktrees and does
not run
(its authoritative description is
"Query delegation readiness and
prepare quality hints for subagent dispatch"). Worktree materialization is the
host's responsibility under native isolation, or an explicit
call — which lays out the canonical
.worktrees/<taskId>-<taskName>
path. The
action performs:
- State validation — verifies workflow state is in phase, plan exists, plan approved
- Quality signal assembly — queries view; if , returns quality hints to embed in prompts. Emits
gate.executed('plan-coverage')
on success (no pre-query needed)
- Benchmark detection — sets
verification.hasBenchmarks
if any task has benchmark criteria
- Readiness verdict — returns
{ ready: true, worktrees: [...], qualityHints: [...] }
(the array reports the expected paths, not created ones) or { ready: false, reason: "..." }
If with reason: "current-branch-protected"
: the response includes a
field (e.g. "checkout the feature/phase branch before dispatching delegation"). Apply the hint, then re-call.
If : Stop. Report the reason to the user. Do not proceed.
If : Extract the
paths and
for prompt construction.
Native isolation — verify worktrees before agents edit. Under native isolation (
),
returns
even when the host has not yet materialized worktrees (
), because isolation is the host's responsibility — readiness cannot be confirmed at prepare-time. When
and none are confirmed ready, the response carries a
warning:
"native isolation requested; N worktree(s) expected but 0 confirmed ready — verify the host materializes worktrees or dispatch may land in the shared checkout." Do not ignore it. After dispatching, and
before any agent edits files, confirm each agent's working directory is under
(e.g. the agent's first reported
). If an agent is NOT in a worktree it has landed in the shared checkout — stop it, create the worktree manually with
git worktree add -b <task-branch> .worktrees/<taskId>-<taskName> <integration-tip>
(the same
layout
uses, so a manually-created worktree is recognized without a second-path retry), redirect the agent to that path, and only then allow edits. Skipping this check risks silent shared-tree corruption across parallel agents.
Task Extraction
From the implementation plan, extract for each task:
- Full task description (paste inline; never reference external files)
- The / stamps are lifted automatically when you pass (above) — you do NOT need to re-transcribe them into ; pass them explicitly only to override the plan for a specific task
- Files to create/modify as worktree-relative paths rooted inside the worktree (e.g. ) — never an absolute parent-repo path, and never a sequence that escapes the worktree root. Either form resolves outside the agent's worktree cwd and silently writes into the main worktree. This is the platform-agnostic line of defense — it must hold on every runtime.
- Test file paths (worktree-relative) and expected test names
- Dependencies on other tasks (for sequencing)
- Property-based testing flag (
testingStrategy.propertyTests
)
For a complete worked example of this flow, see
references/worked-example.md
.
Step 2: Dispatch
Build subagent prompts using
references/implementer-prompt.md
as the template. Each prompt MUST include the full task context — this is the fresh-context principle in action.
Prompt Construction
On runtimes with native agent definitions:
The implementer agent definition already includes the system prompt, model, isolation, skills, hooks, and memory. The dispatch prompt should contain ONLY task-specific context:
- Full task description (requirements, acceptance criteria)
- Working directory (worktree path from Step 1)
- File paths to create/modify and test file paths
- Quality hints (if any)
- PBT flag when
Full prompt template (default):
For each task:
- Fill the implementer prompt template with task-specific details
- Set the to the worktree path from Step 1
- Include quality hints (if any) in the Quality Signals section
- Include PBT section from
references/pbt-patterns.md
when
- Include testing patterns from
references/testing-patterns.md
Tier-selected verification note — dispatch the rendered prompt
resolves each task's risk tier — from the plan stamp when you passed
(the planner's authored value wins over the heuristic; a divergence is surfaced as a
advisory in
). To keep a wave's payload economical it does
not repeat a full rendered prompt on every task. Instead it returns, once, a shared
implementerPromptTemplate
carrying a
placeholder token, a deduped
map (keyed by
"<riskTier>|<boundaryTouching>"
), and a per-task
taskClassifications[i].verificationNoteKey
. Reconstruct a task's tier-selected prompt by replacing that placeholder token in the template with the task's note —
verificationNotes[taskClassifications[i].verificationNoteKey]
— where a low-tier task's key selects a terse static-analysis steer and a high-tier task's selects the test-after + integration-suite rung. (Pass
— alias
outputFormat: "prompt-only"
— to get the fully inline
taskClassifications[i].implementerPrompt
per task instead; it is lossless vs. the splice.)
Dispatch THAT reconstructed prompt — not the static agent default. The shipped
bakes a fixed medium-tier note (a self-contained fallback for runtimes that pre-bind a named agent). Use it verbatim only when no classification exists (e.g. a fixer dispatch). Otherwise, the orchestrator's dispatch payload must be built from
implementerPromptTemplate
with the task's
note spliced in, then fill its
/
/
placeholders (the same template slots in
references/implementer-prompt.md
) with the task-specific context above. Dispatching the static default instead re-imposes medium-RGR ceremony on every task regardless of tier — the exact gap this seam closes. The tier is pure data from the classification stamp; no workflow-type branching is involved.
Decision Runbooks
For dispatch strategy decisions, query the decision runbook:
exarchos_orchestrate({ action: "runbook", id: "dispatch-decision" })
This runbook provides structured criteria for parallel vs sequential dispatch, team sizing, and failure escalation.
Parallel Dispatch
Dispatch all independent tasks using the runtime's native spawn primitive in a single message so the dispatches run in parallel.
typescript
task --agent implementer 'Implement task-001: [title]: Task-specific context: requirements, file paths, acceptance criteria'
Note: Include the full implementer prompt template from
references/implementer-prompt.md
in the dispatch payload so the spawned agent has a self-contained context — runtimes that pre-bind the implementer prompt to a named agent will discard the redundant content automatically.
For parallel grouping strategy and model selection, see
references/parallel-strategy.md
.
Verification Ownership Contract (ONE owner per claim)
Every verification claim has exactly one owner. Re-verifying a claim you do
not own is duplicated work, not defense in depth — it inflates the wave's cost
and hides which run is authoritative when the two disagree.
| Claim | Owner | Where it runs | Everyone else |
|---|
| "This task's behavior is covered and its tests can fail" | Implementer subagent | Its own worktree, via the per-task gates in the task-completion runbook | Lead consumes the recorded evidence; it does not re-run the gates |
| "This task's diff is clean (types, lint, contracts, mocks)" | Implementer subagent | Same per-task gate sequence | Lead consumes the evidence |
| "The wave as a whole did not cascade" | Lead | Once at the wave boundary — after every wave merge lands | Implementers never run the cumulative suite |
| "The wave is complete (all tasks done, branches exist)" | Lead | , after the cumulative suite | — |
Two consequences bind the runbooks:
- is the terminal step of the task-completion runbook. No
blocking gate may run after it — a task that is marked complete has already
passed every gate that could block it.
- is a wave-boundary backstop, not a per-task
gate. It runs exactly once per wave, after the merges, matching its own
action description. Per-task cascade risk is covered by the task's own
scoped gates.
The lead's only independent verification is a spot check — reading the
recorded evidence and, at most, sampling one claim it has concrete reason to
doubt. A blanket re-run of the per-task chain is a contract violation.
Step 3: Monitor and Collect
Subagent Monitoring
Collect background task results using the runtime's result-collection primitive (this may be a poll/await per task or inline replies, depending on the runtime):
text
inline reply from task --agent (no separate collection API)
After each subagent reports completion:
Runbook: For each completed task, execute the task-completion runbook:
exarchos_orchestrate({ action: "runbook", id: "task-completion" })
Execute the returned steps in order. Stop on gate failure.
If the runbook action is unavailable, use
to retrieve gate schemas and run manually:
exarchos_orchestrate({ action: "describe", actions: ["check_test_adequacy", "check_static_analysis", "task_complete"] })
-
Extract provenance from subagent report — parse the subagent's completion output and extract structured provenance fields (
,
,
). These fields are reported by the subagent following the Provenance Reporting section of the implementer prompt.
-
Verify worktree state — confirm each worktree has clean
and passing tests
-
Run blocking gates — the
runbook (referenced above) defines the exact gate sequence (test adequacy, static analysis, then task_complete). On any gate failure, keep the task in-progress and report findings. All gate handlers auto-emit
events, so manual
calls are not needed.
-
Pass provenance in task completion — when marking a task complete, pass the extracted provenance fields in the
parameter so they flow into the
event:
typescript
exarchos_orchestrate({
action: "task_complete",
taskId: "<taskId>",
streamId: "<featureId>",
result: {
summary: "<task summary>",
implements: ["DR-1", "DR-3"],
tests: [{ name: "testName", file: "path/to/test.ts" }],
files: ["path/to/impl.ts", "path/to/test.ts"]
}
})
- Update workflow state — set each passing to via
- Delegation completion gate (D4, advisory) — after ALL tasks pass, run an operational resilience check on the full branch diff before transitioning to review:
typescript
exarchos_orchestrate({
action: "check_operational_resilience",
featureId: "<featureId>",
repoRoot: ".",
baseBranch: "main"
})
This is advisory — findings are recorded for the convergence view but do not block the delegation→review transition. Include findings in the delegation summary for review-phase attention.
- Schema sync — if any task modified API files (, ), run
Failure Recovery
When a task fails:
- Read the failure output from the runtime's result-collection primitive (
inline reply from task --agent (no separate collection API)
)
- Diagnose root cause — do NOT trust the implementer's self-assessment (see R3 adversarial posture)
- Fix the task using the fixer flow below
- Run the runbook gate chain after the fix completes
For the full recovery flow with a concrete example, see
references/worked-example.md
.
Fix Failed Tasks
Dispatch a fresh fixer agent using the runtime's native spawn primitive, carrying the full failure context and the original task description:
typescript
task --agent fixer 'Fix failed task-001: Your implementation failed. [failure context from test output]. Apply adversarial verification: do NOT trust your previous self-assessment, re-read actual test output, identify root cause not symptoms. [Original task context].'
After fix completes, run the
runbook gate chain:
exarchos_orchestrate({ action: "runbook", id: "task-fix" })
If runbook unavailable, use
to retrieve gate schemas:
exarchos_orchestrate({ action: "describe", actions: ["check_test_adequacy", "check_static_analysis", "task_complete"] })
Fix Mode (--fixes)
Handles review failures instead of initial implementation. Uses
references/fixer-prompt.md
template with adversarial verification posture, dispatches fix tasks per issue, then re-invokes review to re-integrate fixes.
Arguments: --fixes <state-file-path>
— state JSON containing review results in
.reviews.<taskId>.specReview
or
.reviews.<taskId>.qualityReview
.
For detailed fix-mode process, see
.
Deprecated: has been superseded by
. Use the shepherd skill for PR feedback workflows.
Context Compaction Recovery
If context compaction occurs during delegation:
- Query workflow state: with
- Check active worktrees: and verify branch state
- Reconcile:
exarchos_workflow reconcile
replays the event stream and patches stale task state (CAS-protected)
- Do NOT re-create branches or re-dispatch agents until confirmed lost
Worktree State Schema
Worktree entries are stored as
in workflow state. Each entry requires:
| Field | Type | Required | Notes |
|---|
| string | Yes | Git branch name |
| string | Conditional | Single task ID (use for 1-task worktrees) |
| string[] | Conditional | Multiple task IDs (use for multi-task worktrees) |
| | | | Yes | Worktree lifecycle status |
Either
or
(non-empty array) is required — at least one must be present.
Single-task example:
json
{ "branch": "feat/task-001", "taskId": "task-001", "status": "active" }
Multi-task example:
json
{ "branch": "feat/integration", "tasks": ["task-001", "task-002"], "status": "active" }
Phase Transitions and Guards
For the full transition table, consult
@skills/checkpoint/references/phase-transitions.md
.
Quick reference: The
→
transition requires guard
— all
must be
in workflow state.
Before transitioning to review: You MUST first update all task statuses to
via
with the tasks array. The phase transition will be rejected by the guard if any task is still pending/in_progress/failed. Update tasks first, then set the phase in a separate call.
Worktree-Bearing Tasks: Auto-Detour to
When a
event carries a worktree association (
or
), the HSM auto-transitions through
before reaching
. The
projection surfaces the merge verb (idempotency-keyed by
${streamId}:merge_orchestrate:${taskId}
) so a runtime that consumes
will dispatch the merge automatically.
Land it through . The integration branch is shared — sibling worktree merges within the same wave (or a concurrent operator) can race for it.
is THE integration-merge path: it holds an optimistic per-
single-writer lease, then composes
unchanged to do the local
with a recorded recovery-point SHA — see
@skills/merge-orchestrator/SKILL.md
. Do
not dispatch raw
to land onto the integration branch — a live foreign lease makes it fail closed (
, naming
). Raw
is for a non-integration merge (a private / scratch branch no sibling will touch) or a crash-resumed caller re-presenting its original lease.
The HSM exits
back to
once the merge terminates (
/
/
), at which point
either re-enters
for the next worktree-bearing task or transitions on to
when all delegation is complete.
This detour is invisible to the delegation skill itself — the all-tasks-complete guard still gates the
transition. The merge-pending substate just sits between task completion and the next dispatch decision.
Task Status Values
| Status | When to use |
|---|
| Task not yet started |
| Task actively being worked on |
| Task finished successfully |
| Task encountered an error (requires fix cycle) |
Schema Discovery
Use
exarchos_workflow({ action: "describe", actions: ["update", "init"] })
for
parameter schemas and
exarchos_workflow({ action: "describe", playbook: "feature" })
for phase transitions, guards, and playbook guidance. Use
exarchos_orchestrate({ action: "describe", actions: ["check_test_adequacy", "task_complete"] })
for orchestrate action schemas.
When integration advances mid-wave
Runbook for recovering when a subagent worktree's branch has diverged from the
integration branch. Triggered by the integration merge's ancestry preflight
(run by the composed
inside
): the
failure message links here verbatim and includes the manual
command. Auto-rebase is
not wired today — operators
must drive recovery by hand.
Symptom
The merge-orchestrator reports an ancestry failure of the form:
text
source branch <feature-branch> is not a descendant of <integration-branch>.
Rebase manually with: git rebase <integration-branch> (run from the <feature-branch> worktree).
Runbook: skills-src/delegate/SKILL.md#when-integration-advances-mid-wave
This means the integration branch advanced (typically because an earlier
worktree merge landed) while the failing worktree was still in flight.
Fast-forward merge is no longer safe — the working branch must catch up
first.
Why this happens
With the worktree base pinned to local HEAD (see prerequisite below), each
subagent worktree is created at the integration branch's tip at dispatch time.
When the orchestrator merges sibling worktrees serially, each merge moves the
integration branch forward. A worktree that was dispatched against an older
integration tip will fail the ancestry preflight when its turn comes.
This is expected behavior under the current single-writer merge contract —
preflight is fail-only on purpose so the operator stays in control.
Recovery procedure
Before each step, verify you are in the
main worktree (not the failing
subagent worktree) and that
is clean.
-
Capture the rollback SHA before doing anything destructive:
bash
git rev-parse <feature-branch> > /tmp/rollback.sha
Keep this until the merge has been verified. If anything goes wrong,
git reset --hard "$(cat /tmp/rollback.sha)"
on the feature branch
restores the pre-rebase state. The filename is intentionally
branch-name-free so slash-delimited branches like
don't break the path with embedded
characters.
-
Rebase the feature branch onto the current integration tip:
bash
cd <feature-worktree-path>
git fetch origin
git rebase <integration-branch>
Resolve any conflicts that surface. The conflicts are real — they reflect
genuine drift between the two branches, not preflight noise. Do
not
pass
blindly; that drops the subagent's work.
-
Re-run the integration merge from the main worktree — through
, which re-composes
's ancestry
preflight under the single-writer lease:
typescript
exarchos_orchestrate({
action: "serialize_merge",
featureId: "<featureId>",
integrationRef: "<integration-branch>",
sourceBranch: "<feature-branch>",
strategy: "squash", // squash | rebase | merge
taskId: "<taskId>",
dryRun: false, // REQUIRED to execute — the action DEFAULTS to dry-run
})
defaults to a dry-run (preflight only, no lease
claimed): omit
and it reports whether the merge
would apply
without mutating anything. Pass
to actually claim the
single-writer lease and perform the merge. The action is declared
shared-mutating, so a read-only caller (a session without write
capability) is denied even the apply path; in that case fall back to a
local-git merge from the main worktree (
git merge --squash <feature-branch>
then commit) and record the equivalent merge
state/events yourself, since that merge sits outside the serialized lease.
The preflight should now pass. Proceed with the orchestrator's normal
merge flow. (Re-run raw
directly only for a
non-integration merge, or as the crash-resumed caller re-presenting its
original
.)
Rollback procedure
If the rebase produces conflicts you cannot resolve safely, or the merge
still fails after rebase:
-
Reset the feature branch to the captured rollback SHA:
bash
cd <feature-worktree-path>
git rebase --abort # if mid-rebase
git reset --hard "$(cat /tmp/rollback.sha)"
-
Mark the task in workflow state and dispatch a fixer (see
the Failure Recovery section above). Do
not delete the worktree —
the fixer needs the original branch state to diagnose the conflict.
-
Record the incident by emitting a
event with
reason: "ancestry-rebase-conflict"
and the failing branch's pre-rebase
SHA so the convergence view captures the rollback.
Why no auto-rebase yet
Auto-rebase is not yet wired. Today the orchestrator stops at
the ancestry preflight on purpose: a botched auto-rebase across diverged
worktrees risks silently dropping subagent work, and the recovery path
above is short enough that operator-driven rebase is preferable to
clever-but-fragile automation.
Transition
After all tasks complete, auto-continue immediately (no user confirmation):
- Verify all
tasks[].status === "complete"
in workflow state
- Update state: with
- Invoke:
[Invoke the exarchos:review skill with args: <plan-path>]
This is NOT a human checkpoint — the workflow continues autonomously.
References
| Document | Purpose |
|---|
references/implementer-prompt.md
| Full prompt template for implementation tasks |
references/fixer-prompt.md
| Fix agent prompt with adversarial verification posture |
references/worked-example.md
| Complete delegation trace with recovery path (R1) |
references/rationalization-refutation.md
| Common rationalizations and counter-arguments (R2) |
references/parallel-strategy.md
| Parallel grouping and model selection |
references/testing-patterns.md
| Arrange/Act/Assert, naming, mocking conventions |
references/pbt-patterns.md
| Property-based testing patterns |
| Detailed fix-mode process |
references/state-management.md
| State patterns and benchmark labeling |
references/troubleshooting.md
| Common failure modes and resolutions |
references/adaptive-orchestration.md
| Adaptive team composition |
references/workflow-steps.md
| Cross-platform step-by-step delegation reference |
references/worktree-enforcement.md
| Worktree isolation rules |