Skip to content

Agent Orchestrator v2 Runbook

Purpose: - operate the coordinated multi-agent execution loop after human signoff, - keep queue state, handoff evidence, review routing, and merge-ready checks auditable, - preserve human-gated release promotion.

Use with: - doc/governance/Agent_Orchestrator_v2_Coordinated_Execution.md - doc/governance/Agent_Queue_Structured_Store_v1.md - doc/governance/Multi_Agent_Lane_Worktrees_v1.md - doc/governance/Platform_Control_Release_Promotion_Policy.md

1. Normal Path

  1. Sync the coordinator checkout:
git fetch origin
git pull --ff-only origin master
make queue-prune-stale ACTOR=coordinator
make orchestrator-status
  1. Review dispatch recommendations:
make orchestrator-tick
  1. Preflight the target lane before assigning work:
scripts/ops/agent_session_adapter.sh preflight --role B-ui
  1. Claim the task:
make queue-claim ROLE=B-ui OWNER=B TASK_ID=<task-id>
  1. Launch or resume the lane:
scripts/ops/agent_session_adapter.sh launch --role B-ui --task-id <task-id>
  1. Agent implements in the role worktree, commits, and records evidence:
make queue-record-evidence TASK_ID=<task-id> COMMAND_TEXT="pnpm --dir packages/web typecheck" RESULT=pass
make queue-record-handoff TASK_ID=<task-id> OWNER=B BRANCH=agent/B-ui COMMIT=<sha> COMMANDS="..." RESULTS="..." CHANGED_FILES="..."
  1. Route review:
make queue-route-review TASK_ID=<task-id> REF=<sha>
  1. Record required reviews:
make queue-record-review TASK_ID=<task-id> REVIEWER_ROLE=D-arch REVIEWER=D STATUS=approved COMMIT=<sha> NOTE="No findings."
make queue-record-review TASK_ID=<task-id> REVIEWER_ROLE=E-governance REVIEWER=E STATUS=approved COMMIT=<sha> NOTE="Gates sufficient."
  1. Verify merge readiness:
make queue-merge-ready TASK_ID=<task-id> REF=<sha>
  1. Merge to master using the coordinator checkout, then mark done:
git switch master
git pull --ff-only origin master
git merge --ff-only <role-branch-or-sha>
git push origin master
make queue-set-status TASK_ID=<task-id> STATUS=done OWNER=<owner> BRANCH=<branch> COMMIT=<sha>
make queue-git-check

2. Blocked Path

Use blocked when work requires an external decision or dependency:

make queue-set-status TASK_ID=<task-id> STATUS=blocked OWNER=<owner> BRANCH=<branch>

Common blockers: - backend contract not merged, - product/architecture decision missing, - dirty lane worktree, - failing environment dependency, - merge conflict from dependency-order mismatch.

Do not force a task to done to hide a blocker. Create or link the upstream task.

3. Review Path

Review routing is changed-file based.

Critical scopes require D/E review: - doc/api/** - doc/architecture/** - doc/governance/** - scripts/ci/** - security/auth/billing/provisioning/terminal/node-agent/release-runtime paths

No self-approval: - implementation role cannot approve its own critical-scope change, - same-model review is allowed only with an explicit exception note.

If review requests changes:

make queue-record-review TASK_ID=<task-id> REVIEWER_ROLE=E-governance REVIEWER=E STATUS=changes_requested NOTE="..."

The implementation role fixes, records new evidence, and asks for review again.

4. Failed-Agent Path

If an agent stalls, crashes, or loses context:

  1. Stop dispatching new work to that lane.
  2. Inspect the lane state:
scripts/ops/agent_session_adapter.sh status --role B-ui
git -C ../gpuas-B-ui status --short --branch
  1. If there is uncommitted work, preserve it with a normal commit or patch before reassigning.
  2. If work cannot continue safely, mark the task blocked with the reason and create a follow-up.

Never reset a role worktree destructively unless the human owner explicitly approves.

5. Merge-Ready Path

make queue-merge-ready verifies: - queue definition/state/cross-reference validation, - handoff evidence exists, - command evidence exists, - required reviews are approved, - branch/ref is based on origin/master, - coordinator worktree is clean.

It does not promote or deploy release branches.

6. Queue DB Recovery

If queue commands fail because local SQLite state is stale:

make queue-prune-stale ACTOR=coordinator
bash scripts/ci/agent_queue_validate.sh

If the SQLite DB is corrupt or unwritable:

  1. Capture the failing DB path:
ruby scripts/ops/agent_queue_store.rb --queue-file doc/governance/Agent_Work_Queue.yaml db-path
  1. Move the DB aside, do not delete it:
mv <db-path> <db-path>.broken.$(date -u +%Y%m%dT%H%M%SZ)
  1. Re-run validation. The store will recreate from YAML definitions/state:
bash scripts/ci/agent_queue_validate.sh

This is a rollback to YAML-derived state, not a release promotion.

7. Release Promotion Handoff

Release promotion remains human-gated.

After work is merged to master, prepare release evidence: - source SHA, - acceptance checks, - required reviews, - known risks, - rollback plan.

Then follow:

make platform-control-local-preflight
scripts/ci/platform_control_promote_release_branch.sh origin/master
PLATFORM_CONTROL_RELEASE_MODE=deploy PLATFORM_CONTROL_RELEASE_PROFILE=standard scripts/ci/gitlab_pipeline_trigger.sh

Do not hand-edit release/platform-control. Do not promote release-only fixes that are not already in master.