Skip to main content
Generaldraphonix

swarming

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.

Stars
218
Source
draphonix/skills
Updated
2026-05-20
Slug
draphonix--skills--swarming
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/draphonix/skills/HEAD/plugins/khuym/skills/swarming/SKILL.md -o .claude/skills/swarming.md

Drops the SKILL.md into .claude/skills/swarming.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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