Multi-Agent Architecture: Roles, Blackboard, and Worktrees

Liza uses 13 specialized roles across 4 pipeline phases, a shared YAML blackboard for coordination, and isolated git worktrees per coding task.

Liza’s multi-agent system is not LLM-all-the-way-down. LLM agents handle judgment — what to build, how to test it, what the architecture should look like. Deterministic Go code handles everything that should not require judgment: state transitions, role boundaries, merge authority, lease management, and concurrent writes to shared state. This hybrid design means critical invariants cannot be circumvented by an agent interpreting rules flexibly, because the enforcement layer does not interpret — it compiles.

​

The Four Pipeline Phases

Liza organizes 13 roles across four sequential phases. Every phase uses adversarial doer/reviewer pairs: nothing advances without an independent reviewer issuing a binding approval.

Specification

The specification phase decomposes your goal into structured epics and user stories.

Role	Responsibility
Orchestrator	Decomposes the goal into planning tasks; rescopes when tasks are blocked or hypothesis-exhausted
Epic Planner	Writes the epic plan — a structured breakdown of the goal into major work streams
Epic Plan Reviewer	Issues binding verdict on the epic plan; rejects with file:line comments
US Writer	Transforms epics into user stories with acceptance criteria and done-when conditions
US Reviewer	Reviews user stories for completeness, testability, and spec alignment

Many-to-one transition: multiple user stories consolidate into a single architecture task via liza proceed.

Architecture

The architecture phase produces an architectural design that the coding phase implements.

Role	Responsibility
Orchestrator	Coordinates the architecture phase; may trigger a master pair for fan-out
Architect	Produces the architectural design: components, interfaces, dependencies, trade-offs
Architecture Reviewer	Reviews for structural soundness, coupling, and spec alignment

The architecture output feeds directly into code planning tasks via architecture-to-code-plan transition.

Coding

The coding phase plans and implements the actual code, running tasks in parallel across isolated worktrees.

Role	Responsibility
Code Planner	Produces a detailed implementation plan for each user story
Code Plan Reviewer	Reviews implementation plans for completeness and risk
Coder	Implements the plan in an isolated git worktree; writes tests
Code Reviewer	Reviews the diff from base commit to review commit; issues approved/rejected verdicts

Multiple coders run in parallel, each on their own worktree. The Go supervisor merges approved work to the integration branch — coders cannot merge their own work.

Integration

The integration phase runs after all coding tasks merge, checking cross-task coherence.

Role	Responsibility
Integration Analyst	Analyzes the integrated codebase for cross-task issues: API mismatches, missing wiring, emergent conflicts
Integration Reviewer	Reviews the integration analysis; findings produce new fix tasks in the coding pair
Coder	Implements fix tasks that the integration analysis surfaces (shared with the coding phase)
Code Reviewer	Reviews integration fix tasks before merge (shared with the coding phase)

Integration findings re-enter the coding phase as targeted fix tasks, so the same adversarial loop applies.

​

Pipeline Flow

  Specification Phase                    Architecture Phase
  ─────────────────────────────────      ──────────────────────────────
  Orchestrator                           Orchestrator
  Epic Planner  ←→  Epic Plan Reviewer   Architect  ←→  Architecture Reviewer
  US Writer     ←→  US Reviewer
         │                                       │
         │  liza proceed (many-to-one)           │  liza proceed
         ▼                                       ▼
  Architecture Phase                     Coding Phase
                                         ──────────────────────────────
                                         Code Planner  ←→  Code Plan Reviewer
                                         Coder         ←→  Code Reviewer
                                                │  all tasks merged
                                                ▼
                                         Integration Phase
                                         ──────────────────────────────
                                         Integration Analyst  ←→  Integration Reviewer

Master planning pairs reuse the same doer and reviewer roles with decomposition-root: true when a planning task would otherwise fan out into too many parallel tasks. They do not add new roles.

​

The Blackboard (state.yaml)

The blackboard is the single source of truth for the entire multi-agent system. Every agent reads from it, writes to it, and is bound by what is in it. You can observe it directly — there is no separate monitoring layer, no derived view that can drift.

# Example task entry on the blackboard
- id: code-planning-1-code-3
  type: coding
  role_pair: coding-pair
  description: User authentication returns a signed JWT; refresh flow invalidates previous tokens.
  status: MERGED
  priority: 1
  assigned_to: coder-2
  base_commit: e7625ed69318836dd495b22855df3a8b91fe32b5
  iteration: 1
  review_commit: 9d9254b893af477fc34f48063169634d200fa332
  approved_by: code-reviewer-1
  merge_commit: 2fa6399223262df6a87c6b1354dfc882b73114c5
  done_when: "POST /auth/login returns a signed JWT; refresh invalidates previous token; tests pass"
  spec_ref: specs/plans/auth-implementation.md
  history:
    - time: 2026-03-06T01:17:22Z
      event: claimed
      agent: coder-2
    - time: 2026-03-06T01:19:30Z
      event: pre_execution_checkpoint
      agent: coder-2
      files_to_modify: [src/auth/login.ts, src/auth/refresh.ts, tests/auth.test.ts]
      intent: Implement JWT login and token refresh per the auth spec.
      validation_plan: "Run the auth test suite; verify login returns a signed token and refresh invalidates the previous one."
    - time: 2026-03-06T01:22:05Z
      event: submitted_for_review
      agent: coder-2
    - time: 2026-03-06T01:24:30Z
      event: approved
      agent: code-reviewer-1
    - time: 2026-03-06T03:06:35Z
      event: merged
      agent: code-reviewer-1
      commit: 2fa6399223262df6a87c6b1354dfc882b73114c5

Key blackboard fields:

