@wkronmiller/lisa 0.1.0

package/bin/lisa.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const { resolve } = require("node:path");
+
+const runtimePath = resolve(__dirname, "lisa-runtime.js");
+const sourcePath = resolve(__dirname, "..", "lisa.ts");
+const useBuiltRuntime = existsSync(runtimePath);
+
+const result = useBuiltRuntime
+  ? spawnSync("bun", [runtimePath, ...process.argv.slice(2)], { stdio: "inherit" })
+  : spawnSync("bun", [sourcePath, ...process.argv.slice(2)], { stdio: "inherit" });
+
+if (result.error) {
+  console.error(useBuiltRuntime
+    ? `Error: Unable to run built lisa runtime at ${runtimePath}`
+    : "Error: Bun is required to run lisa. Install Bun: https://bun.sh");
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/completion.ts

@@ -0,0 +1,58 @@
+/**
+ * Completion detection helpers used by the Lisa CLI.
+ */
+
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+
+export function stripAnsi(input: string): string {
+  return input.replace(ANSI_PATTERN, "");
+}
+
+export function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Returns the last non-empty line of output, after ANSI stripping.
+ */
+export function getLastNonEmptyLine(output: string): string | null {
+  const lines = stripAnsi(output)
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map(line => line.trim())
+    .filter(Boolean);
+
+  return lines.length > 0 ? lines[lines.length - 1] : null;
+}
+
+/**
+ * Checks whether the exact promise tag appears as the final non-empty line.
+ */
+export function checkTerminalPromise(output: string, promise: string): boolean {
+  const lastLine = getLastNonEmptyLine(output);
+  if (!lastLine) return false;
+
+  const escapedPromise = escapeRegex(promise);
+  const pattern = new RegExp(`^<promise>\\s*${escapedPromise}\\s*</promise>$`, "i");
+  return pattern.test(lastLine);
+}
+
+/**
+ * Returns true only when there is at least one task checkbox and all checkboxes are complete.
+ */
+export function tasksMarkdownAllComplete(tasksMarkdown: string): boolean {
+  const lines = tasksMarkdown.split(/\r?\n/);
+  let sawTask = false;
+
+  for (const line of lines) {
+    const match = line.match(/^\s*-\s+\[([ xX\/])\]\s+/);
+    if (!match) continue;
+
+    sawTask = true;
+    if (match[1].toLowerCase() !== "x") {
+      return false;
+    }
+  }
+
+  return sawTask;
+}

package/install.ps1

@@ -0,0 +1,51 @@
+# Install script for Lisa CLI (Windows)
+
+$ErrorActionPreference = "Stop"
+
+Write-Host "Installing Lisa CLI..."
+
+# Check for Bun
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+  Write-Error "Bun is required but not installed. Install Bun: https://bun.sh"
+  exit 1
+}
+
+# Check for optional harness CLIs used by spec generation/import/implementation.
+$hasOpenCode = Get-Command opencode -ErrorAction SilentlyContinue
+$hasClaude = Get-Command claude -ErrorAction SilentlyContinue
+$hasCodex = Get-Command codex -ErrorAction SilentlyContinue
+if (-not $hasOpenCode -and -not $hasClaude -and -not $hasCodex) {
+  Write-Warning "No supported harness CLI found."
+  Write-Host "You can still use lisa spec init, lisa spec status, and lisa spec harness list."
+  Write-Host "To enable agent-backed workflows, install one of:"
+  Write-Host "  OpenCode: npm install -g opencode-ai"
+  Write-Host "  Claude Code: https://claude.ai/code"
+  Write-Host "  Codex: https://developers.openai.com/codex/"
+} elseif (-not $hasOpenCode) {
+  Write-Warning "OpenCode not found. Agent-backed workflows can still use the installed Claude Code or Codex harness."
+}
+
+# Get script directory
+$scriptDir = $PSScriptRoot
+
+# Install dependencies
+Write-Host "Installing dependencies..."
+Push-Location $scriptDir
+bun install
+
+# Link the package (makes 'lisa' command available)
+Write-Host "Linking lisa command..."
+bun link
+
+Pop-Location
+
+Write-Host ""
+Write-Host "Installation complete!"
+Write-Host ""
+Write-Host "Usage:"
+Write-Host ""
+Write-Host "  Lisa Spec CLI:"
+Write-Host "    lisa spec status"
+Write-Host "    lisa spec harness list"
+Write-Host ""
+Write-Host "Learn more: https://github.com/wkronmiller/lisa"

