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