@esneiderbravo/speclaw 0.1.0

package/dist/modules/compass/query.js

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+import { openDb, indexExists } from "./db.js";
+import { getEmbedder, fromBlob, cosine } from "./embedder.js";
+function requireIndex(projectPath) {
+    if (!indexExists(projectPath)) {
+        throw new Error("No index found. Build it first with the index_build tool (creates .speclaw/index.db).");
+    }
+}
+/**
+ * Structural search: find nodes whose name contains `query` (substring match),
+ * ranking exact matches and shorter names first.
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param query - Name or keyword to match as a substring.
+ * @param limit - Maximum number of hits to return.
+ * @returns Matching nodes ordered by relevance.
+ * @throws If no index exists for the project.
+ */
+export function search(projectPath, query, limit = 25) {
+    requireIndex(projectPath);
+    const db = openDb(projectPath);
+    try {
+        const rows = db
+            .prepare(`SELECT s.name, s.kind, f.path AS file, s.start_line AS line, s.signature
+         FROM nodes s JOIN files f ON f.id = s.file_id
+         WHERE s.name LIKE ?
+         ORDER BY (s.name = ?) DESC, length(s.name) ASC
+         LIMIT ?`)
+            .all(`%${query}%`, query, limit);
+        return rows;
+    }
+    finally {
+        db.close();
+    }
+}
+function readSource(projectPath, file, startByte, endByte) {
+    try {
+        const buf = fs.readFileSync(path.join(projectPath, file));
+        return buf.subarray(startByte, endByte).toString("utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Explore an exact node by name: return its verbatim source, callees, and
+ * callers (its blast radius).
+ *
+ * When several nodes share the name, functions and classes are preferred as the
+ * primary result and the rest are surfaced under `otherMatches`. When no exact
+ * match exists, falls back to a fuzzy {@link search} so the caller still gets
+ * useful candidates.
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param query - Exact node name to explore.
+ * @returns The explore result; `found` is `false` when no exact match exists.
+ * @throws If no index exists for the project.
+ */
+export function explore(projectPath, query) {
+    requireIndex(projectPath);
+    const db = openDb(projectPath);
+    try {
+        const matches = db
+            .prepare(`SELECT s.id, s.name, s.kind, s.start_line, s.end_line, s.start_byte, s.end_byte,
+                s.signature, f.path AS file
+         FROM nodes s JOIN files f ON f.id = s.file_id
+         WHERE s.name = ?
+         ORDER BY s.kind = 'function' DESC, s.kind = 'class' DESC
+         LIMIT 10`)
+            .all(query);
+        if (matches.length === 0) {
+            // fall back to fuzzy search so the caller gets something useful
+            const near = search(projectPath, query, 10);
+            return {
+                found: false,
+                message: `No exact symbol named "${query}". ${near.length} similar symbol(s) below.`,
+                otherMatches: near,
+            };
+        }
+        const best = matches[0];
+        const callees = db
+            .prepare(`SELECT e.dst_name AS name, e.line, f.path AS file
+         FROM edges e LEFT JOIN nodes s ON s.id = e.dst_node_id
+         LEFT JOIN files f ON f.id = s.file_id
+         WHERE e.src_node_id = ? AND e.kind = 'call'
+         ORDER BY e.line`)
+            .all(best.id);
+        // Callers: match both the resolved edge AND any call by this name, so
+        // dynamic dispatch (a method/function called by name across sites) is not
+        // missed. Over-approximates conservatively — the point of a blast radius.
+        const callers = db
+            .prepare(`SELECT DISTINCT owner.name AS name, owner.kind AS kind, f.path AS file, e.line
+         FROM edges e
+         JOIN nodes owner ON owner.id = e.src_node_id
+         JOIN files f ON f.id = owner.file_id
+         WHERE (e.dst_node_id = ? OR e.dst_name = ?) AND e.kind = 'call'
+         ORDER BY f.path, e.line`)
+            .all(best.id, best.name);
+        return {
+            found: true,
+            symbol: {
+                name: best.name,
+                kind: best.kind,
+                file: best.file,
+                startLine: best.start_line,
+                endLine: best.end_line,
+                signature: best.signature,
+                source: readSource(projectPath, best.file, best.start_byte, best.end_byte),
+            },
+            callees: callees.map((c) => ({ name: c.name, file: c.file ?? undefined, line: c.line })),
+            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,
+                }))
+                : undefined,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Semantic search: embed the natural-language query and rank nodes by cosine
+ * similarity against the local vector store. Finds code by meaning, not just
+ * by matching identifier substrings.
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param query - Natural-language description of the code being sought.
+ * @param limit - Maximum number of hits to return.
+ * @returns Nodes sorted by descending similarity score.
+ * @throws If no index exists for the project.
+ */
+export async function recall(projectPath, query, limit = 15) {
+    requireIndex(projectPath);
+    const embedder = getEmbedder();
+    const qvec = await embedder.embed(query);
+    const db = openDb(projectPath);
+    try {
+        const rows = db
+            .prepare(`SELECT n.name, n.kind, f.path AS file, n.start_line AS line, n.signature, e.vec
+         FROM node_embeddings e
+         JOIN nodes n ON n.id = e.node_id
+         JOIN files f ON f.id = n.file_id
+         WHERE e.dim = ?`)
+            .all(embedder.dim);
+        const scored = rows.map((r) => ({
+            name: r.name,
+            kind: r.kind,
+            file: r.file,
+            line: r.line,
+            signature: r.signature,
+            score: cosine(qvec, fromBlob(r.vec)),
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Transitive blast radius: every node that (transitively) calls the target,
+ * up to maxDepth hops. Expansion is by call-name, so dynamic dispatch is
+ * included — the conservative answer to "what could break if I change this?".
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param nodeName - Name of the node whose dependents are wanted.
+ * @param maxDepth - Maximum number of call hops to traverse outward.
+ * @returns The reached nodes, each tagged with its discovery depth.
+ * @throws If no index exists for the project.
+ */
+export function impact(projectPath, nodeName, maxDepth = 4) {
+    requireIndex(projectPath);
+    const db = openDb(projectPath);
+    try {
+        const visited = new Set();
+        const results = [];
+        let frontier = [nodeName];
+        for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+            const placeholders = frontier.map(() => "?").join(",");
+            const callers = db
+                .prepare(`SELECT DISTINCT owner.id, owner.name, owner.kind, f.path AS file, MIN(owner.start_line) AS line
+           FROM edges e
+           JOIN nodes owner ON owner.id = e.src_node_id
+           JOIN files f ON f.id = owner.file_id
+           WHERE e.kind = 'call' AND e.dst_name IN (${placeholders})
+           GROUP BY owner.id`)
+                .all(...frontier);
+            const nextNames = new Set();
+            for (const c of callers) {
+                if (visited.has(c.id))
+                    continue;
+                visited.add(c.id);
+                results.push({ name: c.name, kind: c.kind, file: c.file, line: c.line, depth });
+                nextNames.add(c.name);
+            }
+            frontier = [...nextNames];
+        }
+        return results;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Trace a call path from one node to another: BFS forward over call edges (by
+ * name) from `from` until `to` is reached, returning the chain of names. null
+ * path means no route within maxDepth.
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param from - Name of the starting node.
+ * @param to - Name of the target node.
+ * @param maxDepth - Maximum number of call hops to search.
+ * @returns The trace result; `path` is `null` and `hops` is `-1` when no route
+ * is found within `maxDepth`.
+ * @throws If no index exists for the project.
+ */
+export function trace(projectPath, from, to, maxDepth = 8) {
+    requireIndex(projectPath);
+    const db = openDb(projectPath);
+    try {
+        if (from === to)
+            return { from, to, path: [from], hops: 0 };
+        const parent = new Map();
+        const seen = new Set([from]);
+        let frontier = [from];
+        const calleesStmt = db.prepare(`SELECT DISTINCT e.dst_name AS callee
+       FROM edges e JOIN nodes src ON src.id = e.src_node_id
+       WHERE e.kind = 'call' AND src.name = ?`);
+        for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+            const next = [];
+            for (const name of frontier) {
+                const callees = calleesStmt.all(name);
+                for (const { callee } of callees) {
+                    if (seen.has(callee))
+                        continue;
+                    seen.add(callee);
+                    parent.set(callee, name);
+                    if (callee === to) {
+                        const path = [to];
+                        let cur = to;
+                        while (parent.has(cur)) {
+                            cur = parent.get(cur);
+                            path.unshift(cur);
+                        }
+                        return { from, to, path, hops: path.length - 1 };
+                    }
+                    next.push(callee);
+                }
+            }
+            frontier = next;
+        }
+        return { from, to, path: null, hops: -1 };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/modules/compass/register.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { text } from "../../shared/mcp.js";
+import { buildIndex } from "./indexer.js";
+import { explore, search, recall, impact, trace } from "./query.js";
+import { startWatch, stopWatch, watchStatus } from "./watcher.js";
+// ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
+// A local graph of the codebase (nodes = definitions, edges = calls/imports)
+// plus a local vector store for semantic recall. Lives in .speclaw/ (gitignored).
+/**
+ * Register all Compass MCP tools (index, explore, search, recall, impact,
+ * trace, watch) on the given server.
+ *
+ * @param server - The MCP server to register the Compass tools on.
+ */
+export function registerCompass(server) {
+    server.registerTool("compass_index", {
+        description: "Build or incrementally refresh the Compass — speclaw's local code graph (.speclaw/index.db). Parses TS/JS/Python with tree-sitter into nodes (definitions) and edges (calls/imports), and computes a local vector embedding per node for semantic recall. Files unchanged since the last run are skipped by content hash. Run once after init and whenever you want a fresh graph.",
+        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
+    }, async ({ projectPath }) => text(await buildIndex(projectPath)));
+    server.registerTool("compass_explore", {
+        description: "Explore a node in the Compass: returns its verbatim source, location, callees, and resolved callers (blast radius). Use this BEFORE grep/read when locating or understanding code. Requires compass_index to have run.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            node: z.string().describe("Exact node name to explore (function/class/method/type)"),
+        },
+    }, async ({ projectPath, node }) => text(explore(projectPath, node)));
+    server.registerTool("compass_search", {
+        description: "Structural search of the Compass: find nodes by name or keyword (substring match). Returns name, kind, and file:line per hit. Cheaper and more structural than grep. Requires compass_index to have run.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            query: z.string().describe("Name or keyword to search for"),
+            limit: z.number().optional().describe("Max results (default 25)"),
+        },
+    }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
+    server.registerTool("compass_recall", {
+        description: "Semantic search of the Compass: describe what you're looking for in natural language ('where auth tokens are validated') and get the nodes ranked by meaning, using the local vector store — even when the identifier names don't contain your words. Requires compass_index to have run.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            query: z.string().describe("Natural-language description of the code you want"),
+            limit: z.number().optional().describe("Max results (default 15)"),
+        },
+    }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
+    server.registerTool("compass_impact", {
+        description: "Blast radius: every node that transitively calls the target, up to a depth. Answers 'what could break if I change this?' before editing. Includes dynamic-dispatch callers (matched by name). Requires compass_index.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            node: z.string().describe("Node name whose dependents you want"),
+            maxDepth: z.number().optional().describe("Max hops to traverse (default 4)"),
+        },
+    }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
+    server.registerTool("compass_trace", {
+        description: "Trace a call path from one node to another: returns the chain of calls linking them (or null if none within depth). Useful to understand how an entrypoint reaches a sink. Requires compass_index.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            from: z.string().describe("Starting node name"),
+            to: z.string().describe("Target node name"),
+            maxDepth: z.number().optional().describe("Max hops to search (default 8)"),
+        },
+    }, async ({ projectPath, from, to, maxDepth }) => text(trace(projectPath, from, to, maxDepth ?? 8)));
+    server.registerTool("compass_watch", {
+        description: "Keep the Compass index fresh automatically: start/stop a file watcher that incrementally re-indexes on change (debounced). action=start|stop|status. Optional — the index is also refreshed on demand by compass_index.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            action: z.enum(["start", "stop", "status"]).describe("start, stop, or status"),
+        },
+    }, async ({ projectPath, action }) => {
+        const result = action === "start" ? startWatch(projectPath)
+            : action === "stop" ? stopWatch(projectPath)
+                : watchStatus(projectPath);
+        return text(result);
+    });
+}

package/dist/modules/compass/watcher.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+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",
+]);
+function scheduleReindex(projectPath, state) {
+    if (state.timer)
+        clearTimeout(state.timer);
+    state.timer = setTimeout(() => {
+        state.timer = null;
+        buildIndex(projectPath)
+            .then(() => {
+            state.reindexes++;
+        })
+            .catch(() => {
+            /* best-effort: a transient parse/read error must not crash the server */
+        });
+    }, 400);
+}
+function watchDirsRecursively(projectPath, state) {
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        state.watchers.push(fs.watch(dir, () => scheduleReindex(projectPath, state)));
+        for (const e of entries) {
+            if (e.isDirectory() && !SKIP.has(e.name))
+                walk(path.join(dir, e.name));
+        }
+    };
+    walk(projectPath);
+}
+/**
+ * Start watching the project; changes trigger a debounced incremental reindex.
+ *
+ * Prefers a single recursive watch (macOS/Windows) and falls back to watching
+ * each directory individually where recursive watching is unsupported (Linux).
+ * Idempotent: if already watching, returns the current status without starting
+ * a second watcher.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns The watcher status after starting.
+ */
+export function startWatch(projectPath) {
+    if (active.has(projectPath))
+        return watchStatus(projectPath);
+    const state = { watchers: [], reindexes: 0, timer: null, recursive: false };
+    try {
+        // Recursive watch is supported on macOS and Windows.
+        state.watchers.push(fs.watch(projectPath, { recursive: true }, () => scheduleReindex(projectPath, state)));
+        state.recursive = true;
+    }
+    catch {
+        // Linux and others: watch each directory individually.
+        watchDirsRecursively(projectPath, state);
+    }
+    active.set(projectPath, state);
+    return watchStatus(projectPath);
+}
+/**
+ * Stop watching the project, closing all watchers and cancelling any pending
+ * reindex. Safe to call when not watching.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns A status reflecting the stopped watcher (preserving the reindex count).
+ */
+export function stopWatch(projectPath) {
+    const state = active.get(projectPath);
+    if (state) {
+        if (state.timer)
+            clearTimeout(state.timer);
+        for (const w of state.watchers)
+            w.close();
+        active.delete(projectPath);
+    }
+    return { watching: false, reindexes: state?.reindexes ?? 0, mode: null };
+}
+/** Report whether the project is being watched, and in which mode. */
+export function watchStatus(projectPath) {
+    const state = active.get(projectPath);
+    if (!state)
+        return { watching: false, reindexes: 0, mode: null };
+    return {
+        watching: true,
+        reindexes: state.reindexes,
+        mode: state.recursive ? "recursive" : "per-directory",
+    };
+}

package/dist/modules/foundation/assets/AGENTS.template.md

@@ -0,0 +1,61 @@
+# AGENTS.md — {{project_name}}
+
+Operating contract for **every** AI agent (Claude Code, Cursor, Codex, or any
+other) working in this repository. These rules are STRICT and non-negotiable.
+Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
+
+## Project
+
+- **What it is**: {{project_description}}
+- **Organization**: {{organization}}
+- **Stack**: {{stack_summary}}
+
+## Mandatory operating rules
+
+1. **Read [`LAWS.md`](LAWS.md) first.** It is the constitution; it binds the
+   standards below. Open the standard that governs your change before making
+   it. Conflicts resolve in favor of the standard; amendments go through a
+   spec change, never silent deviation.
+2. **Use Compass before file scanning** — the `compass_explore` /
+   `compass_search` / `compass_recall` tools (run `compass_index` first if the
+   graph is missing). Cheat sheet: [`docs/compass.md`](docs/compass.md).
+3. **Follow the spec workflow** for every non-trivial change; archive
+   within the same PR. Rules:
+   [`docs/standards/spec-workflow.md`](docs/standards/spec-workflow.md).
+4. **Run the quality gates yourself** before declaring anything done — see
+   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md):
+   - Tests: `{{test_commands}}`
+   - Lint / type-check: `{{lint_commands}}`
+5. **Respect the conventions** — branches `{{branch_pattern}}`, commits
+   {{commit_style}}, code that reads like its neighbors. See
+   [`docs/standards/base-standards.md`](docs/standards/base-standards.md) and
+   [`docs/standards/conventions.md`](docs/standards/conventions.md).
+6. **Use the skills.** `ai-specs/` is the canonical home for skills, commands,
+   and subagents, mirrored to each IDE directory via symlinks.
+7. **Ask before irreversible or outward-facing actions.**
+
+## The standards (the law, in detail)
+
+| Standard | Governs |
+|----------|---------|
+| [`docs/standards/base-standards.md`](docs/standards/base-standards.md) | Languages, commits, comments, dependencies |
+| [`docs/standards/architecture.md`](docs/standards/architecture.md) | Modules, layering, boundaries |
+| [`docs/standards/backend-standards.md`](docs/standards/backend-standards.md) | Backend layers, docstrings, typing, migrations |
+| [`docs/standards/frontend-standards.md`](docs/standards/frontend-standards.md) | Frontend layers, rendering, i18n, UI |
+| [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md) | Quality gates, testing rules |
+| [`docs/standards/documentation.md`](docs/standards/documentation.md) | Docstring/API-comment convention per language |
+| [`docs/standards/conventions.md`](docs/standards/conventions.md) | Branches, PRs, tracker, versioning |
+| [`docs/standards/spec-workflow.md`](docs/standards/spec-workflow.md) | Spec-driven workflow, archiving |
+| [`docs/compass.md`](docs/compass.md) | Compass usage |
+
+## Directory map for agents
+
+| Path | Purpose |
+| --- | --- |
+| `LAWS.md` | The constitution — binds the standards |
+| `docs/standards/` | The individual laws (one file per standard) |
+| `AGENTS.md` / `CLAUDE.md` | Agent entry points (this contract) |
+| `ai-specs/` | Canonical skills, commands, rules, agents |
+| `.claude/` `.cursor/` `.codex/` `.agents/` | IDE mirrors (symlinks into `ai-specs/`) |
+| `spec/` | Spec-driven workflow: specs, changes, archive |
+| `.mcp.json` | MCP wiring (speclaw) |

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -0,0 +1,72 @@
+# CLAUDE.md — {{project_name}} Agent Operating Rules
+
+Agent rules for the **{{project_name}}** repository ({{project_description}}).
+These rules are STRICT. Read this file at the start of every session.
+Cross-agent context: [`AGENTS.md`](AGENTS.md) · The law: [`LAWS.md`](LAWS.md)
+
+---
+
+## Rule 0 — The Law comes first
+
+Read [`LAWS.md`](LAWS.md) before writing or changing any code. It is the
+constitution: it binds the individual standards below. Open the standard that
+governs the area you're touching **before** touching it:
+
+| You're working on… | Read first |
+|--------------------|-----------|
+| Anything | [`docs/standards/base-standards.md`](docs/standards/base-standards.md) |
+| Structure / boundaries | [`docs/standards/architecture.md`](docs/standards/architecture.md) |
+| Backend code | [`docs/standards/backend-standards.md`](docs/standards/backend-standards.md) |
+| Frontend code | [`docs/standards/frontend-standards.md`](docs/standards/frontend-standards.md) |
+| Tests / gates | [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md) |
+| Docstrings / API comments | [`docs/standards/documentation.md`](docs/standards/documentation.md) |
+| Branches / PRs / tickets | [`docs/standards/conventions.md`](docs/standards/conventions.md) |
+| Any non-trivial change | [`docs/standards/spec-workflow.md`](docs/standards/spec-workflow.md) |
+
+When any instruction conflicts with a standard, **the standard wins** — and if
+you believe it is wrong, propose an amendment via a spec change; never silently
+ignore it.
+
+## Rule 1 — Compass before grep
+
+This repo is indexed by Compass, speclaw's local code graph (`.speclaw/`). Use
+the `compass_explore`, `compass_search`, and `compass_recall` tools **BEFORE**
+grep/find or reading files at random; run `compass_index` first if the graph
+is missing. See [`docs/compass.md`](docs/compass.md). Fall back to Grep/Read
+only when the graph doesn't cover what you need.
+
+## Rule 2 — Spec-driven, always
+
+No non-trivial change lands without a spec change (propose → implement →
+verify → archive). The rules are in
+[`docs/standards/spec-workflow.md`](docs/standards/spec-workflow.md);
+the workflow skills live in `ai-specs/skills/` and the `/spec` commands wrap
+them. A change is not done until it is archived — archiving belongs in the PR.
+
+## Rule 3 — Quality gates are non-negotiable
+
+- Tests: `{{test_commands}}`
+- Lint / type-check: `{{lint_commands}}`
+
+Run them yourself and report real output. Never claim success you did not
+observe. Full rules:
+[`docs/standards/testing-standards.md`](docs/standards/testing-standards.md).
+
+## Rule 4 — Conventions
+
+Branches `{{branch_pattern}}`, commits {{commit_style}}, code that reads like
+its neighbors, comments that carry constraints (never ticket IDs). Full rules:
+[`docs/standards/base-standards.md`](docs/standards/base-standards.md) and
+[`docs/standards/conventions.md`](docs/standards/conventions.md).
+
+## Rule 5 — Skills are law-adjacent
+
+Skills, commands, and subagents live in `ai-specs/` (symlinked into
+`.claude/`, `.cursor/`, `.codex/`, `.agents/`). When a skill matches the
+task, use it — do not improvise a parallel process.
+
+## Rule 6 — Stop conditions
+
+Stop and ask the user before: destructive operations (deletes, force-push,
+schema drops), publishing anything outward-facing (PR reviews, tickets,
+comments), or any action that contradicts a standard.

package/dist/modules/foundation/assets/LAWS.template.md

@@ -0,0 +1,39 @@
+# The Laws of {{project_name}}
+
+> This is the constitution of this project. It does not restate the standards —
+> it **binds** them. Every AI agent working in this repository MUST read this
+> file at the start of a session and MUST comply with every standard it links
+> below. When a standard conflicts with an agent's default behavior, the
+> standard wins.
+
+- **Project**: {{project_name}} — {{project_description}}
+- **Organization**: {{organization}}
+- **Stack**: {{stack_summary}}
+
+## The standards (each is a law)
+
+| Law | File | Governs |
+|-----|------|---------|
+| Base | [`docs/standards/base-standards.md`](docs/standards/base-standards.md) | Languages, commits, comments, dependencies, engineering principles |
+| Architecture | [`docs/standards/architecture.md`](docs/standards/architecture.md) | Modules/bounded contexts, layering, cross-boundary rules |
+| Backend | [`docs/standards/backend-standards.md`](docs/standards/backend-standards.md) | Backend layers, docstrings, typing, tests, migrations |
+| Frontend | [`docs/standards/frontend-standards.md`](docs/standards/frontend-standards.md) | Frontend layers, rendering boundaries, state, i18n, UI |
+| Testing | [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md) | Quality gates, what must be tested, verification |
+| Documentation | [`docs/standards/documentation.md`](docs/standards/documentation.md) | Docstring/API-comment convention per language |
+| Conventions | [`docs/standards/conventions.md`](docs/standards/conventions.md) | Branches, PRs, tracker, versioning |
+| Spec | [`docs/standards/spec-workflow.md`](docs/standards/spec-workflow.md) | Spec-driven workflow, mandatory task steps, archiving |
+| Compass | [`docs/compass.md`](docs/compass.md) | Using the code knowledge graph before grep |
+
+## Binding rules
+
+1. **Read the relevant standard before touching its area.** The table above is
+   the map. Agents open the standard that governs the code they're changing.
+2. **The standards are enforced, not advisory.** A violation is a blocking
+   finding in review.
+3. **Amendments go through the spec workflow.** A standard is changed like code — via a
+   reviewed change (see the spec-workflow law). An agent may propose an amendment;
+   it may never silently ignore a standard.
+4. **Entry points reference the law.** [`CLAUDE.md`](CLAUDE.md) and
+   [`AGENTS.md`](AGENTS.md) point every agent here first.
+
+{{custom_laws}}

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -0,0 +1,43 @@
+# Compass — code intelligence for agents in {{project_name}}
+
+**Compass** is speclaw's local code graph: a pre-indexed map of every symbol
+(node) and relationship (edge) in this workspace, plus a local vector store for
+semantic recall. Agents MUST use it **before** manual grep/read loops when
+exploring or editing code — this is Rule 1 of the agent contract (`AGENTS.md`).
+
+It runs entirely on your machine, needs no LLM and no external service, and
+stores everything in `.speclaw/` (gitignored). It ships inside speclaw — there
+is nothing extra to install.
+
+## Why use it
+
+| Without Compass | With Compass |
+|-----------------|--------------|
+| Many `Grep` + `Read` round-trips (tokens spent scanning) | One `compass_explore` call returns just the relevant node |
+| Guess which file matters | `compass_recall` finds code by meaning |
+| Edit without knowing the blast radius | callers/callees returned with the node |
+| Whole files dumped into context | verbatim source of the node + its neighbors only |
+
+The point is token economy: the agent gets exactly the code it needs to answer
+a request, not whole files.
+
+## The tools
+
+| Tool | Use it to |
+|------|-----------|
+| `compass_index` | Build/refresh the graph (`.speclaw/index.db`). Incremental — unchanged files are skipped by hash. Run once after init and after significant edits. |
+| `compass_explore` | Read a node's verbatim source plus its callers and callees. The default before editing. |
+| `compass_search` | Structural search: find nodes by name/keyword. |
+| `compass_recall` | Semantic search: describe what you want in natural language and get nodes ranked by meaning. |
+| `compass_impact` | Blast radius: every node that transitively calls a target — "what could break if I change this?" before editing. |
+| `compass_trace` | Trace a call path between two nodes — how an entrypoint reaches a sink. |
+| `compass_watch` | Keep the index fresh automatically (start/stop a debounced incremental re-index on file change). |
+
+If the graph is missing (no `.speclaw/index.db`), run `compass_index` first;
+until then, fall back to Grep/Read.
+
+## Project-specific starting points
+
+<!-- Filled in during speclaw init: the project's real entrypoints, core
+modules, and the traces agents need most often. -->
+{{compass_hints}}