Deft Directive Swarm

Structured workflow for a monitor agent to orchestrate N parallel local agents working on story-level xBRIEFs from xbrief/active/.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

⚠️ See also: swarm.md | deft-directive-review-cycle

Platform Requirements

! This skill requires GitHub as the SCM platform and the GitHub CLI (gh) to be installed and authenticated. Issue fetching, PR creation, and post-merge verification all depend on gh.

Branch-Protection Policy Guard

! Before any state mutation (creating worktrees, dispatching sub-agents, opening PRs), run the skill-level branch-policy guard (#746 / #747). Halt with the actionable disclosure message when the project's plan.policy.allowDirectCommitsToMaster is unresolvable AND DEFT_ALLOW_DEFAULT_BRANCH_COMMIT is unset:

deft verify:branch || exit 1

The swarm skill creates branches per agent so the guard is mostly informational here, but a malformed PROJECT-DEFINITION (missing plan.policy block AND no legacy narrative) is a fail-closed signal worth surfacing before the swarm spawns N agents.

Forge-outage drop-back (#3422)

! On attributed platform outage or repeated REST 429/502/503: drop GitHub I/O, report once to the human in chat, and re-probe on plan.policy.forgeOutageRetryMinutes (default 30; USER.md Personal wins; min 5; task policy:show --field=forgeOutageRetryMinutes). Local work that does not need the forge MAY continue. Depth: `scm/github.md` § #3180 / #3422. Complements #3167 / #3180.

⊗ Tight retry, empty-commit thrash, or sending the human to github.com as the only remediation.
⊗ Auto-merge / --skip-ci because a status page is red.

Deterministic Questions Contract

! Every numbered-menu prompt rendered in this skill (Phase 0 Step 0 queue-driven promote prompts (#1142 / N2), Step 0.5 bridge approval gate, Step 5 final-approval gate, Phase 1 Step 3 file-overlap audit gate, Phase 5->6 ready-to-merge gate) MUST follow `../../contracts/deterministic-questions.md`: render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options MUST be Discuss and Back, in that order. The Discuss-pause semantic is documented verbatim there -- on Discuss selection the agent MUST halt the in-progress sequence immediately, prompt What would you like to discuss?, and resume only on an explicit user signal. Implicit resumption is forbidden, and fallback chat replies MUST map only to the displayed number or exact displayed option text.

When to Use

• User says "run agents", "parallel agents", "swarm", or "launch N agents on stories"
• Multiple independent story-level xBRIEFs in xbrief/active/ need to be worked on simultaneously
• A batch of stories are ready and have no mutual dependencies
• Operator re-authorizes a dual-stopped / hard-stopped / conf-hold unit: pursue residual, follow-up hard-stop, same as conf-hold, continue dual-stopped PR, or re-babysit residual — route to § Operator follow-up after dual-stop / hard stop (#3273) one-shot path
• Operator issues a standing residual order: until floor or loop, until greptile meets policy, or pursue residuals until told otherwise — route to the same § standing path (#3448); applies to open cohort / ordered-plan units, not only the last halted PR

Prerequisites

• ! xbrief/active/ contains one or more story-level xBRIEFs with status running
• ! GitHub CLI (gh) is authenticated
• ! git supports worktrees (git worktree available)
• ~ oz CLI available (for oz agent run-cloud cloud launch — see host-generic / Phase 3)

Host-adapter load path (#2928)

Large multi-host skills use a host-neutral core plus one per-host adapter after detect.

Step	Action
1	Read this thin SKILL (triggers, MUST gates, detect, route table)
2	Run Runtime Capability Detection (below) → stable platform descriptor
3	Load host-neutral depth: references/core-phase-*.md + references/core-ops.md as needed for the current phase
4	Load exactly one references/host-*.md from the route table
5	Launch / monitor / hand off using core + that adapter only

Route table (detect → one adapter)

Detected descriptor	Spawn primitive	Load adapter
warp-orchestrated / warp-manual	start_agent / Warp tabs	`references/host-warp.md`
cursor-composer / cursor-cloud-agent	Cursor Task	`references/host-cursor.md`
claude-code	Claude Agent (run_in_background) / claude-agent	`references/host-claude-code.md`
openclaw	sessions_spawn	`references/host-openclaw.md`
grok-build	spawn_subagent	`references/host-grok-build.md`
generic-terminal (or explicit cloud)	serial / paste / oz agent run-cloud	`references/host-generic.md`

Core reference index (host-neutral)

Phase / topic	File
Phase 0 — Allocate	`references/core-phase-0.md`
Phase 1–2 — Select + Setup	`references/core-phase-1-2.md`
Phase 3 — Launch (neutral + detect detail)	`references/core-phase-3.md`
Phase 4 — Monitor	`references/core-phase-4.md`
Phase 5–6 — Review + Close	`references/core-phase-5-6.md`
Crash recovery, prompts, anti-patterns	`references/core-ops.md`

⊗ Load all host adapters “just in case.” Unused host wiring stays out of context (#2928).
≉ Paste full host manuals into this thin SKILL — keep detect short; depth lives in one adapter.

Hard gates (all hosts)

Worktree isolation before parallel spawn

! One isolated git worktree per parallel agent (Phase 2). Create worktrees or consume a worktree-map before dispatch.
! On OpenClaw, parallel leaves: worktree or worktree-map before sessions_spawn; worker cwd = that worktree; fail loud if the cohort would share the repo root (#2929). Full rules: `references/host-openclaw.md`.
⊗ DIY multi-leaf sessions_spawn without worktree prep (#2929).

Next-phase tool dispatch (#2934)

! After a coding cohort completes (last expected child completion / cohort phase boundary), the parent MUST in the same turn either:

• dispatch the next phase with a real tool call (sessions_spawn / host spawn / task swarm:launch / review-cycle start / merge cascade start), or
• write explicit terminal status (blocked / awaiting-human / done) with a machine-checkable reason.

⊗ End the turn with only narrative “I will spawn…” / “review next” and zero tools (#2934).
~ Keep a small phase-state note: cohort_id → phase → next_action|terminal.

Parent-monitor after leaf announce (#2943 / hard-stop #3131)

! After any leaf completion event (subagent_announce / parent-push / host completion notify), the parent’s first response MUST be one of:

• tool-first ground-truth batch (gh / git / worktree or file status) then one consolidate, or
• host yield (sessions_yield on OpenClaw, or equivalent), or
• one short user answer that is not a repeated progress line.

! Hard-stop (machine-checkable, not prose-only): MUST NOT emit N>2 near-identical assistant sentences (or streaming text chunks) in one turn with no tool_use / yield — FC14 text-repetition hang. Library: evaluateParentTurnShape in @deftai/directive-core/parent-turn-shape (packages/core/src/parent-turn-shape/). Hosts SHOULD abort the turn when ok === false. Operator recovery: docs/openclaw-agent-host.md § Operator recovery — FC14. Soft skill text is not sole mitigation (#3131).

! Thin DONE = failed leaf: completion without PR URL / merge evidence is failed (re-dispatch or take over) — not success. Prefer structured fields when present (prUrl, mergeStatus, emptyDiff).

⊗ Multi-sentence progress-only first response after announce with zero tools / yield (#2943 text-repetition hang).
⊗ N>2 near-identical assistant sentences with no tool_use / yield (FC14 / #3131 hard-stop).
⊗ Treat thin DONE (no PR URL / merge evidence) as success (#2943).
⊗ Rely on soft skill prose alone as the sole mitigation for the parent hang (#3131).

Completion latch after first consolidate (#3092)

! After the parent emits one user/caller-visible consolidate for a child runId / settle batch, identical or equivalent completion replay for the same key MUST be silent (no tools, no re-QC, no second final; host silent token when defined, e.g. OpenClaw NO_REPLY). Re-open only on new runId/batch, principal explicit reopen, or materially new evidence (new HEAD, new blocker class). Replay storms: at most one fail-loud note, then silent. Full MUST: templates/agent-prompt-preamble.md §11.5. Depth: references/core-phase-5-6.md. Orthogonal to empty settle ≠ done (#3044).

Dual stop — repair and monitor loops (#2442)

! Multi-iteration swarm repair and monitor loops MUST carry dual stop: success (goal/AC/clean gate) and a failure/budget stop. Single-turn probes (one status check, one heartbeat read) are exempt. Principle: main.md ## Dual Stop Rule (#2442). Defaults and halt-report shape live in `references/core-phase-4.md` (monitor / takeover) and `references/core-ops.md` (prompts + anti-patterns).

! Default failure envelope for repair/monitor class work (unless the operator or xBRIEF names a stricter one):

• max iterations: 3 monitor repair actions (re-dispatch, takeover complete, re-trigger review) for the same leaf/PR failure class, or
• no-progress: same error / same idle state 3+ times with no material worktree or review change (composes with Phase 4 "stuck in an error loop" takeover trigger). Same-fingerprint Greptile residual uses `deft-directive-review-cycle/SKILL.md` Dual stop — Same-fingerprint stop. or
• budget: existing poll caps (pr:watch max-wait, Greptile service-error single retry + escalate) count as budget stops -- do not invent a second unbounded poll loop outside them.

! On failure stop: halt automatic continuation; emit an operator-visible report (what was tried, what is missing, what human decision is needed). ⊗ Silent re-dispatch or infinite monitor continuation after the envelope is exhausted.

! Halt-report resume line (MUST, #3273 / #3448): Terminal dual-stop / hard-stop / conf-residual halt reports MUST end with leftover class (A/B/C) + residual class + conf (if any) + resolved #3095 floor + standing vs one-shot + PR URL (leftover= / floor= / standing=). One-shot phrases: pursue residual | follow-up hard-stop | same as conf-hold | continue dual-stopped PR. Standing phrases: until floor or loop | until greptile meets policy | pursue residuals until told otherwise. Pointer to § Operator follow-up after dual-stop / hard stop. Full template: `references/core-phase-4.md`.

! Composes with minimal-subgraph repair guidance (#2439): keep repairs minimal and bounded by dual-stop -- minimal repair is not a license to thrash. Durable delivery/acceptance circuit-breaker: #3143 packages/core/src/delivery-attempt/ (evaluatePreDispatch, unit ledger). Docs: docs/delivery-attempt.md. Skill defaults remain behavioral; mechanical gate lives in core.

Operator follow-up after dual-stop / hard stop (#3273)

Operator-initiated resume after dual-stop / hard stop / conf-hold — not automatic re-thrash. Depth (A/B/C leftover classes, standing vs one-shot, steps): `references/core-phase-4.md` same section title. Portable consumer + maintainer (task / deft dual-invoke). Continue-until target is the resolved #3095 floor (task policy:show --field=minGreptileConfidence / deft policy:show --field=minGreptileConfidence: typed project policy > framework dogfood 5 > consumer default 4). ⊗ Hard-code 5/5. ⊗ Lower project policy to clear one PR.

Leftover classes (A/B/C, #3448): class A named leftover on already-touched files = in-AC residual, auto-continue under standing until floor or same-fingerprint loop. class B new subsystem / AC fight = park or follow-up. class C score-only = document / same-as-conf-hold. Already-touched leftover is class A unless it needs a new ledger/protocol/story (#2881).

One-shot vs standing: one-shot pursue residual = one pass then re-stop. Standing (until floor or loop / until greptile meets policy / pursue residuals until told otherwise) applies to open cohort / ordered-plan units, not only the last halted PR. Same-fingerprint stop: `deft-directive-review-cycle/SKILL.md` Dual stop (normative). #2442 batch cap still applies.

Thin pointer: dual-invoke pr:merge-ready / pr:watch; spawn one residual worker or review-cycle owner per batch; document authorized conf floor for this PR only as human-merge/override trail (⊗ silent policy rewrite; pr:merge-ready still uses policy floor). ⊗ Unlimited auto-retry. ⊗ Parent self-implement (#2843).

Runtime Capability Detection (summary)

! Before selecting a launch method, probe the environment. Full probe text: `references/core-phase-3.md`.

1. ! Probe for start_agent tool — Warp orchestrated.
2. ! Probe for Warp environment — WARP_* without start_agent → warp-manual.
3. ! Probe for the Cursor Task tool — Tier 1; descriptor cursor-composer / cursor-cloud-agent (#1877). Require Cursor signals (CURSOR_* or Cursor-only Task surface) — not bare Task alone.
4. ! Probe for Claude Code — Tier 1; descriptor claude-code (#3134). Claude-unique signals only: Agent (or CreateAgent / SubagentStart) with background / run_in_background, and/or DEFT_PROBE_CLAUDE_CODE / DEFT_AGENT_RUNTIME=claude-code / CLAUDECODE. ⊗ Misclassify as cursor-composer via bare Task.
5. ! Probe for the OpenClaw sessions_spawn tool — Tier 1; descriptor openclaw (#2875). Do NOT misclassify as grok-build or generic-terminal.
6. ! Probe for spawn_subagent tool — descriptor grok-build.
7. ! Select launch path automatically — load the matching host adapter (route table). No static A/B/C menu.
8. ! Return a stable platform descriptor for Phase 4/6: warp-orchestrated, warp-manual, cursor-composer, cursor-cloud-agent, claude-code, openclaw, grok-build, or generic-terminal.
9. ? Cloud escape hatch — oz agent run-cloud only on explicit user request (host-generic).

⊗ Present static launch options instead of detecting capabilities at runtime.
⊗ Offer Warp-specific launch paths when not inside Warp.
⊗ Classify Claude Code as cursor-composer / generic-terminal when Claude-unique signals are present (#3134).

Retained addressable sub-agents (#3158)

Named mode beside dispatch-and-collect. Canon: `../../swarm/swarm.md` ## Retained addressable sub-agents (#3158).

Mode	When	Mid-scope gate
retained-child (message-later / steer-mid-flight)	Host keeps a live, addressable child (agent_id / session name); parent can re-message or steer mid-flight	Single dispatch MAY pause for approval and continue the same child
dispatch-and-collect (one-shot)	Host has no continue/resume; worker terminal on tool-loop exit	Split-dispatch mandatory (#954): Scope A → report → approve → Scope B

! After platform detect, read the loaded host adapter's Retained / continue-by-id note. Prefer continue-by-agent-id / resume-by-name / steerable mid-flight only when that adapter documents support.
! When the host cannot retain: keep one-shot envelopes and split-dispatch mid-scope gates. Do not claim message-later semantics the platform cannot deliver.
! Stance (#3164): retention is orchestration only — not mid-run constitution self-edit (managed AGENTS, pinned skills, policy).
! Topology (#3155): retained children MUST obey nuclear-family A2A bounds (parent/sibling/child only).
⊗ Force a second full dispatch on a retain-capable host solely because a mid-scope gate exists — re-message the live child instead.
⊗ Invent retain / resume on hosts whose adapter marks one-shot only.

Phase overview

Phase	Goal	Depth
0 Allocate	Queue cohort, readiness, approval	core-phase-0.md
1 Select	Confirm candidates, file-overlap	core-phase-1-2.md
2 Setup	Worktrees + prompt files	core-phase-1-2.md
3 Launch	Detect, preflight, one host spawn	core-phase-3.md + one host-*.md
4 Monitor	Heartbeats, takeover, no duplicate agents	core-phase-4.md (+ host notes)
5 Review	Greptile clean, gates, next-phase tools	core-phase-5-6.md
6 Close	Merge cascade, cohort sweep, cleanup	core-phase-5-6.md

! Follow phases in order. Depth files hold the operative MUST rules; this page is the dispatch card.

Effort estimate on dispatch (#1581)

! When plan items carry optional effort (S/M/L/XL with time anchors in vbrief/vbrief.md), use them for sizing: S/M single-agent, L may need a dedicated agent, XL blocks dispatch until broken into S/M/L. Activate fails closed on XL. Depth: `references/core-phase-0.md` Steps 2–3.
! Plan-item effort is post-planning (confirms/corrects provisional intake estimates). It is not session-start ritual input; ceremony dial (#3214) starts rapid and escalates — do not block cold-start ritual on missing plan-item effort. Headless: no operator confirmation for size or stage transitions.

Critical anti-patterns (dispatch card)

• ⊗ Load all host adapters “just in case” (#2928)
• ⊗ Parallel OpenClaw sessions_spawn on shared repo root without worktrees (#2929)
• ⊗ Prose-only phase handoff after cohort complete (“I will spawn…”) (#2934)
• ⊗ Multi-sentence progress-only first response after leaf announce with zero tools / yield (#2943)
• ⊗ N>2 near-identical assistant sentences with no tool_use / yield (FC14 / #3131 hard-stop)
• ⊗ Treat thin DONE (no PR URL / merge evidence) as success (#2943)
• ⊗ Rely on soft skill prose alone as the sole parent-hang mitigation (#3131)
• ⊗ Second+ user-visible consolidate for the same child runId without new evidence (#3092)
• ⊗ Assign overlapping files to multiple agents
• ⊗ Dispatch or activate work that still has plan.items[].effort: "XL" without breakdown (#1581)
• ⊗ Merge before Greptile exit condition (score > 3, no P0/P1)
• ⊗ Skip Phase 0 approval before Phase 1
• ⊗ Misclassify OpenClaw sessions_spawn as grok-build or generic-terminal (#2875)
• ⊗ Misclassify Claude Code as cursor-composer / generic-terminal (#3134)
• ⊗ Run multi-iteration repair/monitor loops without a failure stop or with silent continuation after the envelope is exhausted (#2442)
• ⊗ Dual-stop/hard-stop halt without #3273 resume line (leftover class + resolved floor + standing vs one-shot), or unlimited residual auto-retry without new operator consent (#3273 / #3448)
• ⊗ Hard-code 5/5 as the continue-until target, or park a class A already-touched leftover as a new story (#3448 / #2881 / #3095)
• ⊗ Force a second full dispatch on a retain-capable host solely for a mid-scope gate, or invent retain on one-shot hosts (#3158)
• ⊗ Use retained-child messaging for mid-run constitution self-edit (#3158 / #3164)
• ⊗ Tight forge-outage retry / empty-commit thrash without a one-shot human report (#3422)

Full anti-pattern list: `references/core-ops.md`.