> ## Documentation Index > Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. > [tab] 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`. > [tab] 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. > [tab] 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. > [tab] 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 ```text theme={null} 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 ``` > [!NOTE] > > 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. ```yaml theme={null} # 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. ```text theme={null} 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. > [!WARNING] > > 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:** > [card] 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. > [card] 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. > [card] 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. > [card] 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.