Skip to content

Multi-Agent Execution Playbook

Purpose: - Define how multiple coding agents work in parallel without corrupting history or stepping on each other. - Keep contract-first and test gates enforceable while increasing throughput.

Scope: - Applies to all concurrent agent workstreams in this repo. - Queue source of truth: doc/governance/Agent_Work_Queue.yaml (validated by scripts/ci/agent_queue_validate.sh). - Completed-history archive: doc/governance/archive/Agent_Work_Queue_2026-03-09.yaml (reference only; never claim work from archive files). - Queue storage evolution: doc/governance/Agent_Queue_Structured_Store_v1.md. - Review workflow extension: doc/governance/Multi_Agent_Review_Model.md (review-lane extension reference). - Persistent lane/worktree helper model: doc/governance/Multi_Agent_Lane_Worktrees_v1.md. - Pre-MVP implementation discipline: doc/governance/Pre_MVP_Simplification_Policy.md. - Task authoring standard: doc/governance/Task_Authoring_Standard.md (required task context, invariants, and handoff evidence format).

1. Workstream Model

Use one persistent git worktree per role/agent and keep work isolated by directory: - $WORKTREE_ROOT/gpuas-A-backend - $WORKTREE_ROOT/gpuas-B-ui - $WORKTREE_ROOT/gpuas-C-ops

Each worktree tracks its own branch (recommended): - agent/A-backend - agent/B-ui - agent/C-ops

Do not run multiple agents in the same filesystem checkout.

Path configuration: - Set WORKTREE_ROOT once per machine (example: $HOME/dev/worktrees). - If unset, default to the parent of the main checkout.

2. Ownership Boundaries

Before coding, assign each workstream: - Owned files/directories (hard boundary) - Contract touchpoints (OpenAPI/AsyncAPI/schema/docs) - Required tests and gates

Preferred ownership split: - Agent A: backend provisioning + worker internals - Agent B: web UI + e2e - Agent C: ops/observability + runbooks + infra docs

Current queue-aligned phase ownership (authoritative examples): - Phase 7 provisioning hardening: A-P7-* (Agent A), C-OPS-00{1..3} (Agent C), dependent B-UX-* (Agent B). - Phase 9C terminal Option C extraction: A-P9C-* (Agent A) then C-OPS-00{4..5} (Agent C). - Agent B must not implement terminal UX assumptions that depend on Option C runtime behavior until A-P9C-001 is merged.

If a file must be co-edited, assign a primary owner and require rebasing before merge.

3. Contract-First Merge Order

