• Orchestrator (you) investigates issues, manages tasks, delegates implementation
• Supervisors (specialized agents) execute fixes in isolated worktrees
• Beads CLI tracks all work with git-native task management
• Hooks enforce workflow discipline automatically

.worktrees/bd-{BEAD_ID}/

ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"

BOOTSTRAP_COMPLETE

• Bootstrap already ran in a previous session
• Skip directly to Step 4: Run Discovery
• Do NOT ask for project info or run bootstrap again

FRESH_SETUP

• This is a new installation
• Proceed to Step 1: Get Project Info </detection-phase>

1. Project directory: Where to install (default: current working directory)
2. Project name: For agent templates (will auto-infer from package.json/pyproject.toml if not provided)
3. Kanban UI: Auto-detect, or ask the user to install

which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"

--with-kanban-ui

Detected Beads Kanban UI. Configuring worktree management via API.

AskUserQuestion(
  questions=[
    {
      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
      "header": "Kanban UI",
      "options": [
        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
      ],
      "multiSelect": false
    }
  ]
)

• If "Yes" → Run

  npm install -g beads-kanban-ui

  , then use

  --with-kanban-ui

  flag
• If "Skip" → do NOT use

  --with-kanban-ui

  flag

Setup phase complete. You MUST restart Claude Code now.

The new hooks and MCP configuration will only load after restart.

After restarting:

1. Open this same project directory
2. Tell me "Continue orchestration setup" or run

   /create-beads-orchestration

   again
3. I will run the discovery agent to complete setup

Do not skip this restart - the orchestration will not work without it.

1. Verify bootstrap completed (check for

   .claude/agents/scout.md

   ) - already done in Step 0
2. Run the discovery agent:

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

• Scan package.json, requirements.txt, Dockerfile, etc.
• Fetch specialist agents from external directory
• Inject beads workflow into each supervisor
• Write supervisors to

  .claude/agents/

1. After discovery completes, tell the user:

Orchestration setup complete!

Created supervisors: [list what discovery created]

You can now use the orchestration workflow:

• Create tasks with

  bd create "Task name" -d "Description"

• The orchestrator will delegate to appropriate supervisors
• All work requires code review before completion </post-restart>

• Beads CLI for git-native task tracking (one bead = one worktree = one task)
• Core agents: scout, detective, architect, scribe, code-reviewer (all run via Claude Task)
• Discovery agent: Auto-detects tech stack and creates specialized supervisors
• Hooks: Enforce orchestrator discipline, code review gates, concise responses
• Worktree-per-task workflow: Isolated development in

  .worktrees/bd-{BEAD_ID}/

--with-kanban-ui

• Worktrees created via API (localhost:3008) with git fallback
• Requires Beads Kanban UI running

--with-kanban-ui

• Worktrees created via raw git commands

1. Create epic:

   bd create "Feature name" -d "Description" --type epic

2. Create design doc (if needed): Dispatch architect to create

   .designs/{EPIC_ID}.md

3. Link design:

   bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"

4. Create children with dependencies:
   bash

   bd create "DB schema" -d "..." --parent {EPIC_ID}              # BD-001.1
   bd create "API endpoints" -d "..." --parent {EPIC_ID} --deps BD-001.1  # BD-001.2
   bd create "Frontend" -d "..." --parent {EPIC_ID} --deps BD-001.2       # BD-001.3

5. Dispatch sequentially: Use

   bd ready

   to find unblocked tasks (each child gets own worktree)
6. User merges each PR: Wait for child's PR to merge before dispatching next
7. Close epic:

   bd close {EPIC_ID}

   after all children merged

• Schema definitions (exact column names, types)
• API contracts (endpoints, request/response shapes)
• Shared constants/enums
• Data flow between layers

• enforce-sequential-dispatch.sh: Blocks dispatch if task has unresolved blockers
• enforce-bead-for-supervisor.sh: Requires BEAD_ID for all supervisors
• validate-completion.sh: Verifies worktree, push, bead status before supervisor completes

• beads CLI: Installed automatically by bootstrap (via brew, npm, or go)