@esneiderbravo/speclaw 0.1.0

package/ATTRIBUTION.md

@@ -0,0 +1,34 @@
+# Attribution
+
+speclaw is a self-contained suite. It does **not** bundle, fork, or depend on
+OpenSpec or CodeGraph at runtime — its spec workflow (the **spec** module) and
+its code graph (the **Compass** module) are original implementations written
+from scratch. But the ideas came from two excellent open-source projects, and
+they deserve the credit. Please star and support the originals:
+
+## OpenSpec — inspiration for the spec module
+
+- **Repo**: https://github.com/Fission-AI/openspec
+- **License**: MIT — Copyright (c) Fission AI
+- **What we took**: the *idea* of spec-driven development for AI agents —
+  proposals, delta specs, a `changes/` workflow, and archiving. speclaw's spec
+  module (`draft → build → sync → archive → explore`, the `spec_*` tools, and
+  the `spec/` layout) is our own implementation of that idea, deliberately
+  simpler, with no external CLI. No OpenSpec code is included.
+
+## CodeGraph — inspiration for the Compass module
+
+- **Repo**: https://github.com/colbymchenry/codegraph
+- **License**: MIT — Copyright (c) Colby McHenry
+- **What we took**: the *idea* of a local, pre-indexed code knowledge graph
+  that saves an agent the tokens of grep/read loops, with semantic search over
+  nodes. speclaw's Compass module (tree-sitter parsing, a `node:sqlite` graph
+  of nodes/edges, a local vector store, and the `compass_*` tools) is our own
+  implementation. No CodeGraph code is included.
+
+## Everything else
+
+The foundation (the LAWS constitution and the granular `docs/standards/`), the
+`ai-specs/` multi-IDE distribution standard, the skill/agent packs, and the MCP
+server are original work by Esneider Bravo, distilled from real production
+projects, and released under the MIT license of this repository.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esneider Bravo
+
+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,134 @@
+<div align="center">
+
+<img src="brand/speclaw-banner.svg" width="820" alt="speclaw — where specs become law">
+
+<br/>
+
+<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=0E8E8E&labelColor=0B0F10&style=flat-square&label=npm" alt="npm"></a>
+&nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8E8E?labelColor=0B0F10&style=flat-square" alt="MIT"></a>
+&nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22">
+
+<br/><br/>
+
+<p align="center">
+<b>AI agents are brilliant and blind</b> — brilliant at writing code, blind to <i>your</i>
+project's rules. <b>speclaw</b> hands them what they're missing: the codebase's
+<b>written laws</b> (a constitution built from your real code), a <b>local map</b> to
+navigate it without burning tokens, and a <b>disciplined workflow</b> for every change.
+<br/>
+One command. No cloud, no LLM, no API keys — <b>everything runs on your machine.</b>
+</p>
+
+<img src="https://img.shields.io/badge/100%25_local-0E8E8E?labelColor=0B0F10&style=flat-square" alt="100% local">
+&nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-0E8E8E?labelColor=0B0F10&style=flat-square" alt="no LLM">
+&nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-0E8E8E?labelColor=0B0F10&style=flat-square" alt="CLI + MCP">
+&nbsp;<img src="https://img.shields.io/badge/any_agent-0E8E8E?labelColor=0B0F10&style=flat-square" alt="any agent">
+
+</div>
+
+<br/>
+
+> [!TIP]
+> **One command sets everything up.** Run `npx @esneiderbravo/speclaw init`, pick the agents you
+> use, and speclaw scaffolds the project, indexes your code, and hands your agent
+> a ready-to-paste prompt to finish the setup.
+
+<br/>
+
+## ◆ Quick start
+
+<p align="center">
+  <img src="brand/terminal-quickstart.svg" width="800" alt="npx @esneiderbravo/speclaw init">
+</p>
+
+<p align="center">Copy &amp; run in your project root: <code>npx @esneiderbravo/speclaw init</code></p>
+
+`init` will:
+
+1. **Ask which agents you use** (Claude Code, Cursor, Codex, …) — and configure
+   only those. Add more later; nothing is forced on you.
+2. Write the **foundation** (constitution + standards) and the **spec workflow**.
+3. **Index your code** with a live progress bar and a summary of what it found.
+4. Register the speclaw **MCP server** in each chosen agent's config.
+5. Print a prompt to paste into your agent so it fills the constitution with your
+   project's real architecture and conventions.
+
+Works with `npm`, `pnpm` (`pnpm dlx @esneiderbravo/speclaw init`), and `yarn`.
+
+<br/>
+
+## ◆ It looks like this
+
+<p align="center">
+  <img src="brand/terminal-init.svg" width="800" alt="speclaw init — terminal output">
+</p>
+
+<p align="center"><i>Teal steps, green checks, a live progress bar — themed with the speclaw palette.</i></p>
+
+<br/>
+
+## ◆ The suite — four modules
+
+| Module | What it does |
+| :-- | :-- |
+| **Foundation** | The project's constitution: `LAWS.md` binding a set of granular standards under `docs/standards/` (base, architecture, backend, frontend, testing, documentation, conventions, spec-workflow), plus strict `CLAUDE.md` / `AGENTS.md` agent contracts — filled from your real codebase. |
+| **Compass** | speclaw's own local code graph. Parses your code (tree-sitter) into nodes + edges plus a local vector store, so an agent finds and understands code with a fraction of the tokens a grep/read loop would cost. No LLM, 100% local, lives in `.speclaw/` (gitignored). |
+| **Spec** | speclaw's own spec-driven workflow: `draft → build → sync → archive` (and `explore`), backed by `spec_*` engine tools. No external CLI. |
+| **Tools** | Opt-in packs of skills and subagents (currently the dev-agents) that agents use for specific tasks. |
+
+Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) and the Spec module by [OpenSpec](https://github.com/Fission-AI/openspec) — both MIT. speclaw reimplements the ideas as its own code and gives full credit; see [ATTRIBUTION.md](ATTRIBUTION.md).
+
+<br/>
+
+## ◆ Two ways to use it
+
+speclaw meets you where you are. Everything works through the **CLI** — so no one
+is blocked by MCP setup — and the same capabilities are exposed as **MCP tools**
+for a smoother, integrated experience once configured. An agent without MCP can
+still use Compass and the spec engine by calling the CLI from its shell.
+
+<p align="center"><b>CLI</b> — the installer &amp; operator, runs anywhere <code>node</code> does</p>
+<p align="center"><img src="brand/terminal-cli.svg" width="800" alt="speclaw CLI commands"></p>
+
+<p align="center"><b>MCP</b> — the integrated agent surface, auto-registered by <code>init</code></p>
+<p align="center"><img src="brand/terminal-mcp.svg" width="800" alt="speclaw MCP tools"></p>
+
+<br/>
+
+## ◆ What lands in your project
+
+<p align="center">
+  <img src="brand/terminal-tree.svg" width="800" alt="what speclaw writes into your project">
+</p>
+
+<br/>
+
+## ◆ Philosophy — why "laws"?
+
+> [!NOTE]
+> A guideline is a suggestion. A **law** is enforced. The most common failure mode
+> of AI coding agents isn't lack of capability — it's working without the project's
+> tacit knowledge: the rules the team actually lives by. speclaw makes that
+> knowledge explicit, executable, and binding, and gives agents a local map
+> (Compass) and a disciplined workflow (Spec) to act on it — without burning tokens.
+
+<br/>
+
+## ◆ Requirements
+
+- **Node.js ≥ 22** — uses the built-in `node:sqlite`.
+- **No native builds, no services, no API keys, no LLM download.** Tree-sitter
+  parsers ship as WASM; the vector store is local.
+
+<br/>
+
+<div align="center">
+
+**[MIT](LICENSE)** &nbsp;·&nbsp; built on ideas from
+[OpenSpec](https://github.com/Fission-AI/openspec) &&nbsp;
+[CodeGraph](https://github.com/colbymchenry/codegraph) &nbsp;·&nbsp;
+see [ATTRIBUTION.md](ATTRIBUTION.md)
+
+<i>speclaw · where specs become law</i>
+
+</div>

package/dist/cli/commands/agent.js

@@ -0,0 +1,42 @@
+import { AGENTS, agentById, configureAgent, detectConfiguredAgents } from "../../shared/agents.js";
+import { emptyReport } from "../../shared/install.js";
+import { ui } from "../lib/ui.js";
+/**
+ * List configured agents or configure a new one (symlinks + MCP).
+ *
+ * @param flags - Parsed flags; `_[0]` is the subcommand (`list`/`add`) and `_[1]` the agent id.
+ */
+export async function runAgent(flags) {
+    const cwd = process.cwd();
+    const [sub, id] = flags._;
+    if (sub === "list" || !sub) {
+        const configured = new Set(detectConfiguredAgents(cwd));
+        ui.heading("Agents");
+        for (const a of AGENTS) {
+            const mark = configured.has(a.id) ? ui.code("configured") : "—";
+            console.log(`  ${a.id.padEnd(10)} ${a.label.padEnd(22)} ${mark}`);
+        }
+        ui.plain();
+        ui.info("Add one:  speclaw agent add <id>");
+        return;
+    }
+    if (sub === "add") {
+        if (!id || !agentById(id)) {
+            ui.err(`Usage: speclaw agent add <${AGENTS.map((a) => a.id).join("|")}>`);
+            process.exit(1);
+        }
+        const report = emptyReport();
+        configureAgent(cwd, id, report);
+        ui.ok(`${agentById(id).label} configured`);
+        for (const s of report.symlinks)
+            ui.info(s);
+        for (const w of report.written)
+            ui.info(w);
+        if (!report.symlinks.length && !report.written.length) {
+            ui.warn("Nothing to do (already configured, or run `speclaw init` first).");
+        }
+        return;
+    }
+    ui.err(`Unknown: agent ${sub}. Use: agent list | agent add <id>`);
+    process.exit(1);
+}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,21 @@
+import { doctor } from "../../modules/foundation/doctor.js";
+import { ui } from "../lib/ui.js";
+/** Verify the installation, printing each check and exiting non-zero on failure. */
+export async function runDoctor(_flags) {
+    const checks = doctor(process.cwd());
+    ui.heading("speclaw doctor");
+    for (const c of checks) {
+        if (c.ok)
+            ui.ok(`${c.name} — ${c.detail}`);
+        else
+            ui.err(`${c.name} — ${c.detail}`);
+    }
+    const failed = checks.filter((c) => !c.ok).length;
+    ui.plain();
+    if (failed === 0)
+        ui.ok("Everything is within the law.");
+    else {
+        ui.warn(`${failed} check(s) failed.`);
+        process.exit(1);
+    }
+}

package/dist/cli/commands/index-build.js

@@ -0,0 +1,24 @@
+import { buildIndex } from "../../modules/compass/indexer.js";
+import { startWatch } from "../../modules/compass/watcher.js";
+import { ui, renderProgress, clearProgress } from "../lib/ui.js";
+/** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
+export async function runIndex(_flags) {
+    const cwd = process.cwd();
+    ui.step("Indexing with Compass");
+    const start = Date.now();
+    const stats = await buildIndex(cwd, (e) => renderProgress(e.done, e.total, e.file));
+    clearProgress();
+    const secs = ((Date.now() - start) / 1000).toFixed(1);
+    ui.ok(`${stats.files} files · ${stats.nodes} nodes · ${stats.edges} edges · ` +
+        `${stats.embeddings} embeddings · ${stats.unchanged} unchanged  (${secs}s)`);
+}
+/** Build the initial index, then watch for file changes to keep it fresh. */
+export async function runWatch(_flags) {
+    const cwd = process.cwd();
+    ui.step("Building initial index");
+    await buildIndex(cwd);
+    const status = startWatch(cwd);
+    ui.ok(`Watching for changes (${status.mode}). Press Ctrl+C to stop.`);
+    // keep the process alive
+    await new Promise(() => { });
+}

package/dist/cli/commands/init.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as clack from "@clack/prompts";
+import { scaffold } from "../../modules/foundation/scaffold.js";
+import { specInit } from "../../modules/spec/engine.js";
+import { buildIndex } from "../../modules/compass/indexer.js";
+import { AGENTS, agentById } from "../../shared/agents.js";
+import { loadPacks } from "../../modules/tools/packs.js";
+import { list } from "../lib/args.js";
+import { ui, c, banner, renderProgress, clearProgress, box } from "../lib/ui.js";
+const PACK_LABELS = {
+    agents: "dev-agents (backend · frontend · product)",
+};
+function detectProjectName(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+        if (pkg.name)
+            return String(pkg.name).replace(/^@[^/]+\//, "");
+    }
+    catch {
+        /* ignore */
+    }
+    return path.basename(cwd);
+}
+/**
+ * Interactive setup: pick agents and packs, scaffold, index, and print the handoff prompt.
+ *
+ * @param flags - Parsed flags; runs interactively on a TTY unless `--agents`, `--yes`, or
+ *   `-y` is set. Honors `--project-name`, `--ticket-prefix`, `--team-language`, `--packs`,
+ *   and `--no-index`.
+ */
+export async function runInit(flags) {
+    const cwd = process.cwd();
+    const projectName = flags["project-name"] || detectProjectName(cwd);
+    const interactive = Boolean(process.stdin.isTTY) && !flags.agents && !flags.yes && !flags.y;
+    let agents;
+    let packs;
+    let ticketPrefix = flags["ticket-prefix"];
+    let teamLanguage = flags["team-language"];
+    banner();
+    if (interactive) {
+        const answers = await clack.group({
+            agents: () => clack.multiselect({
+                message: "Which agents do you use? (space to select)",
+                options: AGENTS.map((a) => ({ value: a.id, label: a.label })),
+                initialValues: ["claude"],
+                required: true,
+            }),
+            packs: () => clack.multiselect({
+                message: "Which tool packs to install?",
+                options: Object.entries(loadPacks()).map(([id, def]) => ({
+                    value: id,
+                    label: id,
+                    hint: def.description.slice(0, 50),
+                })),
+                initialValues: ["agents"],
+                required: false,
+            }),
+            ticketPrefix: () => clack.text({ message: "Ticket prefix (optional, e.g. FAR)", defaultValue: "" }),
+            teamLanguage: () => clack.text({ message: "Team communication language", defaultValue: "English" }),
+        }, { onCancel: () => process.exit(1) });
+        agents = answers.agents;
+        packs = answers.packs;
+        ticketPrefix = answers.ticketPrefix || undefined;
+        teamLanguage = answers.teamLanguage || undefined;
+    }
+    else {
+        agents = list(flags.agents).length ? list(flags.agents) : ["claude"];
+        packs = list(flags.packs).length ? list(flags.packs) : ["agents"];
+    }
+    const unknownAgents = agents.filter((a) => !agentById(a));
+    if (unknownAgents.length) {
+        ui.err(`Unknown agent(s): ${unknownAgents.join(", ")}. Known: ${AGENTS.map((a) => a.id).join(", ")}`);
+        process.exit(1);
+    }
+    const profile = {
+        project_name: projectName,
+        ...(ticketPrefix ? { ticket_prefix: ticketPrefix } : {}),
+        ...(teamLanguage ? { team_language: teamLanguage } : {}),
+    };
+    // 1. Content + chosen agents, with a check per piece installed
+    ui.step(`Setting up ${c.bold(c.cyan(projectName))}`);
+    scaffold(cwd, profile, packs, agents);
+    ui.ok(`Foundation ${c.muted("— LAWS.md + 8 standards + CLAUDE.md/AGENTS.md")}`);
+    ui.ok(`Spec workflow ${c.muted("— draft · build · sync · archive · explore")}`);
+    for (const p of packs)
+        ui.ok(`${PACK_LABELS[p] ?? p + " pack"}`);
+    specInit(cwd);
+    ui.ok(`Spec workspace ${c.muted("— spec/")}`);
+    ui.step("Configuring agents");
+    for (const id of agents)
+        ui.ok(`${agentById(id).label} ${c.muted("— symlinks + MCP")}`);
+    // 2. Compass index with progress
+    if (!flags["no-index"]) {
+        ui.step("Indexing your code with Compass");
+        const stats = await buildIndex(cwd, (e) => renderProgress(e.done, e.total, e.file));
+        clearProgress();
+        ui.ok(c.bold(c.cream(String(stats.files))) + c.muted(" files · ") +
+            c.bold(c.cream(String(stats.nodes))) + c.muted(" nodes · ") +
+            c.bold(c.cream(String(stats.edges))) + c.muted(" edges · ") +
+            c.bold(c.cream(String(stats.embeddings))) + c.muted(" embeddings"));
+    }
+    // 3. Handoff prompt for the chosen agent
+    const primary = agentById(agents[0]);
+    ui.step("You're set — one last step");
+    ui.info(`Paste this into ${c.cyan(primary.label)} to build your constitution:`);
+    ui.plain();
+    box([
+        "Complete speclaw's foundation: analyze this repo and fill",
+        "LAWS.md and docs/standards/* with the real architecture,",
+        "quality gates and conventions. Use init_project to start.",
+    ], "prompt");
+    ui.plain();
+    ui.info(`The dev-agents read those standards for your stack — filling them well`);
+    ui.info(`makes them stack-aware.`);
+    ui.plain();
+    ui.info(`Add an agent:   ${ui.code("speclaw agent add cursor")}`);
+    ui.info(`Refresh index:  ${ui.code("speclaw index")}`);
+    ui.info(`Health check:   ${ui.code("speclaw doctor")}`);
+    ui.plain();
+}

package/dist/cli/commands/query.js

@@ -0,0 +1,69 @@
+import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
+import { ui } from "../lib/ui.js";
+/**
+ * Run a Compass query from the shell — the same surface agents call via MCP.
+ *
+ * @param cmd - The query verb: `explore`, `search`, `recall`, `impact`, or `trace`.
+ * @param flags - Parsed flags supplying the positional query arguments in `_`.
+ * @throws Exits the process with code 1 on missing arguments or query errors.
+ */
+export async function runQuery(cmd, flags) {
+    const cwd = process.cwd();
+    const args = flags._;
+    try {
+        switch (cmd) {
+            case "explore": {
+                const r = explore(cwd, need(args[0], "explore <node>"));
+                if (!r.found) {
+                    ui.warn(r.message ?? "not found");
+                    r.otherMatches?.forEach((m) => ui.info(`${m.name} (${m.kind}) ${m.file}:${m.line}`));
+                    return;
+                }
+                const s = r.symbol;
+                ui.heading(`${s.kind} ${s.name}  ${s.file}:${s.startLine}-${s.endLine}`);
+                console.log(s.source);
+                ui.heading("Callees");
+                r.callees?.forEach((c) => ui.info(`${c.name}${c.file ? ` (${c.file}:${c.line})` : ""}`));
+                ui.heading("Callers");
+                r.callers?.forEach((c) => ui.info(`${c.name} (${c.file}:${c.line})`));
+                return;
+            }
+            case "search": {
+                const hits = search(cwd, need(args[0], "search <query>"));
+                ui.heading(`${hits.length} result(s)`);
+                hits.forEach((h) => ui.info(`${h.name} (${h.kind}) ${h.file}:${h.line}`));
+                return;
+            }
+            case "recall": {
+                const hits = await recall(cwd, need(args[0], 'recall "<query>"'));
+                ui.heading(`${hits.length} result(s) by meaning`);
+                hits.forEach((h) => ui.info(`${h.score.toFixed(3)}  ${h.name} (${h.kind}) ${h.file}:${h.line}`));
+                return;
+            }
+            case "impact": {
+                const nodes = impact(cwd, need(args[0], "impact <node>"));
+                ui.heading(`Blast radius: ${nodes.length} dependent(s)`);
+                nodes.forEach((n) => ui.info(`depth ${n.depth}: ${n.name} (${n.file}:${n.line})`));
+                return;
+            }
+            case "trace": {
+                const r = trace(cwd, need(args[0], "trace <from> <to>"), need(args[1], "trace <from> <to>"));
+                ui.heading(`Trace ${r.from} → ${r.to}`);
+                console.log(r.path ? "  " + r.path.join(" → ") + `  (${r.hops} hops)` : "  no path found");
+                return;
+            }
+        }
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}
+/** Return the value or print a usage error and exit if it is missing. */
+function need(value, usage) {
+    if (!value) {
+        ui.err(`Usage: speclaw ${usage}`);
+        process.exit(1);
+    }
+    return value;
+}

package/dist/cli/commands/spec.js

@@ -0,0 +1,71 @@
+import { specInit, specValidate, specSync, specArchive, specList } from "../../modules/spec/engine.js";
+import { ui } from "../lib/ui.js";
+function today() {
+    // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Run a spec-workflow subcommand: init, list, validate, sync, or archive.
+ *
+ * @param flags - Parsed flags; `_[0]` is the subcommand and `_[1]` the change name where required.
+ * @throws Exits the process with code 1 on unknown subcommands, missing arguments, or engine errors.
+ */
+export async function runSpec(flags) {
+    const cwd = process.cwd();
+    const [sub, change] = flags._;
+    try {
+        switch (sub) {
+            case "init": {
+                const r = specInit(cwd);
+                ui.ok(r.alreadyExisted ? "spec/ already present" : `spec/ created (${r.created.length} entries)`);
+                return;
+            }
+            case "list": {
+                const r = specList(cwd);
+                if (!r.initialized)
+                    return ui.warn("No spec/ — run `speclaw spec init`.");
+                ui.heading("Spec workspace");
+                ui.info(`active changes: ${r.activeChanges.join(", ") || "none"}`);
+                ui.info(`archived: ${r.archivedChanges.join(", ") || "none"}`);
+                ui.info(`capabilities: ${r.capabilities.join(", ") || "none"}`);
+                return;
+            }
+            case "validate": {
+                const r = specValidate(cwd, req(change, "spec validate <change>"));
+                if (r.valid)
+                    ui.ok(`${r.change} is valid (${r.deltaSpecs.length} delta spec(s))`);
+                else {
+                    ui.warn(`${r.change} has ${r.issues.length} issue(s):`);
+                    r.issues.forEach((i) => ui.info(i));
+                }
+                return;
+            }
+            case "sync": {
+                const r = specSync(cwd, req(change, "spec sync <change>"));
+                ui.ok(`promoted ${r.promoted.length} spec(s)`);
+                r.promoted.forEach((p) => ui.info(p));
+                return;
+            }
+            case "archive": {
+                const r = specArchive(cwd, req(change, "spec archive <change>"), today());
+                ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
+                return;
+            }
+            default:
+                ui.err("Usage: speclaw spec <init|list|validate|sync|archive> [change]");
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        ui.err(err.message);
+        process.exit(1);
+    }
+}
+/** Return the value or print a usage error and exit if it is missing. */
+function req(value, usage) {
+    if (!value) {
+        ui.err(`Usage: speclaw ${usage}`);
+        process.exit(1);
+    }
+    return value;
+}

package/dist/cli/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { parseFlags } from "./lib/args.js";
+import { ui } from "./lib/ui.js";
+const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Spec)
+
+Usage: speclaw <command> [options]
+
+Setup
+  init                     Interactive setup: pick agents, scaffold, index, get the prompt
+  agent list               Show which agents are configured
+  agent add <id>           Configure another agent later (symlinks + MCP)
+
+Compass (code intelligence — the same surface agents use via MCP)
+  index                    (Re)build the local code graph, with progress
+  watch                    Keep the index fresh on file changes
+  explore <node>           A node's source + callers/callees
+  search <query>           Find nodes by name/keyword
+  recall "<query>"         Find code by meaning (semantic)
+  impact <node>            Blast radius: everything that (transitively) calls it
+  trace <from> <to>        A call path between two nodes
+
+Spec workflow
+  spec init                Create the spec/ workspace
+  spec list                Active/archived changes and capabilities
+  spec validate <change>   Validate a change's artifacts
+  spec sync <change>       Promote delta specs to canonical
+  spec archive <change>    Finalize and archive a change
+
+Other
+  doctor                   Verify the installation
+  mcp                      Start the MCP server (used by your agent's config)
+  help                     Show this help
+`;
+/** Parse argv and dispatch to the matching command handler. */
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    switch (cmd) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return;
+        case "mcp": {
+            const { startMcpServer } = await import("../server.js");
+            await startMcpServer();
+            return;
+        }
+        case "init":
+            return (await import("./commands/init.js")).runInit(flags);
+        case "agent":
+            return (await import("./commands/agent.js")).runAgent(flags);
+        case "index":
+            return (await import("./commands/index-build.js")).runIndex(flags);
+        case "watch":
+            return (await import("./commands/index-build.js")).runWatch(flags);
+        case "explore":
+        case "search":
+        case "recall":
+        case "impact":
+        case "trace":
+            return (await import("./commands/query.js")).runQuery(cmd, flags);
+        case "spec":
+            return (await import("./commands/spec.js")).runSpec(flags);
+        case "doctor":
+            return (await import("./commands/doctor.js")).runDoctor(flags);
+        default:
+            ui.err(`Unknown command: ${cmd}`);
+            console.log(HELP);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    ui.err(err.message);
+    process.exit(1);
+});

package/dist/cli/lib/args.js

@@ -0,0 +1,44 @@
+/**
+ * Minimal flag parser: `--key value`, `--key=value`, `--bool`, `-x`.
+ *
+ * @param argv - Raw argument tokens (already stripped of the command name).
+ * @returns Flags with named options set and non-flag tokens collected in `_`.
+ */
+export function parseFlags(argv) {
+    const flags = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const [key, inlineVal] = arg.slice(2).split("=", 2);
+            if (inlineVal !== undefined) {
+                flags[key] = inlineVal;
+            }
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+                flags[key] = argv[++i];
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else if (arg.startsWith("-")) {
+            flags[arg.slice(1)] = true;
+        }
+        else {
+            flags._.push(arg);
+        }
+    }
+    return flags;
+}
+/**
+ * Normalize a flag value into a list, splitting comma-separated strings.
+ *
+ * @param value - A flag value that may be an array, a comma-separated string, or absent.
+ * @returns The trimmed, non-empty entries; empty when the value is missing or a boolean.
+ */
+export function list(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return value.split(",").map((s) => s.trim()).filter(Boolean);
+    return [];
+}