npm package: @spec-driven/lisa
Description: Lisa, a spec-driven coding agent orchestration framework
Author: wkronmiller
Latest version: 1.2.2

# 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](https://bun.sh/)

Optional for agent-backed workflows:

- A supported harness CLI: `opencode`, `claude`, `codex`, or `gemini`

```bash
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

```bash
# 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

```text
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

```text
.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.

```md
---
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.

```md
---
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.

```md
---
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

| Command | Purpose |
| --- | --- |
| `lisa skill install --global` | Install Lisa guidance into global harness config roots |
| `lisa skill install --local` | Install Lisa guidance into the current repository |
| `lisa spec init` | Scaffold a `.specs` workspace |
| `lisa spec status` | Show workspace and harness status |
| `lisa spec harness list` | List registered harness adapters and capabilities |
| `lisa spec guide [backend|frontend] [name]` | Create or reuse a draft seed spec and point to the right harness skill |
| `lisa spec generate [backend|frontend] [name]` | Draft a spec with preview and approval |
| `lisa spec diff` | Show changed spec deltas and the derived plan |
| `lisa spec implement` | Apply code and test changes from changed specs |
| `lisa spec check --changed` | Verify only impacted specs |
| `lisa spec check --all` | Scan every base spec and verify active ones |
| `lisa spec import <path...>` | Draft specs from existing code paths |
| `lisa skill install --global|--local` | Install checked-in Lisa skill artifacts for supported harnesses |

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

```bash
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:

```bash
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`:

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

```yaml
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

```bash
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