Farm Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Spawn an Agent Farm to execute multiple issues in parallel with witness monitoring.

Architecture

Mayor (this session)
    |
    +-> ao farm start --agents N
    |       |
    |       +-> Pre-flight validation
    |       +-> Spawn agents in tmux (serial, 30s stagger)
    |       +-> Spawn witness in separate tmux session
    |
    +-> ao inbox (poll for updates)
    |
    +-> Witness sends "FARM COMPLETE" message
    |
    +-> /post-mortem (extract learnings)

Execution Steps

Given /farm [--agents N] [epic-id]:

Step 1: Pre-Flight Validation

Run pre-flight checks before spawning any agents:

ao farm validate 2>/dev/null

If not available, perform manual checks:

1. Verify beads exist:

ls .beads/issues.jsonl 2>/dev/null || echo "ERROR: No beads found. Run /plan first."

2. Check ready issues:

bd ready 2>/dev/null | wc -l

If 0 ready issues, STOP: "No ready issues. Check dependencies or run /plan."

3. Detect circular dependencies:

bd validate --check-cycles 2>/dev/null

If cycle detected, STOP with error listing the cycle.

4. Verify disk space:

df -h . | awk 'NR==2 {print $4}'

If < 5GB, warn user.

Step 2: Determine Agent Count

Default: N = min(5, ready_issues)

If --agents specified: Use that value, but cap at ready_issues count.

READY_COUNT=$(bd ready 2>/dev/null | wc -l | tr -d ' ')
AGENTS=${N:-5}
AGENTS=$((AGENTS < READY_COUNT ? AGENTS : READY_COUNT))

If AGENTS = 0, STOP: "No work available for agents."

Step 3: Spawn Agent Farm

Start the farm with serial agent spawn (30s stagger):

ao farm start --agents $AGENTS --epic <epic-id> 2>&1

This command:

1. Creates tmux session ao-farm-<project>
2. Spawns agents one at a time with 30s delay
3. Spawns witness in separate session ao-farm-witness-<project>
4. Writes .farm.meta with PIDs and state
5. Returns immediately with status message

Expected output:

Farm started: 5 agents, 1 witness
Session: ao-farm-nami
Witness: ao-farm-witness-nami
Check progress: ao inbox
Stop: ao farm stop

Step 4: Monitor Progress (Loop)

Tell the user farm is running, then monitor:

Farm running. Check /inbox periodically for progress updates.

- Witness summarizes every 5 minutes
- Agents send completion messages per issue
- "FARM COMPLETE" signals all work done

Commands:
  ao inbox              - Check messages
  ao farm status        - Show agent states
  ao farm stop          - Graceful shutdown

Optional: Periodically check inbox:

ao inbox --since 5m 2>/dev/null

Step 5: Handle Completion

When witness sends "FARM COMPLETE" message:

1. Verify all issues closed:

bd list --status open 2>/dev/null | wc -l

2. Clean up farm resources:

ao farm stop 2>/dev/null

3. Suggest next step:

Farm complete. X issues closed in Y minutes.
Run /post-mortem to extract learnings.

Error Handling

Circuit Breaker

If >50% agents fail within 60 seconds:

ao farm stop --reason "circuit-breaker"

Tell user: "Circuit breaker triggered. >50% agents failed. Check logs."

Witness Death

If witness process dies (detected via PID check):

if ! kill -0 $(cat .witness.pid 2>/dev/null) 2>/dev/null; then
    echo "ERROR: Witness died. Stopping farm."
    ao farm stop --reason "witness-died"
fi

Orphaned Issues

If issues stuck in_progress after farm stop:

ao farm resume

Key Rules

• Pre-flight first - Never spawn without validation
• Serial spawn - 30s stagger prevents rate limits
• Cap agents - Never more agents than ready issues
• Monitor witness - Check PID health every 30s
• Graceful stop - Clean up all child processes
• Resume capability - Recover from disconnects

Without ao CLI

If ao farm commands not available:

1. Manual tmux spawn:

# Create session
tmux new-session -d -s ao-farm

# For each agent
tmux send-keys -t ao-farm "claude --prompt 'Run /implement on next ready issue'" Enter
sleep 30  # Wait before next agent

2. Manual witness:

tmux new-session -d -s ao-farm-witness
tmux send-keys -t ao-farm-witness "claude --prompt 'Monitor tmux session ao-farm, summarize every 5m'" Enter

3. Manual inbox (beads messages):

bd list --type message --to mayor 2>/dev/null

Agent Farm Behavior

Each spawned agent:

1. Runs /implement loop until no ready issues
2. Claims issues atomically via bd claim
3. Sends completion message via Agent Mail
4. Exits when no more work

Witness:

1. Polls agent tmux panes every 60s
2. Summarizes to mayor every 5m
3. Escalates blockers immediately
4. Sends "FARM COMPLETE" when all agents idle and no ready issues

Exit Conditions

Farm exits when:

• All issues closed (success)
• Circuit breaker triggers (>50% fail)
• Witness dies unexpectedly (error)
• User runs ao farm stop (manual)
• Mayor disconnects (orphaned - use resume)