Lisa

Lisa is a spec-driven agent orchestration CLI.

It turns markdown specs into implementation work, runs a selected coding harness, and checks for drift between specs, code, tests, and benchmark budgets.

What it does

• Treats active specs in .specs/ as the source of truth for intended behavior
• Uses Git diffs on specs to decide what implementation work needs to happen
• Runs a single writer harness for implementation and isolated verifier audits during checks
• Prefers deterministic evidence first: code paths, test paths, test commands, benchmark commands
• Supports multiple harness adapters behind one CLI surface

Install

Lisa currently installs via the repository install.sh script.

Requirements:

• Bun

Optional for agent-backed workflows:

• A supported harness CLI: opencode, claude, codex, or gemini

git clone https://github.com/wkronmiller/lisa
cd lisa
./install.sh

The installer runs bun install, links the lisa command locally, and surfaces harness warnings when supported CLIs are missing.

Quick start

# initialize a workspace in your repo
lisa spec init

# inspect workspace and harness availability
lisa spec status

# install Lisa guidance into local harness configs
lisa skill install --local

# see installed harness adapters
lisa spec harness list

# create or reuse a seed spec for your coding agent
lisa spec guide backend checkout-flow

# create a new spec
lisa spec generate backend checkout-flow

# inspect the spec delta and derived implementation plan
lisa spec diff

# implement changed specs
lisa spec implement

# verify changed specs or all specs
lisa spec check --changed
lisa spec check --all

Core workflow

specs -> git diff -> structured deltas -> plan -> single writer harness -> tests/benchmarks -> parallel read-only verification -> reports

Typical loop:

1. Run lisa skill install --local when you want repo-local harness guidance installed automatically.
2. Run lisa spec guide backend <name> when you want a draft seed spec and harness-specific next steps.
3. Write or update a spec under .specs/backend/ or .specs/frontend/.
4. Run lisa spec implement to turn the spec delta into code and test changes.
5. Run lisa spec check --changed or lisa spec check --all to verify conformance.

Spec layout

.specs/
  project.md                          # optional global project descriptor
  config.yaml
  backend/
    <spec-name>.md
    <spec-name>.bench.<environment>.md
  frontend/
    <spec-name>.md
    <spec-name>.bench.<environment>.md
  environments/
    <environment>.yaml

• project.md is an optional global project descriptor (see below)
• Base behavioral specs live in .specs/backend/ and .specs/frontend/
• Benchmark sidecars live next to their base spec
• Environment definitions live in .specs/environments/
• Runtime artifacts and reports are written under .lisa/

Project descriptor

.specs/project.md is an optional file that declares project-level defaults. When present, its content is included as harness context for all stages (generate, implement, check, import), so the harness knows the project stack instead of guessing.