package/install.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Install script for Lisa CLI
+
+set -e
+
+resolve_output_mode() {
+    local normalized_mode
+    normalized_mode="${LISA_OUTPUT_MODE:-}"
+    normalized_mode="${normalized_mode#"${normalized_mode%%[![:space:]]*}"}"
+    normalized_mode="${normalized_mode%"${normalized_mode##*[![:space:]]}"}"
+    normalized_mode="$(printf '%s' "$normalized_mode" | tr '[:upper:]' '[:lower:]')"
+
+    case "$normalized_mode" in
+        interactive)
+            printf '%s' 'interactive'
+            ;;
+        concise)
+            printf '%s' 'concise'
+            ;;
+        *)
+            if [ -t 1 ]; then
+                printf '%s' 'interactive'
+            else
+                printf '%s' 'concise'
+            fi
+            ;;
+    esac
+}
+
+OUTPUT_MODE="$(resolve_output_mode)"
+
+echo "Installing Lisa CLI..."
+
+# Check for Bun
+if ! command -v bun &> /dev/null; then
+    echo "Error: Bun is required but not installed."
+    echo "Install Bun: curl -fsSL https://bun.sh/install | bash"
+    exit 1
+fi
+
+# Check for optional harness CLIs used by spec generation/import/implementation.
+if ! command -v opencode &> /dev/null && ! command -v claude &> /dev/null && ! command -v codex &> /dev/null && ! command -v gemini &> /dev/null; then
+    echo "Warning: No supported harness CLI found."
+    echo "You can still use lisa spec init, lisa spec status, and lisa spec harness list."
+    echo "To enable agent-backed workflows, install one of:"
+    echo "  OpenCode: npm install -g opencode-ai"
+    echo "  Claude Code: https://claude.ai/code"
+    echo "  Codex: https://developers.openai.com/codex/"
+    echo "  Gemini CLI: https://github.com/google-gemini/gemini-cli"
+elif ! command -v opencode &> /dev/null; then
+    echo "Warning: OpenCode not found."
+    echo "Agent-backed workflows can still use the installed Claude Code, Codex, or Gemini CLI harness."
+fi
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Install dependencies
+echo "Installing dependencies..."
+cd "$SCRIPT_DIR"
+bun install
+
+# Link the package (makes 'lisa' command available)
+echo "Linking lisa command..."
+bun link
+
+echo ""
+echo "Installation complete!"
+echo ""
+
+if [ "$OUTPUT_MODE" = "interactive" ]; then
+    echo "Quick start:"
+    echo ""
+    echo "  1. lisa spec init"
+    echo "     Create the .specs workspace for this repo."
+    echo "  2. lisa skill install --local"
+    echo "     Optionally install repo-local Lisa guidance for supported harnesses."
+    echo "  3. lisa spec generate backend <name>"
+    echo "     Draft a new spec before implementation work starts."
+    echo "     or lisa spec import <path...>"
+    echo "     Draft specs from existing code when you are retrofitting coverage."
+    echo "  4. lisa spec implement"
+    echo "     Turn changed specs into code and test updates."
+    echo "  5. lisa spec check --changed"
+    echo "     Verify the changed specs against code, tests, and benchmarks."
+    echo ""
+    echo "Need the full command list? Run 'lisa spec --help'."
+else
+    echo "Next: run 'lisa spec --help' for available commands."
+fi
+
+echo ""
+echo "Learn more: https://github.com/wkronmiller/lisa"

