> ## 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 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.

```text theme={null}
Goal → Epics → User Stories → Architecture → Implementation Plans → Code → Review → Merge
```

## The 13 Roles Across 4 Phases

> [tab] 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 |

> [tab] 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 |

> [tab] 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 |

> [tab] 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.

```bash theme={null}
# 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:

```bash theme={null}
cat .liza/state.yaml
```

**2. Open the TUI dashboard**

```bash theme={null}
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:

> [tab] general-objective (11 agents)
>
> ```text theme={null}
> 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.

> [tab] functional-spec (7 agents)
>
> ```text theme={null}
> orchestrator
> architect, architecture-reviewer
> code-planner, code-plan-reviewer
> coder, code-reviewer
> ```

> [tab] technical-spec (5 agents)
>
> ```text theme={null}
> 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:

```bash theme={null}
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:

```bash theme={null}
liza get tasks --format table
liza status
```

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

```bash theme={null}
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:

```bash theme={null}
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.

```text theme={null}
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:

```bash theme={null}
# At init time
liza init --auto-resume "Project goal" --spec specs/vision.md

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

> [!WARNING]
>
> `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 |

> [!NOTE]
>
> `detailed-spec` is a legacy alias for `functional-spec` and runs the same 7-agent architecture + coding pipeline.

```bash theme={null}
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

```bash Pause and Resume theme={null}
liza pause              # pause all agents
liza resume             # resume (also advances checkpoints)
liza stop               # graceful stop of all agents
liza start              # restart after stop
```

```bash Checkpoints and Replanning theme={null}
liza sprint-checkpoint  # create a checkpoint manually
liza replan             # amend plan and regenerate output
liza replan code-planning-1   # specify task explicitly if multiple exist
```

```bash Transitions theme={null}
liza proceed <task-id> <transition>   # create child tasks for next phase
# Example:
liza proceed code-planning-1 code-plan-to-coding
```

## Monitoring Commands

```bash theme={null}
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 |

> [!NOTE]
>
> 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).

```bash theme={null}
git log integration --oneline    # see what's been merged so far
```

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

```bash theme={null}
rm -rf .liza
liza init "New goal" --spec specs/new-vision.md
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.