create-beads-orchestration

Create Beads Orchestration

Set up lightweight multi-agent orchestration with git-native task tracking and mandatory code review gates.

---

CRITICAL: Mandatory 4-Step Workflow

DO NOT:

• Skip asking for project info
• Skip asking about provider delegation (Claude-only vs External providers)
• Continue after bootstrap without telling user to restart
• Forget to run discovery after restart
• Consider setup complete until discovery has run

The setup is NOT complete until Step 4 (discovery) has run.

---

Step 1: Get Project Info

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. Provider delegation: MANDATORY - You MUST use AskUserQuestion for this choice

1.1 Get Project Directory and Name

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

1.2 MANDATORY: Ask Provider Delegation Choice

Do NOT skip this. Do NOT assume a default. Do NOT proceed without the user's explicit choice.

AskUserQuestion(
  questions=[{
    "question": "How should read-only agents (scout, detective, architect, scribe, code-reviewer) be executed?",
    "header": "Providers",
    "options": [
      {"label": "Claude only (Recommended)", "description": "All agents run via Claude Task(). Simpler setup, no external dependencies."},
      {"label": "External providers", "description": "Delegate to Codex CLI (with Gemini fallback). Requires codex login and optional gemini CLI."}
    ],
    "multiSelect": false
  }]
)

After user answers:

• If "Claude only" → use --claude-only flag in bootstrap
• If "External providers" → do NOT use --claude-only flag

DO NOT proceed to Step 2 until you have the provider choice from the user.

---

Step 2: Clone and Run Bootstrap

git clone --depth=1 https://github.com/AvivK5498/The-Claude-Protocol "${TMPDIR:-/tmp}/beads-orchestration-setup"

# If user selected "Claude only":
python3 "${TMPDIR:-/tmp}/beads-orchestration-setup/bootstrap.py" \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --claude-only

# If user selected "External providers":
python3 "${TMPDIR:-/tmp}/beads-orchestration-setup/bootstrap.py" \
  --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. Set up .mcp.json for provider_delegator
7. Create CLAUDE.md with orchestrator instructions
8. Update .gitignore

Verify bootstrap completed successfully before proceeding.

---

Step 3: STOP - User Must Restart

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.

---

Step 4: Run Discovery (After Restart)

1. Verify bootstrap completed (check for .claude/agents/scout.md)
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

---

Cleanup (Optional)

rm -rf "${TMPDIR:-/tmp}/beads-orchestration-setup"

---

What This Creates

• Beads CLI for git-native task tracking (one bead = one branch = one task)
• Core agents: scout, detective, architect, scribe, code-reviewer
• Discovery agent: Auto-detects tech stack and creates specialized supervisors
• Hooks: Enforce orchestrator discipline, code review gates, concise responses
• Branch-per-task workflow: Parallel development with automated merge conflict handling

With --claude-only (default):

• All agents run via Claude Task() - no external dependencies

With external providers:

• MCP Provider Delegator enables Codex→Gemini→Claude fallback chain
• Additional enforcement hooks for provider delegation

Requirements

Claude only mode (default):

• beads CLI: Installed automatically (or manually via brew/npm/go)
• uv: Python package manager (only if using external providers)

External providers mode:

• Codex CLI: codex login for authentication (primary provider)
• Gemini CLI: Optional fallback when Codex hits rate limits
• uv: Python package manager for MCP server

More Information

See the full documentation: https://github.com/AvivK5498/The-Claude-Protocol