Multi-Agent Mode: Autonomous Goal-to-Code Pipeline

Thirteen agents, four phases — spec, architecture, coding, integration — with human review at sprint checkpoints and a TUI dashboard for monitoring.

Multi-agent mode hands an entire engineering goal to a coordinated pipeline of specialized agents. You supply a goal and a spec; the system decomposes it into epics, writes user stories, defines architecture, produces implementation plans, writes and reviews code, and merges everything to an integration branch. You stay in the loop at sprint checkpoints — reviewing what the system produced, replanning if needed, and deciding when to advance. It’s the right mode for complex features, full sprints, and production codebases where the work is too large or too structured for an interactive pairing session.

​

Pipeline Overview

The pipeline moves your goal through four phases. Each phase is a role-pair (one doer agent, one reviewer agent) that claims tasks, does work, and submits for peer review. Approved work merges into the integration branch automatically. You review the results at sprint checkpoints before the system advances to the next phase.

Goal → Epics → User Stories → Architecture → Implementation Plans → Code → Review → Merge

​

The 13 Roles Across 4 Phases

Specification

Runs at the general-objective entry point. Decomposes a high-level goal into reviewable, scoped epics and user stories.

Role	Responsibility
orchestrator	Creates and manages task breakdown across all phases
epic-planner	Decomposes the vision into epics; in the master pair, defines the epic-level decomposition framework
epic-plan-reviewer	Reviews epic decomposition; verifies boundaries, refs, and manifest coverage
us-writer	Writes user stories from approved epics
us-reviewer	Reviews user stories for completeness and correctness

Architecture

Runs at general-objective and functional-spec entry points. Defines component boundaries, interfaces, and structural decisions before any code is written.

Role	Responsibility
orchestrator	Manages task flow and sprint transitions
architect	Defines component boundaries, interfaces, and structural decisions
architecture-reviewer	Reviews architectural coherence and structural soundness

Coding

Runs at all entry points. Produces and reviews concrete implementation across all tasks in parallel.

Role	Responsibility
orchestrator	Monitors progress, triggers checkpoints, manages blocking tasks
code-planner	Claims and produces detailed coding plans from architecture output
code-plan-reviewer	Reviews coding plans and submits verdicts
coder	Claims and implements coding tasks in isolated git worktrees
code-reviewer	Reviews coding task diffs and submits verdicts

Integration

Triggered automatically by the orchestrator after all coding tasks complete. Scans the full branch diff for cross-task integration issues before final merge.

Role	Responsibility
integration-analyst	Scans the full branch diff for cross-task integration issues
integration-reviewer	Validates and enriches integration findings
coder	Implements any fix tasks created by the integration phase
code-reviewer	Reviews fix task diffs

​

Quick Start

1. Commit your spec and initialize

   Commit your spec file and .pre-commit-config.yaml to the integration branch before running liza init. Agents work from worktrees created off that branch — uncommitted files won’t be visible.

   # Full pipeline from a high-level goal
   liza init "Build authentication system" --spec specs/vision.md
   
   # Start from an existing functional spec (skips epic/story phases)
   liza init "Implement from functional spec" \
     --spec specs/auth-functional.md \
     --entry-point functional-spec
   
   # Start from a technical spec (coding phase only)
   liza init "Implement from technical spec" \
     --spec specs/auth-technical.md \
     --entry-point technical-spec
   

   Verify initialization:

   cat .liza/state.yaml
   
2. Open the TUI dashboard

   liza tui
   

   The TUI shows live system state: agents, tasks, alerts, and sprint metrics. Leave it open in a dedicated terminal for the duration of the run.

   Key	Action
   s	Spawn agent with configured default CLI
   S	Spawn agent — choose CLI interactively
   p	Pause all agents
   r	Resume
   a	Add a task
   y	Toggle auto-resume (skips manual checkpoint gates)
   c	Trigger sprint checkpoint
   Q	Stop the system

3. Start agents from the TUI

   Press s in the TUI to spawn each role. The roles you need depend on your entry point:

   general-objective (11 agents)

   orchestrator
   epic-planner, epic-plan-reviewer
   us-writer, us-reviewer
   architect, architecture-reviewer
   code-planner, code-plan-reviewer
   coder, code-reviewer
   

   Integration agents (integration-analyst, integration-reviewer) are spawned later when the orchestrator triggers that phase.

   functional-spec (7 agents)

   orchestrator
   architect, architecture-reviewer
   code-planner, code-plan-reviewer
   coder, code-reviewer
   

   technical-spec (5 agents)

   orchestrator
   code-planner, code-plan-reviewer
   coder, code-reviewer
   

   You can run multiple agents of the same role in parallel — they each claim separate tasks:

   liza agent coder    # becomes coder-1
   liza agent coder    # becomes coder-2
   
