/create-beads-orchestration

name: create-beads-orchestration
description: Bootstrap lean multi-agent orchestration with beads task tracking. Use for projects needing agent delegation without heavy MCP overhead.
user-invocable: true

Create Beads Orchestration

Set up lightweight multi-agent orchestration with git-native task tracking for Claude Code.

What This Skill Does

This skill bootstraps a complete multi-agent workflow where:

• **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

Each task gets its own worktree at `.worktrees/bd-{BEAD_ID}/`, keeping main clean and enabling parallel work.

Beads Kanban UI

The setup will auto-detect [Beads Kanban UI](https://github.com/AvivK5498/Beads-Kanban-UI) and configure accordingly. If not found, you'll be offered to install it.

---

Step 0: Detect Setup State (ALWAYS RUN FIRST)

<detection-phase> **Before doing anything else, detect if this is a fresh setup or a resume after restart.**

Check for bootstrap artifacts:

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

**If `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

**If `FRESH_SETUP`:**

• This is a new installation
• Proceed to **Step 1: Get Project Info**

</detection-phase>

---

Workflow Overview

<mandatory-workflow> | Step | Action | When to Run | |------|--------|-------------| | 0 | Detect setup state | **ALWAYS** (determines path) | | 1 | Get project info from user | Fresh setup only | | 2 | Run bootstrap | Fresh setup only | | 3 | **STOP** - Instruct user to restart | Fresh setup only | | 4 | Run discovery agent | After restart OR if bootstrap already complete |

**The setup is NOT complete until Step 4 (discovery) has run.** </mandatory-workflow>

---

Step 1: Get Project Info (Fresh Setup Only)

<critical-step1> **YOU MUST GET PROJECT INFO AND DETECT/ASK ABOUT KANBAN UI BEFORE PROCEEDING TO STEP 2.**

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 </critical-step1>

1.1 Get Project Directory and Name

Ask the user or auto-detect from package.json/pyproject.toml.

1.2 Detect or Install Kanban UI

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

**If KANBAN_FOUND** → Use `--with-kanban-ui` flag. Tell the user: > Detected Beads Kanban UI. Configuring worktree management via API.

**If KANBAN_NOT_FOUND** → Ask:

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

---

Step 2: Run Bootstrap

# With Kanban UI:
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# Without Kanban UI (git worktrees only):
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

The bootstrap script will: 1. Install beads CLI (via brew, npm, or go) 2. Initialize `.beads/` directory 3. Copy agent templates to `.claude/agents/` 4. Copy hooks to `.claude/hooks/` 5. Configure `.claude/settings.json` 6. Create `CLAUDE.md` with orchestrator instructions 7. Update `.gitignore`

**Verify bootstrap completed successfully before proceeding.**

---

Step 3: STOP - User Must Restart

<critical> **YOU MUST STOP HERE AND INSTRUCT THE USER TO RESTART CLAUDE CODE.**

Tell the user:

> **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.**

**DO NOT proceed to Step 4 in this session. The restart is mandatory.** </critical>

---

Step 4: Run Discovery (After Restart OR Detection)

<post-restart> **Run this step if:**

• Step 0 detected `BOOTSTRAP_COMPLETE`, OR
• User returned after restart and said "continue setup" or ran `/create-beads-orchestration` again

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"
)

Discovery will:

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

3. 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>

---

What This Creates

• **Bea