swarm

$swarm

Spawn isolated agents to execute tasks in parallel with Codex session agents. Fresh context per agent.

Integration modes:

• Via $crank - crank creates waves from beads and invokes $swarm for each wave
• Standalone - direct invocation for ad-hoc parallel work

Requires a multi-agent runtime. Prefer runtime-native Codex session agents. If spawning is unavailable, fall back to sequential execution in the current session.

Architecture

Lead (this session)
  |
  +-> Identify the wave: tasks with no blockers
  +-> Build explicit file manifests
  +-> Pre-spawn conflict check (file ownership)
  +-> Spawn one worker per task
  +-> Wait for completion
  +-> Validate changes and close or retry tasks
  +-> Repeat if more work remains

Runtime preference:

1. If spawn_agent is available, use Codex session agents.
2. If your runtime exposes agent_type roles, use worker for execution and explorer for file discovery.
3. If spawning is unavailable, execute sequentially and keep the same file-manifest contract.

Execution

Given $swarm:

Local Mode

In local mode, keep the same file-manifest contract and execute workers sequentially when the runtime cannot spawn agents.

Step 0: Detect Multi-Agent Capability

Check whether the runtime can spawn agents. If not:

WARN: Multi-agent not available. Executing tasks sequentially in this session.

Fall back to serial execution within the current session.

Step 1: Ensure Tasks Exist

Tasks come from one of:

• bd ready output
• An explicit task list from $crank
• A user-provided description that you decompose first

Each task needs:

• id - unique identifier
• subject - what to do
• description - detailed instructions
• files - file manifest for worker ownership
• validation - how to verify completion
• metadata.issue_type - the canonical task type used by the lead when tracking work

Step 1.5: Populate File Manifests

If any task is missing a file manifest, spawn explorer agents to identify files. Use the explorer role if your runtime exposes roles:

spawn_agent(message="You are explorer-1.

Task: Given this task, identify all files that will need to be created or modified.
Return a JSON array of file paths only.
Task subject: <subject>
Task description: <description>")

Inject the discovered file list back into the task manifest before spawning workers.

Step 1.6: Advisory Bead Clustering

When tasks come from bd and scripts/bd-cluster.sh exists, run scripts/bd-cluster.sh --json 2>/dev/null || true before Step 2. Summarize any clusters as consolidation hints only; never run --apply here, and keep Step 2's file-manifest and dependency gates authoritative.

Step 2: Pre-Spawn Conflict Check

Pre-Spawn Friction Gates: Before spawning workers, execute all 5 friction gates (base sync, file manifest, dependency graph, misalignment breaker, wave cap). See references/pre-spawn-friction-gates.md.

wave_tasks = [tasks with status=pending and no blockers]
all_files = {}
for task in wave_tasks:
    for f in task.files:
        if f in all_files:
            CONFLICT: f claimed by both all_files[f] and task.id
        all_files[f] = task.id

On conflict:

• Serialize conflicting workers into separate sub-waves
• Do not spawn overlapping file manifests into the same shared-worktree wave

Display an ownership table before spawning:

File Ownership Map (Wave N):
┌─────────────────────────────┬──────────┬──────────┐
│ File                        │ Owner    │ Conflict │
├─────────────────────────────┼──────────┼──────────┤
│ src/auth/middleware.go      │ task-1   │          │
│ src/api/routes.go           │ task-2   │          │
└─────────────────────────────┴──────────┴──────────┘
Conflicts: 0

Step 3: Spawn Workers

Build one worker prompt per task. Each worker gets a single assignment and a single file manifest.

spawn_agent(message="You are worker-<task-id>.

Assignment: <subject>

<description>

FILE MANIFEST (files you are permitted to modify):
<list of files>

Rules:
1. Stay within your assigned files
2. Run validation: <validation_cmd>
3. Write your result to .agents/swarm/results/<task-id>.json
4. Keep any message back to the lead short

Result file format:
On success:
{\"type\":\"completion\",\"issue_id\":\"<task-id>\",\"status\":\"done\",\"detail\":\"<one-line summary>\",\"artifacts\":[\"path/to/file1\"],\"worktreePath\":\"<absolute-worktree-path-or-empty>\"}

If blocked:
{\"type\":\"blocked\",\"issue_id\":\"<task-id>\",\"status\":\"blocked\",\"detail\":\"<reason>\",\"worktreePath\":\"<absolute-worktree-path-or-empty>\"}

Knowledge artifacts are in .agents/. See .agents/AGENTS.md for navigation.")

If your runtime supports agent_type, mark these as worker agents and keep any file-discovery agents as explorer.

Step 4: Wait and Collect Results

wait_agent(targets=["agent-id-1", "agent-id-2"])

Collect worker result files from .agents/swarm/results/.

If a worker needs a short correction, use:

send_input(target="agent-id-1", message="Validation failed. Fix the test failure and retry.")

If a worker stalls, use:

close_agent(target="agent-id-1")

Step 5: Validate Wave

For each worker result:

1. PASS - accept changes
2. FAIL - log failure, mark for retry, max 2 retries per task
3. BLOCKED - escalate to the lead

After collecting results, run project-level tests appropriate to the wave.

If tests fail, identify which worker's changes caused the break and requeue only that work.

Step 6: Report Results

Output a wave summary with task status, files changed, and any retries.

Test File Naming Validation

When workers create test files, validate naming:

• Go: <source>_test.go or <source>_extra_test.go
• Python: test_<module>.py or <module>_test.py

Output Schema Size Guard

When 5+ workers share the same output schema, cache it to .agents/swarm/output-schema.json and reference it by path instead of inlining it everywhere.

Serial Fallback

If spawning is unavailable, execute tasks sequentially:

for task in wave_tasks:
    1. Read task details
    2. Implement changes
    3. Run validation
    4. Record result

This is slower but functionally identical.

Reference Documents

• [references/conflict-recovery.md](references/conflict-recovery.md)
• [references/cold-start-contexts.md](references/cold-start-contexts.md)
• [references/backend-background-tasks.md](references/backend-background-tasks.md)
• [references/backend-codex-subagents.md](references/backend-codex-subagents.md)
• [references/backend-inline.md](references/backend-inline.md)
• [references/local-mode.md](references/local-mode.md)
• [references/ralph-loop-contract.md](references/ralph-loop-contract.md)
• [references/validation-contract.md](references/validation-contract.md)
• [references/worker-pitfalls.md](references/worker-pitfalls.md)
• [references/pre-spawn-friction-gates.md](references/pre-spawn-friction-gates.md)
• [references/scope-escape-template.md](references/scope-escape-template.md)
• [references/worker-pre-task-checks.md](references/worker-pre-task-checks.md)