Skip to content

Agent Orchestrator v1

Purpose: - Coordinate role agents (A-backend, B-ui, C-ops) against Agent_Work_Queue.yaml. - Keep execution dependency-safe and git-consistent. - Convert test/feedback outcomes into queued work without ad-hoc tracking.

Scope: - v1 is non-destructive orchestration: observe, validate, recommend dispatch. - Queue mutation remains explicit through make queue-claim and make queue-set-status. - Queue storage evolution reference: doc/governance/Agent_Queue_Structured_Store_v1.md. - Review model reference: doc/governance/Multi_Agent_Review_Model.md (manual process overlay in current phase). - Pre-MVP simplification guardrail: doc/governance/Pre_MVP_Simplification_Policy.md.

1. Inputs and Source of Truth

  • Queue definition source: doc/governance/Agent_Work_Queue.yaml
  • Queue execution-state direction: doc/governance/Agent_Queue_Structured_Store_v1.md
  • Queue schema/state validation: scripts/ci/agent_queue_validate.sh
  • Queue/git consistency: scripts/ci/agent_queue_git_consistency.sh
  • Role preflight: scripts/ops/agent_preflight.sh

2. Orchestrator Commands

make orchestrator-status
make orchestrator-tick

orchestrator-status: - runs validators, - prints per-role status summary (done/in_progress/blocked/todo), - prints ready tasks and dependency-blocked tasks.

orchestrator-tick: - runs the full status flow, - emits dispatch recommendations per role: - continue existing in_progress task, or - claim highest-priority ready task.

3. Control Loop (Operator-Driven)

Run this loop at handoff boundaries:

  1. make orchestrator-tick
  2. For each role with recommended claim, start/continue the corresponding agent.
  3. Agent executes work in its role worktree and updates queue status.
  4. On completion, agent records completed_at and merged commit.
  5. Re-run make orchestrator-tick and repeat.

4. Feedback and Testing as Tasks

When testing surfaces new work:

  1. Add a task to Agent_Work_Queue.yaml with:
  2. id, title, role, priority, depends_on, acceptance_checks, notes
  3. state fields initialized as: status=todo, owner='', branch='', completed_at='', commit=''.
  4. Use executable acceptance checks only (no prose).
  5. Run:
  6. scripts/ci/agent_queue_validate.sh
  7. scripts/ci/agent_queue_git_consistency.sh
  8. Commit queue update before dispatching the new task.

Task taxonomy for feedback: - BUG: broken expected flow from existing contract. - GAP: missing implementation required by roadmap/contract. - ENH: non-blocking improvement.

Add BUG|GAP|ENH prefix in task title for scanability.

Feedback Intake Evidence Checklist

Before dispatching a new feedback-derived task, capture this minimum evidence in the task notes or linked doc path:

  1. Source signal:
  2. failing test/job name, operator report, or contract mismatch reference.
  3. Classification:
  4. BUG|GAP|ENH and why that class applies.
  5. Repro/verification command:
  6. exact executable command used to confirm issue or validate fix.
  7. Dependency decision:
  8. whether depends_on is empty or explicitly linked to blocking task IDs.
  9. Orchestration confirmation:
  10. latest make orchestrator-tick output reviewed before claim.

5. Conflict Handling

If an agent reports unexpected unrelated changes: - do not proceed in that worktree. - run make agent-preflight ROLE=<role>. - switch to the correct role worktree/branch and retry. - if drift persists, mark task blocked and escalate via queue notes.

If dependencies are unsatisfied: - task must remain todo/blocked. - do not force in_progress unless a documented architecture exception exists.

6. v1 Guardrails

  • Max one active task per role at a time.
  • No auto-claim/auto-merge in orchestrator v1.
  • All claims and status changes remain explicit commands for auditability.

7. Auto-Continue Rule (No Permission Wait on Ready Work)

When a role has ready work, the agent proceeds without waiting for manual approval.

Required per-role loop: 1. make agent-preflight ROLE=<role> 2. make queue-ready ROLE=<role> 3. If ready task exists: make queue-claim ROLE=<role> OWNER=<owner> BRANCH=<role-branch> 4. Implement and run acceptance checks. 5. Push role branch and merge per playbook. 6. Mark task done with completed_at and merged commit. 7. Run make queue-git-check.

Agent must pause only if one of these blockers occurs: - unresolved dependency (depends_on not done), - queue/git consistency gate failure, - unexpected unrelated local modifications in role worktree, - required contract change not yet approved in source-of-truth docs.

8. Exit Criteria for v1

v1 is sufficient while: - each role has a single active writer, - conflicts are infrequent and quickly resolved by preflight + queue gates.

Move to v2 lane orchestration only when role-level parallel lanes are required.