package/lisa.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+import { runCli } from "./src/cli";
+
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@wkronmiller/lisa",
+  "version": "0.1.0",
+  "description": "Lisa, a spec-driven coding agent orchestration framework",
+  "main": "bin/lisa.js",
+  "bin": {
+    "lisa": "bin/lisa.js"
+  },
+  "scripts": {
+    "start": "bun lisa.ts",
+    "build": "bun build lisa.ts --outfile bin/lisa-runtime.js --target bun",
+    "test": "bun test ./tests",
+    "install-local": "bun link"
+  },
+  "files": [
+    "bin/lisa-runtime.js",
+    "bin/lisa.js",
+    "lisa.ts",
+    "src",
+    "skills",
+    "completion.ts",
+    "README.md",
+    "LICENSE",
+    "install.sh",
+    "install.ps1",
+    "uninstall.sh",
+    "uninstall.ps1"
+  ],
+  "keywords": [
+    "opencode",
+    "ai",
+    "lisa",
+    "spec-driven",
+    "iterative-development",
+    "automation",
+    "ai-agent",
+    "coding-assistant",
+    "llm",
+    "claude",
+    "claude-code",
+    "codex",
+    "gpt",
+    "self-correcting",
+    "autonomous",
+    "developer-tools",
+    "cli",
+    "bun",
+    "typescript"
+  ],
+  "author": "wkronmiller",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:wkronmiller/lisa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wkronmiller/lisa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/wkronmiller/lisa/blob/master/README.md",
+  "devDependencies": {
+    "@types/bun": "^1.3.5"
+  }
+}

package/skills/README.md

@@ -0,0 +1,28 @@
+# Lisa Coding Agent Skills
+
+Checked-in Lisa skill artifacts live under `skills/`.
+
+Supported harness artifacts:
+
+- `skills/codex/AGENTS.md`
+- `skills/opencode/AGENTS.md`
+- `skills/claude-code/CLAUDE.md`
+- `skills/gemini/GEMINI.md`
+
+Install 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 top-level `lisa skill install --global|--local` command surface
+- the user-facing `lisa spec ...` command surface
+- the built-in harness registry in `src/harness/registry.ts`
+- the required `.specs/` layout and active spec structure
+- the `lisa spec guide` seed-authoring workflow and its next-step commands

package/skills/claude-code/CLAUDE.md