---
language: java
runtime: jdk21
framework: spring-boot
default_code_paths:
  - src/main/java/**
default_test_paths:
  - src/test/java/**
default_test_commands:
  - ./gradlew test
build_commands:
  - ./gradlew build
---

# My Service

A Spring Boot REST API for order management.

## Conventions
- Source code follows standard Maven/Gradle layout.
- Tests use JUnit 5 and Mockito.
- Integration tests live in `src/test/java/**/integration/`.

The frontmatter fields provide structured defaults that individual specs can override. The markdown body is freeform and can describe conventions, patterns, or anything else the harness should know.

When a spec declares its own code_paths, test_paths, or test_commands, those values take precedence over the project-level defaults.

lisa spec init scaffolds a project.md template when creating a new workspace.

Spec format

Base specs are markdown with YAML frontmatter.

---
id: frontend.checkout-flow
status: active
code_paths:
  - src/components/checkout/**
  - src/services/orders/**
test_paths:
  - tests/checkout/**
test_commands:
  - npm run test -- checkout
context_paths:
  - docs/checkout-flow.md
  - src/services/payments/types.ts
owners:
  - payments-team
---

# Summary
Enable customers to complete purchase with payment and address validation.

## Use Cases
- Customer reviews cart and enters shipping address.
- Customer selects a payment method.
- System processes payment and creates an order.

## Invariants
- No order is created until payment is captured.
- Retries never double-charge the customer.

## Failure Modes
- Invalid addresses are rejected before payment.
- Payment retries do not create duplicate orders.

## Acceptance Criteria
- Given valid address and payment, an order is created.
- Given payment decline, the customer can retry with another card.

## Out of Scope
- International shipping.

Required sections for active base specs:

• frontmatter with id, status, code_paths, and test_commands or test_paths
• optional context_paths in frontmatter: additional files passed to the harness as context during generate, implement, and check stages
• # Summary
• ## Use Cases
• ## Invariants
• ## Acceptance Criteria
• ## Out of Scope

lisa spec generate also includes ## Failure Modes, and that section is used by planning workflows, but it is not currently required by the validator.

Status values:

• draft: imported, not yet authoritative
• active: source of truth and enforced
• deprecated: kept for history, not enforced for new work

Benchmark sidecars

Use a sidecar spec when a feature has performance requirements.

---
id: frontend.checkout-flow.bench.ci-perf
kind: benchmark
extends: frontend.checkout-flow
status: active
required: true
environment: ci-perf
command: npm run bench:checkout -- --profile ci-perf --output json
baseline: origin/main
noise_tolerance_pct: 5
metrics:
  page_load_ms: "<= 2000"
  checkout_completion_ms: "<= 5000"
  error_rate_pct: "<= 0.1"
---

# Scenario
Checkout flow under expected concurrent load.

lisa spec check runs the benchmark command and enforces declared thresholds for sidecars marked required: true.

baseline is a label used during verification. Lisa does not check out and run the baseline revision automatically; the benchmark command must emit baseline metrics if you want relative regression checks enforced.

Commands

Harness model

Lisa keeps the core workflow harness-agnostic.

Built-in adapters:

• opencode
• codex
• claude-code
• gemini

Harness selection lives in .specs/config.yaml and can be overridden by CLI flags.

Coding agent skills

Checked-in Lisa skill artifacts live under skills/:

• skills/codex/AGENTS.md
• skills/opencode/AGENTS.md
• skills/claude-code/CLAUDE.md
• skills/gemini/GEMINI.md

Install them with:

lisa skill install --local
lisa skill install --global

Install targets:

• Local: AGENTS.md for Codex, .opencode/skills/lisa/SKILL.md for OpenCode, CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI
• Global: ${CODEX_HOME:-~/.codex}/AGENTS.md, ${XDG_CONFIG_HOME:-~/.config}/opencode/skills/lisa/SKILL.md, ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md

Keep these files aligned with the current CLI surface, supported harness adapters, install destinations, and .specs/ layout whenever Lisa workflows change.

Install those checked-in skills into supported harnesses with:

lisa skill install --local
lisa skill install --global

Install targets:

• Codex: AGENTS.md locally, ${CODEX_HOME:-~/.codex}/AGENTS.md globally
• Claude Code: CLAUDE.md locally, ~/.claude/CLAUDE.md globally
• Gemini CLI: GEMINI.md locally, ~/.gemini/GEMINI.md globally
• OpenCode: .opencode/skills/lisa/SKILL.md locally, ${XDG_CONFIG_HOME:-~/.config}/opencode/skills/lisa/SKILL.md globally

Set LISA_OUTPUT_MODE=interactive or LISA_OUTPUT_MODE=concise to override Lisa's help and installer output mode.

lisa spec guide uses those checked-in skill artifacts to point a coding agent at the right harness-specific guidance before you return to lisa spec diff, lisa spec implement, and lisa spec check. In repos that do not keep checked-in skills/ files yet, Lisa materializes the built-in skill under .lisa/skills/ for the selected harness.

Optional managed agent guidance can be enabled in .specs/config.yaml:

agent_guidance:
  enabled: true
  target: docs/lisa-guidance.md

When enabled, successful lisa spec generate, lisa spec implement, and lisa spec import runs refresh only the Lisa-managed block in the target file with the current command surface, skill artifact paths, and active-spec pointers. Avoid targeting AGENTS.md, CLAUDE.md, or GEMINI.md once those files have diverged from Lisa's bundled root guidance, because Lisa only rewrites those root targets when they still match the bundled artifact exactly or already contain a Lisa-managed block.

Example:

default_stage_profiles:
  generate: planner
  implement: implementer
  check: verifier
  import: importer

profiles:
  planner:
    harness: opencode
    allow_edits: false
  implementer:
    harness: opencode
    allow_edits: true
  verifier:
    harness: opencode
    allow_edits: false
  importer:
    harness: opencode
    allow_edits: false

harnesses:
  opencode:
    command: opencode
    args: []
  codex:
    command: codex
    args: []
  claude-code:
    command: claude
    args: []
  gemini:
    command: gemini
    args: []

Reports and outputs

lisa spec check writes:

• .lisa/spec-report.json
• .lisa/spec-report.md
• .lisa/check/<spec-id>.json for per-spec details

Possible verification verdicts:

• PASS
• FAIL
• UNSURE
• SKIPPED

Development

bun install
bun test ./tests
bun build lisa.ts --outfile bin/lisa-runtime.js --target bun

Package scripts:

• bun run start
• bun run test
• bun run build
• bun run install-local

Project status

Lisa is usable today and, based on the current feature set, roughly 80% complete.

Implemented:

• spec parsing and validation
• Git-backed spec diff and planning
• spec generation, implementation, verification, import, and harness listing
• benchmark sidecars and environment-based checks
• parallel snapshot-isolated verifier audits
• built-in opencode, codex, claude-code, and gemini adapters

Still rough:

• lisa spec status is useful but not very deep
• structured-output handling is not fully consistent across adapters
• edge-case coverage around adapter failures and benchmark parsing can be improved
• draft-to-active review flow after import is still lightweight

Design reference

Current design and workflow guidance lives in AGENTS.md and the self-hosted specs under .specs/backend/.

License

MIT