@wkronmiller/lisa 0.1.0

package/skills/gemini/GEMINI.md

@@ -0,0 +1,151 @@
+# Lisa for Gemini CLI
+
+Use this skill when working on Lisa from a Gemini CLI 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 gemini
+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: `GEMINI.md`
+- Global install target: `~/.gemini/GEMINI.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/opencode/AGENTS.md

@@ -0,0 +1,152 @@
+# Lisa for OpenCode
+
+Use this skill when working on Lisa from an OpenCode 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 opencode
+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: `.opencode/skills/lisa/SKILL.md`
+- Global install target: `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/lisa/SKILL.md`
+- The installed `SKILL.md` wraps the checked-in Lisa guidance with the small OpenCode skill frontmatter.
+
+## 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/src/cli.ts

@@ -0,0 +1,85 @@
+import { resolveOutputMode } from "./output-mode";
+import { runSkillCli } from "./skill/cli";
+import { runSpecCli } from "./spec/cli";
+
+const VERSION = "1.2.2";
+
+function printLisaHelp(): void {
+  const outputMode = resolveOutputMode();
+  const interactive = outputMode === "interactive";
+
+  const header = interactive
+    ? `Lisa turns markdown specs into implementation work, then verifies code, tests, and benchmark budgets against those specs.
+
+Workflow:
+  1. init              Scaffold a .specs workspace for the repo
+  2. generate or import Create or draft specs for the behavior you want
+  3. implement         Apply code and test changes from changed specs
+  4. check             Verify specs against code, tests, and benchmarks
+
+Override output mode with LISA_OUTPUT_MODE=interactive or LISA_OUTPUT_MODE=concise.
+
+`
+    : "Lisa - spec-driven agent orchestration\n\n";
+
+  console.log(`${header}Usage:
+  lisa <command>
+
+Commands:
+  skill            Install Lisa guidance for supported harnesses
+  spec             Run Lisa spec workflows
+
+Top-level options:
+  --help, -h       Show Lisa help
+  --version, -v    Show Lisa version
+
+Environment:
+  LISA_OUTPUT_MODE=interactive|concise  Override help/install copy mode
+
+${interactive ? `Typical flow:
+  1. lisa spec init
+     Create the .specs workspace for this repo.
+  2. lisa skill install --local
+     Optionally install repo-local Lisa guidance for supported harnesses.
+  3. lisa spec generate backend <name>
+     Write a new spec for planned work.
+     or lisa spec import <path...>
+     Draft specs from existing code.
+  4. lisa spec implement
+     Turn changed specs into code and test updates.
+  5. lisa spec check --changed
+     Verify mapped tests, benchmarks, and spec compliance.
+` : ""}
+
+Examples:
+  lisa skill install --local
+  lisa skill install --global
+  lisa spec status
+  lisa spec harness list
+  lisa spec guide backend checkout-flow
+`);
+}
+
+export async function runCli(args: string[], cwd = process.cwd()): Promise<number> {
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(`lisa ${VERSION}`);
+    return 0;
+  }
+
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    printLisaHelp();
+    return 0;
+  }
+
+  if (args[0] === "spec") {
+    return runSpecCli(args.slice(1), cwd);
+  }
+
+  if (args[0] === "skill") {
+    return runSkillCli(args.slice(1), cwd);
+  }
+
+  console.error(`Unknown command: ${args[0]}`);
+  printLisaHelp();
+  return 1;
+}

package/src/harness/base-adapter.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+
+import { installSkillArtifact, resolveLocalSkillWorkspace, resolveSkillArtifactPath } from "../skill/artifacts";
+import { detectHarnessCommand } from "./command";
+import type { HarnessAvailability, HarnessSkillInstallDefinition, SkillInstallScope } from "./types";
+
+export interface BaseAdapterConfig {
+  harnessId: string;
+  commandName: string;
+  envVars: string[];
+  artifactName: string;
+  resolveGlobalRoot: () => string;
+  resolveGlobalDestination?: () => string;
+  resolveLocalDestination?: (cwd: string) => string;
+  renderContent?: (content: string) => string;
+}
+
+export function createBaseAdapterHelpers(config: BaseAdapterConfig, cwd = process.cwd()) {
+  function getSkillInstallDefinition(scope: SkillInstallScope): HarnessSkillInstallDefinition {
+    return {
+      scope,
+      sourcePath: resolveSkillArtifactPath(config.harnessId, config.artifactName),
+      destinationPath: scope === "global"
+        ? config.resolveGlobalDestination ? config.resolveGlobalDestination() : join(config.resolveGlobalRoot(), config.artifactName)
+        : config.resolveLocalDestination ? config.resolveLocalDestination(cwd) : join(resolveLocalSkillWorkspace(cwd), config.artifactName),
+    };
+  }
+
+  return {
+    async detect(): Promise<HarnessAvailability> {
+      return detectHarnessCommand(config.commandName, config.envVars);
+    },
+    async getSkillInstallDefinition(scope: SkillInstallScope): Promise<HarnessSkillInstallDefinition> {
+      return getSkillInstallDefinition(scope);
+    },
+    async installSkill(scope: SkillInstallScope) {
+      const definition = getSkillInstallDefinition(scope);
+      const rawContent = readFileSync(definition.sourcePath, "utf8");
+      const content = config.renderContent ? config.renderContent(rawContent) : undefined;
+      return installSkillArtifact(definition, content, {
+        rootPath: scope === "local" ? resolveLocalSkillWorkspace(cwd) : config.resolveGlobalRoot(),
+        scope,
+      });
+    }
+  };
+}

package/src/harness/claude-code.ts

@@ -0,0 +1,106 @@
+import { join } from "path";
+import { resolveHomeDirectory } from "../skill/artifacts";
+import { createBaseAdapterHelpers } from "./base-adapter";
+import { resolveHarnessCommand, runHarnessCommand } from "./command";
+import type {
+  HarnessAdapter,
+  HarnessCapabilities,
+  HarnessRequest,
+  HarnessResult,
+  Stage,
+} from "./types";
+
+const SUPPORTED_STAGES: Stage[] = ["generate", "implement", "check", "import"];
+const CLAUDE_ENV_VARS = ["LISA_CLAUDE_BINARY", "RALPH_CLAUDE_BINARY"];
+
+function getClaudeCodeCapabilities(): HarnessCapabilities {
+  return {
+    canEditFiles: true,
+    canResumeSessions: false,
+    supportsStructuredOutput: true,
+    supportsStreaming: false,
+    supportsModelSelection: true,
+    supportsReadOnlyMode: true,
+  };
+}
+
+function buildClaudeCodeArgs(request: HarnessRequest): string[] {
+  const args = ["-p", request.prompt];
+
+  if (request.model) {
+    args.push("--model", request.model);
+  }
+
+  if (request.outputSchema) {
+    args.push("--output-format", "json", "--json-schema", JSON.stringify(request.outputSchema));
+  }
+
+  if (request.allowEdits) {
+    args.push("--permission-mode", "bypassPermissions", "--dangerously-skip-permissions");
+  } else {
+    args.push("--permission-mode", "plan");
+  }
+
+  if (request.extraArgs?.length) {
+    args.push(...request.extraArgs);
+  }
+
+  return args;
+}
+
+export function createClaudeCodeHarnessAdapter(cwd = process.cwd()): HarnessAdapter {
+  const baseHelpers = createBaseAdapterHelpers(
+    {
+      harnessId: "claude-code",
+      commandName: "claude",
+      envVars: CLAUDE_ENV_VARS,
+      artifactName: "CLAUDE.md",
+      resolveGlobalRoot: () => join(resolveHomeDirectory(), ".claude"),
+    },
+    cwd
+  );
+
+  return {
+    id: "claude-code",
+    displayName: "Claude Code",
+    description: "Direct adapter for the Claude Code CLI.",
+    supportedStages: SUPPORTED_STAGES,
+    ...baseHelpers,
+    async capabilities(): Promise<HarnessCapabilities> {
+      return getClaudeCodeCapabilities();
+    },
+    async run(request: HarnessRequest): Promise<HarnessResult> {
+      const command = request.env?.LISA_HARNESS_COMMAND ?? resolveHarnessCommand("claude", CLAUDE_ENV_VARS);
+      if (!command) {
+        return {
+          status: "failed",
+          finalText: "Claude Code CLI not found.",
+        };
+      }
+
+      const result = runHarnessCommand(command, buildClaudeCodeArgs(request), request);
+      if (!request.outputSchema || result.status !== "success" || !result.finalText?.trim()) {
+        return result;
+      }
+
+      try {
+        const stdout = typeof result.rawEvents?.[0] === "object" && result.rawEvents[0] !== null && "stdout" in result.rawEvents[0]
+          ? (result.rawEvents[0] as { stdout?: unknown }).stdout
+          : undefined;
+        const rawJson = typeof stdout === "string" ? stdout.trim() : result.finalText;
+        return {
+          ...result,
+          structuredOutput: JSON.parse(rawJson),
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const details = `Failed to parse structured output: ${message}`;
+        return {
+          ...result,
+          status: "failed",
+          finalText: [result.finalText?.trim(), details].filter((entry): entry is string => Boolean(entry)).join("\n\n"),
+        };
+      }
+    },
+  };
+}

package/src/harness/codex.ts

@@ -0,0 +1,80 @@
+import { resolveCodexHome } from "../skill/artifacts";
+import { createBaseAdapterHelpers } from "./base-adapter";
+import { resolveHarnessCommand, runHarnessCommand } from "./command";
+import type {
+  HarnessAdapter,
+  HarnessCapabilities,
+  HarnessRequest,
+  HarnessResult,
+  Stage,
+} from "./types";
+
+const SUPPORTED_STAGES: Stage[] = ["generate", "implement", "check", "import"];
+const CODEX_ENV_VARS = ["LISA_CODEX_BINARY", "RALPH_CODEX_BINARY"];
+
+function getCodexCapabilities(): HarnessCapabilities {
+  return {
+    canEditFiles: true,
+    canResumeSessions: false,
+    supportsStructuredOutput: false,
+    supportsStreaming: false,
+    supportsModelSelection: true,
+    supportsReadOnlyMode: true,
+  };
+}
+
+function buildCodexArgs(request: HarnessRequest): string[] {
+  const args = ["exec"];
+
+  if (request.model) {
+    args.push("--model", request.model);
+  }
+
+  if (request.allowEdits) {
+    args.push("--approval-mode", "full-auto", "--sandbox", "workspace-write");
+  } else {
+    args.push("--sandbox", "read-only");
+  }
+
+  if (request.extraArgs?.length) {
+    args.push(...request.extraArgs);
+  }
+
+  args.push(request.prompt);
+  return args;
+}
+
+export function createCodexHarnessAdapter(cwd = process.cwd()): HarnessAdapter {
+  const baseHelpers = createBaseAdapterHelpers(
+    {
+      harnessId: "codex",
+      commandName: "codex",
+      envVars: CODEX_ENV_VARS,
+      artifactName: "AGENTS.md",
+      resolveGlobalRoot: () => resolveCodexHome(),
+    },
+    cwd
+  );
+
+  return {
+    id: "codex",
+    displayName: "Codex",
+    description: "Direct adapter for the OpenAI Codex CLI.",
+    supportedStages: SUPPORTED_STAGES,
+    ...baseHelpers,
+    async capabilities(): Promise<HarnessCapabilities> {
+      return getCodexCapabilities();
+    },
+    async run(request: HarnessRequest): Promise<HarnessResult> {
+      const command = request.env?.LISA_HARNESS_COMMAND ?? resolveHarnessCommand("codex", CODEX_ENV_VARS);
+      if (!command) {
+        return {
+          status: "failed",
+          finalText: "Codex CLI not found.",
+        };
+      }
+
+      return runHarnessCommand(command, buildCodexArgs(request), request);
+    },
+  };
+}