create-kuckit-app 2.0.2 → 2.1.0

package/templates/base/docs/MULTI_AGENT_WORKFLOW.md

@@ -0,0 +1,909 @@
+# Comprehensive Multi-Agent Beads Workflow
+
+> A complete guide to autonomous multi-agent execution using bd, bv, Agent Mail, and specialized skills.
+
+## Master Flow Diagram
+
+```
+╔═════════════════════════════════════════════════════════════════════════════════════════╗
+║                                                                                         ║
+║                    COMPREHENSIVE MULTI-AGENT BEADS WORKFLOW                             ║
+║                                                                                         ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │                           PHASE 1: CREATE                                         │  ║
+║  │                           Tool: file-beads skill + bd                             │  ║
+║  ├───────────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                                   │  ║
+║  │   Plan/Spec ──────► file-beads skill ──────► Raw beads with initial deps         │  ║
+║  │                                                                                   │  ║
+║  │   bd create "Epic: Feature X" -t epic -p 0                                        │  ║
+║  │   bd create "Task A" -t task --blocks <epic>                                      │  ║
+║  │   bd create "Task B" -t task --blocks <epic>                                      │  ║
+║  │   ...                                                                             │  ║
+║  │                                                                                   │  ║
+║  │   Output: .beads/*.md files with dependency structure                             │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │                           PHASE 2: REVIEW                                         │  ║
+║  │                           Tool: bv + review-beads skill                           │  ║
+║  ├───────────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                                   │  ║
+║  │   ┌─────────────────────────────────────────────────────────────────────────┐     │  ║
+║  │   │  bv Analysis (Automated)                                                │     │  ║
+║  │   ├─────────────────────────────────────────────────────────────────────────┤     │  ║
+║  │   │  bv --robot-suggest      → Find missing dependencies                    │     │  ║
+║  │   │  bv --robot-insights     → Detect cycles, bottlenecks                   │     │  ║
+║  │   │  bv --robot-priority     → Validate priorities via graph analysis      │     │  ║
+║  │   └─────────────────────────────────────────────────────────────────────────┘     │  ║
+║  │                                           │                                       │  ║
+║  │                                           ▼                                       │  ║
+║  │   ┌─────────────────────────────────────────────────────────────────────────┐     │  ║
+║  │   │  Apply Fixes                                                            │     │  ║
+║  │   ├─────────────────────────────────────────────────────────────────────────┤     │  ║
+║  │   │  bd dep add <from> <to>        → Add missing deps                       │     │  ║
+║  │   │  bd dep remove <from> <to>     → Break cycles                           │     │  ║
+║  │   │  bd update <id> --priority X   → Adjust priorities                      │     │  ║
+║  │   └─────────────────────────────────────────────────────────────────────────┘     │  ║
+║  │                                           │                                       │  ║
+║  │                                           ▼                                       │  ║
+║  │   ┌─────────────────────────────────────────────────────────────────────────┐     │  ║
+║  │   │  Content Review (Human/AI)                                              │     │  ║
+║  │   ├─────────────────────────────────────────────────────────────────────────┤     │  ║
+║  │   │  • Clarity: Titles action-oriented, descriptions clear                  │     │  ║
+║  │   │  • Completeness: Acceptance criteria defined                            │     │  ║
+║  │   │  • Scope: Issues appropriately sized                                    │     │  ║
+║  │   └─────────────────────────────────────────────────────────────────────────┘     │  ║
+║  │                                                                                   │  ║
+║  │   Output: Healthy graph, polished issues ready for execution                      │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │                           PHASE 3: PLAN                                           │  ║
+║  │                           Tool: bv                                                │  ║
+║  ├───────────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                                   │  ║
+║  │   bv --robot-plan ─────────────────────────────────────────────────────────────►  │  ║
+║  │                                                                                   │  ║
+║  │   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                   │  ║
+║  │   │    Track 1      │  │    Track 2      │  │    Track 3      │                   │  ║
+║  │   │    ────────     │  │    ────────     │  │    ────────     │                   │  ║
+║  │   │   [a → b → c]   │  │    [x → y]      │  │  [m → n → o]    │                   │  ║
+║  │   │                 │  │                 │  │                 │                   │  ║
+║  │   │  Scope:         │  │  Scope:         │  │  Scope:         │                   │  ║
+║  │   │  packages/sdk/**│  │  packages/cli/**│  │  apps/server/** │                   │  ║
+║  │   │                 │  │                 │  │                 │                   │  ║
+║  │   │  Agent:         │  │  Agent:         │  │  Agent:         │                   │  ║
+║  │   │  BlueLake       │  │  GreenCastle    │  │  RedStone       │                   │  ║
+║  │   └─────────────────┘  └─────────────────┘  └─────────────────┘                   │  ║
+║  │                                                                                   │  ║
+║  │   Output: Parallel execution tracks with non-overlapping file scopes              │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │                           PHASE 4: ORCHESTRATE                                    │  ║
+║  │                           Tool: orchestrator skill + Agent Mail                   │  ║
+║  ├───────────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                                   │  ║
+║  │   ┌─────────────────────────────────────────────────────────────────────────┐     │  ║
+║  │   │  ORCHESTRATOR                                                           │     │  ║
+║  │   │  ─────────────                                                          │     │  ║
+║  │   │  1. ensure_project(human_key="<project-path>")                          │     │  ║
+║  │   │  2. register_agent(name="Orchestrator", ...)                            │     │  ║
+║  │   │  3. send_message(thread_id=<epic>, "Kickoff: Track assignments")        │     │  ║
+║  │   │  4. Task() × 3 → Spawn parallel workers                                 │     │  ║
+║  │   └─────────────────────────────────────────────────────────────────────────┘     │  ║
+║  │                           │                                                       │  ║
+║  │          ┌────────────────┼────────────────┐                                      │  ║
+║  │          ▼                ▼                ▼                                      │  ║
+║  │   ┌────────────┐   ┌────────────┐   ┌────────────┐                                │  ║
+║  │   │ Task()     │   │ Task()     │   │ Task()     │                                │  ║
+║  │   │ BlueLake   │   │ GreenCastle│   │ RedStone   │                                │  ║
+║  │   │ Track 1    │   │ Track 2    │   │ Track 3    │                                │  ║
+║  │   └────────────┘   └────────────┘   └────────────┘                                │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                           PHASE 5: EXECUTE (Parallel Workers)                           ║
+║                           Tool: worker skill + All AGENTS.md tools                      ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║  ┌──────────────────────────────────────────────────────────────────────────────────┐   ║
+║  │                                                                                  │   ║
+║  │   Each worker executes beads in their track, using this loop:                    │   ║
+║  │                                                                                  │   ║
+║  │   ╔════════════════════════════════════════════════════════════════════════════╗ │   ║
+║  │   ║                      BEAD EXECUTION LOOP                                   ║ │   ║
+║  │   ║                      (Repeat for each bead in track)                       ║ │   ║
+║  │   ╠════════════════════════════════════════════════════════════════════════════╣ │   ║
+║  │   ║                                                                            ║ │   ║
+║  │   ║   ┌────────────────────────────────────────────────────────────────────┐   ║ │   ║
+║  │   ║   │  1. START BEAD                                                     │   ║ │   ║
+║  │   ║   ├────────────────────────────────────────────────────────────────────┤   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   │  register_agent(name="BlueLake", task="<bead-id>")                 │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  summarize_thread(thread_id="track:BlueLake:<epic>")               │   ║ │   ║
+║  │   ║   │  ┌──────────────────────────────────────────────────────────┐      │   ║ │   ║
+║  │   ║   │  │ Returns context from previous bead:                      │      │   ║ │   ║
+║  │   ║   │  │ • What was done                                          │      │   ║ │   ║
+║  │   ║   │  │ • Learnings & gotchas                                    │      │   ║ │   ║
+║  │   ║   │  │ • Recommendations for current bead                       │      │   ║ │   ║
+║  │   ║   │  └──────────────────────────────────────────────────────────┘      │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  fetch_inbox(agent_name="BlueLake")                                │   ║ │   ║
+║  │   ║   │  → Check for messages from orchestrator or other workers           │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  file_reservation_paths(paths=["packages/sdk/**"],                 │   ║ │   ║
+║  │   ║   │                         reason="<bead-id>", exclusive=true)        │   ║ │   ║
+║  │   ║   │  → Prevent conflicts with other workers                            │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  bd update <bead-id> --status in_progress                          │   ║ │   ║
+║  │   ║   │  bd show <bead-id> → Read requirements                             │   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   └────────────────────────────────────────────────────────────────────┘   ║ │   ║
+║  │   ║                                    │                                       ║ │   ║
+║  │   ║                                    ▼                                       ║ │   ║
+║  │   ║   ┌────────────────────────────────────────────────────────────────────┐   ║ │   ║
+║  │   ║   │  2. WORK ON BEAD                                                   │   ║ │   ║
+║  │   ║   ├────────────────────────────────────────────────────────────────────┤   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   │  Tools from AGENTS.md:                                             │   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   │  ┌──────────────────────────────────────────────────────────────┐  │   ║ │   ║
+║  │   ║   │  │ EXPLORE (gkg MCP)                                            │  │   ║ │   ║
+║  │   ║   │  │ • mcp__gkg__search_codebase_definitions → Find code          │  │   ║ │   ║
+║  │   ║   │  │ • mcp__gkg__get_definition → Jump to definition              │  │   ║ │   ║
+║  │   ║   │  │ • mcp__gkg__get_references → Find all usages                 │  │   ║ │   ║
+║  │   ║   │  └──────────────────────────────────────────────────────────────┘  │   ║ │   ║
+║  │   ║   │                              │                                     │   ║ │   ║
+║  │   ║   │                              ▼                                     │   ║ │   ║
+║  │   ║   │  ┌──────────────────────────────────────────────────────────────┐  │   ║ │   ║
+║  │   ║   │  │ EDIT (morph MCP)                                             │  │   ║ │   ║
+║  │   ║   │  │ • mcp__morph_mcp__edit_file → Fast, accurate edits           │  │   ║ │   ║
+║  │   ║   │  │   Uses "// ... existing code ..." placeholders               │  │   ║ │   ║
+║  │   ║   │  └──────────────────────────────────────────────────────────────┘  │   ║ │   ║
+║  │   ║   │                              │                                     │   ║ │   ║
+║  │   ║   │                              ▼                                     │   ║ │   ║
+║  │   ║   │  ┌──────────────────────────────────────────────────────────────┐  │   ║ │   ║
+║  │   ║   │  │ SEARCH (MCP Docker Toolkit)                                  │  │   ║ │   ║
+║  │   ║   │  │ • mcp__MCP_DOCKER__resolve-library-id → Get library ID first │  │   ║ │   ║
+║  │   ║   │  │ • mcp__MCP_DOCKER__get-library-docs → Library documentation  │  │   ║ │   ║
+║  │   ║   │  │ • mcp__MCP_DOCKER__web_search_exa → Real-time web search     │  │   ║ │   ║
+║  │   ║   │  └──────────────────────────────────────────────────────────────┘  │   ║ │   ║
+║  │   ║   │                              │                                     │   ║ │   ║
+║  │   ║   │                              ▼                                     │   ║ │   ║
+║  │   ║   │  ┌──────────────────────────────────────────────────────────────┐  │   ║ │   ║
+║  │   ║   │  │ UI (shadcn MCP + frontend-design skill)                      │  │   ║ │   ║
+║  │   ║   │  │ • mcp__shadcn__search_items_in_registries                    │  │   ║ │   ║
+║  │   ║   │  │ • mcp__shadcn__get_item_examples_from_registries             │  │   ║ │   ║
+║  │   ║   │  └──────────────────────────────────────────────────────────────┘  │   ║ │   ║
+║  │   ║   │                              │                                     │   ║ │   ║
+║  │   ║   │                              ▼                                     │   ║ │   ║
+║  │   ║   │  Periodically:                                                     │   ║ │   ║
+║  │   ║   │  • fetch_inbox() → Check for messages                              │   ║ │   ║
+║  │   ║   │  • If blocked → send_message(importance="high") to orchestrator    │   ║ │   ║
+║  │   ║   │  • If interface changed → notify other workers                     │   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   └────────────────────────────────────────────────────────────────────┘   ║ │   ║
+║  │   ║                                    │                                       ║ │   ║
+║  │   ║                                    ▼                                       ║ │   ║
+║  │   ║   ┌────────────────────────────────────────────────────────────────────┐   ║ │   ║
+║  │   ║   │  3. COMPLETE BEAD                                                  │   ║ │   ║
+║  │   ║   ├────────────────────────────────────────────────────────────────────┤   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   │  Verify & Close:                                                   │   ║ │   ║
+║  │   ║   │  • bun run check-types && bun run build                            │   ║ │   ║
+║  │   ║   │  • bd close <bead-id> --reason "Summary"                           │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  Report to Orchestrator:                                           │   ║ │   ║
+║  │   ║   │  send_message(                                                     │   ║ │   ║
+║  │   ║   │    to=["Orchestrator"],                                            │   ║ │   ║
+║  │   ║   │    thread_id="<epic-id>",                                          │   ║ │   ║
+║  │   ║   │    subject="[<bead-id>] COMPLETE",                                 │   ║ │   ║
+║  │   ║   │    body_md="Done: ... Next: <next-bead>"                           │   ║ │   ║
+║  │   ║   │  )                                                                 │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  Save Context for Next Bead:                                       │   ║ │   ║
+║  │   ║   │  send_message(                                                     │   ║ │   ║
+║  │   ║   │    to=["BlueLake"],  ◄─────── SELF-ADDRESSED!                      │   ║ │   ║
+║  │   ║   │    thread_id="track:BlueLake:<epic>",                              │   ║ │   ║
+║  │   ║   │    body_md="""                                                     │   ║ │   ║
+║  │   ║   │      ## Learnings                                                  │   ║ │   ║
+║  │   ║   │      - Pattern discovered: ...                                     │   ║ │   ║
+║  │   ║   │      ## Gotchas                                                    │   ║ │   ║
+║  │   ║   │      - Watch out for: ...                                          │   ║ │   ║
+║  │   ║   │      ## For Next Bead                                              │   ║ │   ║
+║  │   ║   │      - Recommendation: ...                                         │   ║ │   ║
+║  │   ║   │    """                                                             │   ║ │   ║
+║  │   ║   │  )                                                                 │   ║ │   ║
+║  │   ║   │                         │                                          │   ║ │   ║
+║  │   ║   │                         ▼                                          │   ║ │   ║
+║  │   ║   │  release_file_reservations(agent_name="BlueLake")                  │   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   └────────────────────────────────────────────────────────────────────┘   ║ │   ║
+║  │   ║                                    │                                       ║ │   ║
+║  │   ║                                    ▼                                       ║ │   ║
+║  │   ║   ┌────────────────────────────────────────────────────────────────────┐   ║ │   ║
+║  │   ║   │  4. NEXT BEAD                                                      │   ║ │   ║
+║  │   ║   ├────────────────────────────────────────────────────────────────────┤   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   │                    ┌─────────────────────┐                         │   ║ │   ║
+║  │   ║   │                    │ More beads in track?│                         │   ║ │   ║
+║  │   ║   │                    └──────────┬──────────┘                         │   ║ │   ║
+║  │   ║   │                     YES │           │ NO                           │   ║ │   ║
+║  │   ║   │                         ▼           ▼                              │   ║ │   ║
+║  │   ║   │              ┌──────────────┐  ┌──────────────────────┐            │   ║ │   ║
+║  │   ║   │              │ Loop back to │  │ Track Complete!      │            │   ║ │   ║
+║  │   ║   │              │ START BEAD   │  │ Report to orchestrator│           │   ║ │   ║
+║  │   ║   │              │ with context │  │ Return summary       │            │   ║ │   ║
+║  │   ║   │              │ from mail    │  └──────────────────────┘            │   ║ │   ║
+║  │   ║   │              └──────────────┘                                      │   ║ │   ║
+║  │   ║   │                                                                    │   ║ │   ║
+║  │   ║   └────────────────────────────────────────────────────────────────────┘   ║ │   ║
+║  │   ║                                                                            ║ │   ║
+║  │   ╚════════════════════════════════════════════════════════════════════════════╝ │   ║
+║  │                                                                                  │   ║
+║  └──────────────────────────────────────────────────────────────────────────────────┘   ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                           PHASE 6: MONITOR & RESOLVE                                    ║
+║                           Tool: orchestrator + Agent Mail                               ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │  ORCHESTRATOR (while workers execute)                                             │  ║
+║  ├───────────────────────────────────────────────────────────────────────────────────┤  ║
+║  │                                                                                   │  ║
+║  │  ┌─────────────────────────────────────────────────────────────────────────┐      │  ║
+║  │  │  Monitor Progress                                                       │      │  ║
+║  │  │  ─────────────────                                                      │      │  ║
+║  │  │  fetch_inbox(urgent_only=true) → Check for blockers                     │      │  ║
+║  │  │  search_messages(query="<epic>") → View all updates                     │      │  ║
+║  │  │  bv --robot-triage --graph-root <epic> → Check completion status        │      │  ║
+║  │  └─────────────────────────────────────────────────────────────────────────┘      │  ║
+║  │                                           │                                       │  ║
+║  │                                           ▼                                       │  ║
+║  │  ┌─────────────────────────────────────────────────────────────────────────┐      │  ║
+║  │  │  Handle Issues                                                          │      │  ║
+║  │  │  ─────────────                                                          │      │  ║
+║  │  │  If blocker → reply_message() with resolution                           │      │  ║
+║  │  │  If file conflict → coordinate between workers                          │      │  ║
+║  │  │  If cross-track dependency → notify waiting worker                      │      │  ║
+║  │  └─────────────────────────────────────────────────────────────────────────┘      │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                           │                                             ║
+║                                           ▼                                             ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                           PHASE 7: COMPLETE                                             ║
+║                           Tool: bd + Agent Mail                                         ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║  ┌───────────────────────────────────────────────────────────────────────────────────┐  ║
+║  │                                                                                   │  ║
+║  │  When all workers report track complete:                                          │  ║
+║  │                                                                                   │  ║
+║  │  1. Verify: bv --robot-triage | jq '.quick_ref.open_count' → Should be 0          │  ║
+║  │                                                                                   │  ║
+║  │  2. Announce:                                                                     │  ║
+║  │     send_message(                                                                 │  ║
+║  │       to=["BlueLake", "GreenCastle", "RedStone"],                                 │  ║
+║  │       thread_id="<epic-id>",                                                      │  ║
+║  │       subject="[<epic-id>] EPIC COMPLETE 🎉",                                     │  ║
+║  │       body_md="Track summaries, deliverables, learnings..."                       │  ║
+║  │     )                                                                             │  ║
+║  │                                                                                   │  ║
+║  │  3. Close: bd close <epic-id> --reason "All tracks complete"                      │  ║
+║  │                                                                                   │  ║
+║  └───────────────────────────────────────────────────────────────────────────────────┘  ║
+║                                                                                         ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                   THREAD HIERARCHY                                      ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║   Epic Thread: <epic-id>                                                                ║
+║   ├── Kickoff message (orchestrator)                                                    ║
+║   ├── [bead-a] COMPLETE (BlueLake)                                                      ║
+║   ├── [bead-x] COMPLETE (GreenCastle)                                                   ║
+║   ├── [bead-b] BLOCKED (BlueLake) ←→ Resolution (Orchestrator)                          ║
+║   ├── Interface change notification                                                     ║
+║   ├── [Track 1] COMPLETE (BlueLake)                                                     ║
+║   ├── [Track 2] COMPLETE (GreenCastle)                                                  ║
+║   ├── [Track 3] COMPLETE (RedStone)                                                     ║
+║   └── EPIC COMPLETE (Orchestrator)                                                      ║
+║                                                                                         ║
+║   Track Thread: track:BlueLake:<epic>         (BlueLake's context)                      ║
+║   ├── bead-a Complete - Context for bead-b                                              ║
+║   ├── bead-b Complete - Context for bead-c                                              ║
+║   └── bead-c Complete - Track summary                                                   ║
+║                                                                                         ║
+║   Track Thread: track:GreenCastle:<epic>      (GreenCastle's context)                   ║
+║   └── ...                                                                               ║
+║                                                                                         ║
+║   Track Thread: track:RedStone:<epic>         (RedStone's context)                      ║
+║   └── ...                                                                               ║
+║                                                                                         ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                   TOOL SUMMARY                                          ║
+╠═════════════════════════════════════════════════════════════════════════════════════════╣
+║                                                                                         ║
+║   ┌──────────────────┬────────────────────────────────────────────────────────────┐     ║
+║   │ Phase            │ Tools                                                      │     ║
+║   ├──────────────────┼────────────────────────────────────────────────────────────┤     ║
+║   │ CREATE           │ file-beads skill, bd create                                │     ║
+║   │ REVIEW           │ bv --robot-suggest/insights/priority, review-beads skill   │     ║
+║   │ PLAN             │ bv --robot-plan                                            │     ║
+║   │ ORCHESTRATE      │ orchestrator skill, Agent Mail, Task()                     │     ║
+║   │ EXECUTE          │ worker skill, gkg, morph, exa, shadcn, Agent Mail          │     ║
+║   │ MONITOR          │ Agent Mail (fetch_inbox, search_messages), bv --robot-triage│    ║
+║   │ COMPLETE         │ bd close, Agent Mail (send_message)                        │     ║
+║   └──────────────────┴────────────────────────────────────────────────────────────┘     ║
+║                                                                                         ║
+╚═════════════════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              ORCHESTRATOR                                   │
+│                              (Main Agent)                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  1. Analyze epic with bv                                                    │
+│  2. Plan parallel tracks                                                    │
+│  3. Spawn worker subagents via Task()                                       │
+│  4. Monitor progress via Agent Mail                                         │
+│  5. Handle cross-track blockers                                             │
+│  6. Announce completion                                                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+           │
+           │ Task() spawns parallel workers
+           ▼
+┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+│  BlueLake        │  │  GreenCastle     │  │  RedStone        │
+│  Track 1         │  │  Track 2         │  │  Track 3         │
+│  [a → b → c]     │  │  [x → y]         │  │  [m → n → o]     │
+├──────────────────┤  ├──────────────────┤  ├──────────────────┤
+│  For each bead:  │  │  For each bead:  │  │  For each bead:  │
+│  • Read context  │  │  • Read context  │  │  • Read context  │
+│  • Reserve files │  │  • Reserve files │  │  • Reserve files │
+│  • Do work       │  │  • Do work       │  │  • Do work       │
+│  • Report mail   │  │  • Report mail   │  │  • Report mail   │
+│  • Save context  │  │  • Save context  │  │  • Save context  │
+│  • Next bead     │  │  • Next bead     │  │  • Next bead     │
+└──────────────────┘  └──────────────────┘  └──────────────────┘
+           │                   │                   │
+           └───────────────────┼───────────────────┘
+                               ▼
+                    ┌─────────────────────┐
+                    │     Agent Mail      │
+                    │  ─────────────────  │
+                    │  Epic Thread:       │
+                    │  • Progress reports │
+                    │  • Bead completions │
+                    │  • Blockers         │
+                    │                     │
+                    │  Track Threads:     │
+                    │  • Bead context     │
+                    │  • Learnings        │
+                    └─────────────────────┘
+```
+
+---
+
+## Phase 1: CREATE
+
+**Tools:** `file-beads` skill + `bd`
+
+### Purpose
+
+Transform a plan or specification into structured beads with initial dependencies.
+
+### Commands
+
+```bash
+# Create epic
+bd create "Epic: Feature X" -t epic -p 0
+
+# Create child tasks
+bd create "Task A" -t task --blocks <epic-id>
+bd create "Task B" -t task --blocks <epic-id>
+bd create "Task C" -t task --deps <task-a-id>
+```
+
+### Alternative: Batch Creation
+
+Use the `file-beads` skill for batch creation from a plan document.
+
+### Output
+
+- `.beads/*.md` files with dependency structure
+
+---
+
+## Phase 2: REVIEW
+
+**Tools:** `bv` + `review-beads` skill
+
+### Purpose
+
+Validate and polish the dependency graph before execution.
+
+### Step 1: Automated Analysis (bv)
+
+```bash
+# Find missing dependencies
+bv --robot-suggest 2>/dev/null | jq '.suggestions.suggestions'
+
+# Detect cycles and bottlenecks
+bv --robot-insights 2>/dev/null | jq '{Cycles, Bottlenecks}'
+
+# Validate priorities
+bv --robot-priority 2>/dev/null | jq '.recommendations[:10]'
+```
+
+### Step 2: Apply Fixes
+
+```bash
+# Add missing dependency
+bd dep add <from-id> <to-id>
+
+# Remove to break cycle
+bd dep remove <from-id> <to-id>
+
+# Adjust priority
+bd update <id> --priority <new-priority>
+```
+
+### Step 3: Content Review
+
+For each issue, verify:
+
+- [ ] Title is action-oriented and specific
+- [ ] Description is clear and unambiguous
+- [ ] Acceptance criteria are defined and testable
+- [ ] Scope is appropriately sized
+
+### Output
+
+- Healthy graph (no cycles)
+- Polished issues ready for execution
+
+---
+
+## Phase 3: PLAN
+
+**Tools:** `bv`
+
+### Purpose
+
+Identify parallel execution tracks with non-overlapping file scopes.
+
+### Command
+
+```bash
+bv --robot-plan 2>/dev/null | jq '.plan.tracks'
+```
+
+### Output Example
+
+| Track | Beads     | File Scope        | Agent       |
+| ----- | --------- | ----------------- | ----------- |
+| 1     | a → b → c | `packages/sdk/**` | BlueLake    |
+| 2     | x → y     | `packages/cli/**` | GreenCastle |
+| 3     | m → n → o | `apps/server/**`  | RedStone    |
+
+### Rules
+
+- File scopes must NOT overlap
+- Each track gets a unique agent name (adjective+noun)
+- Beads within a track execute sequentially
+- Tracks execute in parallel
+
+---
+
+## Phase 4: ORCHESTRATE
+
+**Tools:** `orchestrator` skill + Agent Mail + `Task()`
+
+### Purpose
+
+Initialize project, spawn parallel workers, send kickoff message.
+
+### Step 1: Initialize
+
+```python
+# Ensure project exists
+ensure_project(human_key="/path/to/project")
+
+# Register orchestrator
+register_agent(
+  project_key="/path/to/project",
+  name="Orchestrator",
+  program="amp",
+  model="claude-sonnet-4",
+  task_description="Orchestrator for <epic-id>"
+)
+```
+
+### Step 2: Send Kickoff
+
+```python
+send_message(
+  to=["BlueLake", "GreenCastle", "RedStone"],
+  thread_id="<epic-id>",
+  subject="[<epic-id>] Work Started - Track Assignments",
+  body_md="""
+## Track Assignments
+| Track | Agent | Beads | Scope |
+|-------|-------|-------|-------|
+| 1 | BlueLake | a → b → c | packages/sdk/** |
+| 2 | GreenCastle | x → y | packages/cli/** |
+| 3 | RedStone | m → n → o | apps/server/** |
+
+Begin work!
+""",
+  importance="high"
+)
+```
+
+### Step 3: Spawn Workers (Parallel)
+
+```python
+# Spawn all workers in parallel
+Task(
+  description="Worker BlueLake: Track 1",
+  prompt="""
+You are agent BlueLake working on Track 1 of epic <epic-id>.
+
+## Setup
+1. Read /path/to/project/AGENTS.md for tool preferences
+2. Load the worker skill
+
+## Your Assignment
+- Beads (in order): <bead-a>, <bead-b>, <bead-c>
+- File scope: packages/sdk/**
+- Epic thread: <epic-id>
+- Track thread: track:BlueLake:<epic-id>
+
+## Protocol
+For EACH bead: START → WORK → COMPLETE → NEXT
+See worker skill for detailed steps.
+"""
+)
+
+# Repeat for other tracks...
+```
+
+---
+
+## Phase 5: EXECUTE (Workers)
+
+**Tools:** `worker` skill + All AGENTS.md tools
+
+### Purpose
+
+Each worker autonomously executes beads in their track.
+
+### Bead Execution Loop
+
+For EACH bead in the track:
+
+#### 5.1 START BEAD
+
+```python
+# 1. Register
+register_agent(name="BlueLake", task_description="<bead-id>")
+
+# 2. Read context from previous bead
+summarize_thread(thread_id="track:BlueLake:<epic-id>")
+
+# 3. Check inbox
+fetch_inbox(agent_name="BlueLake", include_bodies=True)
+
+# 4. Reserve files
+file_reservation_paths(
+  paths=["packages/sdk/**"],
+  reason="<bead-id>",
+  exclusive=True
+)
+
+# 5. Claim bead
+# bd update <bead-id> --status in_progress
+# bd show <bead-id>
+```
+
+#### 5.2 WORK ON BEAD
+
+**Use tools from AGENTS.md:**
+
+| Task           | Tool                                       |
+| -------------- | ------------------------------------------ |
+| Find code      | `mcp__gkg__search_codebase_definitions`    |
+| Get definition | `mcp__gkg__get_definition`                 |
+| Find usages    | `mcp__gkg__get_references`                 |
+| Edit file      | `mcp__morph_mcp__edit_file`                |
+| Search docs    | `mcp__MCP_DOCKER__web_search_exa`          |
+| UI components  | `mcp__shadcn__*` + `frontend-design` skill |
+
+**Periodically:**
+
+```python
+# Check for messages
+fetch_inbox(agent_name="BlueLake", since_ts="<start>")
+
+# If blocked
+send_message(
+  to=["Orchestrator"],
+  thread_id="<epic-id>",
+  subject="[<bead-id>] BLOCKED: <reason>",
+  importance="high"
+)
+
+# If interface changed
+send_message(
+  to=["GreenCastle", "RedStone"],
+  thread_id="<epic-id>",
+  subject="[<bead-id>] Interface Change: <what>",
+  importance="high"
+)
+```
+
+#### 5.3 COMPLETE BEAD
+
+```python
+# 1. Verify & close
+# bun run check-types && bun run build
+# bd close <bead-id> --reason "Summary"
+
+# 2. Report to orchestrator
+send_message(
+  to=["Orchestrator"],
+  thread_id="<epic-id>",
+  subject="[<bead-id>] COMPLETE",
+  body_md="Done: <summary>. Next: <next-bead>"
+)
+
+# 3. Save context for next bead (SELF-ADDRESSED!)
+send_message(
+  to=["BlueLake"],
+  thread_id="track:BlueLake:<epic-id>",
+  subject="<bead-id> Complete - Context for Next",
+  body_md="""
+## Learnings
+- <patterns discovered>
+
+## Gotchas
+- <things to watch out for>
+
+## For Next Bead
+- <recommendations>
+"""
+)
+
+# 4. Release reservations
+release_file_reservations(agent_name="BlueLake")
+```
+
+#### 5.4 NEXT BEAD
+
+- If more beads → Loop back to START BEAD
+- If track complete → Report to orchestrator, return summary
+
+---
+
+## Phase 6: MONITOR & RESOLVE
+
+**Tools:** Agent Mail + `bv`
+
+### Purpose
+
+Orchestrator monitors progress and handles issues.
+
+### Commands
+
+```python
+# Check for blockers
+fetch_inbox(agent_name="Orchestrator", urgent_only=True)
+
+# View all updates
+search_messages(query="<epic-id>")
+
+# Check completion status
+# bv --robot-triage --graph-root <epic-id> | jq '.quick_ref'
+```
+
+### Handle Issues
+
+| Issue                  | Action                               |
+| ---------------------- | ------------------------------------ |
+| Worker blocked         | `reply_message()` with resolution    |
+| File conflict          | Coordinate between workers           |
+| Cross-track dependency | Notify waiting worker when unblocked |
+
+---
+
+## Phase 7: COMPLETE
+
+**Tools:** `bd` + Agent Mail
+
+### Purpose
+
+Verify all work done, announce completion, close epic.
+
+### Steps
+
+```python
+# 1. Verify all done
+# bv --robot-triage --graph-root <epic-id> | jq '.quick_ref.open_count'
+# → Should be 0
+
+# 2. Announce completion
+send_message(
+  to=["BlueLake", "GreenCastle", "RedStone"],
+  thread_id="<epic-id>",
+  subject="[<epic-id>] EPIC COMPLETE 🎉",
+  body_md="""
+## Epic Complete
+
+### Track Summaries
+- Track 1 (BlueLake): <summary>
+- Track 2 (GreenCastle): <summary>
+- Track 3 (RedStone): <summary>
+
+### Deliverables
+- <what was built>
+
+### Learnings
+- <key insights>
+"""
+)
+
+# 3. Close epic
+# bd close <epic-id> --reason "All tracks complete"
+```
+
+---
+
+## Thread Hierarchy
+
+```
+Epic Thread: <epic-id>
+├── Kickoff message (Orchestrator)
+├── [bead-a] COMPLETE (BlueLake)
+├── [bead-x] COMPLETE (GreenCastle)
+├── [bead-b] BLOCKED (BlueLake) ←→ Resolution (Orchestrator)
+├── Interface change notification
+├── [Track 1] COMPLETE (BlueLake)
+├── [Track 2] COMPLETE (GreenCastle)
+├── [Track 3] COMPLETE (RedStone)
+└── EPIC COMPLETE (Orchestrator)
+
+Track Thread: track:BlueLake:<epic>
+├── bead-a Complete - Context for bead-b
+├── bead-b Complete - Context for bead-c
+└── bead-c Complete - Track summary
+
+Track Thread: track:GreenCastle:<epic>
+└── ...
+
+Track Thread: track:RedStone:<epic>
+└── ...
+```
+
+---
+
+## Tool Summary
+
+| Phase       | Tools                                                        |
+| ----------- | ------------------------------------------------------------ |
+| CREATE      | `file-beads` skill, `bd create`                              |
+| REVIEW      | `bv --robot-suggest/insights/priority`, `review-beads` skill |
+| PLAN        | `bv --robot-plan`                                            |
+| ORCHESTRATE | `orchestrator` skill, Agent Mail, `Task()`                   |
+| EXECUTE     | `worker` skill, gkg, morph, exa, shadcn, Agent Mail          |
+| MONITOR     | Agent Mail, `bv --robot-triage`                              |
+| COMPLETE    | `bd close`, Agent Mail                                       |
+
+---
+
+## Quick Reference Commands
+
+```bash
+# What to work on
+bv --robot-next
+
+# Get parallel tracks
+bv --robot-plan
+
+# Check graph health
+bv --robot-insights | jq '.Cycles'
+
+# Get priority recommendations
+bv --robot-priority
+
+# Check epic progress
+bv --robot-triage --graph-root <epic-id>
+```
+
+---
+
+## Skills Reference
+
+| Skill          | Use When                                        |
+| -------------- | ----------------------------------------------- |
+| `file-beads`   | Batch create beads from a plan                  |
+| `review-beads` | Polish beads with bv analysis + content quality |
+| `orchestrator` | Plan tracks, spawn workers, monitor progress    |
+| `worker`       | Execute beads with session management           |
+| `beads`        | General bd/bv reference                         |
+
+---
+
+## Context Persistence
+
+The key to multi-session execution is **self-addressed messages** in track threads:
+
+```python
+# After completing each bead, save context for next bead
+send_message(
+  to=["BlueLake"],        # ← SELF-ADDRESSED!
+  thread_id="track:BlueLake:<epic>",
+  body_md="Context for next bead..."
+)
+
+# At start of next bead, read previous context
+summarize_thread(thread_id="track:BlueLake:<epic>")
+```
+
+This ensures context flows between beads even across session boundaries.
+
+---
+
+## See Also
+
+This document integrates with the following Claude Skills:
+
+| Skill                                                           | Purpose                                         |
+| --------------------------------------------------------------- | ----------------------------------------------- |
+| [orchestrator](../.claude/skills/orchestrator/SKILL.md)         | Plan tracks, spawn workers, monitor progress    |
+| [worker](../.claude/skills/worker/SKILL.md)                     | Execute beads with session management           |
+| [planning](../.claude/skills/planning/SKILL.md)                 | Generate execution plans from features          |
+| [file-beads](../.claude/skills/file-beads/SKILL.md)             | Batch create beads from a plan                  |
+| [review-beads](../.claude/skills/review-beads/SKILL.md)         | Polish beads with bv analysis + content quality |
+| [beads](../.claude/skills/beads/SKILL.md)                       | General bd/bv reference                         |
+| [issue-resolution](../.claude/skills/issue-resolution/SKILL.md) | Systematic bug diagnosis and fixes              |
+
+### Tool Reference
+
+The tools referenced in this document are real MCP tools available in the Amp environment:
+
+- **`Task()`** - Amp's Task tool for spawning parallel subagents
+- **`skill()`** - Amp's skill loading function (e.g., `skill("worker")`)
+- **`mcp__gkg__*`** - Graph Knowledge Graph MCP for codebase exploration
+- **`mcp__morph_mcp__*`** - Morph MCP for fast file editing
+- **`mcp__MCP_DOCKER__*`** - Docker Toolkit MCP for web search and docs
+- **`mcp__shadcn__*`** - shadcn MCP for UI components
+- **`mcp__mcp_agent_mail__*`** - Agent Mail MCP for coordination
+
+All `bd` and `bv` commands are real CLI tools from the [beads](https://github.com/steveyegge/beads) project.