4. Monitor progress and handle checkpoints

   Watch task status in the TUI or from the CLI:

   liza get tasks --format table
   liza status
   

   When a sprint completes, the system pauses at a human gate. Review what agents produced, then advance:

   liza resume          # accept results and complete the sprint
   liza resume          # second call archives sprint and starts the next one
   

   If you want to amend a planner’s output before proceeding:

   vim specs/plan.md
   git add specs/plan.md && git commit -m "amend plan"
   liza replan          # invalidates old output, creates new planning task
   

​

Sprint Lifecycle and Human Gates

Liza runs in sprints. Each sprint executes one role-pair (doer + reviewer). Human checkpoints gate transitions between pairs unless you enable auto-resume.

IN_PROGRESS → CHECKPOINT → COMPLETED → (new sprint) IN_PROGRESS
                   │              │              │
                   │              └── liza resume (1st: mark COMPLETED)
                   │
                   └── liza resume (mid-sprint: back to IN_PROGRESS)
                   └── liza replan (amend plan → new planning task)

​

What You Do at Each Checkpoint

At a checkpoint, run /checkpoint-summary in any pairing session to get a prioritized digest of agent decisions, open points, and risks. This surfaces what needs your input faster than reading every artifact yourself.

Situation	Action
Satisfied with planner output	liza resume
Want to change a planner’s output	Edit plan file → commit → liza replan
Want to create child tasks manually	liza proceed <task-id> <transition>
Need to pause for manual changes	Take your time — no command needed
Want to stop entirely	liza stop

​

Auto-Resume (Yolo Mode)

Enable auto-resume to skip manual checkpoint gates and let the pipeline run continuously:

# At init time
liza init --auto-resume "Project goal" --spec specs/vision.md

# At runtime — toggle in the TUI with 'y'

liza pause is always a hard stop and is never auto-resumed. Use it when you need to interrupt the pipeline regardless of auto-resume state.

​

Entry Points

Choose your entry point based on how much specification work Liza should do:

Entry Point	Phases Run	Agents	Use When
general-objective	Spec + Arch + Coding	11 agents	You have a high-level goal and want Liza to do full decomposition
functional-spec	Arch + Coding	7 agents	You have a functional spec and want architecture and implementation
technical-spec	Coding only	5 agents	You have a technical spec and want implementation plans and code

detailed-spec is a legacy alias for functional-spec and runs the same 7-agent architecture + coding pipeline.

liza init "Goal" --spec specs/vision.md --entry-point general-objective
liza init "Goal" --spec specs/functional.md --entry-point functional-spec
liza init "Goal" --spec specs/technical.md --entry-point technical-spec

​

System Control Commands

Pause and Resume

liza pause              # pause all agents
liza resume             # resume (also advances checkpoints)
liza stop               # graceful stop of all agents
liza start              # restart after stop

​

Monitoring Commands

liza status                        # system and task status at a glance
liza get tasks --format table      # all tasks with current states
liza get agents --format table     # registered agents and health
liza analyze                       # circuit breaker pattern detection
cat .liza/log.yaml                 # full activity log

For deeper diagnostics, run /liza-logs in any pairing agent session. It cross-correlates logs across all agents, identifies patterns that inflate token usage, and proposes actionable fixes. Follow with /context-engineering when logs point to prompt bloat, weak handoffs, or missing context.

​

What Agents Do vs. What You Do

Clear separation of responsibilities keeps the human-oversight model intact:

Agents Handle	You Handle
Task decomposition and planning	Reviewing and approving planning output at checkpoints
Code implementation in isolated worktrees	Amending plans with liza replan when agent output needs correction
Peer code review and approval	Final judgment on whether to advance, replan, or stop
Merging approved work to the integration branch	Pushing the integration branch and opening pull requests
Detecting blocking issues and surfacing them	Resolving BLOCKED tasks that require domain knowledge or external access
Integration analysis across all merged tasks	Deciding whether integration findings require fixes before shipping

Liza manages all local git state: task worktrees, task branches, review commits, and the integration branch. Publishing commits to GitHub, opening pull requests, selecting a remote PR base, or enabling automerge is your responsibility — it happens after you decide the integration branch is ready to ship.

​

Worktrees and the Integration Branch

Each coding task gets its own git worktree under .worktrees/task-N/. Agents cannot interfere with each other’s work or with your working copy. Approved tasks merge into the integration branch (default: integration, configurable with --branch at init time).

git log integration --oneline    # see what's been merged so far

To start a completely fresh goal, remove the blackboard and reinitialize:

rm -rf .liza
liza init "New goal" --spec specs/new-vision.md