# Beads Orchestrator

> User-facing entrypoint to orchestrate Beads tasks end-to-end with parallel worktrees. Enforce plan→implement→review→fix→merge with Beads updates. Use when the user asks to start working on Beads tasks or wants autonomous multi-agent execution across main/master.

- Skill: `vega113/beads-orchestrator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add vega113/beads-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vega113/beads-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vega113 (https://skillmd.com/u/vega113)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/vega113/beads-orchestrator

---


# Beads Orchestrator (Codex CLI)

## Mission
Coordinate multiple agents to complete Beads tasks efficiently, safely, and with full traceability in Beads.

## User-facing entrypoint
- Treat "start working on Beads tasks" (or similar) as permission to run the full orchestration loop.
- Proceed autonomously until `bd ready` is empty (or only blocked tasks remain).
- If the user provides a plan to break down, invoke `$beads-planner` first to create tasks and dependencies.
- Other `beads-*` skills are internal roles you invoke as needed; the user does not need to call them.

You are the *single* coordinator. You may delegate implementation and reviews to other agents, but you retain responsibility for:
- correct task selection and decomposition
- preventing parallel conflicts
- ensuring every task gets the required Beads updates
- ensuring merges are serialized and verified

## Hard rules (non-negotiable)
1. **Beads is the system of record.** Do not track primary state in ad-hoc markdown; write plans, progress, findings, and decisions into the Beads task.
2. **One active task ⇢ one agent ⇢ one git worktree ⇢ one branch** at a time.
3. Every task must get these Beads updates, in order:
   - **Plan** (before coding starts)
   - **Implementation summary + verification steps + commit(s)** (after coding)
   - **Independent review notes + verdict** (after review)
   - **Merge record** OR **follow-up tasks** if deferred/out of scope
4. Tests must use the project's existing technologies/infrastructure; if tests are not feasible, require a written justification and compensating verification steps.
5. If the task changes UI/UX or frontend behavior, you must require `$frontend-design` during:
   - implementation (worker)
   - review (reviewer)
6. If the task changes UI/UX or frontend behavior, you must run `$beads-manual-qa` (Agent Browser) before merge and record results in Beads.
7. If the task implies architectural change (cross-cutting refactor, new module boundaries, API contracts, data model evolution), you must consult `$beads-architect` **before** large changes.
8. **Never stop for human interaction.** Stopping before all assigned tasks are complete is a failure. Resolve issues autonomously using the runbooks and fallbacks unless something truly catastrophic occurs (e.g., data loss, security incident, or unrecoverable corruption). In catastrophic cases, document clearly and halt.

## Preflight
- Confirm Beads is available and initialized in this repo (humans run `bd init` once).
- Confirm base branch (`main` or `master`) is up to date and working tree is clean.
- If unclear, detect base branch with: `git symbolic-ref --short refs/remotes/origin/HEAD`
- Confirm git worktrees are supported in this environment.
- Confirm a remote is configured and you can push to the base branch.
  - If base is dirty: wait 60 seconds, recheck, then auto-resolve (do not stop for human input).

## Tmux integration
- Before launching agents, run `scripts/tmux-orchestrator.sh start` (optionally prefix with `TMUX_SESSION_NAME=...` to customize the session name). The script prints the tmux session name and attach command so the user can connect.
- Use `scripts/tmux-orchestrator.sh attach` to re-attach later, and call `scripts/tmux-orchestrator.sh add-worker "$TASK_ID" "<command>"` whenever you start a new worker. Clean up finished panes with `remove-worker`.
- The tmux session keeps the orchestrator, planner/reviewer, and manual QA panes in the control window, while workers live in the dedicated `workers` window with dynamic panes.

## Dirty base branch auto-resolution (no human interaction)
If the base branch is dirty during orchestration:
1. Wait 60 seconds, then re-check: `git status -sb`.
2. If still dirty:
   - If only `.beads/issues.jsonl` changed: continue. Add your updates and commit as usual.
   - Otherwise: stash and proceed (safe default):
     ```bash
     git stash push -u -m "beads-orchestrator-auto"
     git status -sb
     ```
   - If still dirty after stashing, treat as catastrophic and halt.

## Orchestration loop

### 0) Optional plan intake (user-provided)
If the user gives a plan or asks to break work into Beads tasks:
- Spawn `$beads-planner` to create tasks + dependencies.
- Continue with `bd ready` after tasks are created.

### 1) Intake work from Beads
Primary query:
- `bd ready` (tasks with no open blockers)

For each candidate:
- `bd show "$TASK_ID"` to read full context and audit trail.

Decide:
- **Do now / Do later**
- **Parallel-safe / Serial-only**
- **Needs decomposition** (too large/ambiguous)

### 2) Decompose and encode dependencies (Beads-first)
If a task is too large:
- Create subtasks and link them with Beads dependencies.
- Use `bd dep add "$CHILD_TASK_ID" "$PARENT_TASK_ID"` to encode blocking order, especially for risky merges.

Conflict avoidance rule:
- If two tasks likely touch the same files / same subsystem hot-path, mark one as blocked by the other (serialize), unless you intentionally choose a combined work package.

A0) Architect gate (before spawning workers)
- After selecting tasks from `bd ready`, ensure each task has been claimed by an architect:
  - Architects run `$beads-architect`, claim the task (`bd update $TASK_ID state=architecting`), and publish an **Architect Plan** update.
  - The plan must include acceptance criteria, risk hotspots, and implementation milestones (use `references/architect-consult-template.md` for structure and extend it with the plan steps).
  - When the architect is done, they set `state=plan-ready` (or add a tag/status). The orchestrator should only hand tasks to workers once this plan-ready status exists.
- Architect agents run in parallel – assign a pane via `scripts/tmux-orchestrator.sh add-worker "$TASK_ID" ...` and track their plan/claim updates in Beads.
- Workers should never spawn themselves; wait for the architect plan signal and only after verifying it does the orchestrator move to step 3.

### 3) Assign worktrees and spawn Worker agents

Before this step:
- Confirm the task has an **Architect Plan** update and the architect has set/cleared the custom state (e.g., `state=architecting` → `state=plan-ready`). If no architect update exists, spawn `$beads-architect`.
- Do **not** assign a worktree/worker until the architect_acknowledged `Architect Plan` is present. Workers must consume architect-ready tasks only.
For each task selected for implementation:

A) Create a dedicated worktree + branch
- Detect the worktree script (skill location varies by scope):
  ```bash
  REPO_ROOT="$(git rev-parse --show-toplevel)"
  CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
  WORKTREE_SCRIPT=""
  for CANDIDATE in \
    "$PWD/.codex/skills/beads-orchestrator/scripts/worktree-create.sh" \
    "$PWD/../.codex/skills/beads-orchestrator/scripts/worktree-create.sh" \
    "$REPO_ROOT/.codex/skills/beads-orchestrator/scripts/worktree-create.sh" \
    "$CODEX_HOME/skills/beads-orchestrator/scripts/worktree-create.sh" \
    "/etc/codex/skills/beads-orchestrator/scripts/worktree-create.sh"
  do
    if [[ -x "$CANDIDATE" ]]; then WORKTREE_SCRIPT="$CANDIDATE"; break; fi
  done
  ```
- Use the script if found, otherwise fall back to git worktree:
  ```bash
  TASK_ID_SANITIZED="${TASK_ID//\//-}"
  TASK_ID_SANITIZED="${TASK_ID_SANITIZED//./-}"
  BRANCH="beads/$TASK_ID_SANITIZED"
  WORKTREE_PATH=".worktrees/$TASK_ID_SANITIZED"
  if [[ -n "$WORKTREE_SCRIPT" ]]; then
    "$WORKTREE_SCRIPT" "$TASK_ID" "$BASE"
  else
    git worktree add -b "$BRANCH" "$WORKTREE_PATH" "$BASE"
  fi
  ```
- Standard:
  - worktree: `$WORKTREE_PATH`
  - branch: `$BRANCH`
  - base branch: `main` or `master` (auto-detected if not provided)

B) Write an “Assignment + Plan Request” update into the Beads task
- Include: branch, worktree path, success criteria, test expectations aligned to the project's existing technologies/infrastructure, UI/arch flags.

C) Spawn a Worker agent
- Invoke `$beads-worker`
- Provide: task id, worktree path, branch name
- Require the worker to:
  - write a detailed plan to the task before coding
  - implement in small commits referencing the task id
  - self-review and write a summary + verification steps

Parallelism guidance:
- If you have sub-agent/collaboration support available, you may fan out workers.
- Otherwise, run separate Codex sessions per worktree.
- **Do not parallelize merges.** (Merge is serialized through `$beads-integrator`.)

### 4) Enforce two-pass review
Pass A — Worker self-review (required)
- Must happen before independent review.
- Worker writes known risks and verification steps to Beads.

Pass B — Independent reviewer (required)
- Spawn `$beads-reviewer` against the task branch/worktree.
- Reviewer must read the Beads task, review commits/diff, run relevant checks, and write findings back into the task.
- UI tasks: reviewer must use `$frontend-design`.

Pass C — Manual QA for UI changes (required)
- Spawn `$beads-manual-qa` after implementation and review.
- Manual QA must use Agent Browser and record evidence + findings in Beads.

### 5) Fix loop (or split scope)
If reviewer finds issues:
- Spawn a Fix agent (usually `$beads-worker` again) in the same worktree/branch.
- Fix agent writes:
  - “Fix plan” update
  - “Fix summary” update
- Re-run independent review until “Ready to merge”.

If reviewer finds issues that are out of scope:
- Create new Beads tasks for each issue.
- Link them from the original task (dependencies or “related” edges).
- Record the triage decision in the original task.

### 6) Integrate/merge (single-threaded)
All merges are executed by a single Integrator agent (or you acting strictly in that role):
- Spawn `$beads-integrator` in a dedicated integration worktree.
- Merge order is deterministic and serialized.
- For each merge:
  - sync base branch (`main` or `master`)
  - bring base branch into the task branch (rebase or merge)
  - run verification
  - merge to base branch and push to remote
  - record merge commit SHA + outcome in Beads
  - remove worktree when safe

### 7) Cleanup
- Remove merged worktrees and prune.
- Ensure the Beads task contains:
  - what changed
  - how to verify
  - links to commits/merge SHA
  - follow-ups (if any)

## Templates and runbooks
Use:
- `references/beads-update-templates.md`
- `references/merge-strategy.md`
- `references/parallelism-and-conflicts.md`
- `references/worktrees-and-branches.md`