@@ -0,0 +1,151 @@
+# Lisa for Claude Code
+
+Use this skill when working on Lisa from a Claude Code session.
+
+## What Lisa is
+
+Lisa is a spec-driven agent orchestration CLI. Treat `.specs/` as the source of truth for intended behavior.
+
+Core workflow:
+
+```text
+specs -> git diff -> structured deltas -> plan -> single writer harness -> tests/benchmarks -> parallel read-only verification -> reports
+```
+
+## Working in this repo
+
+- Start with `lisa spec status` to inspect the workspace and harness availability.
+- Review active specs in `.specs/backend/` and `.specs/frontend/` before changing behavior.
+- Prefer repo-local Lisa commands over ad hoc workflows that bypass the spec-first model.
+- When behavior changes, update the relevant spec, code, tests, and checked-in docs or skills together.
+
+If the local `lisa` command is not installed yet, run the same workflows from the checkout with `bun run lisa.ts spec ...`.
+
+## Current CLI surface
+
+```text
+lisa skill install --global|--local
+lisa spec init
+lisa spec config [options]
+lisa spec status
+lisa spec harness list
+lisa spec guide [backend|frontend] [name] [options]
+lisa spec generate [backend|frontend] [name] [options]
+lisa spec implement [options]
+lisa spec check --changed|--all [options]
+lisa spec import <path...> [options]
+lisa spec diff [options]
+```
+
+Common repo-local commands:
+
+```bash
+lisa skill install --local
+lisa skill install --global
+lisa spec config --harness claude-code
+lisa spec status
+lisa spec harness list
+lisa spec guide backend checkout-flow
+lisa spec generate backend checkout-flow
+lisa spec diff
+lisa spec implement
+lisa spec check --changed
+lisa spec check --all
+```
+
+## Installing Lisa guidance
+
+```bash
+lisa skill install --local
+lisa skill install --global
+```
+
+- Local install target: `CLAUDE.md`
+- Global install target: `~/.claude/CLAUDE.md`
+
+## Seed guide workflow
+
+- Run `lisa spec guide backend checkout-flow` when you want Lisa to create or reuse a draft seed spec and point you at the right harness-specific skill artifact.
+- Keep editing the seed spec in `.specs/backend/` or `.specs/frontend/` until the placeholders are replaced with real Summary, Use Cases, Invariants, Failure Modes, Acceptance Criteria, and Out of Scope content.
+- After the spec is ready, return to `lisa spec diff`, `lisa spec implement`, and `lisa spec check --changed`.
+
+## Spec layout
+
+```text
+.specs/
+  backend/
+    <spec-name>.md
+    <spec-name>.bench.<environment>.md
+  frontend/
+    <spec-name>.md
+    <spec-name>.bench.<environment>.md
+  environments/
+    <environment>.yaml
+  config.yaml
+```
+
+Create backend specs in `.specs/backend/` and frontend specs in `.specs/frontend/`.
+Keep environment definitions in `.specs/environments/` and workspace harness settings in `.specs/config.yaml`.
+
+## Spec editing rules
+
+Preserve YAML frontmatter and required sections when creating or updating an active base spec.
+
+```md
+---
+id: backend.example-spec
+status: active
+code_paths:
+  - src/example/**
+test_paths:
+  - tests/example/**
+test_commands:
+  - bun test ./tests
+---
+
+# Summary
+
+## Use Cases
+
+## Invariants
+
+## Failure Modes
+
+## Acceptance Criteria
+
+## Out of Scope
+```
+
+Notes:
+
+- `id`, `status`, and `code_paths` are required in frontmatter.
+- Include at least one of `test_paths` or `test_commands`.
+- `# Summary`, `## Use Cases`, `## Invariants`, `## Acceptance Criteria`, and `## Out of Scope` are required for active base specs.
+- `lisa spec generate` also emits `## Failure Modes`, and planning uses it, so keep that section intact when present.
+- Benchmark sidecars belong next to the base spec as `<spec-name>.bench.<environment>.md`.
+
+## Guardrails
+
+- Do not treat spec deletion as permission to remove code silently.
+- Keep edits inside the mapped repo paths unless a small supporting change is required.
+- Prefer the checked-in workflow in this repository over global harness-specific shortcuts.
+
+## Aborting Operations
+
+If you detect that you cannot complete a task due to missing tools or capabilities (e.g., no web browser for UI changes, no file system access for file modifications), you should abort gracefully rather than looping on a task you cannot complete.
+
+To abort, output one of these formats as your final response:
+
+```
+LISA_ABORT: <reason>
+```
+
+Or for multi-line reasons:
+
+```
+LISA_ABORT_START
+<reason>
+LISA_ABORT_END
+```
+
+The workflow will detect the abort signal, stop execution, and report the reason to the user. This prevents wasted time and provides clear feedback about why the operation could not be completed.

package/skills/codex/AGENTS.md

