@lavralabs/lavra 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roberto Mello
+
+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,159 @@
+# lavra
+
+[![License](https://img.shields.io/github/license/roberto-mello/lavra)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/roberto-mello/lavra)](https://github.com/roberto-mello/lavra/releases)
+[![Beads CLI](https://img.shields.io/badge/requires-beads%20CLI-blue)](https://github.com/steveyegge/beads)
+
+**lavra turns your AI coding agent into a development team that gets smarter with every task.**
+
+A plugin for coding agents that orchestrates the full development lifecycle -- from brainstorming to shipping -- while automatically capturing and recalling knowledge so each unit of work makes the next one easier.
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-cc785c?logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
+[![OpenCode](https://img.shields.io/badge/OpenCode-000000?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwb2x5bGluZSBwb2ludHM9IjE2IDE4IDIyIDEyIDE2IDYiLz48cG9seWxpbmUgcG9pbnRzPSI4IDYgMiAxMiA4IDE4Ii8+PC9zdmc+&logoColor=white)](https://opencode.ai/)
+[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-4285F4?logo=google&logoColor=white)](https://github.com/google-gemini/gemini-cli)
+[![Cortex Code](https://img.shields.io/badge/Cortex_Code-29B5E8?logo=snowflake&logoColor=white)](https://www.snowflake.com/en/product/features/cortex-code/)
+
+**[Quick Start](plugins/lavra/docs/quickstart.md)** | **[Full Catalog](docs/CATALOG.md)** | **[Architecture](docs/ARCHITECTURE.md)** | **[Security](docs/SECURITY.md)** | **[Command Map](https://lavra.dev/command-map)** | **[v0.7.0 Release Notes](docs/releases/v0.7.0.md)**
+
+<table>
+<tr>
+<td width="65%">
+
+### Without lavra
+
+- The agent forgets everything between sessions -- you re-explain context every time
+- Planning is shallow: it jumps to code before thinking through the problem
+- Review is inconsistent: sometimes thorough, sometimes a rubber stamp
+- Knowledge stays in your head. When a teammate hits the same bug, they start from zero
+- Shipping is manual: you run tests, create the PR, close tickets, push -- every time
+
+</td>
+<td width="35%" align="center">
+<img src="site/src/assets/forgeftul-agent.jpg" alt="Forgetful agent surrounded by scattered documents" width="280">
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td width="65%">
+
+### With lavra
+
+- **Automatic memory.** Knowledge is captured inline during work and recalled automatically at the start of every session. Hit the same OAuth bug next month? The agent already knows the fix.
+- **Structured planning.** Brainstorm with scope sharpening, research with domain-matched agents, adversarial plan review -- all before a single line of code is written.
+- **Disciplined execution.** Agents follow deviation rules (what to auto-fix vs. escalate), commit per task with traceable bead IDs, and verify every success criterion before marking work done.
+- **Built-in quality gates.** Every implementation runs through a review-fix-learn loop. Knowledge capture is mandatory, not optional.
+- **Team-shareable knowledge.** Memory lives in `.lavra/memory/knowledge.jsonl`, tracked by git. Your team compounds knowledge together.
+
+</td>
+<td width="35%" align="center">
+<img src="site/src/assets/agent-with-memory.jpg" alt="Agent with memory climbing stairs of compounding knowledge" width="280">
+</td>
+</tr>
+</table>
+
+## The workflow
+
+Most of the time, you type three commands:
+
+```
+/lavra-design "I want users to upload photos for listings"
+```
+
+This runs the full planning pipeline as a single command: interactive brainstorm with scope sharpening, structured plan with phased beads, domain-matched research agents, plan revision, and adversarial review. The output is detailed enough that implementation is mechanical.
+
+```
+/lavra-work
+```
+
+Picks up the approved plan and implements it. Auto-routes between single and multi-bead parallel execution. Includes mandatory review, fix loop, and knowledge curation -- all automatic.
+
+```
+/lavra-ship
+```
+
+Rebases on main, runs tests, scans for secrets and debug leftovers, creates the PR, closes beads, and pushes the backup. One command to land the plane.
+
+Add `/lavra-qa` between work and ship when building web apps -- it maps changed files to routes and runs browser-based verification with screenshots.
+
+## Who this is for
+
+Anyone using coding agents who wants consistent, high-quality output instead of hoping the agent gets it right this time.
+
+- **Non-technical users:** `/lavra-design "build me X"` handles the brainstorming, planning, and research. `/lavra-work` handles the implementation with built-in quality gates. You get working software without needing to know how to code.
+- **Solo developers:** The memory system acts as a second brain. Past decisions, patterns, and gotchas surface automatically when they're relevant.
+- **Teams:** Knowledge compounds across contributors. One person's hard-won insight becomes everyone's starting context.
+
+## Install
+
+**Requires:** [beads CLI](https://github.com/steveyegge/beads), `jq`, `sqlite3`
+
+```bash
+npx @lavralabs/lavra@latest
+```
+
+Or manual:
+
+```bash
+git clone https://github.com/roberto-mello/lavra.git
+cd lavra
+./install.sh               # Claude Code (default)
+./install.sh --opencode    # OpenCode
+./install.sh --gemini      # Gemini CLI
+./install.sh --cortex      # Cortex Code
+```
+
+<details>
+<summary><strong>All commands</strong></summary>
+
+**Pipeline (4):** `/lavra-design`, `/lavra-work`, `/lavra-qa`, `/lavra-ship`
+
+**Supporting (9):** `/lavra-quick` (fast path with escalation), `/lavra-learn` (knowledge curation), `/lavra-recall` (mid-session search), `/lavra-checkpoint` (save progress), `/lavra-retro` (weekly analytics), `/lavra-import`, `/lavra-triage`, `/changelog`, `/test-browser`
+
+**Power-user (6):** `/lavra-plan`, `/lavra-research`, `/lavra-eng-review`, `/lavra-review` (15 specialized review agents), `/lavra-work-ralph` (autonomous retry), `/lavra-work-teams` (persistent workers)
+
+**30 specialized agents** across review, research, design, workflow, and docs. Each runs at the right model tier to keep costs 60-70% lower than running everything on Opus.
+
+See [docs/CATALOG.md](docs/CATALOG.md) for the full listing.
+
+</details>
+
+## How knowledge compounds
+
+```
+brainstorm  --DECISION-->  design
+design      <--LEARNED/PATTERN--  auto-recall from prior work
+research    --FACT/INVESTIGATION-->  plan revision
+work        --LEARNED (inline)-->  mandatory knowledge gate
+review      --LEARNED-->  issues become future recall
+retro       synthesizes patterns, surfaces gaps
+```
+
+Six knowledge types (LEARNED, DECISION, FACT, PATTERN, INVESTIGATION, DEVIATION) are captured inline during work and stored in `.lavra/memory/knowledge.jsonl`. At session start, relevant entries are recalled automatically based on your current beads and git branch. The system gets smarter over time -- not just for you, but for your whole team.
+
+<details>
+<summary><strong>Configuration</strong></summary>
+
+**`.lavra/config/lavra.json`** (created automatically) -- toggle workflow phases and execution behavior:
+
+```json
+{
+  "workflow": { "research": true, "plan_review": true, "goal_verification": true },
+  "execution": { "max_parallel_agents": 3, "commit_granularity": "task" }
+}
+```
+
+**`/project-setup`** -- for brownfield projects, run this to generate a codebase profile (stack, architecture, conventions) that informs planning.
+
+</details>
+
+## Acknowledgments
+
+Built by [Roberto Mello](https://github.com/roberto-mello), extending [compound-engineering](https://github.com/EveryInc/compound-engineering-plugin) by [Every](https://every.to). Task tracking by [Beads](https://github.com/steveyegge/beads).
+
+Inspired by Every's writing on [compound engineering](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents), [gstack](https://github.com/garrytan/gstack) by Garry Tan (role-based skills for autonomous workflows), and [Get Shit Done](https://github.com/gsd-build/get-shit-done) (spec-driven development with context engineering).
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execSync, spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const INSTALL_SH = path.join(PKG_ROOT, "install.sh");
+const UNINSTALL_SH = path.join(PKG_ROOT, "uninstall.sh");
+const PKG_JSON = path.join(PKG_ROOT, "package.json");
+
+// ---------------------------------------------------------------------------
+// Version
+// ---------------------------------------------------------------------------
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(PKG_JSON, "utf8"));
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+const VERSION = getVersion();
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+const FLAG = {
+  claude: args.includes("--claude"),
+  opencode: args.includes("--opencode"),
+  gemini: args.includes("--gemini"),
+  global: args.includes("--global"),
+  local: args.includes("--local"),
+  uninstall: args.includes("--uninstall"),
+  yes: args.includes("--yes") || args.includes("-y"),
+  help: args.includes("--help") || args.includes("-h"),
+};
+
+// Positional argument: optional target directory path
+const _positional = args.find((a) => !a.startsWith("-"));
+const TARGET_PATH = _positional ? path.resolve(_positional) : null;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function banner() {
+  // ASCII art banner is printed by install.sh via shared-functions.sh print_banner()
+}
+
+function usage() {
+  banner();
+  console.log("  Usage:");
+  console.log("    npx @lavralabs/lavra@latest                Interactive installer");
+  console.log("    npx @lavralabs/lavra@latest --claude       Claude Code (local project)");
+  console.log("    npx @lavralabs/lavra@latest --opencode     OpenCode (local project)");
+  console.log("    npx @lavralabs/lavra@latest --gemini       Gemini CLI (local project)");
+  console.log("    npx @lavralabs/lavra@latest --global       Install globally (~/.claude/)");
+  console.log("    npx @lavralabs/lavra@latest --uninstall    Uninstall from current project");
+  console.log("    npx @lavralabs/lavra@latest --yes          Skip confirmation prompts");
+  console.log("");
+  console.log("  Flags can be combined:");
+  console.log("    npx @lavralabs/lavra@latest --opencode --yes");
+  console.log("    npx @lavralabs/lavra@latest --claude --global");
+  console.log("");
+}
+
+function die(msg) {
+  console.error(`\n  Error: ${msg}\n`);
+  process.exit(1);
+}
+
+function ensureBash() {
+  try {
+    execSync("bash --version", { stdio: "ignore" });
+  } catch {
+    die("bash is required but was not found on your system.");
+  }
+}
+
+function ensureScript(scriptPath, label) {
+  if (!fs.existsSync(scriptPath)) {
+    die(`${label} not found at ${scriptPath}. The package may be corrupted.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Interactive prompts
+// ---------------------------------------------------------------------------
+
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+async function promptRuntime(rl) {
+  console.log("  Select runtime:");
+  console.log("  1. Claude Code");
+  console.log("  2. OpenCode");
+  console.log("  3. Gemini CLI");
+  console.log("");
+
+  while (true) {
+    const answer = await ask(rl, "  > ");
+    switch (answer) {
+      case "1": return "claude";
+      case "2": return "opencode";
+      case "3": return "gemini";
+      default:
+        console.log("  Please enter 1, 2, or 3.");
+    }
+  }
+}
+
+async function promptScope(rl) {
+  console.log("");
+  console.log("  Install scope:");
+  console.log("  1. This project (current directory)");
+  console.log("  2. Global (~/.claude/)");
+  console.log("");
+
+  while (true) {
+    const answer = await ask(rl, "  > ");
+    switch (answer) {
+      case "1": return "local";
+      case "2": return "global";
+      default:
+        console.log("  Please enter 1 or 2.");
+    }
+  }
+}
+
+async function promptUninstallOrInstall(rl) {
+  console.log("  Action:");
+  console.log("  1. Install");
+  console.log("  2. Uninstall");
+  console.log("");
+
+  while (true) {
+    const answer = await ask(rl, "  > ");
+    switch (answer) {
+      case "1": return "install";
+      case "2": return "uninstall";
+      default:
+        console.log("  Please enter 1 or 2.");
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+function runScript(scriptPath, scriptArgs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("bash", [scriptPath, ...scriptArgs], {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    });
+
+    child.on("error", (err) => {
+      reject(new Error(`Failed to start bash: ${err.message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Script exited with code ${code}`));
+      }
+    });
+  });
+}
+
+function buildInstallArgs(runtime, scope) {
+  const scriptArgs = [];
+
+  // Runtime flag
+  if (runtime === "opencode") scriptArgs.push("-opencode");
+  if (runtime === "gemini") scriptArgs.push("-gemini");
+  // Claude Code is the default — no flag needed
+
+  // --yes passthrough
+  if (FLAG.yes) scriptArgs.push("--yes");
+
+  // Target directory
+  // For global: pass no path — install.sh defaults to ~/.claude and sets GLOBAL_INSTALL=true
+  // Passing ~/.claude explicitly would be treated as a local install, breaking bd init skip
+  if (scope !== "global") {
+    scriptArgs.push(TARGET_PATH || process.cwd());
+  }
+
+  return scriptArgs;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (FLAG.help) {
+    usage();
+    process.exit(0);
+  }
+
+  ensureBash();
+  banner();
+
+  // --- Uninstall path ---
+  if (FLAG.uninstall) {
+    ensureScript(UNINSTALL_SH, "uninstall.sh");
+    const target = TARGET_PATH || process.cwd();
+    console.log(`  Uninstalling lavra from ${target}...\n`);
+    try {
+      await runScript(UNINSTALL_SH, [target]);
+      console.log("\n  Uninstall complete.\n");
+    } catch (err) {
+      die(err.message);
+    }
+    return;
+  }
+
+  ensureScript(INSTALL_SH, "install.sh");
+
+  // Determine runtime
+  let runtime;
+  const runtimeFlags = [FLAG.claude, FLAG.opencode, FLAG.gemini].filter(Boolean).length;
+  if (runtimeFlags > 1) {
+    die("Specify only one runtime: --claude, --opencode, or --gemini");
+  }
+
+  if (FLAG.claude) runtime = "claude";
+  else if (FLAG.opencode) runtime = "opencode";
+  else if (FLAG.gemini) runtime = "gemini";
+
+  // Determine scope
+  let scope;
+  if (FLAG.global && FLAG.local) {
+    die("Specify only one scope: --global or --local");
+  }
+  if (FLAG.global) scope = "global";
+  else if (FLAG.local) scope = "local";
+  else if (TARGET_PATH) scope = "local"; // path argument implies local
+  else if (FLAG.yes) scope = "local";   // --yes with no scope defaults to local
+
+  // Interactive prompts if needed
+  if (!runtime || !scope) {
+    const rl = createRL();
+    try {
+      if (!runtime) {
+        runtime = await promptRuntime(rl);
+        console.log("");
+      }
+      if (!scope) {
+        scope = await promptScope(rl);
+        console.log("");
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  // Build args and run
+  const scriptArgs = buildInstallArgs(runtime, scope);
+  const runtimeLabel = {
+    claude: "Claude Code",
+    opencode: "OpenCode",
+    gemini: "Gemini CLI",
+  }[runtime];
+  const scopeLabel = scope === "global" ? "globally" : "in current project";
+
+  try {
+    await runScript(INSTALL_SH, scriptArgs);
+    console.log("");
+  } catch (err) {
+    die(err.message);
+  }
+}
+
+main().catch((err) => {
+  die(err.message);
+});