DOCSEARCHbyAlgolia
Submit Docs

Liza Orchestration Framework

repository·main·Indexed 43 days ago

https://github.com/liza-mas/liza

An orchestration framework for accountable agents designed for software delivery. Liza enables autonomous, multi-agent software engineering sprints using behavioral contracts, adversarial agent pairs, and mechanical Go-enforced boundaries. It supports three execution modes: Pairing for direct collaboration, Adversarial Pairing for bounded increments, and Full MAS (Multi-Agent System) for unattended sprints with deterministic supervisors and task graphs.

Tokens
263.3K
Snippets
452
Records
1K
Agent score
49%

What's inside Liza

  1. What is Liza?

    main

    Liza is a Pairing and Multi-Agent System (MAS) designed for software delivery. It operates by using a generic, engineered graph for software delivery that is instantiated for each goal and can adapt during execution.

    In Pairing mode, it acts as a collaborative partner. In Multi-Agent mode (MAS), agents decompose goals, produce specifications and code, perform adversarial reviews, and merge changes through code-enforced gates. This allows for unattended execution of sprints while humans retain governance and authority over irreversible effects.

    Key characteristics:

    • Goal-oriented: Moves from a high-level goal to reviewed, tested, and documented code.
    • Provider Agnostic: Uses your existing subscriptions and personal CLI setups (e.g., Claude Code, Codex).
    • Accountable: Uses a behavioral contract to ensure agents reason before acting, admit uncertainty, and verify claims rather than faking progress.

  2. Overview of the ACP Plugin

    main
    The plugin/acp package is an independent Go package designed for tracking ACP-style task runs and benchmarking the performance difference between 'warm' (session-reusing) and 'fresh' (new session) executions. It is decoupled from Liza's internal supervisor packages to ensure that benchmarks and downstream ACP tooling remain stable even as the core runtime evolves.

  3. Liza v1 Scope and Target Audience

    main

    Target Audience

    Liza is designed for:

    • Solo developers or small teams with experience using Claude Code.
    • Users comfortable with terminal-based workflows.
    • Projects where quality, auditability, and speed are priorities.

    MVP Scope (v1)

    • Roles: One Planner, one Coder, and one Code Reviewer (running in parallel as single instances per role).
    • Workflow: Single goal and single sprint at a time.
    • Interface: Terminal-based observation and shell script tooling.
    • State: YAML-based blackboard with file locking (flock).
    • Safety: Human-triggered circuit breaker analysis and checkpoint-based retrospectives.

    Out of Scope (v1)

    • IDE integration or Web dashboards.
    • Multi-repo coordination or parallel coders.
    • Real-time circuit breakers (v1 uses human-triggered analysis).
    • SQLite backend (uses YAML instead).

  4. Understand the Repository Purpose and Structure

    main

    This repository automates a job search workflow for Tangi Vass. It manages a structured set of data including a master CV, company research, job descriptions, and generated application materials.

    Key Data Components

    • CV/Resume: Managed in profile/CV-en.yaml (YAML format).
    • Company Inventory: Tracked in the companies/ directory.
    • Job Descriptions: Crawled and stored in job_data/job_desc/.
    • Targeted CVs: Generated in the leads/ directory based on fit analysis.

    Directory Map

    • crawlers/: Pipeline scripts for data collection.
    • tests/: Unit tests.
    • profile/CV-en.yaml: The master CV source.
    • job_data/: Runtime outputs from crawlers.
    • leads/: Generated application materials.
    • docs/: Project documentation.
    • specs/: Specifications and TODO lists.

  5. Understand the Liza Architecture and System Components

    main

    Liza's architecture is documented through several key layers. To understand how the system is structured, refer to the following documentation groups:

    • C4 Diagrams: System context, container, and component diagrams.
    • Overview: Detailed system components, data flow, and directory structure.
    • Roles: Definitions of responsibilities for the Planner, Coder, and Code Reviewer.
    • State Machines: Definitions of task states, agent states, and exit codes.
    • Blackboard Schema: The structure of state.yaml, including locking mechanisms and operations.
    • Supervision Model: Defines action responsibility between the supervisor and the agent via CLI commands.

  6. Use the `liza` Go CLI for orchestration

    main

    The liza binary is the primary interface for all system mechanics. It handles task management, agent supervision, worktree operations, and state validation.

    Note: Locking is handled internally by the binary; you do not need to use external tools like flock.

  7. Liza core components and architecture

    main

    Liza is a stack-agnostic, peer-supervised multi-agent orchestration system implemented in Go. It uses a declarative pipeline and a YAML-based blackboard for state management.

    Key Components:

    • CLI & TUI: The primary runtime is the liza CLI (Cobra-based) and a Bubble Tea TUI. These interface with the application's domain model and operations.
    • Blackboard (.liza/state.yaml): The source of truth for system state, managed via internal/db.Blackboard.
    • Domain Model: Defines core concepts like tasks, agents, sprints, and leases.
    • Pipeline & Prompts: Loads declarative configurations and assembles agent prompts using a builder pattern.
    • Agent Runtime: Manages agent roles (e.g., LLMAgent, CLIAgent), provider catalogs, and execution plans.
    • Git & Worktrees: Handles per-task Git worktrees for isolated execution.
    • Application Operations (internal/ops/): The service layer that coordinates blackboard transactions, Git operations, and task lifecycles.

  8. Software Architecture Review Protocol Overview

    main

    The software-architecture-review skill is a protocol used for implementation planning, code review supplements, or explicit architectural evaluation. It follows a structured process of Discovery → Analysis → Recommendations to evaluate software trade-offs.

    Key Concepts:

    • REVIEW_FILE: The canonical output file, located at specs/architecture/architecture-review.md.
    • Templates: Use templates to anchor cognition; complete Phase 1 (Discovery) before moving to Phase 2 (Analysis).
    • Time Budgeting: Discovery (Phase 1) should be at least as thorough as Analysis and Recommendations combined to avoid missing critical findings.

  9. Understand the Liza System Architecture

    main

    Liza is an orchestration system for accountable agents composed of three primary agent roles and a human supervisor. The system uses a 'blackboard' pattern for coordination and isolated worktrees for execution.

    Core Components

    • Human: Leads specs, observes terminals, reads the blackboard, and can pause or kill agents.
    • Orchestrator: Decomposes goals into tasks and rescopes them upon failure.
    • Coder: Claims tasks and iterates on implementation until approved.
    • Code Reviewer: Examines work, approves/rejects, and merges code.

    State and Workspace Management

    • Blackboard (.liza/): Contains state.yaml (coordination state) and log.yaml (activity history).
    • Worktrees (.worktrees/): Provides isolated workspaces for each task (e.g., .worktrees/task-1/).

    LLM Provider Support

    Liza is LLM-agnostic, but compliance levels vary:

    • Full Compliance: Claude, Codex.
    • Partial Compliance: Gemini, Mistral.

  10. Understand the repository structure and key paths

    main

    The repository is organized to support an automated job search workflow. Key directories include:

    • crawlers/: Pipeline scripts for data collection.
    • tests/: Unit tests.
    • profile/CV-en.yaml: The master CV in structured YAML format.
    • job_data/: Runtime outputs from the pipeline.
    • leads/: Generated application materials (targeted CVs).
    • docs/: Project documentation.
    • specs/: Specifications and TODO lists.
    • companies/: Inventory of tracked companies.
    • job_data/job_desc/: Crawled job descriptions.

    For a complete structural overview, refer to docs/USAGE.md.

  11. Understand the Liza Repository Structure

    main

    Liza is organized into several functional directories that define its behavior, context, and capabilities:

    • contracts/: Behavioral contracts (e.g., CORE.md) that govern agent behavior and prevent failure modes.
    • specs/: Durable agent context (specifications) that survives restarts and prevents agents from rediscovering requirements.
    • skills/: Specialized protocols (e.g., debugging/, testing/) that agents load conditionally for specific tasks.
    • lessons/: Project-specific operational insights captured to prevent recurring mistakes.
    • cmd/: The entry point for the liza Go CLI.
    • templates/: Document templates for bootstrapping new artifacts like Vision documents or ADRs.
    • support-docs/: Operational documentation installed to ~/.liza/support-docs/ via liza setup.

  12. Understand Agent Supervision and Recovery

    main

    Every agent is wrapped by a Go supervisor that manages its lifecycle and enforces system invariants.

    Supervisor Responsibilities

    • Lifecycle: Handles registration, heartbeats, and post-exit cleanup.
    • Loop Detection: Detects restart loops (exit code 42) by comparing state hashes. If no progress is made, the task is BLOCKED with exponential backoff.
    • Supervisor-only actions: Registration, heartbeat, and post-exit reset (these cannot be performed by agents).

    Recovery Mechanisms

    • Generation-Fenced Recovery: Uses opaque registration generations to ensure that only the current-generation authority can perform authenticated lifecycle writes.
    • Approved Merge Takeover: If a final approver exits, a deterministic current-generation reviewer can resume an already-approved merge, preserving all approval metadata and quorum evidence.
    • Rejected-task Handoff: When reclaiming a task, the system treats assigned_to, lease_expires, worktree, base_commit, and physical task artifact as a single locked tuple to ensure a healthy worktree is reused.