@esneiderbravo/speclaw 0.1.7 → 0.1.9

package/README.md

@@ -35,7 +35,7 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 
 <br/>
 
-## ◆ Quick start
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Quick start
 
 Install speclaw globally (once), then run `init` in your project root:
 
@@ -67,7 +67,7 @@ too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run
 
 <br/>
 
-## ◆ It looks like this
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; It looks like this
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-init.png" width="800" alt="speclaw init — terminal output">
@@ -77,7 +77,7 @@ too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run
 
 <br/>
 
-## ◆ The suite — four modules
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The suite — four modules
 
 | Module | What it does |
 | :-- | :-- |
@@ -90,7 +90,44 @@ Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) an
 
 <br/>
 
-## ◆ Two ways to use it
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The spec-driven workflow (Lawbook)
+
+Lawbook is speclaw's answer to the biggest risk with AI agents: **code that
+drifts from intent.** No non-trivial change lands without a spec change — the
+intent is written first, the code is made to match it, and the spec is promoted
+to the project's canonical record. It's a loop of five steps:
+
+```
+explore  →  draft  →  build  →  sync  →  archive
+```
+
+| Step | What happens |
+| :-- | :-- |
+| **explore** | Think an idea through *before* committing to it — should we do this, and how. Writes nothing. |
+| **draft** | Create the change under `lawbook/changes/<name>/`: a `proposal.md` (why · what · non-goals), **delta specs** in `specs/<capability>/spec.md`, an optional `design.md`, and a `tasks.md` checklist. |
+| **build** | Implement the tasks in order, keeping code and spec in agreement. |
+| **sync** | Promote the change's delta specs into the canonical `lawbook/specs/` — the always-true description of how the system behaves. |
+| **archive** | Validate, promote, and move the change to `lawbook/changes/archive/` — **in the same PR**, never a post-merge chore. |
+
+**Delta specs are normative and testable.** Requirements use `SHALL`/`MUST`
+under `### Requirement:` headers, each with one or more `#### Scenario:` blocks
+whose acceptance criteria hold without production integrations. `lawbook_validate`
+checks that the code matches what the spec promises before you sync or archive.
+
+**Three ways to drive it — same engine, no external CLI:**
+
+- **In your agent** — the `/lawbook:explore`, `/lawbook:draft`, `/lawbook:build`, `/lawbook:sync`, `/lawbook:archive` commands (installed as skills).
+- **MCP tools** — `lawbook_init`, `lawbook_validate`, `lawbook_sync`, `lawbook_archive`, `lawbook_list`.
+- **CLI** — `speclaw lawbook init | list | validate | sync | archive`.
+
+The workspace is committed under `lawbook/`: `specs/` (canonical), `changes/`
+(in-flight), `changes/archive/` (shipped), and `config.yaml` (the mandatory task
+steps every change must include). The standards themselves are amended the same
+way — through a spec change reviewed by a human.
+
+<br/>
+
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; 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**
@@ -105,7 +142,7 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 
 <br/>
 
-## ◆ What lands in your project
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; What lands in your project
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-tree.png" width="800" alt="what speclaw writes into your project">
@@ -113,7 +150,7 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 
 <br/>
 
-## ◆ Philosophy — why "laws"?
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Philosophy — why "laws"?
 
 > [!NOTE]
 > A guideline is a suggestion. A **law** is enforced. The most common failure mode
@@ -124,7 +161,7 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 
 <br/>
 
-## ◆ Staying up to date
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date
 
 speclaw checks for new releases in the background (at most once a day) and nudges
 you when one lands. To upgrade:
@@ -143,7 +180,7 @@ packs this project already uses.
 
 <br/>
 
-## ◆ Requirements
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Requirements
 
 - **Node.js ≥ 22** — uses the built-in `node:sqlite`.
 - **No native builds, no services, no API keys, no LLM download.** Tree-sitter

package/dist/cli/commands/init.js

