@wkronmiller/lisa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Th0rgal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,407 @@
+# 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