---
name: swarming
description: Use when validating approves execution. Orchestrates bounded Codex workers, local reservations, worker results, rescues, and phase handoff. Tends the swarm but never implements beads directly.
metadata:
  version: '1.0'
  role: orchestrator
  ecosystem: khuym
  position: 5-of-9
  upstream: validating
  downstream: reviewing
  dependencies:
    beads-cli:
      kind: command
      command: br
      missing_effect: degraded
      reason: Swarm tending checks bead state and closure through br.
    beads-viewer:
      kind: command
      command: bv
      missing_effect: unavailable
      reason: Live graph triage is required to route and supervise workers.
---

# Swarming

If `.khuym/onboarding.json` is missing or stale for the current repo, stop and invoke `khuym:using-khuym` before continuing.

You are the orchestrator. Launch workers, monitor coordination, handle escalations, and keep the swarm moving. Do not implement beads directly; spawned workers use `khuym:executing`.

## Coordination Substrate

Same-session swarming uses:

- beads and `bv` for work selection and graph state
- Codex subagents for bounded parallel execution
- `.khuym/reservations.json` for local file ownership
- the parent Codex thread for `[DONE]`, `[BLOCKED]`, `[HANDOFF]`, and `[NOOP]` results

No external mail server is required for the default path.

## When to Use

Invoke after `khuym:validating` says: `Validation complete. Current phase passes. Invoke khuym:swarming skill.`

Prerequisites:

- current-phase beads are approved and open
- `EPIC_ID` is known
- `node .codex/khuym_status.mjs --json` has been run when available
- `history/learnings/critical-patterns.md` has been read when present

## Operating Contract

1. Confirm readiness with `bv --robot-triage --graph-root <EPIC_ID>`.
2. Sweep expired reservations.
3. Choose each ready bead parent-side, then spawn bounded worker subagents with `references/swarming-reference.md`.
4. Record `agent_id`, `agent_nickname`, bead, and status in `.khuym/state.json`.
5. Tend the live graph, reservations, and worker results until the phase is clean.
6. Write `.khuym/HANDOFF.json` before pausing near context limits.
7. Run final graph, reservation, and quality checks before handing off.

Load `references/swarming-reference.md` for spawn context, tend-loop rules, result templates, handoff content, and red flags.

## Hard Rules

- Never spawn workers before validation approves execution.
- Never let workers pick beads themselves; pass one explicit `assigned_bead_id` from the orchestrator.
- Never let workers edit without local reservations.
- Do not resolve file conflicts by asking workers to be careful; adjust reservations or bead scope.
- Silence alone is not failure. Do not send routine mid-flight `send_input(...)` check-ins.
- Reserve interrupts for explicit user aborts or confirmed deadlocks where the user wants preemption.
- If context usage passes roughly 65%, write `.khuym/HANDOFF.json` and pause safely.

## Completion Signal

Swarming is complete when either:

- the current phase is executed and the workflow returns to planning for the next phase, or
- the final phase is executed and the user can be told: `Swarm execution complete for the final phase. Invoke khuym:reviewing.`

## Reference Files

| File | When to Load |
|---|---|
| `references/swarming-reference.md` | Orchestration flow, worker prompt, result formats |
| `.khuym/state.json` | Runtime worker and phase state |
| `.khuym/HANDOFF.json` | Pause/resume artifact |