@@ -0,0 +1,151 @@
+# Lisa for Codex
+
+Use this skill when working on Lisa from a Codex session.
+
+## What Lisa is
+
+Lisa is a spec-driven agent orchestration CLI. Treat `.specs/` as the source of truth for intended behavior.
+
+Core workflow:
+
+```text
+specs -> git diff -> structured deltas -> plan -> single writer harness -> tests/benchmarks -> parallel read-only verification -> reports
+```
+
+## Working in this repo
+
+- Start with `lisa spec status` to inspect the workspace and harness availability.
+- Review active specs in `.specs/backend/` and `.specs/frontend/` before changing behavior.
+- Prefer repo-local Lisa commands over ad hoc workflows that bypass the spec-first model.
+- When behavior changes, update the relevant spec, code, tests, and checked-in docs or skills together.
+
+If the local `lisa` command is not installed yet, run the same workflows from the checkout with `bun run lisa.ts spec ...`.
+
+## Current CLI surface
+
+```text
+lisa skill install --global|--local
+lisa spec init
+lisa spec config [options]
+lisa spec status
+lisa spec harness list
+lisa spec guide [backend|frontend] [name] [options]
+lisa spec generate [backend|frontend] [name] [options]
+lisa spec implement [options]
+lisa spec check --changed|--all [options]
+lisa spec import <path...> [options]
+lisa spec diff [options]
+```
+
+Common repo-local commands:
+
+```bash
+lisa skill install --local
+lisa skill install --global
+lisa spec config --harness codex
+lisa spec status
+lisa spec harness list
+lisa spec guide backend checkout-flow
+lisa spec generate backend checkout-flow
+lisa spec diff
+lisa spec implement
+lisa spec check --changed
+lisa spec check --all
+```
+
+## Installing Lisa guidance
+
+```bash
+lisa skill install --local
+lisa skill install --global
+```
+
+- Local install target: `AGENTS.md`
+- Global install target: `${CODEX_HOME:-~/.codex}/AGENTS.md`
+
+## Seed guide workflow
+
+- Run `lisa spec guide backend checkout-flow` when you want Lisa to create or reuse a draft seed spec and point you at the right harness-specific skill artifact.
+- Keep editing the seed spec in `.specs/backend/` or `.specs/frontend/` until the placeholders are replaced with real Summary, Use Cases, Invariants, Failure Modes, Acceptance Criteria, and Out of Scope content.
+- After the spec is ready, return to `lisa spec diff`, `lisa spec implement`, and `lisa spec check --changed`.
+
+## Spec layout
+
+```text
+.specs/
+  backend/
+    <spec-name>.md
+    <spec-name>.bench.<environment>.md
+  frontend/
+    <spec-name>.md
+    <spec-name>.bench.<environment>.md
+  environments/
+    <environment>.yaml
+  config.yaml
+```
+
+Create backend specs in `.specs/backend/` and frontend specs in `.specs/frontend/`.
+Keep environment definitions in `.specs/environments/` and workspace harness settings in `.specs/config.yaml`.
+
+## Spec editing rules
+
+Preserve YAML frontmatter and required sections when creating or updating an active base spec.
+
+```md
+---
+id: backend.example-spec
+status: active
+code_paths:
+  - src/example/**
+test_paths:
+  - tests/example/**
+test_commands:
+  - bun test ./tests
+---
+
+# Summary
+
+## Use Cases
+
+## Invariants
+
+## Failure Modes
+
+## Acceptance Criteria
+
+## Out of Scope
+```
+
+Notes:
+
+- `id`, `status`, and `code_paths` are required in frontmatter.
+- Include at least one of `test_paths` or `test_commands`.
+- `# Summary`, `## Use Cases`, `## Invariants`, `## Acceptance Criteria`, and `## Out of Scope` are required for active base specs.
+- `lisa spec generate` also emits `## Failure Modes`, and planning uses it, so keep that section intact when present.
+- Benchmark sidecars belong next to the base spec as `<spec-name>.bench.<environment>.md`.
+
+## Guardrails
+
+- Do not treat spec deletion as permission to remove code silently.
+- Keep edits inside the mapped repo paths unless a small supporting change is required.
+- Prefer the checked-in workflow in this repository over global harness-specific shortcuts.
+
+## Aborting Operations
+
+If you detect that you cannot complete a task due to missing tools or capabilities (e.g., no web browser for UI changes, no file system access for file modifications), you should abort gracefully rather than looping on a task you cannot complete.
+
+To abort, output one of these formats as your final response:
+
+```
+LISA_ABORT: <reason>
+```
+
+Or for multi-line reasons:
+
+```
+LISA_ABORT_START
+<reason>
+LISA_ABORT_END
+```
+
+The workflow will detect the abort signal, stop execution, and report the reason to the user. This prevents wasted time and provides clear feedback about why the operation could not be completed.