orchestrator

Original source / Raw SKILL.md

---
name: orchestrator
description: Multi-agent parallel execution with autonomous workers. Use when plan.md has Track Assignments section or user triggers /conductor-orchestrate, "run parallel", "spawn workers". MUST load maestro-core skill first for routing.
---

# Orchestrator - Multi-Agent Parallel Execution

> **Spawn autonomous workers to execute tracks in parallel using Agent Mail coordination.**

## Agent Mail: CLI Primary, MCP Fallback

This skill uses a **lazy-load pattern** for Agent Mail:

| Priority | Tool | When Available |
|----------|------|----------------|
| **Primary** | `bun toolboxes/agent-mail/agent-mail.js` | Always (via Bash) |
| **Fallback** | MCP tools (via `mcp.json`) | When skill loaded + MCP server running |

**Detection flow:**
```
1. Try CLI: bun toolboxes/agent-mail/agent-mail.js health-check
   ↓ success? → Use CLI for all Agent Mail operations
   ↓ fails?
2. Fallback: MCP tools (lazy-loaded via skills/orchestrator/mcp.json)
```

**CLI benefits:** Zero token cost until used, no MCP server dependency.

## Core Principles

- **Load core first** - Load [maestro-core](../maestro-core/SKILL.md) for routing table and fallback policies
- **CLI first** - Use `bun toolboxes/agent-mail/agent-mail.js` CLI before falling back to MCP tools
- **Pre-register workers** before spawning (Agent Mail validates recipients)
- **Workers own their beads** - can `bd claim/close` directly (unlike sequential mode)
- **File reservations prevent conflicts** - reserve before edit, release on complete
- **Summary before exit** - all workers MUST send completion message
- **TDD by default** - workers follow RED → GREEN → REFACTOR cycle (use `--no-tdd` to disable)

## When to Use

| Trigger | Condition |
|---------|-----------| 
| Auto-routed | `/conductor-implement` when plan has Track Assignments |
| File-scope | `/conductor-implement` when ≥2 non-overlapping file groups detected |
| Direct | `/conductor-orchestrate` or `co` |
| Phrase | "run parallel", "spawn workers", "dispatch agents" |
| **See also** | `ca` for [autonomous execution](../conductor/references/workflows/autonomous.md) |

## Auto-Trigger Behavior

Parallel execution starts **automatically** when detected - no confirmation needed:

```
📊 Parallel execution detected:
- Track A: 2 tasks (src/api/)
- Track B: 2 tasks (lib/)
- Track C: 1 task (schemas/)

⚡ Spawning workers...
```

## Quick Reference

| Action | Tool |
|--------|------|
| Parse plan.md | `Read("conductor/tracks/<id>/plan.md")` |
| Initialize | `bun toolboxes/agent-mail/agent-mail.js macro-start-session` |
| Spawn workers | `Task()` for each track |
| Monitor | `bun toolboxes/agent-mail/agent-mail.js fetch-inbox` |
| Resolve blockers | `bun toolboxes/agent-mail/agent-mail.js reply-message` |
| Complete | `bun toolboxes/agent-mail/agent-mail.js send-message`, `bd close epic` |
| Track threads | `bun toolboxes/agent-mail/agent-mail.js summarize-thread` |
| Auto-routing | Auto-detect parallel via `metadata.json.beads` |

## 8-Phase Orchestrator Protocol

0. **Preflight** - Session identity, detect active sessions
1. **Read Plan** - Parse Track Assignments from plan.md
2. **Validate** - Health check Agent Mail CLI (HALT if unavailable)
3. **Initialize** - ensure_project, register orchestrator + all workers
4. **Spawn Workers** - Task() for each track (parallel)
5. **Monitor + Verify** - fetch_inbox, verify worker summaries
   - Workers use track threads (`TRACK_THREAD`) for bead-to-bead context
6. **Resolve** - reply_message for blockers
7. **Complete** - Send summary, close epic, `rb` review

See [references/workflow.md](references/workflow.md) for full protocol.

## Worker 4-Step Protocol