@@ -104,10 +104,14 @@ export async function runInit(flags) {
         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"));
+        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 — printed as a single flush-left
     // line so it copy-pastes cleanly (no borders, no wrapping artifacts).

package/dist/cli/commands/lawbook.js

@@ -1,4 +1,4 @@
-import { specInit, specValidate, specSync, specArchive, specList } from "../../modules/lawbook/engine.js";
+import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/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.
@@ -17,7 +17,9 @@ export async function runSpec(flags) {
         switch (sub) {
             case "init": {
                 const r = specInit(cwd);
-                ui.ok(r.alreadyExisted ? "lawbook/ already present" : `lawbook/ created (${r.created.length} entries)`);
+                ui.ok(r.alreadyExisted
+                    ? "lawbook/ already present"
+                    : `lawbook/ created (${r.created.length} entries)`);
                 return;
             }
             case "list": {

package/dist/cli/commands/update.js

@@ -39,7 +39,10 @@ export async function runUpdate(flags) {
                 return;
             }
             ui.step(`Updating ${pkgName()} globally`);
-            const install = spawnSync("npm", ["install", "-g", `${pkgName()}@latest`], { stdio: "inherit", shell: winShell });
+            const install = spawnSync("npm", ["install", "-g", `${pkgName()}@latest`], {
+                stdio: "inherit",
+                shell: winShell,
+            });
             if (install.status !== 0) {
                 ui.err("Global update failed. Try again with elevated permissions (e.g. sudo), or check your npm setup.");
                 process.exit(1);
@@ -47,7 +50,10 @@ export async function runUpdate(flags) {
             ui.ok(`Updated to ${latest}`);
             // Re-exec the NEWLY installed binary so migrations run with the new assets
             // and any new feature steps — not this (now-stale) process.
-            const re = spawnSync("speclaw", ["update", "--migrate-only"], { stdio: "inherit", shell: winShell });
+            const re = spawnSync("speclaw", ["update", "--migrate-only"], {
+                stdio: "inherit",
+                shell: winShell,
+            });
             if (re.error) {
                 ui.warn(`Upgraded — now run ${ui.code("speclaw update --migrate-only")} to apply project changes.`);
                 return;

package/dist/cli/commands/visualize.js

@@ -5,7 +5,11 @@ import { ui, c } from "../lib/ui.js";
 function openInBrowser(file) {
     const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     try {
-        spawn(cmd, [file], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+        spawn(cmd, [file], {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32",
+        }).unref();
     }
     catch {
         /* best-effort */
@@ -28,8 +32,10 @@ export async function runVisualize(flags) {
             limit: flags.limit ? Number(flags.limit) : undefined,
         });
         ui.step("Compass graph");
-        ui.ok(c.bold(c.cream(String(r.shown))) + c.muted(" nodes · ") +
-            c.bold(c.cream(String(r.links))) + c.muted(" edges") +
+        ui.ok(c.bold(c.cream(String(r.shown))) +
+            c.muted(" nodes · ") +
+            c.bold(c.cream(String(r.links))) +
+            c.muted(" edges") +
             (focus ? c.muted(` · focused on ${focus}`) : c.muted(` · top of ${r.total}`)));
         ui.info(`→ ${ui.code(".speclaw/graph.html")}`);
         if (!flags["no-open"]) {

package/dist/cli/lib/args.js

@@ -39,6 +39,9 @@ export function list(value) {
     if (Array.isArray(value))
         return value;
     if (typeof value === "string")
-        return value.split(",").map((s) => s.trim()).filter(Boolean);
+        return value
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
     return [];
 }

package/dist/cli/lib/ui.js

@@ -11,8 +11,7 @@ const PALETTE = {
     amber: [227, 179, 65], // #E3B341 — warning
     red: [235, 90, 90],
 };
-const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") &&
-    !process.env.NO_COLOR;
+const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") && !process.env.NO_COLOR;
 function paint(rgb, s) {
     if (!colorOn)
         return s;

package/dist/cli/lib/update-check.js

@@ -56,7 +56,10 @@ async function fetchLatest(name) {
  * @returns True when `latest` is strictly newer than `current`.
  */
 export function isNewer(latest, current) {
-    const parse = (v) => v.split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+    const parse = (v) => v
+        .split("-")[0]
+        .split(".")
+        .map((n) => parseInt(n, 10) || 0);
     const a = parse(latest);
     const b = parse(current);
     for (let i = 0; i < 3; i++) {
@@ -79,7 +82,7 @@ export function isNewer(latest, current) {
 export async function checkForUpdates(opts = {}) {
     const current = pkgVersion();
     const cache = readCache();
-    let latest = null;
+    let latest;
     if (!opts.force && cache && Date.now() - cache.checkedAt < TTL_MS) {
         latest = cache.latest;
     }
@@ -113,8 +116,17 @@ export async function maybeNotifyUpdate(cmd) {
         if (!updateAvailable || !latest)
             return;
         process.stderr.write("\n" +
-            "  " + c.amber("⬆ speclaw ") + c.muted(current + " → ") + c.cyan(latest) + c.muted(" available") + "\n" +
-            "  " + c.muted("run ") + c.cyan("speclaw update") + c.muted(" — upgrades and applies only what's new") + "\n\n");
+            "  " +
+            c.amber("⬆ speclaw ") +
+            c.muted(current + " → ") +
+            c.cyan(latest) +
+            c.muted(" available") +
+            "\n" +
+            "  " +
+            c.muted("run ") +
+            c.cyan("speclaw update") +
+            c.muted(" — upgrades and applies only what's new") +
+            "\n\n");
     }
     catch {
         /* the notifier is best-effort — never let it break a command */

package/dist/modules/compass/db.js

@@ -108,9 +108,7 @@ export function openDb(projectPath) {
     if (isStale(db))
         resetSchema(db);
     db.exec(SCHEMA);
-    const row = db
-        .prepare("SELECT value FROM meta WHERE key = 'schema_version'")
-        .get();
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
     if (!row) {
         db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
     }

package/dist/modules/compass/indexer.js

@@ -6,9 +6,23 @@ import { langForPath } from "./languages.js";
 import { extract } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
 const SKIP_DIRS = new Set([
-    ".git", "node_modules", "dist", "build", ".next", "out", "coverage",
-    "__pycache__", ".venv", "venv", ".speclaw", ".mypy_cache", ".pytest_cache",
-    "vendor", "target", ".turbo", ".cache",
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    "out",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".speclaw",
+    ".mypy_cache",
+    ".pytest_cache",
+    "vendor",
+    "target",
+    ".turbo",
+    ".cache",
 ]);
 const MAX_FILE_BYTES = 1_500_000;
 function hashOf(content) {
@@ -57,8 +71,13 @@ export async function buildIndex(projectPath, onProgress) {
     const db = openDb(projectPath);
     const embedder = getEmbedder();
     const stats = {
-        files: 0, nodes: 0, edges: 0, embeddings: 0,
-        unchanged: 0, removed: 0, embedder: embedder.id,
+        files: 0,
+        nodes: 0,
+        edges: 0,
+        embeddings: 0,
+        unchanged: 0,
+        removed: 0,
+        embedder: embedder.id,
     };
     const existing = new Map();
     for (const row of db.prepare("SELECT id, path, hash FROM files").all()) {

package/dist/modules/compass/query.js

@@ -112,7 +112,11 @@ export function explore(projectPath, query) {
             callers,
             otherMatches: matches.length > 1
                 ? matches.slice(1).map((m) => ({
-                    name: m.name, kind: m.kind, file: m.file, line: m.start_line, signature: m.signature,
+                    name: m.name,
+                    kind: m.kind,
+                    file: m.file,
+                    line: m.start_line,
+                    signature: m.signature,
                 }))
                 : undefined,
         };

package/dist/modules/compass/register.js

@@ -74,8 +74,10 @@ export function registerCompass(server) {
             action: z.enum(["start", "stop", "status"]).describe("start, stop, or status"),
         },
     }, async ({ projectPath, action }) => {
-        const result = action === "start" ? startWatch(projectPath)
-            : action === "stop" ? stopWatch(projectPath)
+        const result = action === "start"
+            ? startWatch(projectPath)
+            : action === "stop"
+                ? stopWatch(projectPath)
                 : watchStatus(projectPath);
         return text(result);
     });

package/dist/modules/compass/watcher.js

@@ -3,8 +3,17 @@ import path from "node:path";
 import { buildIndex } from "./indexer.js";
 const active = new Map();
 const SKIP = new Set([
-    ".git", "node_modules", "dist", "build", ".next", ".speclaw",
-    "__pycache__", ".venv", "venv", ".mypy_cache", ".pytest_cache",
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".speclaw",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".mypy_cache",
+    ".pytest_cache",
 ]);
 function scheduleReindex(projectPath, state) {
     if (state.timer)

package/dist/modules/foundation/doctor.js

@@ -15,9 +15,7 @@ export function doctor(projectPath) {
     checks.push({
         name: "ai-specs directory",
         ok: has("ai-specs"),
-        detail: has("ai-specs")
-            ? "present"
-            : "missing — run the scaffold tool first",
+        detail: has("ai-specs") ? "present" : "missing — run the scaffold tool first",
     });
     checks.push({
         name: "LAWS.md constitution",
@@ -87,9 +85,7 @@ export function doctor(projectPath) {
     checks.push({
         name: "lawbook workflow",
         ok: has("lawbook"),
-        detail: has("lawbook")
-            ? "lawbook/ present"
-            : "missing — run the `lawbook_init` tool",
+        detail: has("lawbook") ? "lawbook/ present" : "missing — run the `lawbook_init` tool",
     });
     checks.push({
         name: "Compass index",

package/dist/modules/foundation/register.js

@@ -7,30 +7,74 @@ import { AGENTS, configureAgent } from "../../shared/agents.js";
 import { emptyReport } from "../../shared/install.js";
 const profileShape = {
     project_name: z.string().describe("Short project name, e.g. the repo name"),
-    project_description: z.string().optional().describe("One-line description of what the project does"),
+    project_description: z
+        .string()
+        .optional()
+        .describe("One-line description of what the project does"),
     organization: z.string().optional().describe("Company/team name"),
-    stack_summary: z.string().optional().describe("e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'"),
-    architecture: z.string().optional().describe("e.g. 'hexagonal architecture with bounded contexts'"),
-    test_commands: z.string().optional().describe("Real commands, e.g. 'pytest backend/tests && npm run test'"),
-    lint_commands: z.string().optional().describe("Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'"),
+    stack_summary: z
+        .string()
+        .optional()
+        .describe("e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'"),
+    architecture: z
+        .string()
+        .optional()
+        .describe("e.g. 'hexagonal architecture with bounded contexts'"),
+    test_commands: z
+        .string()
+        .optional()
+        .describe("Real commands, e.g. 'pytest backend/tests && npm run test'"),
+    lint_commands: z
+        .string()
+        .optional()
+        .describe("Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'"),
     branch_pattern: z.string().optional().describe("e.g. 'feature/<ticket-id>-<slug>'"),
     commit_style: z.string().optional().describe("e.g. 'conventional commits, imperative, English'"),
-    custom_laws: z.string().optional().describe("Extra markdown appended to LAWS.md — project-specific binding rules the analysis surfaced"),
-    compass_hints: z.string().optional().describe("Markdown bullets with the repo's real entrypoints and common traces, inserted into docs/compass.md"),
-    base_standards_extra: z.string().optional().describe("Markdown with any project-specific cross-cutting rules, appended to docs/standards/base-standards.md"),
-    modules_table: z.string().optional().describe("Markdown table of the repo's real modules/bounded contexts + one-line responsibility, for docs/standards/architecture.md"),
-    layering_rules: z.string().optional().describe("Markdown describing the layers and their allowed dependencies, for docs/standards/architecture.md"),
-    backend_layers: z.string().optional().describe("Markdown layer table (Layer | File | Responsibility) from the real backend, for docs/standards/backend-standards.md"),
-    frontend_layers: z.string().optional().describe("Markdown layer table from the real frontend, for docs/standards/frontend-standards.md"),
-    versioning_rules: z.string().optional().describe("The repo's versioning/release convention, for docs/standards/conventions.md"),
-    documentation_extra: z.string().optional().describe("Repo-specific docstring notes (keep only the languages used, the enforced linter), appended to docs/standards/documentation.md"),
+    custom_laws: z
+        .string()
+        .optional()
+        .describe("Extra markdown appended to LAWS.md — project-specific binding rules the analysis surfaced"),
+    compass_hints: z
+        .string()
+        .optional()
+        .describe("Markdown bullets with the repo's real entrypoints and common traces, inserted into docs/compass.md"),
+    base_standards_extra: z
+        .string()
+        .optional()
+        .describe("Markdown with any project-specific cross-cutting rules, appended to docs/standards/base-standards.md"),
+    modules_table: z
+        .string()
+        .optional()
+        .describe("Markdown table of the repo's real modules/bounded contexts + one-line responsibility, for docs/standards/architecture.md"),
+    layering_rules: z
+        .string()
+        .optional()
+        .describe("Markdown describing the layers and their allowed dependencies, for docs/standards/architecture.md"),
+    backend_layers: z
+        .string()
+        .optional()
+        .describe("Markdown layer table (Layer | File | Responsibility) from the real backend, for docs/standards/backend-standards.md"),
+    frontend_layers: z
+        .string()
+        .optional()
+        .describe("Markdown layer table from the real frontend, for docs/standards/frontend-standards.md"),
+    versioning_rules: z
+        .string()
+        .optional()
+        .describe("The repo's versioning/release convention, for docs/standards/conventions.md"),
+    documentation_extra: z
+        .string()
+        .optional()
+        .describe("Repo-specific docstring notes (keep only the languages used, the enforced linter), appended to docs/standards/documentation.md"),
 };
 // ─── The foundation module: analyze the repo, then write the constitution ───
 /** Register the foundation MCP tools (init_project, scaffold, configure_agent, doctor). */
 export function registerFoundation(server) {
     server.registerTool("init_project", {
         description: "START HERE to initialize speclaw in a project. Returns the analysis questionnaire the agent must answer by reading the target repo, plus the available skill packs. Do NOT guess answers — investigate the codebase (package.json, pyproject.toml, CI config, existing docs) and confirm the pack selection with the user before calling scaffold.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project to initialize") },
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project to initialize"),
+        },
     }, async () => {
         const packs = loadPacks();
         return text({
@@ -53,14 +97,19 @@ export function registerFoundation(server) {
             projectPath: z.string().describe("Absolute path to the project"),
             profile: z.object(profileShape).describe("Project profile gathered by analyzing the repo"),
             packs: z.array(z.string()).describe("Optional tool pack names (quality, workflow, agents)"),
-            agents: z.array(z.string()).optional().describe(`Agent ids to configure (symlinks + MCP): ${AGENTS.map((a) => a.id).join(", ")}. Usually the CLI handles this; omit to write content only.`),
+            agents: z
+                .array(z.string())
+                .optional()
+                .describe(`Agent ids to configure (symlinks + MCP): ${AGENTS.map((a) => a.id).join(", ")}. Usually the CLI handles this; omit to write content only.`),
         },
     }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
     server.registerTool("configure_agent", {
         description: "Configure one agent's integration in an already-scaffolded project: create its IDE symlinks into ai-specs and register the speclaw MCP server in its config. Re-runnable; add agents one at a time.",
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
-            agent: z.enum(AGENTS.map((a) => a.id)).describe("Agent id to configure"),
+            agent: z
+                .enum(AGENTS.map((a) => a.id))
+                .describe("Agent id to configure"),
         },
     }, async ({ projectPath, agent }) => {
         const report = emptyReport();

package/dist/modules/lawbook/engine.js

@@ -115,7 +115,12 @@ export function specValidate(projectPath, change) {
     const changeDir = path.join(specRoot(projectPath), "changes", change);
     const issues = [];
     if (!fs.existsSync(changeDir)) {
-        return { change, valid: false, issues: [`change "${change}" not found under lawbook/changes/`], deltaSpecs: [] };
+        return {
+            change,
+            valid: false,
+            issues: [`change "${change}" not found under lawbook/changes/`],
+            deltaSpecs: [],
+        };
     }
     if (!fs.existsSync(path.join(changeDir, "proposal.md")))
         issues.push("missing proposal.md");
@@ -138,7 +143,12 @@ export function specValidate(projectPath, change) {
             issues.push(`${rel}: no "### Requirement:" header`);
         }
     }
-    return { change, valid: issues.length === 0, issues, deltaSpecs: deltas.map((f) => path.relative(projectPath, f)) };
+    return {
+        change,
+        valid: issues.length === 0,
+        issues,
+        deltaSpecs: deltas.map((f) => path.relative(projectPath, f)),
+    };
 }
 /**
  * Promote a change's delta specs into the canonical specs/, overwriting the
@@ -214,7 +224,8 @@ export function specList(projectPath) {
         const abs = path.join(root, rel);
         if (!fs.existsSync(abs))
             return [];
-        return fs.readdirSync(abs, { withFileTypes: true })
+        return fs
+            .readdirSync(abs, { withFileTypes: true })
             .filter((e) => e.isDirectory() && e.name !== "archive")
             .map((e) => e.name);
     };

package/dist/modules/lawbook/register.js

@@ -47,7 +47,10 @@ export function registerSpec(server) {
         inputSchema: {
             projectPath: z.string().describe("Absolute path to the project"),
             change: z.string().describe("Change name (folder under lawbook/changes/)"),
-            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("Today's date, YYYY-MM-DD"),
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe("Today's date, YYYY-MM-DD"),
         },
     }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
 }

package/dist/shared/agents.js

@@ -1,12 +1,42 @@
 import fs from "node:fs";
 import path from "node:path";
+import { ensureGitignore } from "./install.js";
 /** The agents speclaw can configure. Add one here and the CLI picks it up. */
 export const AGENTS = [
-    { id: "claude", label: "Claude Code", ideDir: ".claude", linkTargets: ["skills", "commands", "agents"], mcpFile: ".mcp.json" },
-    { id: "cursor", label: "Cursor", ideDir: ".cursor", linkTargets: ["skills", "commands", "rules"], mcpFile: ".cursor/mcp.json" },
-    { id: "codex", label: "Codex", ideDir: ".codex", linkTargets: ["skills", "commands"], mcpFile: ".codex/mcp.json" },
-    { id: "windsurf", label: "Windsurf", ideDir: ".windsurf", linkTargets: ["skills", "commands"], mcpFile: ".windsurf/mcp.json" },
-    { id: "agents", label: "Generic (AGENTS.md)", ideDir: ".agents", linkTargets: ["skills", "agents"] },
+    {
+        id: "claude",
+        label: "Claude Code",
+        ideDir: ".claude",
+        linkTargets: ["skills", "commands", "agents"],
+        mcpFile: ".mcp.json",
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        ideDir: ".cursor",
+        linkTargets: ["skills", "commands", "rules"],
+        mcpFile: ".cursor/mcp.json",
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        ideDir: ".codex",
+        linkTargets: ["skills", "commands"],
+        mcpFile: ".codex/mcp.json",
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        ideDir: ".windsurf",
+        linkTargets: ["skills", "commands"],
+        mcpFile: ".windsurf/mcp.json",
+    },
+    {
+        id: "agents",
+        label: "Generic (AGENTS.md)",
+        ideDir: ".agents",
+        linkTargets: ["skills", "agents"],
+    },
 ];
 /**
  * Look up a known agent definition by its id.
@@ -30,6 +60,10 @@ function isSymlink(p) {
 }
 /** Register the speclaw stdio MCP server in an agent's config file, merging into any existing config and skipping if already present. */
 function writeMcpConfig(projectPath, mcpFile, report) {
+    // The agent MCP config is per-developer wiring — regenerated by `speclaw init`
+    // / `agent add`, points at a local runner — not shared source. Keep it out of
+    // version control (done regardless of whether we write or skip the file below).
+    ensureGitignore(projectPath, mcpFile, "speclaw agent MCP config (per-developer; regenerated by init)", report);
     const mcpPath = path.join(projectPath, mcpFile);
     let config = {};
     if (fs.existsSync(mcpPath))

package/dist/shared/manifest.js

@@ -12,7 +12,10 @@ function manifestPath(projectPath) {
 export function readManifest(projectPath) {
     try {
         const m = JSON.parse(fs.readFileSync(manifestPath(projectPath), "utf8"));
-        return { version: String(m.version ?? "0.0.0"), packs: Array.isArray(m.packs) ? m.packs.map(String) : [] };
+        return {
+            version: String(m.version ?? "0.0.0"),
+            packs: Array.isArray(m.packs) ? m.packs.map(String) : [],
+        };
     }
     catch {
         return null;

package/dist/shared/version.js

@@ -10,7 +10,10 @@ function readPkg() {
     const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
     try {
         const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-        cached = { name: String(pkg.name ?? "@esneiderbravo/speclaw"), version: String(pkg.version ?? "0.0.0") };
+        cached = {
+            name: String(pkg.name ?? "@esneiderbravo/speclaw"),
+            version: String(pkg.version ?? "0.0.0"),
+        };
     }
     catch {
         cached = { name: "@esneiderbravo/speclaw", version: "0.0.0" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "publishConfig": {
     "access": "public"
   },
@@ -38,6 +38,9 @@
     "build": "tsc && node scripts/copy-assets.mjs",
     "brand": "node scripts/render-brand.mjs",
     "start": "node dist/cli/index.js",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "check": "prettier --check . && eslint .",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -52,8 +55,14 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.9.0",
+    "prettier": "^3.9.6",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.65.0"
   }
 }