Execute

Execution Flow

Step 1: Setup

1. Register as orchestrator:
   - ensure_project(human_key=<project_path>)
   - register_agent(name="Coordinator", program="claude-code", model=<model>)

2. Create session tracking:
   - Initialize TodoWrite with execution stages
   - Note start time

Step 2: Discovery

# Get all ready beads
bd ready --json

# Get graph analysis and execution plan
bv --robot-triage
bv --robot-plan

Parse the output to understand:

• Which beads are ready now
• What the dependency structure is
• Which beads must complete before others can start

Step 3: Phase Identification

Beads naturally form phases based on dependencies:

Phase 1: Beads with no blockers (can start immediately)
Phase 2: Beads blocked by Phase 1 beads
Phase 3: Beads blocked by Phase 2 beads
...

For each phase, identify:

• Which beads belong to it
• When it can start (all blockers from previous phase done)

Step 4: Track Computation

Within each phase, group beads into parallel tracks:

Goal: Beads in different tracks have NO overlapping files, so agents can work simultaneously without conflicts.

Method:

1. For each bead, extract file scope from:
   • edit_locus field if present
   • File paths mentioned in description
   • Parent directory patterns
2. Group beads whose file scopes don't overlap
3. Each group = one track

Example:

Phase 1 has 6 beads:
  bd-101, bd-102 → src/auth/**         → Track A
  bd-103, bd-104 → src/api/**          → Track B
  bd-105         → src/models/**       → Track C
  bd-106, bd-107 → tests/**            → Track D

4 tracks can run in parallel.

Step 5: Spawn Workers

For each track, spawn a worker agent using the Task tool:

Task(
    description=f"Worker: Track {track.name}",
    prompt=WORKER_PROMPT.format(
        track_name=track.name,
        bead_ids=track.beads,
        file_scope=track.files,
        project_path=project_path
    ),
    subagent_type="general-purpose",
    run_in_background=True
)

Worker Prompt Template:

You are a worker agent executing beads for parallel execution.

## Your Assignment
- **Track:** {track_name}
- **Beads:** {bead_ids}
- **File Scope:** {file_scope}
- **Project:** {project_path}

## Instructions

### 1. Startup
Run `/prime` to register with Agent Mail and get oriented.

### 2. Execute Each Bead

For each bead in your assignment, in order:

1. **Claim it:**

bd update {bead_id} --status in_progress --assignee {your_name}

Reserve files via Agent Mail. Send [CLAIMED] announcement.

2. **Implement (TDD-first):**
- Read bead description for test requirements
- Write tests first
- Implement to pass tests
- Run `ubs --staged` before commit
- Commit with bead ID in message

3. **Close it:**

bd close {bead_id} --reason "Completed: <summary>"

Release reservations. Send [CLOSED] announcement.

4. **Move to next bead** in your track.

### 3. Handle Failures

If a bead fails after 3 attempts:
1. STOP trying
2. Send [BLOCKED] message:

send_message( to=["Coordinator"], subject="[BLOCKED] {your_name} - {bead_id}", body_md="Failed after 3 attempts.\n\nError: {details}", importance="urgent" )

3. Continue to next bead in your track (if any)

### 4. Track Complete

When ALL beads in your track are closed (or blocked):

send_message( to=["Coordinator"], subject="[TRACK COMPLETE] {track_name}", body_md="Beads completed: {list}\nBeads blocked: {list}", importance="high" )

Then STOP and wait. Do not pick up other work.

## Rules
1. ONLY work on beads in YOUR track
2. ONLY touch files in YOUR scope
3. TDD always — tests before implementation
4. Security gate — ubs --staged before every commit
5. 3-try limit — after 3 failures, send [BLOCKED], move on
6. Announce everything — [CLAIMED], [CLOSED], [BLOCKED], [TRACK COMPLETE]

Step 6: Monitor Progress

The orchestrator monitors workers:

while phase_in_progress:
    # Check Agent Mail inbox
    messages = fetch_inbox("Coordinator", limit=20, since_ts=last_check)

    for msg in messages:
        if "[TRACK COMPLETE]" in msg.subject:
            mark_track_done(extract_track(msg))
            acknowledge_message(msg.id)

        elif "[BLOCKED]" in msg.subject:
            record_blocked(msg)
            acknowledge_message(msg.id)

    # Check background task status
    for task_id in worker_tasks:
        status = TaskOutput(task_id, block=False)
        if status.completed:
            handle_worker_complete(task_id)

    # Update TodoWrite with current state
    update_progress_display()

    # Check if phase is complete
    if all_tracks_done():
        break

    # Wait before next check (avoid spinning)
    # Continue with other orchestrator work or brief pause

Step 7: Phase Boundary

When all tracks in current phase complete:

# 1. Run calibration
run_calibrate()  # This runs /calibrate skill

# 2. Check result
if calibration_passed:
    send_message(
        to=[ALL_WORKERS],
        subject="[PHASE COMPLETE] Phase {n}",
        body_md="Calibration passed. Proceeding to Phase {n+1}."
    )

    # Compute tracks for next phase
    next_phase_beads = get_phase_beads(n + 1)
    if next_phase_beads:
        tracks = compute_tracks(next_phase_beads)
        spawn_workers(tracks)
    else:
        # No more phases
        execution_complete()