For cross-cutting changes, merge in this order: 1. Contracts/docs (doc/api/*.yaml, doc/architecture/*.md, schema/spec deltas) 2. Generated artifacts (make codegen) 3. Backend/frontend implementations 4. Integration/e2e tests

No implementation PR merges before corresponding contract changes are present.

UI/Backend Contract Boundary (Symmetric Rule)

  • UI agents must not change API/event contracts directly; they raise a contract request to Architecture/Governance.
  • Backend agents must not introduce UX-impacting contract changes unilaterally; they raise the change to Architecture/Governance and notify UI owner before implementation.
  • Architecture/Governance owns final contract decision (accept/defer/reject) and updates contract docs first.
  • Implementation starts only after contract docs are updated and dependency order is reflected in queue tasks.

4. Daily Parallel Cadence

Each agent should run this loop: 1. Run role preflight (make agent-preflight ROLE=<role>) 2. Sync local worktree branch with master at start of cycle 3. Implement one vertical slice 4. Run owned tests locally 5. Commit with narrow scope 6. Push worktree branch 7. Update queue status and metadata

Mandatory queue synchronization: 8. Update task status through the supported queue utilities (make queue-set-status) at each handoff. 9. If blocked by dependency, set blocked immediately and reference blocking task ID in handoff notes.

5. Conflict Policy

If conflicts occur: - Rebase worktree branch onto master; do not merge master repeatedly into role branches. - Keep commits scoped; avoid unrelated file churn. - If conflict touches contracts, pause and resolve contract source-of-truth first.

Never resolve conflicts by dropping tests or removing gate checks.

If conflict is between agents on the same phase boundary: - Resolve in dependency order from queue (depends_on), not by who pushed first. - For terminal Option C work, backend extraction (A-P9C-001) wins over UI/ops branch assumptions.

6. CI/Gate Expectations Per Agent PR

Minimum per PR: - go test or pnpm test for owned area - lint for owned area - contract/codegen validation when touching doc/api/* - integration/e2e tests when changing async workflows or auth/session paths

Required documentation updates when behavior changes: - queue definition/state model and any required snapshot/export path per doc/governance/Agent_Queue_Structured_Store_v1.md - relevant phase in doc/Implementation_Roadmap.md

Queue acceptance checks policy: - acceptance_checks entries must be executable shell commands, not prose. - Prefer make ... commands or concrete go test / pnpm ... commands. - A task cannot be marked done unless its acceptance command list was run and recorded in handoff. - A task cannot be marked done if the change only masks a symptom while leaving the upstream root cause unresolved.

Implementation reality-check policy (required for high-risk tasks): - Applies to terminal/auth/provisioning/security/runtime tasks. - A task cannot be marked done with spec/tests alone; it must include: - at least one code-anchor evidence command (for example rg -q "terminal.open" cmd/node-agent/catalog.go), and - at least one runtime-path validation command (unit/integration/e2e or environment-mode smoke) that proves the active path is exercised. - If runtime path is intentionally deferred, the task status must be blocked with explicit blocker/task dependency; do not mark done. - Reviewer feedback must explicitly classify completion as: - implemented (runtime path present), or - design-only (spec/docs only, not executable path).

7. Handoff Format

Each agent handoff must include: - Commits pushed - Files changed - Tests run (exact commands) - Remaining risks/blockers - Next recommended slice

Use this exact structure to keep handoffs machine- and human-readable.

Queue fields to include in handoff header: - task_id - status (in_progress / blocked / done) - depends_on satisfaction (yes / no)

8. Anti-Patterns

Do not: - Commit another agent's staged/unrelated changes. - Edit generated files manually without regenerating from contract. - Push large mixed commits spanning backend + UI + ops unless explicitly coordinated. - Mark roadmap items complete without runnable validation. - Close incidents with local/downstream workarounds while the owning upstream defect remains open.

8a. Root-Cause Evidence Requirement

For defect tasks, every handoff must include: - root cause statement (single sentence), - owning layer/file where root cause was fixed, - proof command showing the root-cause path is now covered (test or runtime check).

Symptom mitigation without this evidence must remain in_progress or blocked, never done.

9. Queue Command Workflow

Role-based pickup and updates:

  1. Show ready work for a role 

    make queue-ready ROLE=A-backend

  2. Claim next ready task for an owner 

    make queue-claim ROLE=A-backend OWNER=agent-a BRANCH=agent/A-backend

  3. Claim a specific task ID (optional) 

    make queue-claim ROLE=B-ui OWNER=agent-b TASK_ID=B-UX-001 BRANCH=agent/B-ui

  4. Update status during handoff 

    make queue-set-status TASK_ID=A-P7-001 STATUS=blocked OWNER=agent-a
make queue-set-status TASK_ID=A-P7-001 STATUS=done OWNER=agent-a

Validation: - scripts/ci/agent_queue_validate.sh - scripts/ci/agent_queue_git_consistency.sh - Included in scripts/ci/gitlab_local_dry_run.sh

Orchestrator helper (non-destructive): 

make orchestrator-status
make orchestrator-tick
Reference: doc/governance/Agent_Orchestrator_v1.md.

10. Interim Merge Policy (Before Reviewer Agent Exists)

Until a dedicated reviewer agent is introduced, the coding agent owns the full task cycle.

Required sequence per task: 1. Claim from queue (in_progress) from the role worktree. 2. Implement and run required checks for that task. 3. Push worktree branch to remote for backup and traceability. 4. Fast-forward merge into master only after local checks pass. 5. Mark queue task done only after merge to master and record completion metadata.

Commands: 

# one-time setup
export WORKTREE_ROOT="${WORKTREE_ROOT:-$(cd .. && pwd)}"
git worktree add "$WORKTREE_ROOT/gpuas-A-backend" -b agent/A-backend master
git worktree add "$WORKTREE_ROOT/gpuas-B-ui" -b agent/B-ui master
git worktree add "$WORKTREE_ROOT/gpuas-C-ops" -b agent/C-ops master

# 1) claim
make queue-claim ROLE=A-backend OWNER=agent-a BRANCH=agent/A-backend

# 2) push role branch
git push -u origin agent/A-backend

# 3) rebase role branch on latest master (required before ff-only merge)
git checkout agent/A-backend
git fetch origin
git rebase origin/master
git push --force-with-lease origin agent/A-backend

# 4) merge to master
git checkout master
git pull --ff-only origin master
git merge --ff-only agent/A-backend
git push origin master

# 5) mark done after merge
make queue-set-status TASK_ID=A-P7-001 STATUS=done OWNER=agent-a

When reviewer-agent workflow is added: - step (4) changes to reviewer approval + merge. - the rest of the queue lifecycle remains unchanged.

11. Dependency-Gated Execution Rule

Do not start a task from a worktree if any depends_on task is not done.

Required check before make queue-claim: 

make agent-preflight ROLE=<role>
scripts/ci/agent_queue_validate.sh
make queue-ready ROLE=<role>

If an urgent exception is required: - create a short ADR note under doc/architecture/adr/ with reason and rollback plan. - mark task blocked until the exception is approved.

12. Worktree Lifecycle (Teardown)

Role worktrees are persistent across tasks. Teardown only when: - a role has no remaining todo/in_progress/blocked tasks for the current phase, or - worktree state is irrecoverably stale/corrupt and needs clean recreation.

Teardown/recreate commands: 

export WORKTREE_ROOT="${WORKTREE_ROOT:-$(cd .. && pwd)}"
git worktree remove "$WORKTREE_ROOT/gpuas-A-backend"
git branch -D agent/A-backend
git worktree add "$WORKTREE_ROOT/gpuas-A-backend" -b agent/A-backend master

Before teardown: - ensure role branch is pushed/synced. - ensure claimed queue tasks are not left in_progress accidentally.

13. Future State (V2) — Lane-Based Scaling

V1 is intentionally simple: one role -> one persistent worktree -> one canonical branch. This is sufficient while each role has a single active writer.

V2 trigger: - sustained parallel work inside one role (for example B-ui split into B1 + B2), or - one owner actively running multiple role lanes at once (B + C).

Planned V2 extensions (deferred by design): 1. Queue schema adds lane field: - examples: A-backend:1, B-ui:1, B-ui:2, C-ops:1. 2. Branch/worktree mapping becomes role+lane scoped: - branch: agent/B-ui-1, agent/B-ui-2 - worktree: $WORKTREE_ROOT/gpuas-B-ui-1, $WORKTREE_ROOT/gpuas-B-ui-2 3. Validator enforces max in_progress per (role,lane) and valid mapping. 4. Optional parent/child task fields for decomposition: - parent_id, slice, merge_order. 5. Handoff schema includes lane identifier for deterministic ownership tracing. 6. Parent/child merge sequencing rule to define in ADR at V2 adoption time: - whether child tasks can merge independently, or - whether parent gate requires all children done before merge.

Until V2 is activated: - do not split a role into parallel lanes inside V1 queue/branch model. - if a role needs temporary fan-out, schedule sequential slices or create an ADR exception first.