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

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

  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:

  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