# Swarming > Use after pulse:validating approves execution and swarm mode is recommended, when the current work slice should be run by coordinated parallel workers. - Skill: `quanpersie2001/swarming` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add quanpersie2001/swarming` - Raw SKILL.md: https://api.skillmd.com/api/skills/quanpersie2001/swarming/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: quanpersie2001 (https://skillmd.com/u/quanpersie2001) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/quanpersie2001/swarming --- # Swarming If preflight readiness is missing, stale, or blocked (check `.pulse/tooling-status.json`), stop and invoke `pulse:using-pulse` before continuing. ## Role Boundary — Read First You are the **ORCHESTRATOR**. You launch workers, monitor coordination, handle escalations, and keep the swarm moving. You do NOT implement beads. If you find yourself editing source files, stop immediately — that is the `pulse:executing` skill's job. - **swarming** = launches and tends workers (this skill) - **executing** = each worker's self-routing implementation loop ## Hard Rule — Active Swarm Must Not Ignore Actionable Coordination If workers are spawned, online, busy, blocked, or expected to report, you are in a tending phase whenever there is actionable coordination work. While actionable signals exist, keep looping through the active coordination surface and the live bead graph. Do not ignore pending coordination work: - inspect worker follow-ups - inspect the live graph - send reminders - resolve conflicts - escalate only when the next move truly requires human judgment If the runtime has no autonomous wakeup or polling mechanism and there is no current actionable signal, run one complete tend cycle, update `.pulse/STATE.md` plus owner handoff/resume instructions, report that the swarm is paused awaiting the next actionable signal, and do not claim swarm completion. User escalation is for real product decisions, unresolved blockers, or persistent worker silence after you have already tried to recover the swarm through the active coordination surface. ## Communication Standard Blocker reports, conflict reports, and handoffs should be written so a busy teammate can understand them in one read. Prefer: - what is blocked - what is happening right now - one concrete example of the collision or failure - what needs to happen next Do not hide the real issue behind labels like `reservation conflict`, `startup drift`, or `runtime blocker` without explaining the practical effect. ## When to Use Invoke only if all are true: - `pulse:validating` has approved execution - current-work beads are in `open` status and approved for execution - `.pulse/tooling-status.json` says `recommended_mode=swarm` - the active CLI exposes a real native swarm path for this session - if `.pulse/scripts/pulse_status.mjs` exists, run `node .pulse/scripts/pulse_status.mjs --json` first to confirm onboarding, current work slice, reservations, and any saved handoff before launching the swarm If preflight recommends `single-worker`, do not invoke this skill. Invoke `pulse:executing` directly instead. Read `references/runtime-adapter-spec.md` before adapting these instructions to a concrete runtime. --- ## Phase 1: Confirm Swarm Readiness 1. Read `.pulse/tooling-status.json` 2. Read `.pulse/state.json` if present, then `.pulse/STATE.md` 3. Identify the current epic or feature bead root 4. Run a live graph check: ```bash bv --robot-triage --graph-root ``` Confirm: - open executable work exists - no validation blockers remain - dependencies are sane Update `.pulse/state.json` and `.pulse/STATE.md` with current swarm intent and epic ID. --- ## Phase 2: Initialize the Coordination Surface Use the smallest runtime primitives that preserve these behaviors: - spawn workers - deliver startup context - observe worker progress - send coordinator follow-ups - receive worker reports - prevent overlapping file edits through the shared reservation helper - write and restore owner-scoped handoffs Adapter mapping: ### Claude Code - use `TeamCreate` when explicit teammate coordination helps - use `Agent` to spawn bounded workers - use `SendMessage` for coordinator ↔ worker follow-ups - use `Task*` only as optional runtime metadata, never as the work graph ### Codex - use the native subagent spawn path - use parent-thread follow-ups as the coordination surface - keep bead selection and handoffs in the shared Pulse artifacts Shared rules: - beads plus `bv` stay the source of truth for work selection - `.pulse/scripts/pulse_reservations.mjs` is the file-coordination layer for every runtime - `.pulse/STATE.md`, `.pulse/state.json`, and `.pulse/handoffs/` stay authoritative for pause/resume - do not invent extra registration, inbox, or topic mechanics when the runtime does not use them Post the swarm start notification on the active coordination surface using `references/swarming-appendix.md`. That coordination surface is where workers report startup acknowledgments, completions, blockers, conflicts, handoffs, and receive overseer broadcasts. --- ## Phase 3: Spawn Workers Spawn bounded workers that immediately load `pulse:executing`. Provide each worker: - `runtime_identity` - `coordinator_identity` - `adapter_name` - `epic_id` - `feature_name` - optional `startup_hint` - scoped task-specific context by default; full parent-context inheritance only when explicitly needed Do not invent worker identities locally. Use the identity returned by the runtime's worker-spawn primitive. Do **not** assign workers fixed tracks, fixed waves, or fixed bead lists as the normal case. Workers are expected to: 1. read `AGENTS.md` and project context 2. load `pulse:executing` 3. post an `[ONLINE]` acknowledgment 4. run `bv --robot-priority` 5. reserve bead paths through `.pulse/scripts/pulse_reservations.mjs` 6. implement and report 7. loop Mark spawned workers in `.pulse/STATE.md` under `## Active Workers` immediately after each spawn result. Use one line per worker: `- Runtime: | Adapter: | Status: spawned | Current bead: -` The worker startup acknowledgment later updates the same line to `online`. Use the worker prompt template in `references/swarming-appendix.md`. --- ## Phase 4: Monitor + Tend The swarm is live; now you manage it. Run a poll-act-repeat loop for as long as any of these are true: - a worker is `spawned`, `online`, `busy`, or `blocked` - a worker owes a startup acknowledgment, completion report, blocker alert, or handoff - `bv --robot-triage --graph-root ` still shows ready or in-progress work Every loop cycle must do all of the following: 1. Inspect every new worker update on the active coordination surface 2. Update `.pulse/STATE.md` to reflect the latest worker status 3. Reply, remind, or coordinate immediately when a worker is blocked or waiting 4. Re-run the live graph check when a bead closes, a blocker clears, a worker goes silent, or the coordination surface looks stale 5. Refresh reservation state when a conflict, release, or stalled worker could affect file ownership Use live graph checks for oversight, not assignment: ```bash bv --robot-triage --graph-root ``` Do not ignore actionable coordination while the swarm is active. If updates are quiet and the runtime cannot autonomously wake or poll, complete one full tend cycle, persist state/handoff/resume instructions, and pause without claiming completion. ### Worker Event Handling Treat worker events as protocol-driven, not ad hoc. The canonical protocol, required fields, and coordinator message bodies are in `references/swarming-appendix.md`. If a required event field is missing, request a corrected event and do not infer missing values. Minimum coordinator obligations per cycle: 1. Validate incoming event shape against the contract. 2. Update the worker entry in `.pulse/STATE.md` keyed by runtime identity. 3. Verify bead-state transitions in `br`/`bv` before acknowledging completion. 4. Resolve reservations through `.pulse/scripts/pulse_reservations.mjs` before permitting overlapping edits. 5. Serialize same-branch commits by granting at most one `COMMIT_SLOT_GRANTED` at a time; defer any worker that is ready to commit without the active slot. 6. Escalate to the user when blockers require product judgment or a worker stays silent through the appendix silence ladder. Handoff ownership rule: - normal handoff path is same-runtime-identity resume only - a worker must never consume another worker's handoff directly - if the original runtime identity is unavailable, only the coordinator may reassign the orphaned handoff Before coordinator reassignment, confirm and record all of the following: 1. prior worker inactivity is confirmed 2. reservation state for the prior owner is safe for transfer 3. same-branch commit queue state is safe for transfer 4. reassignment metadata is written to `.pulse/handoffs/manifest.json` and the owner handoff file before resume, including previous owner, new owner, reason, and coordinator approval ### Context Checkpoint After each significant event, estimate your own context budget. **If context >65% used:** 1. Write `.pulse/handoffs/coordinator.json` using the shared handoff envelope from `../using-pulse/references/handoff-contract.md`. 2. Register it in `.pulse/handoffs/manifest.json` using the same `summary`, `next_action`, and path. 3. Broadcast a pause notification on the active coordination surface that includes the rendered handoff summary, resume briefing, and transfer block highlights sourced from that JSON. 4. If `.pulse/checkpoints//...` is in use, capture or refresh the feature checkpoint before leaving the swarm pause boundary. 5. Report to the user that the orchestrator paused safely and how to resume. 6. Do NOT abandon the swarm without writing the handoff. The coordinator handoff must follow the same companion contract as planning/executing/validating: - `summary` -> short orchestrator handoff headline - `next_action` + `read_first` -> resume briefing for the next swarm turn - `payload.transfer` -> detailed transfer block for live worker state, blockers, and restart notes Do not write the retired global handoff file. --- ## Phase 5: Swarm Complete When no current-work beads remain `in_progress` and the graph shows no remaining executable work for the active work slice, treat this as a graph-state signal only and verify review eligibility from approved shape artifacts + `.pulse/STATE.md` before any handoff: 1. Run final bead verification: ```bash bv --robot-triage --graph-root ``` 2. If orphaned or blocked beads remain: - report which beads remain and why - ask the user whether to defer, create cleanup beads, or continue later 3. If all current-work beads are closed: - run final build/test commands appropriate to the project - clear `## Active Workers` from `.pulse/STATE.md` - inspect approved shape artifacts and `.pulse/STATE.md`: - work-shape path: `history//work-shape.md` - phase-plan path: `history//phase-plan.md` - epic-map path: `history//epic-map.md` and `history//current-story-pack.md` - determine review eligibility from those artifacts and current-work completion state, not from graph emptiness alone - if shape artifact and `.pulse/STATE.md` disagree about approved/current work slice or whether later slices remain: stop and route back to planning/state sync before any review handoff - if more work slices remain: - keep the whole-feature epic open ``` Active skill: swarming -> COMPLETE Swarm: - current work slice complete Next: planning for next work slice ``` - if this was the final work slice and the artifacts agree no later work remains: ``` Active skill: swarming -> COMPLETE Swarm: - final work slice complete Next: reviewing ``` 4. Handoff message: - if more work slices remain: > "Swarm execution complete for the current work slice. The whole-feature epic stays open. Return to `pulse:planning` to prepare the next work slice." - if this was the final work slice: > "Swarm execution complete for the final work slice. Invoke `pulse:reviewing`." --- ## Red Flags Stop and diagnose before continuing if you see: - **Worker implements multiple beads at once** — self-routing does not mean parallelizing within one worker - **Orchestrator edits source files** — role violation - **Workers are idle but ready beads exist** — inspect the active coordination surface, inspect the graph, and recover the swarm instead of waiting for the user - **No coordination activity for >5 poll cycles while work remains** — workers may be stuck, off-thread, or context-exhausted; run the silence ladder - **The same file conflict repeats** — bead decomposition may be too coarse; escalate - **Workers stop using `bv --robot-priority` and start freelancing** — re-broadcast the execution contract - **Build/test failures accumulate without intervention** — create fix beads or stop and escalate - **Swarm is attempted while preflight recommended `single-worker`** — stop and use standalone executing - **An empty epic subtree is treated as proof the whole feature is complete** — confirm final-slice review eligibility from approved shape artifact (`work-shape.md` | `phase-plan.md` | `epic-map.md`) + `.pulse/STATE.md` before handing off to reviewing --- ## Reference Files Load when needed: | File | Load When | |---|---| | `references/swarming-appendix.md` | Worker startup template, message protocol, silence ladder, and coordinator handoff contract | | `references/runtime-adapter-spec.md` | Adapting canonical swarm behaviors to a concrete runtime | | `docs/evaluation/pulse-swarming-hardening.md` | Re-running RED/GREEN pressure tests for swarm coordination behavior |