> ## 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. # Liza Sprint Lifecycle: Goal Decomposition to Merged Code > A Liza sprint moves from goal decomposition through implementation and review to merge, with human oversight gates at planning and sprint checkpoints. A sprint is one execution cycle in Liza: a set of tasks assigned to a role-pair (doer + reviewer), running until all tasks reach a terminal state. Sprints chain together across pipeline phases — specification, architecture, coding, integration — with human oversight gates between each phase. Understanding the sprint lifecycle lets you know when to intervene, what to look for at each checkpoint, and how to keep the system moving forward. ## What a Sprint Is Each sprint executes one role-pair from the pipeline. The orchestrator creates tasks, doer agents claim and implement them, reviewer agents approve or reject the work, and approved work merges into the integration branch. When all tasks in a sprint reach a terminal state, the sprint completes and a human gate fires before the next phase begins. Liza runs in sprints because bounded cycles are easier to review and recover. You inspect one cohort of work at a time, not an unbounded stream of activity. ## Sprint States ```text theme={null} IN_PROGRESS → CHECKPOINT → COMPLETED → (new sprint) IN_PROGRESS ``` | State | Meaning | | - | - | | **IN\_PROGRESS** | Agents are actively working; tasks are being claimed, implemented, and reviewed | | **CHECKPOINT** | The system has paused for human review; no new task transitions until you act | | **COMPLETED** | All tasks in the sprint are terminal; the sprint is ready to archive | Running `liza resume` at CHECKPOINT has two behaviors depending on whether tasks are complete: * **Not all tasks terminal** → returns sprint to IN\_PROGRESS (resumes current sprint) * **All tasks terminal** → marks sprint COMPLETED; run `liza resume` a second time to archive and advance to the next pipeline phase > [!NOTE] > > This two-step advance is intentional. The first `liza resume` lets you review the final state before archiving. The second advances the pipeline and creates child tasks for the next role-pair. ## The Two Human Gates Liza builds two mandatory human review points into every pipeline phase. ### Gate 1: Planning Checkpoint (PLANNING\_COMPLETE) After the orchestrator decomposes your goal into tasks, it fires a `PLANNING_COMPLETE` checkpoint before coding begins. This is your opportunity to review the proposed task breakdown and either approve it or amend it. **What happens:** 1. The orchestrator completes planning and populates `output[]` with the proposed task breakdown 2. The sprint checkpoints — orchestrator transition execution pauses 3. You review the proposed tasks with `liza get tasks` 4. You run `liza resume` to approve coding, or edit the plan and run `liza replan` to revise it > [!TIP] > > Use `/checkpoint-summary` in any pairing agent session to get a prioritized digest of agent decisions, open points, and risks. This is faster than reading every planning artifact yourself. ### Gate 2: Sprint Checkpoint Sprint checkpoints fire at the end of each sprint (when all tasks are terminal) or when you trigger one manually. Hard checkpoints pause all agents. Use this gate to review progress before the system advances to the next pipeline phase. **What happens:** 1. The sprint reaches CHECKPOINT (all tasks terminal or manually triggered) 2. All agents pause 3. You review progress, check for anomalies, and decide what to do next 4. You run `liza resume` to continue (or `liza replan`, `liza stop`, etc.) ## The Planning Transition in Detail The planning phase follows a **two-wake model**: **1. Orchestrator decomposes** The orchestrator claims the planning task, analyzes the goal document, and produces `output[]` entries representing the proposed task breakdown. Each entry maps to a future implementation task. **2. Checkpoint fires** When planning output is ready, the system checkpoints. The sprint status moves to CHECKPOINT. You see this in `liza status` as a `PLANNING_COMPLETE` trigger. **3. Human reviews** You inspect the proposed tasks: ```bash theme={null} liza get tasks liza get tasks --format table liza status ``` Read the plan artifacts referenced in the planning task's `output[]`. Check scope, sequencing, and coverage against your goal document. **4. Human approves or replans** If satisfied, run `liza resume` to approve and start coding. If you want to change the plan: ```bash theme={null} vim specs/plan.md # amend planner deliverables git add -A && git commit -m "amend plan" liza replan # auto-detects the planning task ``` `liza replan` invalidates the old task's output (preserved for audit, marked superseded), creates a new planning task, and returns the sprint to IN\_PROGRESS. The planner agent picks up the new task and regenerates the task breakdown. ## Checkpoint Actions When a sprint is at CHECKPOINT, you have several options: | Action | Command | When to Use | | - | - | - | | Accept and resume | `liza resume` | Satisfied with planner output or sprint progress — continue | | Amend and replan | Edit plan, commit, then `liza replan` | Want to change a planner's output before proceeding | | Pipeline transition | `liza proceed ` | Manually create child tasks for the next role-pair | | Pause for manual work | *(no command)* | Need to make manual changes before continuing | | Abort | `liza stop` | Want to stop entirely | ## Checkpoint Trigger Types | Trigger | Type | What It Means | | - | - | - | | `PLANNING_COMPLETE` | Transition | Planner output is ready; review before coding begins | | `MANY_TO_ONE_READY` | Transition | A fan-in cohort is ready to create its consolidated child task | | Manual (`liza sprint-checkpoint`) | Hard | You triggered it; all agents pause | | Circuit breaker pattern | Hard | Systemic failure pattern detected; all agents halt | | Anomaly threshold | Hard | Too many anomalies detected; review before continuing | | Blackboard validation failure | Hard | State invariants violated; all agents pause | | Provider quota exhausted | Signal | A provider's quota is exhausted; pause and resume to clear | > [!NOTE] > > Transition checkpoints (`PLANNING_COMPLETE`, `MANY_TO_ONE_READY`) only pause orchestrator transition execution. Doer and reviewer agents may continue working on already-claimable tasks in the current sprint while you review. ## Multi-Sprint Continuity Liza chains sprints together as tasks flow through pipeline phases. When you run `liza resume` the second time after a sprint completes, Liza archives the sprint and creates child tasks for the next role-pair based on the `output[]` entries from approved tasks. Tasks can carry context forward across sprints. Each task's `output[]`, `history[]`, and worktree state provide continuity between phases. Agents in later phases receive parent task context so they understand the decisions made upstream. To start a completely fresh goal (different spec, different direction), remove the blackboard and re-initialize: ```bash theme={null} rm -rf .liza liza init "New goal" --spec path/to/new-goal.md ``` ## Key Commands for Sprint Management > [card] liza status > > Dashboard overview: goal, sprint state, agent states, task summary, and available transitions. Your first stop at any checkpoint. > [card] liza get tasks > > List all tasks with current states, assignments, and lease information. Add `--format table` for a compact view or `--status blocked` to filter. > [card] liza sprint-checkpoint > > Manually trigger a checkpoint. Pauses all agents and generates a sprint summary at `.liza/sprint_summary.md`. > [card] liza replan > > Re-invokes the planner to amend the task breakdown. Run after editing plan artifacts and committing the changes. > [card] liza resume > > Resume from CHECKPOINT, PAUSED, or COMPLETED. Advances the sprint state machine. Run twice to complete a sprint and start the next one. > [card] liza analyze > > Circuit breaker pattern detection. Run this at checkpoints to surface systemic anomalies before resuming. ```bash theme={null} liza pause # Pause all agents (PAUSED — agents wait, not killed) liza stop # Stop all agents (agents exit and must be restarted) liza resume # Resume from CHECKPOINT / PAUSED / COMPLETED liza sprint-checkpoint # Force a checkpoint and generate sprint summary liza replan # Trigger replanning (auto-detects planning task) liza replan # Trigger replanning for a specific planning task liza analyze # Run circuit breaker pattern detection liza status # Full dashboard liza get tasks # All tasks with states liza get tasks --format table # Compact tabular view liza get metrics # Sprint metrics ``` ## What to Look For at Checkpoints Before running `liza resume`, check for these conditions: > [tab] Blocked tasks > > Tasks in BLOCKED state have questions or dependencies an agent could not resolve. Run: > > ```bash theme={null} > liza get tasks --status blocked > ``` > > Read the `blocked_reason` and `blocked_questions` fields for each blocked task. Answer the questions and run `liza unblock-task --reason "..."` to return the task to claimable status. > [tab] Hypothesis-exhausted tasks > > If multiple coders have failed on the same task, it may indicate a spec gap or architectural issue. Run `liza status` and look for tasks with high `iteration` counts or `review_cycles_total` values. Use `liza assess-hypothesis-exhausted ` to record an orchestrator assessment. > [tab] Circuit breaker patterns > > Run `liza analyze` at every checkpoint. If the circuit breaker has tripped, review `.liza/circuit_breaker_report.md` before resuming. Fix the root cause first — resuming without fixing it resets the counter but does not address the underlying issue. > [tab] Anomalies > > Check `.liza/alerts.log` for recent alerts. Common signals include repeated BLOCKED tasks with the same reason (spec gap), high review cycle counts (unclear acceptance criteria), and integration failures clustering on the same files (ownership conflict). ## Auto-Resume (Yolo Mode) By default, every checkpoint requires manual `liza resume`. You can enable auto-resume to let agents advance through checkpoints without your approval: * **At init time:** `liza init --auto-resume "Goal"` * **At runtime:** Press `y` in the TUI to toggle (displays "Auto-resume: ON/OFF" on the status line) When auto-resume is enabled, agents automatically call `liza resume` on CHECKPOINT or COMPLETED sprint status. Use `liza pause` for a hard stop — pause is never auto-resumed. > [!WARNING] > > Auto-resume skips the human review gates. Use it only when you trust the pipeline output or want uninterrupted execution for well-understood work. For new goals or complex pipelines, keep manual review enabled. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.