> ## 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 Recipes: Common Workflows, Commands, and Patterns > Copy-paste recipes for common Liza workflows: running autonomous agents, pausing and resuming, handling rejections, sprint checkpoints, and state queries. These recipes cover the most common Liza workflows. Each one is self-contained — copy the commands, adapt the task IDs and agent names, and run. For deeper explanations of the underlying mechanics, see the [Sprint Lifecycle](https://lizamas.mintlify.site/guides/sprint-lifecycle.md) and [Recovery](https://lizamas.mintlify.site/guides/recovery.md) guides. > [accordion] Start autonomous agents > > The TUI is the primary way to spawn and monitor agents. Open it first, then start the system. > > ```bash theme={null} > # Open the live TUI > liza tui > ``` > > From the TUI, press **`S`** to spawn agents (prompts for CLI selection) or **`s`** to spawn using the configured default CLI. Role names autocomplete from the pipeline config. > > For a `technical-spec` entry point (5 agents: orchestrator, code-planner, code-plan-reviewer, coder, code-reviewer): > > ```bash theme={null} > # Alternatively, spawn from the CLI in separate terminals > liza agent orchestrator --agent-id orchestrator-1 > liza agent code-planner --agent-id code-planner-1 > liza agent code-plan-reviewer --agent-id code-plan-reviewer-1 > liza agent coder --agent-id coder-1 > liza agent coder --agent-id coder-2 > liza agent code-reviewer --agent-id code-reviewer-1 > ``` > > Monitor progress from additional terminals: > > ```bash theme={null} > watch -n 5 'liza get tasks --format table' # Task status every 5s > watch -n 5 'liza get agents --format table' # Agent status every 5s > watch -n 10 'liza status' # Dashboard every 10s > tail -f .liza/alerts.log # Live alert stream > ``` > > Stop cleanly when done: > > ```bash theme={null} > liza stop --reason "work session complete" > ``` > > **TUI keyboard shortcuts:** `s` spawn (default CLI), `S` spawn (pick CLI), `p` pause, `r` resume, `a` add task, `c` checkpoint, `y` toggle auto-resume, `Q` stop. > [accordion] Pause and resume > > Pause all agents to make manual state adjustments. Paused agents stay alive and wait — they do not exit. Stopped agents exit and must be restarted. > > ```bash theme={null} > # 1. Pause all agents > liza pause --reason "Manual state adjustments" > > # 2. Make your changes > vim .liza/state.yaml > > # 3. Always validate after manual edits > liza validate > > # 4. Resume > liza resume > ``` > > If you need to check the system state before resuming: > > ```bash theme={null} > liza status # Full dashboard > liza get tasks --format table # Task states > liza get agents # Agent states and lease status > liza analyze # Check for circuit breaker patterns > ``` > > To resume after a sprint completes (two-step advance): > > ```bash theme={null} > liza resume # First: marks sprint COMPLETED (if all tasks terminal) > liza resume # Second: archives sprint and starts the next one > ``` > [accordion] Handle task rejection > > When a reviewer rejects a task, agents with active coder sessions automatically reclaim rejected tasks and get the rejection feedback in their prompt. For manual handling: > > ```bash theme={null} > # 1. Check what was rejected and why > liza get tasks # Shows rejection_reason field > > # 2. The task is in CODE_REJECTED (or equivalent) state > # Release the current claim if needed > liza release-claim > > # 3. Claim the task manually > liza claim-task coder-1 > > # 4. Navigate to the task worktree > cd .worktrees/ > > # 5. Address the rejection feedback > # (edit files, fix the issues) > > # 6. Commit your changes > git add . > git commit -m "Address review feedback: [summary]" > > # 7. Resubmit for review > cd ../.. > liza submit-for-review HEAD --agent-id coder-1 > ``` > > Watch for high review cycle counts — 5 or more cycles on the same task usually signals an unclear acceptance criterion in the spec: > > ```bash theme={null} > liza get tasks # Check review_cycles_total field > ``` > [accordion] Recover from an agent crash > > Use `recover-task` when you know the task ID. Use `recover-agent` when you know the agent ID and want full cleanup. > > **Recover by task ID (recommended):** > > ```bash theme={null} > # Preserve worktree — keeps any work the agent completed > liza recover-task > > # Discard worktree — clean restart on the task > liza recover-task --fresh > > # Bypass live-PID checks (use if PID is still alive) > liza recover-task --force > ``` > > **Recover by agent ID:** > > ```bash theme={null} > # Recover only (release claim + remove worktree + delete agent) > liza recover-agent coder-1 > > # Recover and respawn in one step > liza recover-agent coder-1 --cli claude > > # Then restart manually if needed > liza agent coder --agent-id coder-1 > ``` > > **If the agent's lease has expired, restarting the supervisor works automatically:** > > ```bash theme={null} > liza agent coder --agent-id coder-1 > # Output: "Took over expired lease for coder-1" > ``` > > Both commands are idempotent — safe to run multiple times. > [accordion] Sprint checkpoint > > A sprint checkpoint pauses all agents and generates a sprint summary. Use it at the end of a sprint, before a major direction change, or when you want to review progress before continuing. > > ```bash theme={null} > # 1. Trigger a checkpoint (pauses all agents) > liza sprint-checkpoint > > # 2. Read the sprint summary > cat .liza/sprint_summary.md > > # 3. Review task distribution and agent activity > liza get tasks --format table > liza get metrics > > # 4. Check for anomalies > liza analyze > > # 5. Make decisions, then resume > liza resume > ``` > > At a checkpoint, you can also replan if the task breakdown needs adjustment: > > ```bash theme={null} > vim specs/plan.md # Edit the plan > git add specs/plan.md > git commit -m "Amend plan: [reason]" > liza replan # Auto-detects the planning task > liza replan # Or specify explicitly > ``` > [accordion] Circuit breaker escalation > > When the circuit breaker trips, all agents halt and the sprint moves to CHECKPOINT. Review the pattern, fix the root cause, then resume. > > ```bash theme={null} > # 1. Run analysis to see the detected pattern > liza analyze > > # 2. Read the circuit breaker report > cat .liza/circuit_breaker_report.md > > # 3. Read the sprint summary for broader context > cat .liza/sprint_summary.md > ``` > > Common patterns and their fixes: > > | Pattern | Typical Fix | > | - | - | > | `retry_cluster` | Redesign the component causing repeated retries | > | `debt_accumulation` | Refactor to address root causes instead of patching | > | `assumption_cascade` | Correct the wrong assumption in the spec and replan | > | `spec_gap_cluster` | Fill the ambiguous spec sections causing agent questions | > | `workaround_pattern` | Fix the root cause instead of patching its symptoms | > | `external_service_outage` | Wait for the service or switch to a stub/mock | > > ```bash theme={null} > # 4. Fix the root cause (update spec, architecture, goal document, etc.) > vim specs/vision.md # or relevant file > > # 5. Commit changes > git add -A && git commit -m "Fix circuit breaker root cause: [description]" > > # 6. Resume (clears mode and exits checkpoint) > liza resume > ``` > [accordion] Integration failure recovery > > When a task merge fails due to conflicts or test failures, the task moves to INTEGRATION\_FAILED with its worktree preserved. > > ```bash theme={null} > # 1. Inspect the failure > liza get tasks # Confirms INTEGRATION_FAILED status > > # 2. Check the conflicts > cd .worktrees/ > git status # Lists conflicted files > git diff # Shows conflict details > > # 3. Any coder can claim for conflict resolution > cd ../.. > liza claim-task coder-2 > > # 4. Resolve the conflicts > cd .worktrees/ > # Edit the conflicted files to resolve > git add . > git commit -m "Resolve integration conflict with integration branch" > > # 5. Resubmit for review (goes through full review cycle again) > cd ../.. > liza submit-for-review HEAD --agent-id coder-2 > ``` > [accordion] Quick state queries with liza get > > `liza get` queries the blackboard state directly. Use it instead of parsing `.liza/state.yaml` manually. > > ```bash theme={null} > # System state > liza get config.mode # RUNNING / PAUSED / STOPPED > liza get sprint.status # IN_PROGRESS / CHECKPOINT / COMPLETED > liza get sprint.elapsed # e.g. "2d 5h 30m" > > # Tasks > liza get tasks # All tasks > liza get tasks --format table # Compact table view > liza get tasks --status blocked # Blocked tasks only > liza get tasks # Single task with all fields > > # Agents > liza get agents # All agents > liza get agents --format table # Compact table view > liza get agents --zombies # Live processes missing from state > > # Metrics and anomalies > liza get metrics # Sprint metrics > liza get metrics --format json # Machine-readable > liza get anomalies # Anomaly history > > # Field path queries > liza get tasks.0.status # Status of the first task > ``` > > Use `liza get` in scripts to avoid parsing YAML: > > ```bash theme={null} > MODE=$(liza get config.mode) > BLOCKED=$(liza get tasks --format json | jq '[.[] | select(.status=="BLOCKED")] | length') > DONE=$(liza get sprint.metrics.tasks_done) > > echo "Mode: $MODE | Blocked: $BLOCKED | Done: $DONE" > ``` > [accordion] Supersede a task > > Use `liza supersede-task` when a task needs to be replaced with smaller tasks, or when its work was completed externally. > > **Replace with new tasks (split due to complexity):** > > ```bash theme={null} > # 1. Create the replacement tasks > liza add-task --id task-4 \ > --desc "Implement auth token generation" \ > --spec specs/auth.md \ > --done "Token generation tests pass" \ > --scope "auth module only" > > liza add-task --id task-5 \ > --desc "Implement auth token validation" \ > --spec specs/auth.md \ > --done "Validation tests pass" \ > --scope "auth module only" > > # 2. Supersede the original with the replacements > liza supersede-task task-4,task-5 \ > --reason "Split into smaller tasks due to complexity" > > # 3. Clean up the old worktree (branch is preserved for successor access) > liza wt-delete > ``` > > **Supersede with no replacement (work already done externally):** > > ```bash theme={null} > liza supersede-task \ > --reason "Work already merged in prior sprint" \ > --recoverability-command "liza recover-task " > ``` > > `liza supersede-task` works from BLOCKED, REJECTED, or any pipeline-declared initial state. > [accordion] Cancel a task > > Use `liza cancel-task` to abandon a task that is no longer needed. The task moves to ABANDONED with an audit trail. > > ```bash theme={null} > liza cancel-task "Reason for cancellation" > ``` > > Examples: > > ```bash theme={null} > liza cancel-task task-3 "Requirements changed — feature descoped from MVP" > liza cancel-task task-7 "Duplicate of task-2, which already covers this" > ``` > > `cancel-task` works on non-approved, non-terminal tasks including active, submitted, and reviewing tasks. It releases Liza state claims and removes the task worktree and branch. It does not kill a live provider process — if an agent is mid-session, it will see its claim released on next heartbeat and exit gracefully. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.