{"id":40952388,"url":"https://github.com/liza-mas/liza","last_synced_at":"2026-04-06T12:00:53.999Z","repository":{"id":333166688,"uuid":"1136343145","full_name":"liza-mas/liza","owner":"liza-mas","description":"Disciplined Multi Coding Agent System","archived":false,"fork":false,"pushed_at":"2026-04-01T22:10:47.000Z","size":5374,"stargazers_count":97,"open_issues_count":0,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-03T01:14:48.924Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liza-mas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T14:17:24.000Z","updated_at":"2026-04-02T19:39:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liza-mas/liza","commit_stats":null,"previous_names":["liza-mas/liza"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/liza-mas/liza","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liza-mas%2Fliza","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liza-mas%2Fliza/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liza-mas%2Fliza/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liza-mas%2Fliza/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liza-mas","download_url":"https://codeload.github.com/liza-mas/liza/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liza-mas%2Fliza/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31471466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-22T05:15:17.738Z","updated_at":"2026-04-06T12:00:53.979Z","avatar_url":"https://github.com/liza-mas.png","language":"Go","funding_links":[],"categories":["Codex Workflow Frameworks"],"sub_categories":[],"readme":"# Liza: Hardened Multi-Agent Coding\n\n\u003e Because *\"it worked in the demo\"* is not what on-call engineers are looking for.\n\nThe full **[hardening inventory](docs/liza-hardened-mas.md)** to push to production with peace of mind.\n\n![Liza's TUI](docs/img/liza-tui.png)\n\n**[Demo video](https://drive.google.com/drive/folders/1Iea-nNxAazBHeLXL7IElXnG5r1i1E-Ha?usp=sharing)** (45min).\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/liza-mas/liza)\n\n## Table of Contents\n\n- [What is Liza?](#what-is-liza)\n- [How Liza Compares](#how-liza-compares)\n- [Getting Started](#getting-started)\n- [Architecture](#architecture)\n- [Status](#status)\n- [Naming](#naming)\n- [License](#license)\n\n## What is Liza?\n\nLiza is simultaneously a **Pairing** and **Multi-Agent System** (MAS)\noptimized for **doing things right on the first pass** — with the auditability to prove it.\nLiza bets on time-to-quality and durable codebase maintainability through automated reviews and documentation\n(e.g. the [ADR Backfill](skills/adr-backfill) skill).\n\n\u003e Soufiane Keli – VP Software Engineering, Octo Technology (Accenture) – maps AI engineering maturity across 5 levels,\n\u003e from autocomplete (L1) to software factory (L5, still theoretical). He places Liza at L4 – Collaborative Agent Networks:\n\u003e \u003cbr\u003e\n\u003e *\"Multiple specialized agents work together on design, code, testing, and deployment. Humans orchestrate. This is typically\n\u003e what's happening with BMAD, BEADS, and LIZA. Very few organizations have genuinely reached this level in 2026.\"*\n\n### Main characteristics:\n\n- **Behavior, Posture, Know-How** — three layers that make coding agents useful:\n  - **Behavior**: A [behavioral contract](contracts/) enforces governance intrinsically — not through external scaffolding as *Harness Engineering* does. Optional project [guardrails](GUARDRAILS.md) extend the contract with project-specific constraints.\n  - **Posture**: Original pairing postures (User Duck, Socratic Coach, Challenger, etc.)\n  - **Know-How**: 20 composable [skills](skills/) encode methodology\n  - *[Full analysis](https://medium.com/@tangi.vass/behavior-posture-know-how-the-three-layers-that-make-ai-agents-useful-d485388442eb)*\n- **Autonomous Spec-driven Coding System:**\n  - From **general goal** to code and tests, with multi-stage decomposition into intermediate artifacts (epics, US, implementation plans)\n    that are AI generated but human reviewed.\n  - Automatic task decomposition based on complexity with dependency management for parallel execution. Many-to-one transitions consolidate sibling tasks (e.g. N user stories → 1 architecture task).\n  - Multi-sprints: agents are fully autonomous within a sprint, user steers between sprints via Liza CLI - review of produced artifacts, continuous improvement, and steering of the next sprint\n  - A TUI (`liza tui`) displays live system state and lets you spawn agents, pause/resume, add tasks, and trigger checkpoints.\n- **Adversarial architecture:**\n  - One Orchestrator role + 12 others across three pipeline phases.\n  - Every activity is dual — a doer and a reviewer: epic planning, epic writing, US writing, code planning, coding - everything.\n  - They interact like on a PR review — submission, feedback comments, verdict, revised submission, etc. — until approval.\n- **Hybrid hardened architecture:**\n  - LLM agents wrapped by code-enforced supervisors and working on isolated git worktrees.\n  - The supervisor does the **deterministic code-enforced actions** (worktree management, merges, TDD enforcement, etc),\n    leaving the **judgment to the agent**. Strict task state machine with 43+ validation rules.\n  - Agents communicate and act through Liza's **MCP tools**.\n  - 35k LOC of Go (+92k of tests). Liza is not a prompt collection.\n  - Agent logs recording for automatic analysis and continuous improvements (token optimization, MCP server usage analysis, ...)\n- **Multi-model:**\n  - Liza wraps provider **CLIs**, not their APIs. This means your existing subscription (Claude Max, ChatGPT Pro, etc.) works — no API keys or per-token billing required — and your personal setup is used.\n  - BYOM: Claude Code, Codex CLI, Kimi, Mistral, Gemini. [Not all are made equal though](docs/demo-benchmark).\n- **Structured workflow:**\n  - Defined as a composable and customizable YAML pipeline with declarative sub-pipelines (e.g. specification, coding).\n  - Coordination is performed via an auditable YAML **blackboard** that acts as both the Kanban board of the agents with full historized state details and the support for PR-like comments made by the reviewer agents.\n  - Agents don't discover work — they receive pre-claimed tasks in bootstrap prompt. Eliminates race conditions and cognitive overhead.\n- **Resilience:**\n  - Circuit breaker: pattern detection (loops, repeated failures) triggers automatic sprint checkpoint\n  - Crash recovery: `recover-agent` and `recover-task` commands for idempotent cleanup after hard crashes\n  - Context handoff: agents hand off with structured notes when approaching context limits\n\nSee the complete [vision](\u003cspecs/build/1 - Vision.md\u003e) and [genesis](docs/how-liza-grew-up.md) of Liza.\n\n### What it looks like in practice\n\nWithout the contract, an agent that hits a problem it can't solve has two options: admit failure or fake progress. Its training overwhelmingly favors the second. **Faking progress feels collaborative** — *look, I'm trying things!*\n\nSo it spirals. Random changes dressed up as hypotheses. Each iteration more elaborate, more confident, more wrong. You watch the diff grow and wonder if any of this is moving toward a solution. If you're clever, you end up reverting.\n\nUnder the contract, there's a third option: **say \"I'm stuck\" and mean it.** The contract makes that safe — no penalty for uncertainty, no pressure to perform progress. And the Approval Request mechanism forces agents to write down their reasoning before acting. *\"I'll try random things until something works\"* is hard to write in a structured plan. Surface the reasoning, and the reasoning improves — no better model required.\n\nThis won't self-correct. Sycophancy drives engagement — that's what gets optimized. Acting fast with little thinking controls inference costs. Model providers optimize for adoption and cost efficiency, not engineering reliability.\n\nTen months of pairing under this contract, and the vigilance tax dropped to near zero. I can mostly focus on the architecture and more specifically build up a MAS upon the contract.\n\nHere is a [demo video](https://drive.google.com/drive/folders/1Iea-nNxAazBHeLXL7IElXnG5r1i1E-Ha?usp=sharing) of an implementation of a basic Todo CLI\nusing Liza in Multi-agent mode - spec-driven with intermediate epic and User Story creation, fully autonomous agents within sprints, human reviews between sprints.\n\n## How Liza Compares\n\n### MAS Architecture\n\nThe multi-agent coding space splits into four categories:\n\n- **Orchestration frameworks** (CrewAI, LangGraph, AutoGen) — general-purpose multi-agent building blocks; none address behavioral trust in software engineering.\n- **Company simulators** (MetaGPT, ChatDev) — SOP-based pipelines mimicking software teams; trust assumed through process compliance.\n- **Scheduler/runners** (Symphony, Paperclip) — work dispatch and workspace isolation above coding agents; trust delegated to whatever happens inside each session.\n- **Behavioral enforcement** (Liza) — deterministic supervisors enforce state transitions, role boundaries, and merge authority mechanically; agents handle judgment under a behavioral contract addressing 55+ failure modes.\n\n| | Liza | CrewAI | Ruflo | Symphony | Paperclip |\n|---|---|---|---|---|---|\n| **Trust approach** | Behavioral contract (55+ failure modes) | Post-hoc output validation | Track-record based (Q-learning) | Implementation-dependent | Budget/approval governance |\n| **Review loop** | Adversarial doer/reviewer pairs | Optional manager mode | None | None | None |\n| **Role enforcement** | Code-enforced (Go supervisor) | Prompt suggestion | Claude hooks (provider-specific) | None (single-agent) | Org chart hierarchy |\n| **Failure handling** | Structural prevention + escalation | Retry on output failure | Pattern matching from past successes | Implementation-dependent | Budget auto-pause |\n\n**Where Liza leads** — no competitor offers any of these:\n- Failure mode catalog (55+) with mechanical countermeasures\n- Adversarial doer/reviewer pairs on every task\n- Code-enforced role boundaries (Go supervisor, not prompt suggestions)\n- Provider compliance matrix tested empirically across 5 providers\n- Multi-sprint continuity, crash recovery, context pressure management\n\n**Where others lead:**\n- **Ecosystem**: CrewAI (45k stars, production v1.9.0, enterprise product) and MetaGPT (64k stars) have far larger communities\n- **Cost tracking**: Paperclip ships per-agent/task/project budgets today; Liza's is planned\n- **Flexibility**: CrewAI works for any domain; Liza is software-engineering-only\n\n### Spec-Driven Process\n\nSpec-driven development is becoming the standard approach for AI coding. Most tools differ in *what altitude* they expect the input at and *who owns product decisions*.\n\n| | Liza                                              | Spec Kit | OpenSpec | Kiro | GSD |\n|---|---------------------------------------------------|---|---|---|---|\n| **Input level** | High-level goal (problem, users, behavior, scope) | High-level goal → agent-generated spec | Detailed delta-specs on existing system | Interactive 3-doc generation | Detailed spec required |\n| **Who decides what to build** | Human via pairing (Coach/Challenger modes)        | Agent generates, human approves | Human (spec pre-decided) | Agent drives, human confirms | Human (pre-written) |\n| **Decomposition** | Orchestrator decomposes into adversarial tasks    | Agent decomposes spec into tasks | Slash commands structure tasks | Agent decomposes from spec | Planner sizes to context budget |\n| **Review** | Doer/reviewer pairs with quorum                   | None | Advisory (verify warns, doesn't block) | None (single-agent) | Checker + verifier (not adversarial) |\n\nMost tools either expect the detailed spec already done (OpenSpec, GSD) or have the agent write it (Spec Kit, Kiro, MetaGPT). Liza treats goal-setting as a synchronous human-agent collaboration where the human makes product decisions and the agent helps surface gaps — then enforces those decisions mechanically during execution.\n\n**Rule of thumb: agents may make implementation choices but not product decisions.** The [goal document](docs/how-to-produce-a-goal.md) is where every product decision lives. The goal-setting phase uses pairing (Coach mode for surfacing WHY, Challenger mode for stress-testing WHAT) because this phase has the highest decision density — every ambiguity resolved here prevents wrong turns downstream.\n\n[Full competitive survey →](specs/architecture/mas-survey.md)\n\n---\n\n## Getting Started\n\n### Requirements\n\n- A supported coding agent CLI: Claude Code, Codex, Kimi, Mistral, or Gemini (see [Provider Compatibility](#provider-compatibility)).\n  Liza runs on top of these CLIs — your provider subscription covers usage, no separate API billing needed.\n- Git 2.38+ (for full worktree support)\n- Go 1.25.5+ (only for building from source — pre-built binaries available via `install.sh`)\n\n### Installation\n\nLiza relies on two executables: `liza` and `liza-mcp`:\n- By default they install to `~/.local/bin` (created automatically, no sudo needed).\n- Set the `INSTALL_DIR` environment variable to override.\n- If upgrading from a previous install in `/usr/local/bin`, old binaries are removed automatically.\n\n**Quick install (latest release, macOS/Linux):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | bash\n```\n\n**Options:**\n\n```bash\n# Specific version\ncurl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | VERSION=v1.0.0 bash\n\n# Build from a branch (requires Go and make)\ncurl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | BRANCH=main bash\n\n# Custom directory\ncurl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | INSTALL_DIR=~/.local/bin bash\n```\n\n**From a local clone:**\n\n```bash\ngit clone https://github.com/liza-mas/liza.git \u0026\u0026 cd liza\nmake install\n```\n\n**Verify:**\n\n```bash\nliza version\n```\n\n```bash\nliza setup  # initial install or liza upgrade: installs contracts + skills to ~/.liza/\n# With: agent-specific activation (skill symlinks, contract config)\nliza setup --claude --codex --gemini --mistral\n```\n\n\u003e **️⚠️ Customize your tool setup:**\u003cbr\u003e\n\u003e The installed `~/.liza/AGENT_TOOLS.md` ships with a default\n\u003e MCP server and tool configuration. It defines which tools agents prefer (IDE integrations,\n\u003e search providers, documentation sources, etc.) and is specific to each user's environment.\u003cbr\u003e\n\u003e Context management is of paramount importance. Make sure you use tools that reduce token usage.\u003cbr\u003e\n\u003e Recos: [RTK](https://github.com/rtk-ai/rtk), filesystem MCP, MorphLLM MCP, Perplexity MCP.\u003cbr\u003e\n\u003e Edit `~/.liza/AGENT_TOOLS.md` to match your own setup — remove tools you don't have,\n\u003e add ones you do, and adjust precedence rules accordingly.\u003cbr\u003e\n\u003e Or better, provide your own file at install time: `liza setup --agent-tools ~/my-tools.md`.\u003cbr\u003e\n\nTo init your project repo, do:\n```bash\n# Interactive wizard (recommended for first use):\nliza init\n\n# Or with explicit flags:\nliza init --claude --codex --gemini --mistral\n```\nThe interactive wizard walks through mode selection (pairing vs full MAS), agent selection, and handles existing `CLAUDE.md` conflicts automatically. Claude is fully automated; for other CLIs see [contract activation](https://github.com/liza-mas/liza/blob/main/contracts/contract-activation.md) for additional manual steps.\n\n### Pairing and MAS Modes\n\n\u003e **New to Liza?** Start with Pairing mode — it's the fastest way to experience how the behavioral contract changes agent behavior. The trust you build watching agents pause at gates, surface assumptions, and validate before claiming done is what makes letting them run autonomously in Multi-Agent mode a comfortable next step.\n\n- **Pairing**: See [Pairing Guide](docs/USAGE_PAIRING.md) — human-agent collaboration under contract\n- **Multi-Agent (Liza)**: See [USAGE](docs/USAGE_MULTI_AGENTS.md), then try the [DEMO](docs/DEMO.md)\n- **Reference**: [Configuration](docs/CONFIGURATION.md) · [Recipes](docs/RECIPES.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)\n\n**Pairing mode** — install once, then start coding in any project (`liza init` still required per project):\n\nWhen starting your CLI session (`claude`, `codex`, ...), pairing mode will be selected automatically.\nIt should start by displaying a canary test inspired by [Van Halen's M\u0026M's trick](https://colterreed.com/blog/the-genius-of-banishing-brown-mms/) — Four words coming from four different contract files to show what the agent actually read thoroughly.\nReading the contract files is enforced by a hook for Claude, by instructions for other agents.\n\nThe agent reads the contract, builds mental models, and operates as a senior peer:\nanalyzing before acting, presenting approval requests at every state change, validating before claiming done.\nOr you may choose to make it your Socratic colleague, your rubber duck, or your challenger.\n\n**Multi-agent mode** — autonomous spec-to-code pipeline:\n1. `liza init \"[Goal description]\" --spec vision.md`. Use the `--entry-point detailed-spec` option to skip the spec phase and go coding directly.\n2. `liza tui` — the TUI shows live system state (agents, tasks, alerts, sprint metrics). From it you can spawn agents with role autocompletion (`s`), pause/resume the system, add tasks, and trigger sprint checkpoints.\n   Check [Quick Start](docs/USAGE_MULTI_AGENTS.md#quick-start-target-usage) for required roles and options (using a CLI other than Claude, logging).\n\nRefer to [How to Produce a Goal Document For Liza](docs/how-to-produce-a-goal.md) to write a good input doc to use as a `--spec` argument.\n\n### Common Commands\n\n```bash\nliza setup                                          # One-time global setup\nliza setup --agent-tools ~/my-tools.md              # Custom AGENT_TOOLS.md\nliza init \"Project goal\" --spec specs/vision.md     # Initialize blackboard\nliza init \"Goal\" --spec s.md \\\n  --config pipeline.yaml --entry-point epic-planning # Pipeline-configured init\nliza add-task --id t1 --desc \"...\" --spec \"...\" \\\n  --done \"...\" --scope \"...\"                        # Add tasks\nliza tui                                            # Live TUI (spawn agents, monitor, manage)\nliza agent coder                                    # Start agent supervisor (or spawn from TUI)\nliza validate                                       # Validate state\nliza get tasks                                      # Query tasks\nliza status                                         # Dashboard overview\nliza proceed                                        # Transition between pipeline phases\nliza pause / liza resume                            # Human intervention\nliza stop / liza start                              # System control\nliza sprint-checkpoint                              # Sprint checkpoint\nliza recover-agent \u003cid\u003e                             # Crash recovery (agents)\nliza recover-task \u003cid\u003e                              # Crash recovery (tasks)\nliza analyze                                        # Circuit breaker analysis\n```\n\n\u003e ️⚠️ To use Claude Code with your Claude subscription, make sure the ANTHROPIC_API_KEY environment variable is not set by default on a new shell start ([Claude support](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code), not specific to Liza).\n\n---\n\n## Architecture\n\nMost spec-driven multi-agent systems are LLM-all-the-way-down: agents coordinating agents, with compliance dependent on\nprompt adherence and artifact-based workflows.\n\nLiza is a hybrid system:\n- The agents are the popular coding agent CLIs.\n- The workflow is declarative but relies on a code-enforced state machine\n- The supervisors that wrap every agent and the validation rules are also deterministic Go code.\n  This means critical invariants — state transitions, role boundaries, merge authority, TDD gates — are enforced\n  mechanically, not by asking a LLM to please follow rules.\n  Liza's mechanical layer cannot fabricate, cannot skip gates, cannot interpret rules flexibly.\n- The LLM side is equally differentiated. Liza agents operate under a behavioral contract: 55+ documented\n  LLM failure modes each mapped to a specific countermeasure, an explicit state machine\n  with forbidden transitions, and tiered rules that define what degrades gracefully\n  versus what never bends.\n\nReliability is built into every component.\n\n```mermaid\ngraph TB\n    AP[\"Doer / Reviewer LLM Agent Pairs · \u003csmall\u003ejudgment layer\u003c/small\u003e\"]\n    H[\"User\"] --\u003e|commands| CLI[\"Go CLI · \u003ci\u003eliza\u003c/i\u003e\"]\n    CLI --\u003e|spawns| S[\"Supervisor · \u003csmall\u003edeterministic Go\u003c/small\u003e\"]\n\n    CLI --\u003e BB[\"YAML Blackboard\u003cbr\u003e\u003csmall\u003estate.yaml\u003c/small\u003e\"]\n    MCP --\u003e BB\n    MCP --\u003e WT[\"Git Worktrees\u003cbr\u003e\u003csmall\u003eisolated workspaces\u003c/small\u003e\"]\n\n    S --\u003e|wraps| AP\n    PL[\"YAML Pipeline \u0026 Roles\"] --\u003e |specializes| S\n    S --\u003e PB\n    BC[\"Behavioral Contract\"] --\u003e|harness| AP\n    PB[\"Prompt Builder\"] --\u003e|bootstrap prompt| AP\n    SK[\"Skills\"] --\u003e|empowers| AP\n    SP[\"Specs\"] \u003c--\u003e|drives / produces| AP\n    AP --\u003e|calls| MCP[\"MCP Tools · \u003csmall\u003edeterministic Go\u003c/small\u003e\"]\n\n    style CLI fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    style S fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    style MCP fill:#4a90d9,stroke:#2c5ea0,color:#fff\n    style AP fill:#e8833a,stroke:#c0652a,color:#fff\n    style PB fill:#5bb87d,stroke:#3d8a5a,color:#fff\n    style BC fill:#5bb87d,stroke:#3d8a5a,color:#fff\n    style SK fill:#5bb87d,stroke:#3d8a5a,color:#fff\n    style SP fill:#5bb87d,stroke:#3d8a5a,color:#fff\n    style BB fill:#b0b8c4,stroke:#8a929e,color:#333\n    style WT fill:#b0b8c4,stroke:#8a929e,color:#333\n    style PL fill:#b0b8c4,stroke:#8a929e,color:#333\n```\n\nRoles aren't composable, Skills are: agents aren't constrained regarding their capabilities by a rigid \"Act as a...\" prompt\nand may use any skill they consider relevant to adapt to the situation.\n\n**Liza has the built-in capability to do things right on the first pass.**\n\nLiza has 13 roles organized in three pipeline phases:\n- **Specification phase**: orchestrator, epic-planner, epic-plan-reviewer, us-writer, us-reviewer\n- **Coding phase**: orchestrator, architect, architecture-reviewer, code-planner, code-plan-reviewer, coder, code-reviewer\n- **Integration phase**: integration-analyst, integration-reviewer, coder, code-reviewer\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                         Human                               │\n│   (leads specs, observes terminals, reads blackboard,       │\n│               kills agents, pauses system)                  │\n└─────────────────────────────────────────────────────────────┘\n                              │\n    ┌─────────── Specification Phase ──────────┐\n    │                                          │\n    │  Orchestrator (decomposes \u0026 rescopes)    │\n    │  Epic Planner ←→ Epic Plan Reviewer      │\n    │  US Writer    ←→ US Reviewer             │\n    │                                          │\n    └──────────────────┬───────────────────────┘\n                       │ liza proceed (us-to-coding, many-to-one)\n    ┌──────────── Coding Phase ────────────────┐\n    │                                          │\n    │  Orchestrator (decomposes \u0026 rescopes)    │\n    │  Architect    ←→ Architecture Reviewer   │\n    │  Code Planner ←→ Code Plan Reviewer      │\n    │  Coder        ←→ Code Reviewer           │\n    │                                          │\n    └──────────────────┬───────────────────────┘\n                       │ all coding tasks merged\n    ┌──────────── Integration Phase ───────────┐\n    │                                          │\n    │  Integration Analyst ←→ Integration Rev. │\n    │  (findings → fix tasks in coding-pair)   │\n    │                                          │\n    └──────────────────┬───────────────────────┘\n                       │\n                       ▼\n              ┌─────────────────┐\n              │   .liza/        │\n              │   state.yaml    │  ← blackboard\n              │   log.yaml      │  ← activity history\n              │   alerts.log    │  ← watch daemon output\n              │   archive/      │  ← terminal-state tasks\n              └─────────────────┘\n                       │\n                       ▼\n              ┌─────────────────┐\n              │  .worktrees/    │\n              │  task-1/        │  ← isolated workspaces\n              │  task-2/        │\n              └─────────────────┘\n```\n\nSee [Architecture](specs/architecture) and [C4 Diagrams](specs/architecture/c4/c4.md).\n\n### Task Lifecycle\n\nEach role pair follows the same intra-pair flow (concrete state names are role-pair-specific, e.g. `DRAFT_CODE`, `IMPLEMENTING_CODE`):\n\n```\ninitial → executing → submitted → reviewing → approved → MERGED\n             │ ↑                      ↓           │\n             │ └────── rejected ──────┘           │\n             │                                     ↓\n             ├──\u003e BLOCKED               INTEGRATION_FAILED\n             │    ├──\u003e SUPERSEDED\n             │    └──\u003e ABANDONED\n             │\n             └──\u003e initial (release claim)\n```\n\nInter-pair transitions (`liza proceed`) create downstream tasks between sprints:\n\n```\n  Spec phase                           Coding phase\n\n  Epic Planner ─approved─► MERGED      Architect ─approved─► MERGED\n       │ epic-to-us (per-subtask)           │ arch-to-code-plan (per-subtask)\n       ▼                                    ▼\n  US Writer ─approved─► MERGED         Code Planner ─approved─► MERGED\n       │ us-to-coding (many-to-one)         │ code-plan-to-coding (per-subtask)\n       ▼                                    ▼\n  Architect (coding phase)             Coder ─approved─► MERGED\n                                            │ all tasks merged\n                                            ▼\n                                       Integration Analyst (auto)\n```\n\nExample of a task on the blackboard:\n```yaml\n    - id: code-planning-1-code-3\n      type: coding\n      role_pair: coding-pair\n      description: Role infrastructure recognizes the 4 new roles with correct runtime/workflow mapping.\n      status: MERGED\n      priority: 1\n      assigned_to: coder-2\n      base_commit: e7625ed69318836dd495b22855df3a8b91fe32b5\n      iteration: 1\n      review_commit: 9d9254b893af477fc34f48063169634d200fa332\n      approved_by: code-reviewer-1\n      merge_commit: 2fa6399223262df6a87c6b1354dfc882b73114c5\n      lease_expires: 2026-03-06T01:47:22.075108537Z\n      spec_ref: specs/plans/sub-pipelines-phase2.md\n      done_when: ToWorkflow(\"epic-planner\") returns \"epic_planner\" (and all 4 pairs); IsValidRuntime(\"us-writer\") returns true; AllRuntime() returns 9 roles; Tests pass\n      scope: internal/roles/roles.go, internal/roles/roles_test.go, internal/models/state.go\n      created: 2026-03-06T01:17:00.99638669Z\n      history:\n        - time: 2026-03-06T01:17:22.075108537Z\n          event: claimed\n          agent: coder-2\n        - time: 2026-03-06T01:19:30.131578505Z\n          event: pre_execution_checkpoint\n          agent: coder-2\n          files_to_modify:\n            - internal/roles/roles.go\n            - internal/roles/roles_test.go\n            - internal/models/state.go\n          intent: Add 4 new role constants (epic-planner, epic-plan-reviewer, us-writer, us-reviewer) with runtime↔workflow mapping, update AllRuntime()/AllWorkflow() to return 9 roles, and add Role* aliases in models/state.go.\n          validation_plan: 'Run `go test ./internal/roles/ ./internal/models/` in worktree. Verify: ToWorkflow(\"epic-planner\")→\"epic_planner\" for all 4 new roles, IsValidRuntime(\"us-writer\")→true, AllRuntime() returns 9 roles.'\n        - time: 2026-03-06T01:22:05.371651393Z\n          event: submitted_for_review\n          agent: coder-2\n        - time: 2026-03-06T01:24:30.366073081Z\n          event: approved\n          agent: code-reviewer-1\n        - time: 2026-03-06T03:06:35.560908548+01:00\n          event: merged\n          agent: code-reviewer-1\n          commit: 2fa6399223262df6a87c6b1354dfc882b73114c5\n          tests_ran: false\n```\n\n---\n\n## Status\n\nSee [Release Notes](docs/release_notes/) for version history and [RELEASE.md](RELEASE.md) for maintainer release workflow.\n\n**Where Liza works today:**\n- **Pairing mode** is battle-tested — agents write **~90% of production code** under human supervision\n- **Multi-agent mode** produces solid specs and code through the full goal-to-merge pipeline with 13 roles across 3 phases — starting from release v0.4.0, all major Liza changes are implemented using this mode\n\nLiza is a collaborative agent network (L4 AI maturity) but its architecture has been designed to support a software factory (L5) where humans focus on strategy and product vision. Still a long way to go.\n\n**Implemented roles:**\n- Orchestrator (decomposes goal into planning tasks)\n- Epic Planner / Epic Plan Reviewer\n- US Writer / US Reviewer\n- Architect / Architecture Reviewer\n- Code Planner / Code Plan Reviewer\n- Coder / Code Reviewer\n- Integration Analyst / Integration Reviewer\n\n**Planned role pairs:**\n- Sprint Analyzer role — analyze agent logs at sprint boundaries, capitalize on patterns via lesson-capture\n- Security Auditor / Security Audit Reviewer — review the security of the code\n\n**Roadmap:**\n- Context handoff as blackboard event — structured positive/negative findings on every task completion\n- Deterministic pre/post hooks at role transitions — mechanical checks before spawning agents and before their handoff\n- Orchestrator-routed model selection — assign tasks to models based on estimated complexity\n\n### Provider Compatibility\n\nThe contract is a capability test. It requires meta-cognitive machinery—the ability to parse instructions as executable specifications, observe state, pause at gates.\n\n| Provider | Classification                          | Notes |\n|----------|-----------------------------------------|-------|\n| Claude Opus 4.x | Fully compatible | Reference provider |\n| GPT-5.x-Codex | Fully compatible | Equally capable |\n| Kimi 2.5 | Compatible but poor on real-world tasks | Responsive to tooling feedback |\n| Mistral Devstral-2 | Partial | Requires explicit activation and supervision |\n| Gemini 2.5 Flash | Incompatible | Architectural limitation—no prompt-level fix |\n\nSee [Model Capability Assessment](docs/demo-benchmark/wrap-up.md) for detailed analysis.\n\n## Naming\n\n**Liza** combines two references:\n\n**Lisa Simpson**—the disciplined, systematic counterpoint to Ralph Wiggum. The [Ralph Wiggum technique](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) loops agents until they converge through persistence. Lisa makes sure the work is actually right.\n\n**ELIZA**—the 1966 chatbot that demonstrated structured dialogue patterns. Liza is about structured collaboration patterns: explicit states, binding verdicts, auditable transitions.\n\nLiza doesn't make agents smarter. It makes them accountable.\n\n## License\n\nApache 2.0\n\n## Acknowledgments\n\nThe behavioral contract draws on research into LLM failure modes, sycophancy patterns, and code generation failures. The multi-agent design incorporates ideas from:\n\n- **[SpecKit](https://github.com/github/spec-kit)** — Project specification\n- **[BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)** — Role templates and workflow patterns\n- **Classical blackboard architecture** — Shared state coordination\n- **[Ralph Wiggum technique](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)** — Iteration until convergence, validated by an adversarial agent instead of mechanical check or self-declaration\n- Stephen Oberther (**[liza-go](https://github.com/smo921/liza-go)**) — Shell to Go CLI migration\n- **[CrewAI](https://github.com/crewAIInc/crewAI)'s composable guardrails concept** — Reduced to Liza's convention-over-code pattern.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliza-mas%2Fliza","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliza-mas%2Fliza","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliza-mas%2Fliza/lists"}