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 and Recovery guides.

Start autonomous agents

The TUI is the primary way to spawn and monitor agents. Open it first, then start the system.

# 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):

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

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:

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.

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.

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

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):

liza resume    # First: marks sprint COMPLETED (if all tasks terminal)
liza resume    # Second: archives sprint and starts the next one

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:

# 1. Check what was rejected and why
liza get tasks <task-id>       # Shows rejection_reason field

# 2. The task is in CODE_REJECTED (or equivalent) state
#    Release the current claim if needed
liza release-claim <task-id>

# 3. Claim the task manually
liza claim-task <task-id> coder-1

# 4. Navigate to the task worktree
cd .worktrees/<task-id>

# 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 <task-id> 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:

liza get tasks <task-id>    # Check review_cycles_total field

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):

# Preserve worktree — keeps any work the agent completed
liza recover-task <task-id>

# Discard worktree — clean restart on the task
liza recover-task <task-id> --fresh

# Bypass live-PID checks (use if PID is still alive)
liza recover-task <task-id> --force

Recover by agent ID:

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

liza agent coder --agent-id coder-1
# Output: "Took over expired lease for coder-1"

Both commands are idempotent — safe to run multiple times.

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.

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

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 <task-id>                         # Or specify explicitly

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.

# 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

# 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

Integration failure recovery

When a task merge fails due to conflicts or test failures, the task moves to INTEGRATION_FAILED with its worktree preserved.

# 1. Inspect the failure
liza get tasks <task-id>          # Confirms INTEGRATION_FAILED status

# 2. Check the conflicts
cd .worktrees/<task-id>
git status                        # Lists conflicted files
git diff                          # Shows conflict details

# 3. Any coder can claim for conflict resolution
cd ../..
liza claim-task <task-id> coder-2

# 4. Resolve the conflicts
cd .worktrees/<task-id>
# 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 <task-id> HEAD --agent-id coder-2

Quick state queries with liza get

liza get queries the blackboard state directly. Use it instead of parsing .liza/state.yaml manually.

# 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 <task-id>          # 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:

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"

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):

# 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-id> 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 <task-id>

Supersede with no replacement (work already done externally):

liza supersede-task <task-id> \
  --reason "Work already merged in prior sprint" \
  --recoverability-command "liza recover-task <task-id>"

liza supersede-task works from BLOCKED, REJECTED, or any pipeline-declared initial state.

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.

liza cancel-task <task-id> "Reason for cancellation"

Examples:

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.