All workers MUST follow this exact sequence:

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  STEP 1: INITIALIZE  - bun toolboxes/agent-mail/agent-mail.js macro-start-session   │
│  STEP 2: EXECUTE     - claim beads, do work, close beads                            │
│  STEP 3: REPORT      - bun toolboxes/agent-mail/agent-mail.js send-message          │
│  STEP 4: CLEANUP     - bun toolboxes/agent-mail/agent-mail.js release-file-reservations │
└──────────────────────────────────────────────────────────────────────────────┘
```

| Step | Tool | Required |
|------|------|----------|
| 1 | `bun toolboxes/agent-mail/agent-mail.js macro-start-session` | ✅ FIRST |
| 2 | `bd update`, `bd close` | ✅ |
| 3 | `bun toolboxes/agent-mail/agent-mail.js send-message` | ✅ LAST |
| 4 | `bun toolboxes/agent-mail/agent-mail.js release-file-reservations` | ✅ |

**Critical rules:**
- ❌ Never start work before `macro-start-session`
- ❌ Never return without `send-message` to orchestrator
- ❌ Never touch files outside assigned scope

See [references/worker-prompt.md](references/worker-prompt.md) for full template.

## Agent Routing

| Intent Keywords | Agent Type | File Reservation |
|-----------------|------------|------------------|
| `research`, `find`, `locate` | Research | None (read-only) |
| `review`, `check`, `audit` | Review | None (read-only) |
| `plan`, `design`, `architect` | Planning | `conductor/tracks/**` |
| `implement`, `build`, `create` | Execution | Task-specific scope |
| `fix`, `debug`, `investigate` | Debug | None (read-only) |

See [references/intent-routing.md](references/intent-routing.md) for mappings.

## Anti-Patterns

| ❌ Don't | ✅ Do |
|----------|-------|
| Spawn workers without pre-registration | Register all workers BEFORE spawning |
| Skip completion summary | Always send_message before exit |
| Ignore file reservation conflicts | Wait or resolve before proceeding |
| Use orchestration for simple tasks | Use sequential `/conductor-implement` |

## Lazy References

Load references only when needed:

| Phase | Trigger Condition | Reference |
|-------|-------------------|-----------|
| Always | On skill load | SKILL.md (this file) |
| Phase 3 (Initialize) | Setting up Agent Mail, project registration | [agent-mail.md](references/agent-mail.md) |
| Phase 4 (Spawn) | Before dispatching worker agents | [worker-prompt.md](references/worker-prompt.md) |
| Phase 6 (Handle Issues) | Cross-track dependencies, blocker resolution | [agent-coordination.md](references/agent-coordination.md) |

### All References

| Topic | File |
|-------|------|
| Full workflow | [workflow.md](references/workflow.md) |
| Architecture | [architecture.md](references/architecture.md) |
| Coordination modes | [coordination-modes.md](references/coordination-modes.md) |
| Agent Mail protocol | [agent-mail.md](references/agent-mail.md) |
| Agent Mail CLI | [agent-mail-cli.md](references/agent-mail-cli.md) |
| Worker prompt template | [worker-prompt.md](references/worker-prompt.md) |
| Preflight/session brain | [preflight.md](references/preflight.md) |
| Intent routing | [intent-routing.md](references/intent-routing.md) |
| Summary format | [summary-protocol.md](references/summary-protocol.md) |
| Auto-routing | [auto-routing.md](references/auto-routing.md) |
| Track threads | [track-threads.md](references/track-threads.md) |

## Related

- [maestro-core](../maestro-core/SKILL.md) - Routing and fallback policies
- [conductor](../conductor/SKILL.md) - Track management, `/conductor-implement`
- [tracking](../tracking/SKILL.md) - Issue tracking, `bd` commands


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../maestro-core/SKILL.md

```markdown
---
name: maestro-core
description: Use when any Maestro skill loads - provides skill hierarchy, HALT/DEGRADE policies, and trigger routing rules for orchestration decisions
---

# Maestro Core - Workflow Router

Central hub for Maestro workflow skills. Routes triggers, defines hierarchy, and handles fallbacks.

## Skill Hierarchy

```
conductor (1) > orchestrator (2) > designing (3) > tracking (4) > specialized (5)
```

Higher rank wins on conflicts.

## Ownership Matrix

| Skill | Owns | Primary Triggers |
|-------|------|------------------|
| conductor | Implementation + autonomous | `ci`, `ca`, `/conductor-implement`, `/conductor-autonomous` |
| orchestrator | Parallel execution | `co`, `/conductor-orchestrate` |
| designing | Phases 1-10 (design → track creation) | `ds`, `cn`, `/conductor-newtrack`, `/conductor-design` |
| tracking | Task/bead management | `bd *`, `fb`, `rb` |
| handoff | Session cycling | `ho`, `/conductor-finish`, `/conductor-handoff` |
| creating-skills | Skill authoring | "create skill", "write skill" |

## Workflow Chain

```
ds/cn → design.md → /conductor-newtrack → spec.md + plan.md → fb → tracking → ci/co/ca → implementation
```

## Routing Table

**CRITICAL:** After loading `maestro-core`, you MUST explicitly load the target skill via `skill(name="...")` before proceeding.

See **[routing-table.md](references/routing-table.md)** for complete trigger → skill mappings, phrase triggers, and conditional routing logic.

### Quick Triggers

| Trigger | Skill |
|---------|-------|
| `ds`, `cn` | designing |
| `ci` | conductor |
| `ca` | conductor |
| `co` | orchestrator |
| `fb`, `rb`, `bd *` | tracking |
| `ho` | handoff |

### Routing Flow

```
1. User triggers command (e.g., `ci`)
2. Load maestro-core → get routing table
3. Look up trigger → find target skill
4. MUST call skill tool to load target skill
5. Follow loaded skill instructions
```

## Fallback Policies

| Condition | Action | Message |
|-----------|--------|---------|
| `bd` unavailable | HALT | `❌ Cannot proceed: bd CLI required` |
| `conductor/` missing | DEGRADE | `⚠️ Standalone mode - limited features` |
| Agent Mail unavailable | HALT | `❌ Cannot proceed: Agent Mail required for coordination` |

## Quick Reference

| Concern | Reference |
|---------|-----------|
| Complete workflow | [workflow-chain.md](references/workflow-chain.md) |
| All routing rules | [routing-table.md](references/routing-table.md) |
| Terms and concepts | [glossary.md](references/glossary.md) |
| CLI toolboxes | [toolboxes.md](references/toolboxes.md) |

## Related Skills

- [designing](../designing/SKILL.md) - Double Diamond design sessions (phases 1-10)
- [conductor](../conductor/SKILL.md) - Implementation execution
- [orchestrator](../orchestrator/SKILL.md) - Multi-agent parallel execution
- [tracking](../tracking/SKILL.md) - Issue tracking and dependency graphs
- [handoff](../handoff/SKILL.md) - Session cycling and context preservation
- [creating-skills](../creating-skills/SKILL.md) - Skill authoring and best practices
- [sharing-skills](../sharing-skills/SKILL.md) - Contributing skills upstream
- [using-git-worktrees](../using-git-worktrees/SKILL.md) - Isolated workspaces

```

### ../conductor/references/workflows/autonomous.md

```markdown
# Autonomous Execution (Ralph)

Third execution mode alongside `ci` (implement) and `co` (orchestrate).

## Trigger

- `ca` or `/conductor-autonomous`

## Purpose

Invoke Ralph autonomous loop to iterate through stories with automated verification passes.

## ⚠️ MANDATORY: Direct Shell Invocation

**When `ca` is triggered, ALWAYS run the shell script directly:**

```bash
./toolboxes/ralph/ralph.sh <track-path> [max_iterations]
```

Do NOT use Task() or sub-agents. Ralph.sh spawns fresh Amp instances for each iteration - this is the core pattern.

## Prerequisites

- Track exists with `metadata.json`
- `ralph.enabled == true` in metadata.json
- `ralph.stories` object is populated
- `ralph.active == false` (no other ca running)

## Preflight Checks

| Check | Condition | Action on Failure |
|-------|-----------|-------------------|
| Track exists | `metadata.json` present | HALT: "Track not found" |
| Ralph enabled | `ralph.enabled == true` | HALT: "Ralph not enabled for this track" |
| Ralph available | `ralph.active == false` | HALT: "Ralph already running" |
| Stories exist | `ralph.stories` non-empty | HALT: "No stories to execute" |

### Blocking Other Commands

When `ralph.active == true`:

| Command | Behavior |
|---------|----------|
| `ci` | HALT: "Ralph execution in progress" |
| `co` | HALT: "Ralph execution in progress" |
| `ca` | HALT: "Ralph already running" |

## Execution Flow

When user types `ca`:

1. **Find active track** - Look for track with `ralph.enabled == true`
2. **Run preflight checks** - Validate prerequisites
3. **Execute directly via Bash:**

```bash
./toolboxes/ralph/ralph.sh conductor/tracks/<track_id> 10
```

4. Ralph.sh handles:
   - Setting `ralph.active = true` (exclusive lock)
   - Spawning fresh Amp instances per iteration
   - Updating `ralph.stories[id].passes` status
   - Releasing lock on completion/error

## Invocation Examples

```bash
# Basic invocation (default 10 iterations)
./toolboxes/ralph/ralph.sh conductor/tracks/<track_id>

# With custom iteration limit
./toolboxes/ralph/ralph.sh conductor/tracks/<track_id> 5

# Example with real track
./toolboxes/ralph/ralph.sh conductor/tracks/ralph-test_20260109 10
```

## State Updates

### On Start

```json
{
  "ralph": {
    "active": true,
    "startedAt": "2025-01-08T12:00:00Z"
  }
}
```

### On Completion

```json
{
  "ralph": {
    "active": false,
    "completedAt": "2025-01-08T14:30:00Z"
  },
  "workflow": {
    "state": "DONE"
  }
}
```

## Progress Tracking

Progress is written to `<track>/progress.txt`:

```
Story 1/5: auth-login ✓
Story 2/5: auth-logout ✓  
Story 3/5: session-mgmt ~ (in progress)
Story 4/5: password-reset -
Story 5/5: mfa-setup -
```

Story completion updates `ralph.stories[id].passes`:

```json
{
  "ralph": {
    "stories": {
      "auth-login": { "id": "auth-login", "title": "Login flow", "priority": 1, "passes": true, "beadId": "proj-abc1" },
      "auth-logout": { "id": "auth-logout", "title": "Logout flow", "priority": 2, "passes": true, "beadId": "proj-def2" },
      "session-mgmt": { "id": "session-mgmt", "title": "Session management", "priority": 3, "passes": false, "beadId": "proj-ghi3" }
    }
  }
}
```

**Note:** `ralph.stories` is an **object keyed by story ID** (not an array). This enables direct lookup: `.ralph.stories[$id].passes = true`.

## Lock Behavior

The `ralph.active` flag provides an exclusive lock:

- Prevents concurrent `ci`/`co` execution during autonomous mode
- Prevents multiple `ca` invocations
- Lock is released on completion or error

**Recovery:** If Ralph crashes, manually set `ralph.active = false` in metadata.json.

## Error Handling

| Error | Action |
|-------|--------|
| Story fails verification | Continue to next story, mark as failed |
| Max iterations reached | Exit gracefully, update state |
| Script crash | Lock remains - manual recovery needed |

## Related

- [implement.md](implement.md) - Standard implementation workflow
- [../../beads/integration.md](../beads/integration.md) - Beads integration points
- [../../../orchestrator/SKILL.md](../../../orchestrator/SKILL.md) - Parallel execution

```

### references/workflow.md

```markdown
# Orchestrator Workflow

8-phase orchestrator protocol for multi-agent parallel execution.

## Phase 0: Preflight (Session Brain)

Before mode selection, run session coordination preflight.

**Trigger conditions:**
- `/conductor-implement`
- `/conductor-orchestrate`

**Skip conditions:**
- `ds` (design sessions always fresh)
- `bd ready`, `bd show`, `bd list` (query commands)

### 4-Step Protocol

1. **IDENTITY**: Generate session ID, register with Agent Mail CLI
2. **DETECT**: `fetch-inbox` CLI for messages from last 30 min, parse [SESSION START], [HEARTBEAT], [SESSION END]
3. **DISPLAY**: Show active sessions, warn on conflicts (track/files/beads)
4. **PROCEED**: No conflicts → continue; Conflicts → prompt user; Stale → takeover prompt

### Timeout Behavior

Agent Mail timeout: 3 seconds
On timeout: Warn and proceed without coordination

### Message Subjects

- `[SESSION START] {display_name}` - Sent on preflight completion
- `[HEARTBEAT] Track {track}` - Sent every 5 min during work
- `[SESSION END] {display_name}` - Sent on session completion

### Conflict Types

| Type | Detection | User Options |
|------|-----------|--------------|
| Track | Same track as active session | [P]roceed / [S]witch / [W]ait |
| File | Overlapping file reservations | [P]roceed / [W]ait |
| Bead | Same bead claimed | Shows "claimed by X" |

### Stale Session Handling

Threshold: 10 minutes since last activity
Options: [T]ake over / [W]ait / [I]gnore

See [preflight.md](preflight.md) for details.

## Mode Selection (Pre-Phase)

Before starting phases, determine coordination mode:

```bash
# Auto-select mode based on conditions
# Check Agent Mail CLI availability
toolboxes/agent-mail/agent-mail.js health-check
if [ $? -ne 0 ]; then
    MODE="LIGHT"  # Fallback - no Agent Mail CLI
elif [ -n "$CROSS_DEPS" ]; then
    MODE="FULL"   # Need coordination for cross-track deps
else
    MODE="FULL"   # Default for complex work
fi
```

| Mode | Phases Used | Agent Mail | Heartbeats |
|------|-------------|------------|------------|
| **LIGHT** | 1, 4, 7 (skip 2, 3, 5, 6) | No | No |
| **FULL** | All 7 phases | Yes | Yes (>10 min) |

## Phase Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  Phase 0: Preflight         - Session identity, detect active sessions     │
│  Phase 1: Read Plan         - Parse Track Assignments                      │
│  Phase 2: Validate          - Health check Agent Mail (FULL only)          │
│  Phase 3: Initialize        - Register orchestrator, create epic (FULL)    │
│  Phase 4: Spawn Workers     - Task() for each track (parallel)             │
│  Phase 5: Monitor + Verify  - Poll inbox, verify summaries (FULL only)     │
│  Phase 6: Handle Issues     - Resolve blockers, file conflicts (FULL only) │
│  Phase 7: Complete          - Verify, send summary, close epic, rb review  │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Phase 1: Read Plan (or Accept Auto-Generated)

**Option A: From plan.md (manual orchestration)**

```python
# Read from conductor track
plan = Read("conductor/tracks/<track-id>/plan.md")
metadata = Read("conductor/tracks/<track-id>/metadata.json")

# Extract from Track Assignments section:
EPIC_ID = metadata.beads.epicId
TRACKS = parse_track_assignments(plan)
# Result:
# [
#   { track: 1, agent: "BlueLake", tasks: ["1.1.1", "1.1.2"], scope: "skills/orchestrator/**", depends_on: [] },
#   { track: 2, agent: "GreenCastle", tasks: ["2.1.1", "2.2.1"], scope: "skills/design/**", depends_on: ["1.2.3"] },
# ]

CROSS_DEPS = metadata.beads.crossTrackDeps
# [{ from: "1.2.3", to: "2.1.1" }]
```

**Option B: From auto-orchestration (fb Phase 6)**

```python
# Assignments passed directly from fb
TRACKS = auto_generated_tracks  # Already in correct format
EPIC_ID = auto_generated_epic_id
CROSS_DEPS = auto_generated_cross_deps
```

Both options produce the same TRACKS structure for Phase 4.

**Option C: From Planning Pipeline (pl mode)**

When orchestration is triggered from the planning pipeline (`pl` command), spike learnings from design.md Section 5 are extracted and injected into worker prompts:

```python
# Extract spike learnings from design.md
design_md = Read("conductor/tracks/<track-id>/design.md")
spike_learnings = parse_section_5(design_md)
# Result:
# {
#   "overall": ["Learning 1", "Learning 2"],
#   "by_scope": {
#     "skills/orchestrator/**": ["Orchestrator-specific learning"],
#     "skills/conductor/**": ["Conductor-specific learning"]
#   }
# }

# Map learnings to tracks by file scope
for track in TRACKS:
    track.spike_learnings = spike_learnings.get("overall", [])
    scope_learnings = spike_learnings.get("by_scope", {}).get(track.scope, [])
    track.spike_learnings.extend(scope_learnings)
```

**Spike Learning Injection:**

The planning pipeline extracts learnings from design.md Section 5 and:
1. Parses overall learnings (apply to all tracks)
2. Matches scope-specific learnings to tracks by file scope patterns
3. Injects combined learnings into `{SPIKE_LEARNINGS}` placeholder in worker prompts

This ensures workers start with context from spike/discovery phases.

### Parsing design.md Section 5 (Spike Results)

Extract spike learnings with structured format:

```python
def parse_spike_results(design_md: str) -> list[dict]:
    """Parse Section 5: Spike Results from design.md"""
    spikes = []
    section_5 = extract_section(design_md, "## 5. Spike Results")
    
    for spike_block in section_5.split("### Spike:"):
        if not spike_block.strip():
            continue
        spike = {
            "spike_id": extract_field(spike_block, "id") or generate_id(),
            "question": spike_block.split("\n")[0].strip(),
            "result": extract_field(spike_block, "Result"),  # YES/NO
            "learnings": extract_list(spike_block, "Learnings"),
            "code_path": extract_field(spike_block, "Code reference")
        }
        spikes.append(spike)
    return spikes

# Example output:
# [
#   {
#     "spike_id": "spike-001",
#     "question": "Can Stripe SDK work with Node 18?",
#     "result": "YES",
#     "learnings": ["Use [email protected] for Node 18", "Webhook verification needs raw body"],
#     "code_path": "conductor/spikes/billing/spike-001/"
#   }
# ]
```

### Mapping Spikes to Beads by File Scope

Match spike code paths to bead file scopes from metadata.json:

```python
def map_spikes_to_beads(spikes: list, metadata: dict) -> dict[str, list]:
    """Map spike learnings to beads by file scope matching"""
    bead_learnings = {}
    
    for bead_id, bead_info in metadata["beads"]["planTasks"].items():
        file_scope = bead_info.get("fileScope", "")
        matching_learnings = []
        
        for spike in spikes:
            code_path = spike.get("code_path", "")
            # Match by package/domain patterns
            # e.g., spike in conductor/spikes/billing/ → beads with packages/api/**
            if scope_matches(code_path, file_scope):
                matching_learnings.extend(spike["learnings"])
        
        if matching_learnings:
            bead_learnings[bead_id] = matching_learnings
    
    return bead_learnings

def scope_matches(spike_path: str, bead_scope: str) -> bool:
    """Heuristic matching between spike path and bead file scope"""
    # Extract domain from spike path: conductor/spikes/<track>/<domain>/
    spike_domain = spike_path.split("/")[2] if len(spike_path.split("/")) > 2 else ""
    
    # Match against bead scope patterns
    return (
        spike_domain in bead_scope or
        fnmatch(spike_path, f"*{bead_scope.replace('**', '*')}*")
    )
```

### Injecting into Worker Prompt

Add spike learnings to worker prompt template under dedicated section:

```python
def inject_spike_learnings(worker_prompt: str, bead_id: str, bead_learnings: dict) -> str:
    """Inject spike learnings into worker prompt {SPIKE_LEARNINGS} placeholder"""
    learnings = bead_learnings.get(bead_id, [])
    
    if not learnings:
        section = "No spike learnings applicable to this bead."
    else:
        section = format_learnings_section(learnings, spikes)
    
    return worker_prompt.replace("{SPIKE_LEARNINGS}", section)

def format_learnings_section(learnings: list, spikes: list) -> str:
    """Format spike learnings for worker prompt"""
    lines = ["## Spike Learnings", ""]
    
    for spike in spikes:
        if any(l in learnings for l in spike["learnings"]):
            lines.append(f"### Spike: {spike['question']}")
            lines.append(f"**Result**: {spike['result']}")
            lines.append(f"**Code reference**: `{spike['code_path']}`")
            lines.append("")
            lines.append("#### Key Learnings")
            for learning in spike["learnings"]:
                if learning in learnings:
                    lines.append(f"- {learning}")
            lines.append("")
    
    return "\n".join(lines)
```

**Rendered output in worker prompt:**

```markdown
## Spike Learnings

### Spike: Can Stripe SDK work with Node 18?
**Result**: YES
**Code reference**: `conductor/spikes/billing/spike-001/`

#### Key Learnings
- Use [email protected] for Node 18
- Webhook verification needs raw body
```

### Fallback Chain for Missing Spike Code

When spike code reference is missing or inaccessible:

| Priority | Source | Action |
|----------|--------|--------|
| Primary | Embedded in bead description | Use directly from metadata.beads.planTasks[bead_id].spikeContext |
| Secondary | design.md Section 5 | Parse and extract learnings |
| Tertiary | Oracle reconstruct | `oracle(task="reconstruct spike learnings", context=spike_path)` |

```python
def get_spike_learnings(bead_id: str, metadata: dict, design_md: str) -> list:
    """Get spike learnings with fallback chain"""
    # Primary: Embedded in bead
    bead_info = metadata["beads"]["planTasks"].get(bead_id, {})
    if spike_context := bead_info.get("spikeContext"):
        return spike_context
    
    # Secondary: design.md Section 5
    spikes = parse_spike_results(design_md)
    bead_learnings = map_spikes_to_beads(spikes, metadata)
    if learnings := bead_learnings.get(bead_id):
        return learnings
    
    # Tertiary: Oracle reconstruct from spike code
    spike_path = bead_info.get("relatedSpikePath")
    if spike_path and path_exists(spike_path):
        return oracle_reconstruct_learnings(spike_path)
    
    return []  # No learnings available
```

### Parsing Track Assignments Table

| Track | Agent | Tasks | File Scope | Depends On |
|-------|-------|-------|------------|------------|
| 1 | BlueLake | 1.1.*, 1.2.* | skills/orchestrator/** | - |
| 2 | GreenCastle | 2.1.*, 2.2.* | skills/design/** | 1.2.3 |

Map tasks to bead IDs using `metadata.json.beads.planTasks`.

## Phase 2: Validate Agent Mail (NEW)

**Before spawning workers, verify Agent Mail CLI is functional:**

```bash
# Health check - HALT if unavailable
toolboxes/agent-mail/agent-mail.js health-check --reason "Pre-spawn orchestrator validation"
if [ $? -ne 0 ]; then
    echo "⚠️ Agent Mail CLI unavailable - falling back to sequential"
    # Route to /conductor-implement
    exit 1
fi
```

**Why this matters:** Your demo showed workers executing without Agent Mail registration. This gate prevents that scenario.

### Validation Checklist

| Check | Action on Fail |
|-------|----------------|
| `health-check` succeeds | Fall back to sequential |
| `macro-start-session` succeeds | Fall back to sequential |

## Phase 3: Initialize Agent Mail

Use `macro-start-session` CLI to combine project setup, agent registration, and file reservations in a single call:

```bash
# Initialize orchestrator with single macro call
toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key <absolute-project-path> \
  --program amp \
  --model <model> \
  --task-description "Orchestrator for <epic-id>" \
  --file-reservation-paths '["conductor/tracks/<track-id>/**"]' \
  --inbox-limit 10
```

```python
# Parse JSON output
import json
session = json.loads(output)

# Extract session info
ORCHESTRATOR_NAME = session["agent"]["name"]
PROJECT_KEY = session["project"]["human_key"]

# Check for any conflicts from recent inbox
for msg in session.get("inbox", []):
    if "[SESSION START]" in msg.get("subject", ""):
        print(f"⚠️ Active session detected: {msg['subject']}")
```

```bash
# Create epic thread - send to self (orchestrator)
# Workers join thread via macro-start-session when spawned
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key ${PROJECT_KEY} \
  --sender-name ${ORCHESTRATOR_NAME} \
  --to '["${ORCHESTRATOR_NAME}"]' \
  --thread-id <epic-id> \
  --subject "EPIC STARTED: <title>" \
  --body-md "Spawning workers for parallel execution.

## Track Assignments
| Track | Agent | Scope |
|-------|-------|-------|
| 1 | BlueLake | skills/orchestrator/** |
| 2 | GreenCastle | skills/design/** |

Workers: Follow 4-step protocol in worker-prompt.md"
```

## Phase 4: Spawn Worker Subagents

### Mode-Specific Behavior

| Aspect | LIGHT Mode | FULL Mode |
|--------|------------|-----------|
| Worker prompt | Light template (no Agent Mail) | Full 4-step template |
| Worker registration | Skip | Self-register via `macro-start-session` CLI |
| File reservations | Skip (rely on scope isolation) | Via macro-start-session |
| Result collection | Task() return values | Agent Mail messages |
| TDD | Yes (default) | Yes (default) |

**Note:** Workers self-register when they start. The orchestrator does NOT pre-register workers—each worker calls `macro-start-session` CLI as their first step, which handles registration automatically.

**TDD enforcement:** Workers follow RED → GREEN → REFACTOR cycle by default. Pass `--no-tdd` to disable.

> **Cross-skill reference:** Load the [conductor skill](../../conductor/SKILL.md) for detailed TDD methodology (cycle, gates, enforcement).

### Agent Routing

Before spawning, determine agent type based on task intent. See [agent-routing.md](agent-routing.md) for:
- Routing tables by category (Research, Review, Planning, Execution, Debug)
- Spawn patterns for each agent type
- File reservation patterns

### Spawn Logic (FULL Mode)

Spawn all workers in parallel using Task() tool:

```python
# Track expected workers for Phase 5 verification
expected_workers = []

for track in TRACKS:
    agent_type = route_intent(track.description)
    spawn_pattern = get_spawn_pattern(agent_type)
    
    expected_workers.append(track.agent)
    
    Task(
      description=f"Worker {track.agent}: Track {track.track}",
      prompt=spawn_pattern.format(
        AGENT_NAME=track.agent,
        TRACK_N=track.track,
        EPIC_ID=epic_id,
        TASK_LIST=", ".join(track.tasks),
        BEAD_LIST=", ".join([planTasks[t] for t in track.tasks]),
        FILE_SCOPE=track.scope,
        ORCHESTRATOR=ORCHESTRATOR_NAME,  # From Phase 3
        PROJECT_PATH=project_path,
        DEPENDS_ON=track.depends_on,
        MODEL=model,
        MODE="FULL"  # Workers know to use Agent Mail
      )
    )
```

### Spawn Logic (LIGHT Mode)

Simplified spawn without Agent Mail:

```python
# Collect results directly from Task() returns
worker_results = []

for track in TRACKS:
    result = Task(
      description=f"Worker {track.agent}: Track {track.track}",
      prompt=f"""
You are {track.agent}, a worker for Track {track.track}.

## Assignment
- **Beads**: {track.beads}
- **File Scope**: {track.scope}

## Protocol (LIGHT MODE - No Agent Mail)

1. **Execute beads:**
   ```bash
   bd update <bead-id> --status in_progress
   # ... do work ...
   bd close <bead-id> --reason completed
   ```

2. **Return structured result:**
   ```python
   return {{
       "status": "SUCCEEDED",
       "files_changed": [...],
       "key_decisions": [...],
       "issues": [],
       "beads_closed": [...]
   }}
   ```

NO Agent Mail registration, messaging, or heartbeats required.
"""
    )
    worker_results.append(result)

# Skip to Phase 7 with collected results
```

See [worker-prompt.md](worker-prompt.md) for the 4-step worker protocol (FULL mode).

### Parallel vs Sequential

- **Independent tracks**: Spawn all workers simultaneously
- **Dependent tracks**: Worker prompt includes dependency to wait for

Workers check inbox for dependency completion before starting blocked beads.

## Phase 5: Monitor Progress + Verify Summaries (ENHANCED)

Poll for updates while workers execute, **verify all workers sent summaries**, and re-dispatch when new beads become ready:

```python
wave = 1
active_workers = initial_workers  # From Phase 4
workers_with_summaries = set()

while active_workers or has_ready_beads(EPIC_ID):
    # Wait for current wave to complete
    wait_for_workers(active_workers)
    
    # ──────────────────────────────────────────────────────────
    # NEW: Verify workers sent summaries via Agent Mail CLI
    # ──────────────────────────────────────────────────────────
    # Fetch inbox using CLI
    inbox_json=$(toolboxes/agent-mail/agent-mail.js fetch-inbox \
        --project-key <path> \
        --agent-name ${ORCHESTRATOR_NAME} \
        --include-bodies true \
        --limit 50)
    ```
    
    ```python
    # Parse inbox JSON
    import json
    inbox = json.loads(inbox_json)
    
    for msg in inbox:
        if "[TRACK COMPLETE]" in msg.get("subject", ""):
            # Extract agent name from message
            agent = msg.get("sender_name")
            workers_with_summaries.add(agent)
            print(f"✓ Received summary from {agent}")
    
    # Check for missing summaries
    missing = set(expected_workers) - workers_with_summaries
    if missing and not active_workers:
        print(f"⚠️ Missing summaries from: {', '.join(missing)}")
        # Log but don't block - workers may have used fallback mode
    ```
    
    ```bash
    # Check for blockers
    blockers_json=$(toolboxes/agent-mail/agent-mail.js fetch-inbox \
        --project-key <path> \
        --agent-name ${ORCHESTRATOR_NAME} \
        --urgent-only true)
    
    for blocker in blockers:
        handle_blocker(blocker)
    
    # Query for newly-ready beads (unblocked by completed work)
    ready_beads = bash(f"bd ready --json | jq '[.[] | select(.epic == \"{EPIC_ID}\")]'")
    
    if ready_beads:
        wave += 1
        print(f"Wave {wave}: {len(ready_beads)} beads now ready")
        
        # Generate new track assignments for this wave
        new_tracks = generate_track_assignments(ready_beads)
        expected_workers.extend([t.agent for t in new_tracks])
        
        # Spawn new workers
        active_workers = spawn_workers(new_tracks)
        
        # Update metadata
        update_wave_state(wave, ready_beads)
    else:
        active_workers = []  # No more work
```

### Wave Execution Display

```text
┌─ WAVE EXECUTION ───────────────────────┐
│ Wave 1: 3 beads (bd-2, bd-3, bd-4)     │
│   → Spawned 3 workers                  │
│   → All completed ✓                    │
│   → Summaries: 3/3 ✓                   │
├────────────────────────────────────────┤
│ Wave 2: 2 beads (bd-5, bd-6)           │
│   → Spawned 2 workers                  │
│   → All completed ✓                    │
│   → Summaries: 2/2 ✓                   │
├────────────────────────────────────────┤
│ All waves complete                     │
│ Total summaries: 5/5 ✓                 │
└────────────────────────────────────────┘
```

### Summary Verification Report (NEW)

After all workers complete:

```text
┌─ SUMMARY VERIFICATION ─────────────────┐
│ Expected: 5 workers                    │
│ Received: 5 summaries                  │
├────────────────────────────────────────┤
│ ✓ BlueLake     - SUCCEEDED             │
│ ✓ GreenCastle  - SUCCEEDED             │
│ ✓ RedStone     - SUCCEEDED             │
│ ✓ PurpleMoon   - PARTIAL (1 blocker)   │
│ ✓ OrangeStar   - SUCCEEDED             │
├────────────────────────────────────────┤
│ Status: All workers reported           │
└────────────────────────────────────────┘
```

### Why Wave Re-dispatch Matters

Without re-dispatch:
- Wave 1 workers complete → beads 2.1, 3.1 become unblocked
- Main agent falls back to sequential execution ❌

With re-dispatch:
- Wave 1 workers complete → check `bd ready --json`
- Newly-ready beads found → spawn Wave 2 workers ✓
- Continues until no more ready beads

### Progress Indicators

```text
📊 Epic Progress: 12/26 beads complete
├── Track 1 (BlueLake): 6/6 ✓
├── Track 2 (GreenCastle): 4/5 [~]
└── Track 3 (RedStone): 2/15 [~]
```

## Phase 6: Handle Cross-Track Issues

### Blocker Resolution

When worker reports blocker:

```bash
# 1. Read blocker message (urgent only)
blocker_json=$(toolboxes/agent-mail/agent-mail.js fetch-inbox \
  --project-key <path> \
  --agent-name ${ORCHESTRATOR_NAME} \
  --urgent-only true \
  --limit 1)

# 2. Assess and respond
toolboxes/agent-mail/agent-mail.js reply-message \
  --project-key <path> \
  --message-id ${blocker_id} \
  --sender-name ${ORCHESTRATOR_NAME} \
  --body-md "Resolution: ..."
```

### File Conflict Resolution

When two workers need same file:

```bash
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key <path> \
  --sender-name ${ORCHESTRATOR_NAME} \
  --to '["<Holder>"]' \
  --thread-id <epic-id> \
  --subject "File conflict resolution" \
  --body-md "<Requester> needs <files>. Can you release?"
```

### Cross-Track Dependency Notification

When Track 1 completes task needed by Track 2:

```bash
# Worker 1 sends (handled by worker protocol):
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key <path> \
  --sender-name ${WORKER_NAME} \
  --to '["<Worker2>"]' \
  --thread-id <epic-id> \
  --subject "[DEP] 1.2.3 COMPLETE - Track 2 unblocked" \
  --body-md "Task 1.2.3 complete. Track 2 can proceed with 2.1.1."
```

## Phase 7: Epic Completion

### Verify All Child Beads Closed

Before closing epic, verify no lingering beads:

```python
# Check for open child beads
open_beads = bash(f"bd list --parent={epic_id} --status=open --json | jq 'length'")

if int(open_beads) > 0:
    # List lingering beads
    lingering = bash(f"bd list --parent={epic_id} --status=open --json")
    print(f"⚠️ Lingering beads found: {open_beads}")
    print(lingering)
    
    # Prompt user
    choice = prompt("[C]lose all / [S]kip / [A]bort?")
    if choice == 'C':
        bash(f"bd close $(bd list --parent={epic_id} --status=open --json | jq -r '.[].id') --reason completed")
    elif choice == 'A':
        raise Exception("Aborted: lingering beads")
    # Skip continues to close epic
```

### Verify All Complete

```python
# Check via bd CLI
open_beads = bash("bd list --status=open --parent=<epic-id> --json | jq 'length'")
assert open_beads == "0"

# NEW: Verify summary coverage via Agent Mail
missing_summaries = set(expected_workers) - workers_with_summaries
if missing_summaries:
    print(f"⚠️ Workers without summaries: {missing_summaries}")
```

### Send Epic Complete Summary

```bash
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key <path> \
  --sender-name ${ORCHESTRATOR_NAME} \
  --to '["Worker1", "Worker2", "Worker3"]' \
  --thread-id ${epic_id} \
  --subject "EPIC COMPLETE: <title>" \
  --body-md "## Summary

- **Duration**: X hours
- **Tracks**: 3 complete
- **Beads**: 26 closed
- **Summaries received**: 3/3 ✓

### Per-Track Summary

#### Track 1 (BlueLake)
- Created skills/orchestrator/ directory structure
- Created SKILL.md, workflow.md, worker-prompt.md

#### Track 2 (GreenCastle)
- Updated conductor routing
- Added /conductor-orchestrate routing

#### Track 3 (RedStone)
- Updated CODEMAPS
- Updated AGENTS.md

### Files Changed
- skills/orchestrator/SKILL.md
- skills/orchestrator/references/*.md
- skills/conductor/SKILL.md
- ..."
```

### Close Epic

```python
bash("bd close <epic-id> --reason 'All tracks complete'")
```

### Spawn rb Sub-Agent for Final Review

```python
Task(
  description="Final review: rb for epic <epic-id>",
  prompt="""
Run rb to review all completed beads for epic <epic-id>.

## Your Task
1. Verify all beads are properly closed
2. Check for any orphaned work or missing implementations
3. Validate acceptance criteria from spec.md
4. Report any issues or concerns

## Expected Output
Summary of review findings and overall quality assessment.
"""
)
```

### Review Completion

After rb finishes:
1. Collect review findings
2. Present completion summary to user
3. Suggest next steps (e.g., `/conductor-finish`)

```
┌─────────────────────────────────────────┐
│ ✓ Auto-Orchestration Complete           │
│                                         │
│ Workers: 3 spawned, 3 complete          │
│ Summaries: 3/3 received ✓               │
│ Beads: 26 closed                        │
│ Review: Passed                          │
│                                         │
│ → Next: /conductor-finish               │
└─────────────────────────────────────────┘
```

## Graceful Fallback

If Agent Mail CLI is unavailable at any phase:

```bash
# Check Agent Mail CLI availability
toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key ${project_path} \
  --program amp \
  --model ${model}

if [ $? -ne 0 ]; then
    echo "⚠️ Agent coordination unavailable - falling back to sequential"
    # Route to standard /conductor-implement
    exit 1
fi
```

## Timing Constraints

| Constraint | Value | Action on Breach |
|------------|-------|------------------|
| Worker heartbeat | Every 5 min (optional for <10min tasks) | Mark worker as stale after 10 min |
| Cross-dep timeout | 30 min | Escalate to orchestrator |
| Monitor interval | 30 sec | Poll inbox and beads |
| Summary timeout | 2 min after Task completes | Log warning, continue |
| Total epic timeout | None | Manual intervention |

## State Tracking

Orchestrator maintains state in `implement_state.json`:

```json
{
  "execution_mode": "PARALLEL_DISPATCH",
  "orchestrator_name": "PurpleMountain",
  "expected_workers": ["BlueLake", "GreenCastle", "RedStone"],
  "workers_with_summaries": ["BlueLake", "GreenCastle"],
  "workers": {
    "BlueLake": { "track": 1, "status": "complete", "beads_closed": 6, "summary_received": true },
    "GreenCastle": { "track": 2, "status": "complete", "beads_closed": 5, "summary_received": true },
    "RedStone": { "track": 3, "status": "in_progress", "current_bead": "my-workflow:3-3cmw.14", "summary_received": false }
  },
  "waves": [
    { "wave": 1, "beads": ["bd-2", "bd-3", "bd-4"], "status": "complete" },
    { "wave": 2, "beads": ["bd-5", "bd-6"], "status": "complete" }
  ],
  "started_at": "2025-12-30T01:30:00Z",
  "last_poll": "2025-12-30T02:15:00Z"
}
```

## References

- [agent-routing.md](agent-routing.md) - Agent routing tables, spawn patterns, file reservations
- [worker-prompt.md](worker-prompt.md) - 4-step worker protocol with mandatory summary
- [summary-protocol.md](summary-protocol.md) - Required summary format for all agents
- [intent-routing.md](intent-routing.md) - Intent → agent type mappings
- [Agent Directory](../agents/README.md) - Available agent types and profiles

```

### references/worker-prompt.md

```markdown
# Worker Prompt Template

Template for spawning autonomous workers via Task() tool.

## Simplified 4-Step Protocol

Workers follow exactly 4 mandatory steps. No exceptions.

```
┌─────────────────────────────────────────────────────────────┐
│  STEP 1: REGISTER (FIRST - before ANY other action)        │
│  STEP 2: EXECUTE  (claim beads, do work, close beads)      │
│  STEP 3: REPORT   (send summary via Agent Mail)            │
│  STEP 4: CLEANUP  (release file reservations)              │
└─────────────────────────────────────────────────────────────┘
```

## Template

```markdown
You are {AGENT_NAME}, an autonomous worker agent for Track {TRACK_N}.

## Assignment

- **Epic**: {EPIC_ID}
- **Track**: {TRACK_N}
- **Tasks**: {TASK_LIST}
- **Beads**: {BEAD_LIST}
- **File Scope**: {FILE_SCOPE}
- **Depends On**: {DEPENDS_ON}
- **Orchestrator**: {ORCHESTRATOR}
- **Project Path**: {PROJECT_PATH}

## Tool Preferences (from AGENTS.md)

{TOOL_PREFERENCES}

## Spike Learnings (from design.md)

{SPIKE_LEARNINGS}

## ⚠️ CRITICAL: 4-Step Protocol (MANDATORY)

You MUST follow these 4 steps in exact order. Skipping any step is a protocol violation.

---

### STEP 1: INITIALIZE SESSION (FIRST ACTION - NO EXCEPTIONS)

Before ANY other action, initialize your session with Agent Mail using the CLI toolbox:

```bash
# This MUST be your FIRST action - before reading files, before claiming beads
# macro-start-session handles SELF-REGISTRATION (creates/updates agent profile)
bun toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key {PROJECT_PATH} \
  --program amp \
  --model {MODEL} \
  --agent-name {AGENT_NAME} \
  --file-reservation-paths '["{FILE_SCOPE}"]' \
  --file-reservation-ttl-seconds 3600 \
  --task-description "Worker for Track {TRACK_N}: {TRACK_DESCRIPTION}" \
  --inbox-limit 10

# If session init fails (non-zero exit), HALT immediately
# The command outputs JSON with session info and inbox
```

```python
# Parse the JSON output
import json
result = json.loads(output)

if not result.get("success"):
    return {"status": "FAILED", "reason": "Agent Mail session init failed"}

# DISCOVER EPIC THREAD: Use inbox (returned in result) to find epic thread
# The orchestrator sends an initial message to the epic thread that workers can locate
inbox = result.get("inbox", [])
epic_thread = None
for msg in inbox:
    if "{EPIC_ID}" in msg.get("thread_id", "") or "[EPIC]" in msg.get("subject", ""):
        epic_thread = msg.get("thread_id")
        break

# Alternative: Use fetch-inbox directly if you need more messages
# bun toolboxes/agent-mail/agent-mail.js fetch-inbox --project-key {PROJECT_PATH} --agent-name {AGENT_NAME} --limit 20
```

**Why this matters:** 
- `macro-start-session` CLI handles self-registration (creates/updates agent profile)
- Workers use the inbox (returned in `result.inbox`) to discover the epic thread
- The orchestrator sends initial messages to the epic thread that workers can locate
- Without this, you cannot send messages or see dependency notifications

---

### STEP 2: EXECUTE (Per-Bead Loop)

{IF DEPENDS_ON}
**Check dependencies first:**
```python
# Look for dependency completion in inbox (loaded by macro_start_session)
for msg in result.inbox:
    if "[DEP]" in msg.subject and "{DEPENDS_ON}" in msg.subject:
        break  # Dependency satisfied
else:
    # Wait - poll every 30 seconds
    pass
```
{/IF}

For EACH bead in [{BEAD_LIST}]:

#### 2.1 START
```bash
# Read track thread via CLI for prior bead context
# This provides learnings, gotchas, and context from previous beads
bun toolboxes/agent-mail/agent-mail.js summarize-thread \
  --project-key "{PROJECT_PATH}" \
  --thread-id "{TRACK_THREAD}"
```

```python
# Parse JSON output and review prior context before starting work
thread_summary = json.loads(output)
if thread_summary.get("key_points"):
    print(f"📋 Prior context: {len(thread_summary['key_points'])} learnings from previous beads")

# Reserve files for this bead (if not already reserved)
# Claim bead
bash(f"bd update {bead_id} --status in_progress")
```

#### 2.2 WORK (TDD by default)

Follow TDD cycle for each implementation task (skip with `--no-tdd` flag passed to worker).

> **Cross-skill reference:** Load the [conductor](../../conductor/SKILL.md) skill for full TDD methodology.

**TDD Cycle Summary:**
1. **RED**: Write a failing test that defines expected behavior
2. **GREEN**: Write minimal code to make the test pass
3. **REFACTOR**: Clean up code while keeping tests green

**Phase updates (track in bead notes):**

| Phase | Bead Note | Action |
|-------|-----------|--------|
| RED | `IN_PROGRESS: RED phase - writing failing test` | Write test, verify fails |
| GREEN | `IN_PROGRESS: GREEN phase - making test pass` | Minimal code to pass |
| REFACTOR | `IN_PROGRESS: REFACTOR phase - cleaning up` | Clean code, stay green |

```python
# Example: Update bead notes at each phase
bash(f"bd update {bead_id} --notes 'IN_PROGRESS: RED phase - writing failing test'")
```

**During execution:**
- Check inbox periodically for blockers
- Track files you change and decisions you make

#### 2.3 COMPLETE
```python
# Close bead
bash(f"bd close {bead_id} --reason completed")

# Save structured context to track thread (self-message)
# This context is read by subsequent beads via summarize_thread()
bun toolboxes/agent-mail/agent-mail.js send-message \
  --project-key {PROJECT_PATH} \
  --sender-name {AGENT_NAME} \
  --to '["{AGENT_NAME}"]' \
  --thread-id {TRACK_THREAD} \
  --subject "[CONTEXT] Bead {bead_id} complete" \
  --body-md "## Learnings
- What worked well: [specific technique or approach]
- Pattern discovered: [reusable pattern for future beads]
- Tool/API insight: [useful knowledge about tools used]

## Gotchas
- Edge case: [specific edge case and how it was handled]
- Pitfall avoided: [what to watch out for]
- Assumption corrected: [any wrong assumptions and corrections]

## Next Notes
- Setup needed: [any setup required for next bead]
- Files to reference: [key files for context]
- Open questions: [unresolved items for future beads]"
```

#### 2.4 NEXT
- Release files if not needed for next bead
- Loop to next bead in track

**Rules during execution:**
- ✅ You CAN use `bd update` and `bd close` directly
- ✅ You CAN read/write files in your reserved scope
- ❌ Do NOT touch files outside your scope
- ❌ Do NOT release reservations until Step 4

---

### STEP 3: REPORT (Send Summary via Agent Mail)

**MANDATORY:** You MUST send a message via CLI before returning. This is non-negotiable.

```bash
# CRITICAL: This call is REQUIRED before returning
bun toolboxes/agent-mail/agent-mail.js send-message \
  --project-key {PROJECT_PATH} \
  --sender-name {AGENT_NAME} \
  --to '["{ORCHESTRATOR}"]' \
  --thread-id {EPIC_ID} \
  --subject "[TRACK COMPLETE] Track {TRACK_N}" \
  --body-md "## Status
SUCCEEDED

## Files Changed
- path/to/file1.ts (added)
- path/to/file2.ts (modified)

## Key Decisions
- Decision 1: rationale
- Decision 2: rationale

## Issues (if any)
None

---

## Track Details
- **Agent**: {AGENT_NAME}
- **Beads closed**: X
- **Duration**: Xm"
```

**Status values:**
- `SUCCEEDED` - All beads completed
- `PARTIAL` - Some beads completed, blockers remain
- `FAILED` - Could not complete, error encountered

---

### STEP 4: CLEANUP (Release Reservations)

```bash
# Release all file reservations
bun toolboxes/agent-mail/agent-mail.js release-file-reservations \
  --project-key {PROJECT_PATH} \
  --agent-name {AGENT_NAME}
```

```python
# Return structured summary (matches Agent Mail message)
return {
    "status": "SUCCEEDED",
    "files_changed": files_changed,
    "key_decisions": key_decisions,
    "issues": [],
    "beads_closed": [{BEAD_LIST}]
}
```

---

## Blocker Handling

If you encounter a blocker during Step 2:

```bash
bun toolboxes/agent-mail/agent-mail.js send-message \
  --project-key {PROJECT_PATH} \
  --sender-name {AGENT_NAME} \
  --to '["{ORCHESTRATOR}"]' \
  --thread-id {EPIC_ID} \
  --subject "[BLOCKER] Track {TRACK_N}: {BLOCKER_SUMMARY}" \
  --body-md "Details of the blocker..." \
  --importance urgent

# Mark bead as blocked
bd close {bead_id} --reason blocked
```

Then continue to Step 3 (report) with status `PARTIAL` or `FAILED`.

---

## Agent Mail CLI Required (No Fallback)

If Agent Mail CLI is unavailable (macro-start-session fails):

```bash
# ❌ Agent Mail CLI unavailable - HALT immediately
echo "❌ HALT: Cannot initialize session - Agent Mail unavailable"
echo "   Worker cannot proceed without:"
echo "   - File reservations (risk of conflicts)"
echo "   - Message capability (cannot report progress/blockers)"
exit 1
# Return: {"status": "HALTED", "reason": "Agent Mail unavailable"}
```

**Do NOT fall back to local execution.** Parallel workers without Agent Mail coordination will cause file conflicts and cannot report status.

---

## Quick Reference

| Step | Action | Tool | Required |
|------|--------|------|----------|
| 1 | Register | `bun toolboxes/agent-mail/agent-mail.js macro-start-session` | ✅ FIRST |
| 2 | Execute | `bd update`, `bd close` | ✅ |
| 3 | Report | `bun toolboxes/agent-mail/agent-mail.js send-message` | ✅ LAST |
| 4 | Cleanup | `bun toolboxes/agent-mail/agent-mail.js release-file-reservations` | ✅ |

## What NOT To Do

- ❌ Start working before calling `macro-start-session`
- ❌ Return without calling `send-message`
- ❌ Release reservations before completing all beads
- ❌ Touch files outside your `{FILE_SCOPE}`
- ❌ Ignore blockers - report them immediately

## Heartbeats (Optional)

For long-running tasks (>10 minutes), send periodic heartbeats:

```bash
bun toolboxes/agent-mail/agent-mail.js send-message \
  --project-key {PROJECT_PATH} \
  --sender-name {AGENT_NAME} \
  --to '["{ORCHESTRATOR}"]' \
  --thread-id {EPIC_ID} \
  --subject "[HEARTBEAT] Track {TRACK_N}" \
  --body-md "Working on bead {current_bead}..."
```

**Skip heartbeats for tasks <10 minutes** - the overhead isn't worth it.
```

## Variable Reference

| Variable | Description |
|----------|-------------|
| `{AGENT_NAME}` | Worker name (e.g., "BlueLake") |
| `{TRACK_N}` | Track number (1, 2, 3...) |
| `{EPIC_ID}` | Epic bead ID |
| `{TASK_LIST}` | Task IDs from plan (e.g., "1.1.1, 1.1.2") |
| `{BEAD_LIST}` | Mapped bead IDs |
| `{FILE_SCOPE}` | Glob pattern for files |
| `{DEPENDS_ON}` | Blocking task IDs |
| `{ORCHESTRATOR}` | Orchestrator agent name |
| `{PROJECT_PATH}` | Absolute workspace path |
| `{MODEL}` | Model name |
| `{TRACK_DESCRIPTION}` | Brief track description |
| `{TRACK_THREAD}` | Thread ID format: `track:{AGENT_NAME}:{EPIC_ID}` |
| `{TOOL_PREFERENCES}` | Tool preferences from project AGENTS.md |
| `{SPIKE_LEARNINGS}` | Spike learnings from design.md Section 5 (pl mode) |

## Example

```markdown
You are BlueLake, an autonomous worker agent for Track 1.

## Assignment

- **Epic**: my-workflow:3-3cmw
- **Track**: 1
- **Tasks**: 1.1.1, 1.1.2, 1.1.3
- **Beads**: my-workflow:3-3cmw.1, my-workflow:3-3cmw.2, my-workflow:3-3cmw.3
- **File Scope**: skills/orchestrator/**
- **Depends On**: (none)
- **Orchestrator**: PurpleMountain
- **Project Path**: /Users/dev/my-workflow

## ⚠️ CRITICAL: 4-Step Protocol (MANDATORY)

### STEP 1: REGISTER (FIRST ACTION - NO EXCEPTIONS)

bun toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key /Users/dev/my-workflow \
  --program amp \
  --model claude-opus-4-5@20251101 \
  --agent-name BlueLake \
  --file-reservation-paths '["skills/orchestrator/**"]' \
  --task-description "Worker for Track 1: Create orchestrator skill"

### STEP 2: EXECUTE
...

### STEP 3: REPORT
...

### STEP 4: CLEANUP
...
```

```

### references/intent-routing.md

```markdown
# Intent Routing

> **Maps user intent keywords to specialized sub-agents.**

## Quick Reference

| Intent Keywords | Agent Type | Description |
|-----------------|------------|-------------|
| `research`, `find`, `locate`, `where is` | Research | Codebase exploration |
| `review`, `check`, `audit`, `security` | Review | Code/security review |
| `plan`, `design`, `architect`, `structure` | Planning | Design decisions |
| `implement`, `build`, `create`, `add` | Execution | Code implementation |
| `fix`, `debug`, `investigate`, `trace` | Debug | Bug investigation |
| `test`, `verify`, `validate` | Testing | Test creation/verification |
| `refactor`, `improve`, `optimize` | Refactor | Code improvement |
| `document`, `explain`, `describe` | Docs | Documentation |
| `analyze`, `understand`, `how does` | Analysis | Code comprehension |
| `migrate`, `upgrade`, `convert` | Migration | Version/format updates |
| `configure`, `setup`, `install` | Config | Environment setup |
| `deploy`, `release`, `ship` | Deploy | Deployment tasks |
| `monitor`, `log`, `track` | Observability | Monitoring setup |
| `benchmark`, `performance`, `profile` | Performance | Performance analysis |
| `integrate`, `connect`, `hook` | Integration | System integration |

## Agent Categories

### Research Agents

Handle codebase exploration and understanding.

| Agent | Keywords | Responsibilities |
|-------|----------|-----------------|
| Locator | `find`, `where`, `locate` | Find files, functions, symbols |
| Analyzer | `analyze`, `understand`, `how does` | Deep code analysis |
| Pattern | `pattern`, `convention`, `example` | Find existing patterns |
| Web | `docs`, `api`, `external` | External documentation |

### Review Agents

Handle code quality and security.

| Agent | Keywords | Responsibilities |
|-------|----------|-----------------|
| CodeReview | `review`, `check` | General code review |
| SecurityAudit | `security`, `audit`, `vulnerability` | Security analysis |
| PerformanceReview | `perf`, `slow`, `optimize` | Performance review |

### Planning Agents

Handle design and architecture decisions.

| Agent | Keywords | Responsibilities |
|-------|----------|-----------------|
| Architect | `design`, `architect`, `structure` | System design |
| Planner | `plan`, `approach`, `strategy` | Implementation planning |

### Execution Agents

Handle implementation work.

| Agent | Keywords | Responsibilities |
|-------|----------|-----------------|
| Implementer | `implement`, `build`, `create` | Write new code |
| Modifier | `add`, `change`, `update` | Modify existing code |
| Fixer | `fix`, `bug`, `patch` | Bug fixes |
| Refactorer | `refactor`, `improve`, `clean` | Code improvement |

### Debug Agents

Handle investigation and debugging.

| Agent | Keywords | Responsibilities |
|-------|----------|-----------------|
| Debugger | `debug`, `investigate` | Find root cause |
| Tracer | `trace`, `follow`, `track` | Trace execution |

## Routing Logic

```python
def route_intent(user_request: str) -> AgentType:
    keywords = extract_keywords(user_request.lower())
    
    # Priority order matters - first match wins
    if any(k in keywords for k in ['security', 'audit', 'vulnerability']):
        return AgentType.SECURITY_REVIEW
    
    if any(k in keywords for k in ['review', 'check']):
        return AgentType.CODE_REVIEW
    
    if any(k in keywords for k in ['debug', 'investigate', 'trace']):
        return AgentType.DEBUG
    
    if any(k in keywords for k in ['fix', 'bug']):
        return AgentType.FIXER
    
    if any(k in keywords for k in ['test', 'verify', 'validate']):
        return AgentType.TESTING
    
    if any(k in keywords for k in ['implement', 'build', 'create', 'add']):
        return AgentType.EXECUTION
    
    if any(k in keywords for k in ['refactor', 'improve', 'optimize']):
        return AgentType.REFACTOR
    
    if any(k in keywords for k in ['plan', 'design', 'architect']):
        return AgentType.PLANNING
    
    if any(k in keywords for k in ['document', 'explain', 'describe']):
        return AgentType.DOCS
    
    if any(k in keywords for k in ['research', 'find', 'locate', 'where']):
        return AgentType.RESEARCH
    
    if any(k in keywords for k in ['analyze', 'understand', 'how does']):
        return AgentType.ANALYSIS
    
    # Default to research for ambiguous requests
    return AgentType.RESEARCH
```

## Multi-Agent Dispatch

Some requests need multiple agents:

| Request Pattern | Agents Dispatched |
|-----------------|-------------------|
| "Review and fix X" | Review → Fix (sequential) |
| "Find and document X" | Research + Docs (parallel) |
| "Implement with tests" | Execution + Testing (sequential) |
| "Debug and trace X" | Debug + Tracer (parallel) |

## Agent Spawn Template

```bash
Task(
    description=f"""You are {agent_name}, a {agent_type} specialist.

## Assignment
{task_description}

## Context
{relevant_context}

## File Scope
{file_patterns}

## Protocol
1. Reserve files before editing:
   toolboxes/agent-mail/agent-mail.js file-reservation-paths \
     project_key:"$PROJECT_PATH" \
     agent_name:"$AGENT_NAME" \
     paths:'["<scope>"]' \
     exclusive:true
2. Do the work
3. Send summary via Agent Mail CLI before returning
4. Return structured result

## CRITICAL
- Stay within file scope
- Report via `bun toolboxes/agent-mail/agent-mail.js send-message` before returning
""",
    prompt=user_request
)
```

## Error Handling

| Scenario | Handling |
|----------|----------|
| Unknown intent | Default to Research agent |
| Multiple matches | Use priority order |
| Agent fails | Main thread handles, retries or escalates |
| File conflict | Agent waits for reservation |

```

### references/agent-mail.md

```markdown
# Agent Mail Protocol

> **Note:** All examples use CLI syntax (`--arg value`). MCP function calls are available as fallback but CLI is preferred for consistency.

## Orchestrator Registration (Phase 2)

On spawn, the orchestrator MUST:
1. Register itself via `macro-start-session` CLI
2. Workers self-register via `macro-start-session` on startup

```bash
# Orchestrator initialization
toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key /path/to/project \
  --program amp \
  --model claude-opus-4-5@20251101 \
  --task-description "Orchestrator for epic ${epic_id}"

# Workers self-register on startup (no pre-registration needed)
# Each worker calls macro-start-session which handles:
# - ensure_project (idempotent)
# - register_agent (auto-generates name)
# - file_reservation_paths (optional)
# - fetch_inbox (returns prior context)
```

> **Why self-register?** Workers calling `macro-start-session` handles all setup atomically. The orchestrator only needs to register itself—workers register on spawn. Use `--auto-contact-if-blocked true` on `send-message` to auto-establish contact with newly-registered workers.

## Inbox Fetch Pattern

Check inbox for context from prior sessions and worker updates:

```bash
# On session start - load prior context
toolboxes/agent-mail/agent-mail.js fetch-inbox \
  --project-key /path/to/project \
  --agent-name OrchestratorName \
  --include-bodies true \
  --limit 20
```

```python
# Parse JSON output and process prior context
import json
messages = json.loads(output)

for msg in messages:
    if "[TRACK COMPLETE]" in msg.get("subject", ""):
        mark_track_complete(msg)
    elif "[BLOCKER]" in msg.get("subject", ""):
        handle_blocker(msg)
    elif "[HEARTBEAT]" in msg.get("subject", ""):
        update_worker_status(msg)
```

## Mandatory Summary Protocol

All workers (including orchestrator) MUST send a summary before returning:

```bash
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key /path/to/project \
  --sender-name OrchestratorName \
  --to '["Worker1", "Worker2"]' \
  --thread-id ${epic_id} \
  --subject "EPIC COMPLETE: ${title}" \
  --body-md "## Status
SUCCEEDED

## Files Changed
- path/to/file.ts (added)

## Key Decisions
- Decision: rationale

## Issues (if any)
None"
```

See [summary-protocol.md](summary-protocol.md) for complete format.

## Session Brain (Phase 0)

The orchestrator includes a "session brain" that coordinates multiple Amp sessions:

- **Auto-registration**: Sessions register identity with Agent Mail CLI on startup
- **Conflict detection**: Warns when sessions work on same track/files/beads
- **Stale takeover**: Prompts to take over inactive sessions (>10 min)
- **Always-on**: Preflight runs automatically on /conductor-implement and /conductor-orchestrate

### Session Identity Format

- Internal: `{BaseAgent}-{timestamp}` (unique, e.g., `BlueLake-1735689600`)
- Display: `{BaseAgent} (session HH:MM)` (human-readable, e.g., `BlueLake (session 10:30)`)

See [preflight.md](preflight.md) for protocol details.

```

### references/agent-coordination.md

```markdown
# Agent Coordination

When Agent Mail CLI is available, agents can coordinate file access and share context.

## Session Protocol

**Session start:**
```bash
# Check inbox for context from previous sessions
toolboxes/agent-mail/agent-mail.js fetch-inbox \
  --project-key "$PROJECT_PATH" \
  --agent-name "$AGENT_NAME"
```

**Session end:**
```bash
# Send handoff message for next session
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key "$PROJECT_PATH" \
  --sender-name "$SENDER_NAME" \
  --to '["RecipientAgent"]' \
  --subject "Handoff context" \
  --body-md "Context for next session..."
```

## Parallel Dispatch

Before dispatching parallel subagents:
1. Reserve files with `bun toolboxes/agent-mail/agent-mail.js file-reservation-paths`
2. Inject coordination block into Task prompts
3. Release reservations after completion

## Failure Handling

If Agent Mail CLI is unavailable:
- Proceed without coordination (work completion is mandatory)
- Show `⚠️ Agent coordination unavailable` warning
- Don't block on optional features

## Autonomous Mode (Ralph)

For `ca` execution, coordination is handled differently:
- Ralph uses exclusive `ralph.active` lock instead of file reservations
- Spawns fresh Amp instances per iteration (not Task())
- Progress tracked via `<track>/progress.txt`

See [autonomous.md](../../conductor/references/workflows/autonomous.md) for details.

```

### references/architecture.md

```markdown
# Orchestrator Architecture

## System Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              ORCHESTRATOR                                   │
│                              (Main Agent)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. Read plan.md Track Assignments                                          │
│  2. Initialize Agent Mail                                                   │
│  3. Spawn workers via Task()                                                │
│  4. Monitor progress via fetch_inbox                                        │
│  5. Handle cross-track blockers                                             │
│  6. Announce completion                                                     │
└─────────────────────────────────────────────────────────────────────────────┘
           │
           │ Task() spawns parallel workers
           ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Worker A        │  │  Worker B        │  │  Worker C        │
│  Track 1         │  │  Track 2         │  │  Track 3         │
├──────────────────┤  ├──────────────────┤  ├──────────────────┤
│  For each bead:  │  │  For each bead:  │  │  For each bead:  │
│  • Reserve files │  │  • Reserve files │  │  • Reserve files │
│  • bd claim      │  │  • bd claim      │  │  • bd claim      │
│  • Do work       │  │  • Do work       │  │  • Do work       │
│  • bd close      │  │  • bd close      │  │  • bd close      │
│  • Report mail   │  │  • Report mail   │  │  • Report mail   │
└──────────────────┘  └──────────────────┘  └──────────────────┘
           │                   │                   │
           └───────────────────┼───────────────────┘
                               ▼
                    ┌─────────────────────┐
                    │     Agent Mail      │
                    │  ─────────────────  │
                    │  Epic Thread:       │
                    │  • Progress reports │
                    │  • Bead completions │
                    │  • Blockers         │
                    └─────────────────────┘
```

## Key Difference from /conductor-implement

| Aspect | /conductor-implement | /conductor-orchestrate |
|--------|---------------------|----------------------|
| Execution | Sequential, main agent | Parallel, worker subagents |
| bd access | Main agent only | **Workers CAN claim/close** |
| Coordination | N/A | Agent Mail CLI |
| File locking | N/A | `bun toolboxes/agent-mail/agent-mail.js file-reservation-paths` |
| Context | In-memory | Track threads (persistent) |

## Auto-Orchestration Integration

When triggered from `fb` (file beads) auto-orchestration:

1. Track Assignments are **auto-generated** from beads dependency graph
2. No manual Track Assignments section needed in plan.md
3. Orchestrator receives assignments via in-memory call, not file parsing

### Auto-Generated vs Manual

| Source | How Detected | Behavior |
|--------|--------------|----------|
| Auto-generated | Called from fb Phase 6 | Assignments passed in-memory |
| Manual | User runs `/conductor-orchestrate` | Parse from plan.md |

Both flows converge at Phase 3 (Spawn Workers).

## Directory Structure

```
skills/orchestrator/
├── SKILL.md           # Main skill file
├── agents/            # Agent profiles by category
│   ├── research/      # Locator, Analyzer, Pattern, Web, GitHub
│   ├── review/        # CodeReview, SecurityAudit, PerformanceReview
│   ├── planning/      # Architect, Planner
│   ├── execution/     # Implementer, Modifier, Fixer, Refactorer
│   └── debug/         # Debugger, Tracer
├── references/        # Workflow documentation
│   ├── workflow.md    # 8-phase orchestrator protocol
│   ├── preflight.md   # Session Brain preflight
│   ├── worker-prompt.md
│   └── patterns/
└── scripts/           # Session brain utilities
    └── preflight.py   # Preflight protocol implementation
```

## Lazy Loading Requirements

Host-side changes required for Maestro loader to support deferred reference loading.

### Overview

The loader currently loads all skill content eagerly. To reduce token consumption and improve startup time, the loader should support **lazy loading** of references based on workflow phase or trigger conditions.

### Host-Side Loader Changes

#### 1. Load SKILL.md Only (Core Instructions)

```python
# Current behavior: loads SKILL.md + all references
skill_content = load_skill("orchestrator")  # Loads everything

# New behavior: loads SKILL.md only
skill_content = load_skill("orchestrator")  # Loads SKILL.md core
# References loaded separately on-demand
```

#### 2. Parse `## Lazy References` Table

The loader must detect and parse the `## Lazy References` section in SKILL.md:

```markdown
## Lazy References

| When | Load |
|------|------|
| Phase 4 (spawn) | [worker-prompt.md](references/worker-prompt.md) |
| Cross-track deps | [agent-coordination.md](references/agent-coordination.md) |
| Conflict resolution | [agent-mail.md](references/agent-mail.md) |
```

**Parsing Requirements:**
- Detect `## Lazy References` heading (exact match, case-sensitive)
- Parse markdown table with `When | Load` columns
- Extract trigger condition from `When` column
- Extract file path from markdown link in `Load` column
- Store as trigger → file path mapping

#### 3. Load References on Trigger Activation

When a specific phase or trigger activates, inject the corresponding reference:

```python
# Trigger conditions (examples)
TRIGGER_PATTERNS = {
    "Phase 4": ["spawn", "Task(", "worker"],
    "Cross-track deps": ["dependency", "blocked", "waiting"],
    "Conflict resolution": ["conflict", "file_reservation", "overlap"],
}

def check_trigger(context: str, trigger: str) -> bool:
    """Check if trigger condition is met based on context."""
    patterns = TRIGGER_PATTERNS.get(trigger, [])
    return any(p in context for p in patterns)

def lazy_load_if_needed(skill: str, context: str):
    """Load deferred references when trigger activates."""
    for trigger, ref_path in skill.lazy_references.items():
        if check_trigger(context, trigger):
            inject_reference(ref_path)
```

#### 4. Backwards Compatibility

Support both eager and deferred loading patterns:

| Section | Behavior | Use Case |
|---------|----------|----------|
| `## References` | **Eager** - Load with SKILL.md | Critical references always needed |
| `## Lazy References` | **Deferred** - Load on trigger | Phase-specific or rare-path references |

**Migration Path:**
1. Existing skills with only `## References` continue to work unchanged
2. Skills can add `## Lazy References` section incrementally
3. No breaking changes to existing skill format

### Trigger Detection Strategies

| Strategy | Description | Complexity |
|----------|-------------|------------|
| **Keyword match** | Match trigger patterns in user input/context | Low |
| **Phase tracking** | Track workflow phase via state machine | Medium |
| **Semantic match** | Use embeddings to match intent to trigger | High |

**Recommended:** Start with keyword match, add phase tracking for orchestrator.

### Example Loader Implementation

```python
class SkillLoader:
    def load(self, skill_name: str) -> LoadedSkill:
        """Load skill with lazy reference support."""
        skill_path = self.resolve_skill(skill_name)
        
        # Step 1: Load SKILL.md only
        content = read_file(skill_path / "SKILL.md")
        
        # Step 2: Parse sections
        eager_refs = self.parse_references(content)      # ## References
        lazy_refs = self.parse_lazy_references(content)  # ## Lazy References
        
        # Step 3: Load eager references immediately
        for ref in eager_refs:
            content += read_file(skill_path / ref)
        
        return LoadedSkill(
            content=content,
            lazy_refs=lazy_refs,  # Deferred until trigger
        )
    
    def parse_lazy_references(self, content: str) -> dict[str, str]:
        """Parse ## Lazy References table into trigger → path mapping."""
        # Find section
        match = re.search(r"## Lazy References\n\n\|.*\n\|.*\n((?:\|.*\n)*)", content)
        if not match:
            return {}
        
        # Parse table rows
        refs = {}
        for line in match.group(1).strip().split("\n"):
            parts = line.split("|")
            if len(parts) >= 3:
                trigger = parts[1].strip()
                load_cell = parts[2].strip()
                # Extract path from markdown link [text](path)
                path_match = re.search(r"\[.*\]\((.*)\)", load_cell)
                if path_match:
                    refs[trigger] = path_match.group(1)
        return refs
```

### Acceptance Criteria

- [ ] Loader parses `## Lazy References` table from SKILL.md
- [ ] Eager references (`## References`) load immediately with skill
- [ ] Lazy references load only when trigger condition activates  
- [ ] Existing skills without `## Lazy References` work unchanged
- [ ] Token savings measurable (target: 40-60% reduction for complex skills)

```

### references/coordination-modes.md

```markdown
# Coordination Modes

> **Note:** For autonomous execution (`ca`), see [autonomous.md](../../conductor/references/workflows/autonomous.md).
> Ralph is a third execution mode alongside `ci` (sequential) and `co` (parallel).

Orchestrator supports two modes based on task complexity and Agent Mail availability.

## Mode Comparison

| Mode | Agent Mail | Heartbeats | Use Case |
|------|------------|------------|----------|
| **Light** | Not required | No | Simple parallel tasks, no cross-deps, tasks <10 min |
| **Full** | Required | Yes (>10 min) | Complex coordination, blockers, cross-track deps |

## Mode Selection

```python
# Auto-select mode based on conditions
if not agent_mail_available():
    mode = "LIGHT"  # Fallback only when unavailable
else:
    mode = "FULL"   # Always use Agent Mail coordination when available
```

## Light Mode Behavior

- Workers execute via Task() and return structured results
- No Agent Mail registration, messaging, or heartbeats
- Orchestrator collects results from Task() return values
- Cross-track deps handled via Task() sequencing (spawn dependent tracks after blockers complete)

### Worker Protocol (3-Step)

```
┌─────────────────────────────────────────────────────────────┐
│  STEP 1: EXECUTE  (bd update/close - claim and work)       │
│  STEP 2: RETURN   (structured result via Task() return)    │
│  STEP 3: (none)   (no Agent Mail, no reservations)         │
└─────────────────────────────────────────────────────────────┘
```

**Light mode rules:**
- ❌ No Agent Mail registration or messaging
- ❌ No file reservations (rely on file scope isolation)
- ❌ No heartbeats
- ✅ Return structured summary via Task() return value

### Task Return Format

When Agent Mail unavailable, workers return structured results:

```python
return {
    "status": "SUCCEEDED",  # or "PARTIAL" or "FAILED"
    "files_changed": [
        {"path": "path/to/file.ts", "action": "added"},
        {"path": "path/to/other.ts", "action": "modified"}
    ],
    "key_decisions": [
        {"decision": "Used X pattern", "rationale": "because Y"}
    ],
    "issues": [],  # Empty if none
    "beads_closed": ["bd-101", "bd-102"]
}
```

Orchestrator collects these returns and aggregates into final summary.

## Full Mode Behavior

- Full Agent Mail protocol (register, message, heartbeat)
- Real-time progress monitoring via `bun toolboxes/agent-mail/agent-mail.js fetch-inbox`
- Cross-track dependency notifications
- Blocker resolution via `bun toolboxes/agent-mail/agent-mail.js reply-message`

### Worker Protocol (4-Step)

```
┌───────────────────────────────────────────────────────────────────────┐
│  STEP 1: INITIALIZE (bun toolboxes/agent-mail/agent-mail.js macro-start-session - FIRST)       │
│  STEP 2: EXECUTE    (bd update/close - claim and work)                │
│  STEP 3: REPORT     (bun toolboxes/agent-mail/agent-mail.js send-message - MANDATORY summary)  │
│  STEP 4: CLEANUP    (bun toolboxes/agent-mail/agent-mail.js release-file-reservations)         │
└───────────────────────────────────────────────────────────────────────┘
```

**Key rules:**
- ✅ STEP 1 must be FIRST action (orchestrator pre-registered you)
- ✅ STEP 3 must happen BEFORE returning (non-negotiable)
- ✅ Workers CAN use `bd update` and `bd close` directly
- ⏭️ Heartbeats only for tasks >10 minutes

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| max_workers | 3 | Maximum parallel workers |
| heartbeat_interval | 5 min | Worker heartbeat frequency |
| stale_threshold | 10 min | When to consider worker stale |
| cross_dep_timeout | 30 min | Max wait for cross-track dependency |

## Fallback Behavior

If Agent Mail unavailable:

```text
⚠️ Agent coordination unavailable - falling back to sequential execution
```

Routes to standard `/conductor-implement` instead.

```

### references/agent-mail-cli.md

```markdown
# Agent Mail CLI Reference

CLI tool for agent coordination via Agent Mail MCP, generated using MCPorter.

## Location

`toolboxes/agent-mail/agent-mail.js`

## Quick Start

```bash
# Check server status
toolboxes/agent-mail/agent-mail.js health-check

# List all tools
toolboxes/agent-mail/agent-mail.js --help
```

## Common Commands

### Session Setup

```bash
# Start a session (project + agent + inbox in one call)
toolboxes/agent-mail/agent-mail.js macro-start-session \
  --human-key /path/to/project \
  --program claude-code \
  --model opus-4.5
```

### Messaging

```bash
# Send message
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key /path/to/project \
  --sender-name BlueLake \
  --to '["GreenCastle"]' \
  --subject "Status update" \
  --body-md "Work complete"

# Fetch inbox
toolboxes/agent-mail/agent-mail.js fetch-inbox \
  --project-key /path/to/project \
  --agent-name BlueLake

# Reply to message
toolboxes/agent-mail/agent-mail.js reply-message \
  --project-key /path/to/project \
  --message-id 123 \
  --sender-name BlueLake \
  --body-md "Acknowledged"
```

### Agent Management

```bash
# Register agent
toolboxes/agent-mail/agent-mail.js register-agent \
  --project-key /path/to/project \
  --program claude-code \
  --model opus-4.5 \
  --task-description "Working on feature X"

# Who is an agent
toolboxes/agent-mail/agent-mail.js whois \
  --project-key /path/to/project \
  --agent-name BlueLake
```

### File Reservations

```bash
# Reserve files
toolboxes/agent-mail/agent-mail.js file-reservation-paths \
  --project-key /path/to/project \
  --agent-name BlueLake \
  --paths '["src/api/*.py"]' \
  --ttl-seconds 3600

# Release reservations
toolboxes/agent-mail/agent-mail.js release-file-reservations \
  --project-key /path/to/project \
  --agent-name BlueLake
```

## Argument Syntax

The CLI uses standard `--flag value` format:

```bash
# Flag with value (space-separated)
command --flag value

# JSON for arrays/objects
command --paths '["file1.ts", "file2.ts"]'

# Boolean flags
command --include-bodies true

# String values with spaces (use quotes)
command --body-md "Message with spaces"
```

### Parameter Naming

CLI flags use kebab-case (hyphens), which map to the MCP's snake_case parameters:

| MCP Parameter | CLI Flag |
|---------------|----------|
| `project_key` | `--project-key` |
| `sender_name` | `--sender-name` |
| `body_md` | `--body-md` |
| `include_bodies` | `--include-bodies` |
| `ttl_seconds` | `--ttl-seconds` |

## Environment Variables

- `AGENT_MAIL_TOKEN` - Bearer token for authentication (if required)

## See Also

- [Agent Mail MCP Documentation](../../orchestrator/references/agent-mail.md)
- [Orchestrator Workflow](../../orchestrator/references/workflow.md)

```

### references/preflight.md

```markdown
# Preflight Protocol Reference

Multi-session awareness protocol for orchestrator and conductor commands.

## Overview

Preflight (Phase 0) runs before `/conductor-implement` or `/conductor-orchestrate` to detect concurrent sessions and prevent conflicts.

## Phase 0: 4-Step Protocol

```
┌────────────────────────────────────────────────────────────────┐
│  PHASE 0: PREFLIGHT                                            │
├────────────────────────────────────────────────────────────────┤
│  Step 1: IDENTITY   - Register agent, generate session ID      │
│  Step 2: DETECT     - Scan for active sessions via Agent Mail  │
│  Step 3: DISPLAY    - Show session status, prompt if conflict  │
│  Step 4: PROCEED    - Continue or abort based on user choice   │
└────────────────────────────────────────────────────────────────┘
```

### Step 1: Identity

Register agent identity and generate session ID:

```bash
# Generate unique session identity
timestamp=$(date +%s)
session_id="${BASE_AGENT}-${timestamp}"
display_name="${BASE_AGENT} (session $(date +%H:%M))"

# Register with Agent Mail
toolboxes/agent-mail/agent-mail.js register-agent \
    --project-key "$PROJECT_PATH" \
    --name "$session_id" \
    --program amp \
    --model "$MODEL" \
    --task-description "Session started at $(date +%H:%M)"
```

### Step 2: Detect

Scan for active sessions:

```bash
# Fetch inbox to discover other sessions (2-hour lookback)
since_ts=$(date -u -v-2H +"%Y-%m-%dT%H:%M:%SZ")  # macOS
# since_ts=$(date -u -d "2 hours ago" +"%Y-%m-%dT%H:%M:%SZ")  # Linux

toolboxes/agent-mail/agent-mail.js fetch-inbox \
    --project-key "$PROJECT_PATH" \
    --agent-name "$session_id" \
    --since-ts "$since_ts" \
    --include-bodies true

# Filter for session announcements in output:
# - Look for "[SESSION START]" in subject
# - Parse session_info and check if not stale
# - Build active_sessions list
```

### Step 3: Display

Show session status using display formats (see below).

### Step 4: Proceed

Based on conflict detection:
- **No conflicts**: Proceed to Phase 1
- **Track conflict**: Prompt with [P]roceed/[S]witch/[W]ait
- **Stale session**: Prompt with [T]ake/[W]ait/[I]gnore

## Trigger Conditions

| Command | Preflight | Notes |
|---------|-----------|-------|
| `/conductor-implement` | ✅ Yes | Always runs Phase 0 |
| `/conductor-orchestrate` | ✅ Yes | Always runs Phase 0 |
| `/conductor-autonomous` | ⚠️ Partial | Ralph has own lock via `ralph.active` |
| `ds` | ❌ Skip | Design sessions don't conflict |
| `bd ready` | ❌ Skip | Read-only command |
| `bd show` | ❌ Skip | Read-only command |
| `bd list` | ❌ Skip | Read-only command |

## Skip Rules

Preflight is skipped when:
1. Command is read-only (`bd ready`, `bd show`, `bd list`)
2. Command is design phase (`ds`, `/conductor-design`)
3. Explicit `--skip-preflight` flag passed

**Note:** If Agent Mail is unavailable during preflight, orchestrator HALTs (does not degrade).

## Agent Mail Integration

### Registration

```bash
# Full registration with task context
toolboxes/agent-mail/agent-mail.js register-agent \
    --project-key "$PROJECT_PATH" \
    --name "$session_id" \
    --program amp \
    --model claude-opus-4-5@20251101 \
    --task-description "Track: $track_id, Started: $timestamp"
```

### Inbox Fetch

```bash
# Fetch with 2-hour lookback for session detection
toolboxes/agent-mail/agent-mail.js fetch-inbox \
    --project-key "$PROJECT_PATH" \
    --agent-name "$session_id" \
    --since-ts "2025-01-01T08:00:00Z" \
    --include-bodies true \
    --limit 50
```

## Error Handling

### Timeout Behavior

Agent Mail operations timeout after 3 seconds:

```bash
# Timeout handling is built into the CLI toolbox
# If timeout occurs, exit with error

toolboxes/agent-mail/agent-mail.js register-agent \
    --project-key "$PROJECT_PATH" \
    --name "$session_id" \
    --program amp \
    --model "$MODEL"

if [ $? -ne 0 ]; then
    # HALT - Agent Mail is required
    echo "❌ Cannot proceed: Agent Mail timeout"
    exit 1
fi
```

### Unavailable Service

```bash
# Check Agent Mail availability via health-check
toolboxes/agent-mail/agent-mail.js health-check --reason "Preflight check"

if [ $? -ne 0 ]; then
    echo "❌ Cannot proceed: Agent Mail required for orchestration"
    # HALT - do not proceed without Agent Mail
    exit 1
fi
```

## Display Formats

### Active Sessions Box

```
┌─ ACTIVE SESSIONS ──────────────────────────────────────────┐
│                                                            │
│ 🟢 BlueLake (session 10:30) - active                       │
│    Track: cc-v2-integration                                │
│    Beads: bd-101 (in_progress)                             │
│    Files: src/api/**                                       │
│    Last seen: 2 min ago                                    │
│                                                            │
│ 🟡 GreenCastle (session 09:15) - stale (12 min)            │
│    Track: doc-updates                                      │
│    Beads: bd-201 (in_progress)                             │
│    Files: docs/**                                          │
│    Last seen: 12 min ago                                   │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

### Conflict Prompt

```
┌─ CONFLICTS DETECTED ───────────────────────────────────────┐
│ ⚠️  TRACK CONFLICT                                         │
│     BlueLake (session 10:30) is already on cc-v2-integration│
│                                                            │
│ Options:                                                   │
│ [P]roceed anyway - work on different files/beads           │
│ [S]witch track - pick a different track                    │
│ [W]ait - let other session finish first                    │
└────────────────────────────────────────────────────────────┘
```

### Stale Takeover Prompt

```
┌─ STALE SESSION DETECTED ───────────────────────────────────┐
│ GreenCastle (session 09:15) inactive for 12 minutes        │
│                                                            │
│ Reserved files: skills/orchestrator/**                     │
│ Claimed beads: bd-201 (in_progress)                        │
│                                                            │
│ ⚠️  Warning: May have uncommitted work                      │
│                                                            │
│ [T]ake over - release reservations, reset beads to open    │
│ [W]ait - check again in 5 min                              │
│ [I]gnore - proceed without their files/beads               │
└────────────────────────────────────────────────────────────┘
```

## Session Status Indicators

| Icon | Status | Meaning |
|------|--------|---------|
| 🟢 | Active | Heartbeat within 5 min |
| 🟡 | Stale | No heartbeat for 5-10 min |
| 🔴 | Inactive | No heartbeat for >10 min |
| ⚪ | Unknown | No session data available |

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `preflight_timeout` | 3s | Max time for Agent Mail operations |
| `session_lookback` | 2h | How far back to scan for sessions |
| `stale_threshold` | 10 min | When to consider session stale |
| `heartbeat_interval` | 5 min | Expected heartbeat frequency |

## References

- [session-identity.md](session-identity.md) - Identity format and collision handling
- [patterns/session-lifecycle.md](patterns/session-lifecycle.md) - Full lifecycle with multi-session
- [agent-coordination.md](agent-coordination.md) - Agent Mail coordination patterns

```

### references/summary-protocol.md

```markdown
# Summary Protocol

> **Standard format for sub-agent completion reports via Agent Mail.**

## Overview

Sub-agents MUST send a summary message via Agent Mail before returning. This ensures:
- Main thread has visibility into completed work
- Context is preserved across sessions
- Errors are properly reported

## Summary Format

```markdown
## Status
SUCCEEDED | PARTIAL | FAILED

## Files Changed
- path/to/file1.ts (added)
- path/to/file2.ts (modified)
- path/to/file3.ts (deleted)

## Key Decisions
- Decision 1: rationale
- Decision 2: rationale

## Issues (if any)
- Issue description
```

## Status Values

| Status | Meaning | When to Use |
|--------|---------|-------------|
| `SUCCEEDED` | Task fully completed | All acceptance criteria met |
| `PARTIAL` | Task partially completed | Some work done, blockers remain |
| `FAILED` | Task could not be completed | Error or blocker prevented work |

## Agent Mail Message Structure

```bash
toolboxes/agent-mail/agent-mail.js send-message \
    --project-key "/path/to/project" \
    --sender-name "BlueLake" \
    --to '["Orchestrator"]' \
    --subject "Completed: $task_id - $task_summary" \
    --body-md "$summary_template" \
    --importance normal \
    --thread-id "$epic_thread_id"
```

## Example: Successful Completion

```bash
toolboxes/agent-mail/agent-mail.js send-message \
    --project-key "/Users/dev/myproject" \
    --sender-name "BlueLake" \
    --to '["Orchestrator"]' \
    --subject "Completed: bd-101 - Add user authentication" \
    --body-md "## Status
SUCCEEDED

## Files Changed
- src/auth/middleware.ts (added)
- src/routes/login.ts (modified)
- tests/auth.test.ts (added)

## Key Decisions
- Used JWT for tokens: standard, well-supported
- 15min token expiry: balances security/UX

## Issues (if any)
None" \
    --importance normal \
    --thread-id "epic-my-workflow-001"
```

## Example: Partial Completion

```bash
toolboxes/agent-mail/agent-mail.js send-message \
    --project-key "/Users/dev/myproject" \
    --sender-name "GreenCastle" \
    --to '["Orchestrator"]' \
    --subject "Partial: bd-102 - Database migration" \
    --body-md "## Status
PARTIAL

## Files Changed
- migrations/001_users.sql (added)
- src/db/schema.ts (modified)

## Key Decisions
- Split migration into phases: safer rollback

## Issues (if any)
- Blocked by bd-100 (schema design not finalized)
- Tests skipped pending schema approval" \
    --importance high \
    --thread-id "epic-my-workflow-001"
```

## Example: Failed Task

```bash
toolboxes/agent-mail/agent-mail.js send-message \
    --project-key "/Users/dev/myproject" \
    --sender-name "RedStone" \
    --to '["Orchestrator"]' \
    --subject "Failed: bd-103 - Deploy to staging" \
    --body-md "## Status
FAILED

## Files Changed
None

## Key Decisions
N/A

## Issues (if any)
- CI pipeline failed: missing DEPLOY_KEY secret
- Cannot proceed without DevOps input
- Marked bead as blocked" \
    --importance high \
    --thread-id "epic-my-workflow-001"
```

## Files Changed Format

Use consistent action verbs:

| Action | Meaning |
|--------|---------|
| `added` | New file created |
| `modified` | Existing file changed |
| `deleted` | File removed |
| `renamed` | File moved/renamed |

## Key Decisions Guidelines

Document decisions that:
- Affect architecture or design
- Deviate from initial plan
- Have trade-offs worth noting
- Future developers should understand

## Thread Linking

Always include `--thread-id` to link messages to the epic:
- Enables thread summarization
- Groups related work
- Maintains conversation history

## Validation

Before sending, verify:
1. ☐ Status reflects actual outcome
2. ☐ All changed files listed
3. ☐ Important decisions documented
4. ☐ Issues describe blockers with bead IDs
5. ☐ thread_id links to correct epic

```

### references/auto-routing.md

```markdown
# Auto-Routing to Parallel Execution

When `/conductor-implement` runs without explicit Track Assignments in plan.md,
the system can auto-detect opportunities for parallel execution.

## Detection Priority

| Priority | Check | Trigger |
|----------|-------|---------|
| 1 | Track Assignments in plan.md | Explicit parallel dispatch |
| **1.5** | **fileScopes in metadata.json** | **File-scope grouping** |
| 2 | beads.planTasks with ≥2 independent | Bead dependency analysis |

## Detection Algorithm

1. **Check Track Assignments** - Explicit parallel routing (Priority 1)
2. **Check metadata.json.beads.fileScopes** - File-scope based routing (Priority 1.5)
3. **Check metadata.json.beads.planTasks** - Maps plan tasks to bead IDs
4. **Verify with `bd list --json`** - Runtime source of truth
5. **Analyze dependency graph** - Find beads with no blockers
6. **Threshold: ≥2 independent beads** - Triggers auto-orchestration

## Priority 1.5: File Scope Routing

If `metadata.json.beads.fileScopes` exists:

1. **Load file scopes** from metadata.json
2. **Run parallel-grouping** algorithm (load [conductor skill](../../conductor/SKILL.md) for details)
3. **Check threshold**: ≥2 non-overlapping groups → PARALLEL_DISPATCH
4. **Generate Track Assignments** dynamically if not present in plan.md

### Algorithm Reference

> **Cross-skill reference:** Load the [conductor](../../conductor/SKILL.md) skill for file-scope-extractor and parallel-grouping algorithms.

**Summary of algorithms:**
- **Extraction**: Parse `### Files:` sections from plan.md tasks, extract glob patterns
- **Grouping**: Cluster tasks by non-overlapping file scopes, merge small groups

## Flow

```
┌─────────────────────────────────────────────────────────────┐
│                    /conductor-implement                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │ Priority 1: Track Assignments?│
              └───────────────────────────────┘
                    │               │
                   YES              NO
                    │               │
                    ▼               ▼
           PARALLEL_DISPATCH   ┌─────────────────────┐
                               │ Priority 1.5:       │
                               │ beads.fileScopes?   │
                               └─────────────────────┘
                                    │           │
                                  EXISTS      MISSING
                                    │           │
                                    ▼           ▼
                         ┌──────────────┐   ┌─────────────────────┐
                         │ Run parallel │   │ Priority 2:         │
                         │ grouping     │   │ beads.planTasks?    │
                         └──────────────┘   └─────────────────────┘
                               │                 │           │
                               ▼               EXISTS      MISSING
                    ┌──────────────────────┐     │           │
                    │ Groups ≥ 2?          │     ▼           ▼
                    └──────────────────────┘ ┌──────────────┐ TIER 1/2
                         │           │       │ Count beads  │ evaluation
                        YES          NO      │ with no deps │
                         │           │       └──────────────┘
                         ▼           ▼             │
               PARALLEL_DISPATCH   TIER 1/2        ▼
                                   evaluation  ┌──────────────────────┐
                                               │ Independent ≥ 2?     │
                                               └──────────────────────┘
                                                    │           │
                                                   YES          NO
                                                    │           │
                                                    ▼           ▼
                                          PARALLEL_DISPATCH   TIER 1/2
                                                              evaluation
```

## Auto-Generated Track Assignments

When auto-routing triggers:

1. **Query bead dependencies:**
   ```bash
   bd list --json | jq '[.[] | select(.dependencies | length == 0)]'
   ```

2. **Group by file scope:**
   - Extract file paths from bead titles/descriptions
   - Same directory → same track
   - Different top-level directories → different tracks

3. **Generate Track Assignments table:**
   
   | Track | Beads | Depends On |
   |-------|-------|------------|
   | 1 | bd-1, bd-2 | - |
   | 2 | bd-3 | - |
   | 3 | bd-4, bd-5 | bd-2, bd-3 |

4. **Route to orchestrator skill**

5. **Execute in parallel waves**

## Example

Given metadata.json:
```json
{
  "beads": {
    "planTasks": {
      "1.1": "bd-1",
      "1.2": "bd-2",
      "2.1": "bd-3"
    }
  }
}
```

If bd-1 and bd-3 have no dependencies:
- 2 independent beads detected
- Auto-generate 2 tracks
- Route to parallel execution

## State Tracking

When auto-routing triggers, implement_state.json records:
```json
{
  "execution_mode": "PARALLEL_DISPATCH",
  "routing_trigger": "auto_detect",
  "routing_evaluation": {
    "has_track_assignments": false,
    "auto_detect_triggered": true,
    "independent_beads_count": 3,
    "agent_mail_available": true
  }
}
```

## Fallback Behavior

If auto-detection finds < 2 independent beads:
- Continue to TIER 1/2 heuristic evaluation
- May still route to parallel if TIER thresholds met

If Agent Mail unavailable:
- Fall back to sequential execution regardless of bead count

## Related

> **Cross-skill reference:** Load the [conductor](../../conductor/SKILL.md) skill for implementation routing (Phase 2b).

- [workflow.md](workflow.md) - Orchestrator workflow

> **Cross-skill reference:** Load the [tracking](../../tracking/SKILL.md) skill for FILE_BEADS and planTasks mapping.

```

### references/track-threads.md

```markdown
# Track Thread Protocol

Bead-to-bead context preservation using self-addressed messages.

## Two-Thread Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    TWO-THREAD ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  EPIC THREAD                      TRACK THREAD                  │
│  thread_id: <epic-id>             thread_id: track:<agent>:<epic>│
│  ─────────────────                ───────────────────────────── │
│  • Progress reports               • Bead-to-bead learnings      │
│  • Blockers                       • Gotchas discovered          │
│  • Cross-track issues             • Next bead hints             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Thread ID Format

| Thread Type | Format | Example |
|-------------|--------|---------|
| Epic | `<epic-id>` | `my-workflow:3-ktgt` |
| Track | `track:<agent>:<epic>` | `track:BlueLake:my-workflow:3-ktgt` |

## Per-Bead Loop

### 1. START BEAD
```bash
# Read prior context from track thread
toolboxes/agent-mail/agent-mail.js summarize-thread \
  --project-key "$PROJECT_PATH" \
  --thread-id "track:$AGENT:$EPIC"

# Reserve files
toolboxes/agent-mail/agent-mail.js file-reservation-paths \
  --project-key "$PROJECT_PATH" \
  --agent-name "$AGENT" \
  --paths '["<file-scope>"]' \
  --reason "<bead-id>"

# Claim bead
bd update <bead-id> --status in_progress
```

### 2. WORK ON BEAD
- Implement requirements
- Check inbox periodically
- Escalate blockers to epic thread

### 3. COMPLETE BEAD
```bash
# Close bead
bd close <bead-id> --reason completed

# Report to orchestrator (epic thread)
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key "$PROJECT_PATH" \
  --sender-name "$AGENT" \
  --to '["<Orchestrator>"]' \
  --thread-id "<epic-id>" \
  --subject "[<bead-id>] COMPLETE" \
  --body-md "Done: <summary>. Next: <next-bead-id>"

# Save context for next bead (track thread - self message)
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key "$PROJECT_PATH" \
  --sender-name "$AGENT" \
  --to '["<self>"]' \
  --thread-id "track:$AGENT:$EPIC" \
  --subject "<bead-id> Complete - Context for next" \
  --body-md "## Learnings
- What worked well
- What was tricky

## Gotchas
- Edge cases discovered
- Things to avoid

## Next Notes
- Context for next bead
- Dependencies or setup needed"

# Release files
toolboxes/agent-mail/agent-mail.js release-file-reservations \
  --project-key "$PROJECT_PATH" \
  --agent-name "$AGENT"
```

### 4. NEXT BEAD
- Loop to START with next bead
- **Read track thread for context!**

## Context Structure

Messages to track thread MUST include:

| Section | Purpose |
|---------|---------|
| Learnings | What worked, patterns discovered |
| Gotchas | Pitfalls, edge cases, things to avoid |
| Next Notes | Context specifically for next bead |

## Example

```bash
# Worker BlueLake after completing bead bd-11
toolboxes/agent-mail/agent-mail.js send-message \
  --project-key "$PROJECT_PATH" \
  --sender-name "BlueLake" \
  --to '["BlueLake"]' \
  --thread-id "track:BlueLake:my-workflow:3-ktgt" \
  --subject "bd-11 Complete - Context for bd-12" \
  --body-md "## Learnings
- Stripe SDK requires raw body for webhook verification
- Use stripe.webhooks.constructEvent() not manual parsing

## Gotchas
- STRIPE_WEBHOOK_SECRET env var must be set in test env
- Don't JSON.parse the body before verification

## Next Notes
- bd-12 needs to implement the actual event handlers
- checkout.session.completed handler should create subscription record
- Reference spike code in conductor/spikes/billing-spike/webhook-test/"
```

## Benefits

1. **No context loss** - Each bead picks up where last left off
2. **Learnings persist** - Gotchas discovered early prevent issues later
3. **Spike references** - Track thread can point to spike code
4. **Searchable** - Agent Mail FTS5 can find historical context

## Related

- [worker-prompt.md](worker-prompt.md) - Worker protocol
- [workflow.md](workflow.md) - Full orchestrator workflow
- [agent-mail.md](agent-mail.md) - Messaging protocol

```

### ../conductor/SKILL.md

```markdown
---
name: conductor
description: Implementation execution for context-driven development. Trigger with ci, /conductor-implement, or /conductor-* commands. Use when executing tracks with specs/plans. For design phases, see designing skill. For session handoffs, see handoff skill.
---

# Conductor: Implementation Execution

Execute tracks with TDD and parallel routing.

## Entry Points

| Trigger | Action | Reference |
|---------|--------|-----------|
| `/conductor-setup` | Initialize project context | [workflows/setup.md](references/workflows/setup.md) |
| `/conductor-implement` | Execute track (auto-routes if parallel) | [workflows/implement.md](references/workflows/implement.md) |
| `ca`, `/conductor-autonomous` | **Run ralph.sh directly** (no Task/sub-agents) | [workflows/autonomous.md](references/workflows/autonomous.md) |
| `/conductor-status` | Display progress overview | [structure.md](references/structure.md) |
| `/conductor-revise` | Update spec/plan mid-work | [workflows.md#revisions](references/workflows.md#revisions) |

## Related Skills (Not Owned by Conductor)

| For... | Use Skill | Triggers |
|--------|-----------|----------|
| Design phases (1-8) | [designing](../designing/SKILL.md) | `ds`, `cn`, `/conductor-design`, `/conductor-newtrack` |
| Session handoffs | [handoff](../handoff/SKILL.md) | `ho`, `/conductor-finish`, `/conductor-handoff` |

## Quick Reference

| Phase | Purpose | Output | Skill |
|-------|---------|--------|-------|
| Requirements | Understand problem | design.md | designing |
| Plan | Create spec + plan | spec.md + plan.md | designing |
| **Implement** | Build with TDD | Code + tests | **conductor** |
| **Autonomous** | Ralph loop execution | Auto-verified stories | **conductor** |
| Reflect | Verify before shipping | LEARNINGS.md | handoff |

## Core Principles

- **Load core first** - Load [maestro-core](../maestro-core/SKILL.md) for routing table and fallback policies
- **TDD by default** - RED → GREEN → REFACTOR (use `--no-tdd` to disable)
- **Beads integration** - Zero manual `bd` commands in happy path
- **Parallel routing** - `## Track Assignments` in plan.md triggers orchestrator
- **Validation gates** - Automatic checks at each phase transition

## Directory Structure

```
conductor/
├── product.md, tech-stack.md, workflow.md  # Project context
├── code_styleguides/                       # Language-specific style rules
├── CODEMAPS/                               # Architecture docs
├── handoffs/                               # Session context
├── spikes/                                 # Research spikes (pl output)
└── tracks/<track_id>/                      # Per-track work
    ├── design.md, spec.md, plan.md         # Planning artifacts
    └── metadata.json                       # State tracking (includes planning state)
```

See [structure.md](references/structure.md) for full details.

## Beads Integration

All execution routes through orchestrator with Agent Mail coordination:
- Workers claim beads via `bd update --status in_progress`
- Workers close beads via `bd close --reason completed|skipped|blocked`
- File reservations via `file_reservation_paths`
- Communication via `send_message`/`fetch_inbox`

See [beads/integration.md](references/beads/integration.md) for all 13 integration points.

## `/conductor-implement` Auto-Routing

1. Read `metadata.json` - check `orchestrated` flag
2. Read `plan.md` - check for `## Track Assignments`
3. Check `beads.fileScopes` - file-scope based grouping (see [execution/file-scope-extractor](references/execution/file-scope-extractor.md))
4. If parallel detected (≥2 non-overlapping groups) → Load [orchestrator skill](../orchestrator/SKILL.md)
5. Else → Sequential execution with TDD

### File Scope Detection

File scopes determine parallel routing (see [execution/parallel-grouping](references/execution/parallel-grouping.md)):
- Tasks touching same files → sequential (same track)
- Tasks touching different files → parallel (separate tracks)

## Anti-Patterns

- ❌ Manual `bd` commands when workflow commands exist
- ❌ Ignoring validation gate failures
- ❌ Using conductor for design (use [designing](../designing/SKILL.md) instead)
- ❌ Using conductor for handoffs (use [handoff](../handoff/SKILL.md) instead)

## Related

- [designing](../designing/SKILL.md) - Double Diamond design + track creation
- [handoff](../handoff/SKILL.md) - Session cycling and finish workflow
- [tracking](../tracking/SKILL.md) - Issue tracking (beads)
- [orchestrator](../orchestrator/SKILL.md) - Parallel execution
- [maestro-core](../maestro-core/SKILL.md) - Routing policies

```

### ../tracking/SKILL.md

```markdown
---
name: tracking
description: >
  Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides
  persistent memory that survives conversation compaction. Use when work spans multiple sessions, has
  complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like
  "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or
  "update status". MUST load maestro-core skill first for routing.
metadata:
  version: "2.2.0"
---

## Prerequisites

- **Load maestro-core first** - [maestro-core](../maestro-core/SKILL.md) for routing table and fallback policies
- Routing and fallback policies are defined in [AGENTS.md](../../AGENTS.md).

# Tracking - Persistent Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

## Entry Points

| Trigger | Reference | Action |
|---------|-----------|--------|
| `bd`, `beads` | `references/workflow.md` | Core CLI operations |
| `fb`, `file-beads` | `references/FILE_BEADS.md` | File beads from plan → auto-orchestration |
| `rb`, `review-beads` | `references/REVIEW_BEADS.md` | Review filed beads |

## Quick Decision

**bd vs TodoWrite**:
- "Will I need this in 2 weeks?" → **YES** = bd
- "Could history get compacted?" → **YES** = bd
- "Has blockers/dependencies?" → **YES** = bd
- "Done this session?" → **YES** = TodoWrite

**Rule**: If resuming in 2 weeks would be hard without bd, use bd.

## Essential Commands

| Command | Purpose |
|---------|---------|
| `bd ready` | Show tasks ready to work on |
| `bd create "Title" -p 1` | Create new task |
| `bd show <id>` | View task details |
| `bd update <id> --status in_progress` | Start working |
| `bd update <id> --notes "Progress"` | Add progress notes |
| `bd close <id> --reason completed` | Complete task |
| `bd dep add <child> <parent>` | Add dependency |
| `bd sync` | Sync with git remote |

## Session Protocol

1. **Start**: `bd ready` → pick highest priority → `bd show <id>` → update to `in_progress`
2. **Work**: Add notes frequently (critical for compaction survival)
3. **End**: Close finished work → `bd sync` → `git push`

## Reference Files

| Category | Files |
|----------|-------|
| **Workflows** | `workflow.md`, `WORKFLOWS.md`, `FILE_BEADS.md`, `REVIEW_BEADS.md` |
| **CLI** | `CLI_REFERENCE.md`, `DEPENDENCIES.md`, `LABELS.md` |
| **Integration** | `conductor-integration.md`, `VILLAGE.md`, `GIT_INTEGRATION.md` |
| **Operations** | `AGENTS.md`, `RESUMABILITY.md`, `TROUBLESHOOTING.md` |

## Anti-Patterns

- ❌ Using TodoWrite for multi-session work
- ❌ Forgetting to add notes (loses context on compaction)
- ❌ Not running `bd sync` before ending session
- ❌ Creating beads for trivial single-session tasks

## Related

- [maestro-core](../maestro-core/SKILL.md) - Workflow router and skill hierarchy
- [conductor](../conductor/SKILL.md) - Automated beads operations via facade
- [orchestrator](../orchestrator/SKILL.md) - Multi-agent parallel execution

```