Field	Purpose
goal	The original goal document — source of truth for scope
tasks	All tasks with full history — claims, checkpoints, verdicts, merges
agents	Registered agents with role, provider, and heartbeat timestamp
sprint	Current sprint number, mode (RUNNING / PAUSED / CIRCUIT_BREAKER_TRIPPED)
circuit_breaker	Active failure patterns and escalation evidence

The blackboard uses atomic writes with lock-owner metadata so concurrent agents cannot corrupt shared state. A three-phase claim pattern prevents race conditions when multiple coders compete for the same task.

​

Task Lifecycle

Every task travels through a defined state machine. Terminal states are irreversible. Agents do not discover work — they receive pre-claimed tasks in their bootstrap prompt, eliminating race conditions and the cognitive overhead of self-assignment.

DRAFT → READY → IMPLEMENTING → READY_FOR_REVIEW → REVIEWING → APPROVED → MERGED
                     │                                  │
                     │             REJECTED ────────────┘
                     │             (structured feedback → revise → resubmit)
                     │
                     ├──→ BLOCKED
                     │         ├──→ SUPERSEDED
                     │         └──→ ABANDONED
                     │
                     └──→ DRAFT (release claim)

Each transition validates preconditions in Go code:

• Claiming requires READY status
• Submission requires a pre-execution checkpoint and test files
• Verdict requires the reviewer to verify the commit SHA matches worktree HEAD
• Merge requires approval from the required quorum of reviewers
• Forbidden transitions are rejected immediately with a clear error

Iteration limits prevent infinite loops: 10 coder iterations, 5 review cycles. After exhaustion, the task becomes BLOCKED and the orchestrator escalates.

Hypothesis exhaustion: if two independent coders fail the same task, the system presumes the task framing is wrong. The task is blocked for rescoping — not reassigned to a third coder.

​

Git Worktree Isolation

Every task runs in its own git worktree at .worktrees/{taskID}. Coders work in complete isolation from each other — no shared working directory, no interference between parallel tasks.

1. Task claimed

   The supervisor creates a fresh worktree for the task, branched from the current integration branch HEAD.

2. Coder implements

   The coder commits all changes to the task worktree. Before submission, the supervisor rebases the worktree onto the current integration branch — conflicts abort the submission cleanly.

3. Reviewer examines

   The reviewer verifies the commit SHA recorded in the blackboard matches the worktree HEAD, then reviews all changes from base_commit to review_commit — not just the latest delta.

4. Supervisor merges

   Only after reviewer approval does the supervisor merge to the integration branch. It uses a no-checkout merge strategy so multiple reviewers can merge in parallel without interfering with each other.

5. Worktree deleted

   On terminal states (MERGED, ABANDONED, SUPERSEDED), the worktree is deleted. A fresh attempt gets a fresh worktree — no contamination from a failed approach.

Coders cannot commit to or merge to the integration branch directly. The merge path is always: coder commits to worktree → reviewer approves → supervisor merges. This is enforced by MCP middleware, not by instruction.

Merge authority is structural: the blackboard records approved_by and merge_commit on every task. The full audit trail is always available — who wrote the code, who approved it, which commit merged it.

​

The Supervisor Model

The Go supervisor wraps every agent. It handles what should not require judgment — registration, heartbeat, post-exit cleanup, state transitions — and leaves judgment to the agent.

What the supervisor enforces that agents cannot circumvent:

MCP Tool Middleware

Every tool call passes through role validation before reaching the handler. A coder cannot submit a verdict. A reviewer cannot write an implementation checkpoint. Violations fail with a clear message naming the agent, role, and forbidden operation.

TDD Gate

Code submission requires test files — enforced across 8 languages. No test files means automatic rejection. A waiver path exists but requires written justification that the reviewer (not the coder) verifies.

Lease System

Tasks are held with time-bounded leases (default 30 minutes). Heartbeats refresh leases. Stale leases are detected and released automatically — a dead agent cannot hold a task indefinitely.

Secret Masking

Agent output is automatically scrubbed of sensitive environment variable values before it reaches any log. Agents do not need to actively redact — the masker enforces Tier 0 invariant T0.5 mechanically.

​

Circuit Breaker

The circuit breaker watches for systemic failure patterns across agents and tasks. When it detects a pattern, it pauses the sprint, generates a markdown report with evidence, and waits for a human decision. It never proposes solutions, modifies code, or continues execution autonomously.

Pattern	Threshold	Classification
Retry cluster	≥3 retry loops with similar errors	ARCHITECTURE_FLAW
Debt accumulation	≥3 trade-offs creating tech debt	SCOPE_FLAW
Assumption cascade	Same assumption violated across 2+ tasks	SPEC_FLAW
Spec gap cluster	Multiple tasks hitting the same ambiguity	SPEC_FLAW
Workaround pattern	2+ workarounds sharing a root cause	ARCHITECTURE_FLAW
External service outage	2+ tasks blocked by the same service	EXTERNAL_DEPENDENCY

You can also trigger a checkpoint manually at any time with liza checkpoint — the system pauses, you review, and you resume with any steering adjustments.

​

Orchestrator Wake Conditions

The orchestrator wakes on blackboard change events (with polling fallback) and evaluates conditions in priority order:

1. INITIAL_PLANNING — no tasks exist yet; decompose the goal
2. BLOCKED_TASKS — actionable blocked tasks await escalation or rescoping
3. HYPOTHESIS_EXHAUSTED — two coders failed the same task; rescope
4. IMMEDIATE_DISCOVERY — new findings not yet converted to tasks
5. PLANNING_COMPLETE — all planned tasks are terminal; proceed to next phase
6. SPRINT_COMPLETE — all tasks terminal with no unconsumed output; close sprint

If the sprint is already in CHECKPOINT or COMPLETED state, SPRINT_COMPLETE is suppressed to prevent re-wake loops.