@esneiderbravo/speclaw 1.0.1 → 2.0.0

package/dist/modules/cortex/harness.js

@@ -0,0 +1,270 @@
+/**
+ * Deterministic multi-agent harness state for a lawbook change.
+ *
+ * Speclaw does not spawn LLMs. This module only persists stage transitions;
+ * the host agent (Cursor/Claude/…) follows the Cortex skill and calls these
+ * ops via `speclaw cortex` or the `cortex` MCP tool.
+ *
+ * Cortex must not import from the lawbook module (no cycles). Ceremony level
+ * is read locally from `change.json` `confirmedLevel` (default 3).
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const HARNESS_STAGES = [
+    "exploring",
+    "planning",
+    "questions",
+    "implementing",
+    "reviewing",
+    "testing",
+    "archiving",
+    "done",
+];
+export const harnessOps = ["status", "start", "advance", "rework"];
+const DEFAULT_MAX_REWORK = 3;
+function specRoot(projectPath) {
+    return path.join(projectPath, "lawbook");
+}
+function changeDir(projectPath, change) {
+    return path.join(specRoot(projectPath), "changes", change);
+}
+function harnessPath(projectPath, change) {
+    return path.join(changeDir(projectPath, change), "harness.json");
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function requireChangeDir(projectPath, change) {
+    const dir = changeDir(projectPath, change);
+    if (!fs.existsSync(dir)) {
+        throw new Error(`change "${change}" not found under lawbook/changes/`);
+    }
+    return dir;
+}
+/**
+ * Read confirmed ceremony level from change.json without importing lawbook.
+ * Missing file or field → 3.
+ */
+function readConfirmedLevel(projectPath, change) {
+    const p = path.join(changeDir(projectPath, change), "change.json");
+    if (!fs.existsSync(p))
+        return 3;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        const n = raw.confirmedLevel;
+        if (n === 0 || n === 1 || n === 2 || n === 3)
+            return n;
+    }
+    catch {
+        /* default */
+    }
+    return 3;
+}
+/** Read harness.json or return null when absent. */
+export function readHarness(projectPath, change) {
+    requireChangeDir(projectPath, change);
+    const p = harnessPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+function writeHarness(projectPath, change, state) {
+    const p = harnessPath(projectPath, change);
+    fs.writeFileSync(p, JSON.stringify(state, null, 2) + "\n");
+}
+function nextAfterExplore(level) {
+    return level === 0 ? "implementing" : "planning";
+}
+function nextAfterImplement(level) {
+    return level === 0 ? "testing" : "reviewing";
+}
+/**
+ * Legal one-step advances (not rework). Rework is handled separately.
+ */
+function allowedAdvance(from, level, verdict) {
+    switch (from) {
+        case "exploring":
+            return nextAfterExplore(level);
+        case "planning":
+            return "implementing";
+        case "questions":
+            return "planning";
+        case "implementing":
+            return nextAfterImplement(level);
+        case "reviewing":
+            if (verdict === "FAIL") {
+                throw new Error(`harness advance from reviewing with FAIL requires op "rework" (not advance)`);
+            }
+            if (verdict !== "PASS") {
+                throw new Error(`harness advance from reviewing requires verdict PASS or FAIL`);
+            }
+            return "testing";
+        case "testing":
+            if (verdict === "FAIL") {
+                throw new Error(`harness advance from testing with FAIL requires op "rework"`);
+            }
+            if (verdict !== "PASS") {
+                throw new Error(`harness advance from testing requires verdict PASS or FAIL`);
+            }
+            return "archiving";
+        case "archiving":
+            return "done";
+        case "done":
+            throw new Error(`harness already done — no further advance`);
+        default: {
+            const _exhaustive = from;
+            throw new Error(`unknown stage ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Dispatch a harness op for a change.
+ *
+ * // Covers: req~harness-state~1
+ */
+export function handleHarness(args) {
+    const { projectPath, change, harnessOp } = args;
+    requireChangeDir(projectPath, change);
+    if (harnessOp === "status") {
+        return { state: readHarness(projectPath, change) };
+    }
+    if (harnessOp === "start") {
+        const existing = readHarness(projectPath, change);
+        if (existing && existing.stage !== "done") {
+            throw new Error(`harness already started for "${change}" (stage=${existing.stage}); use status/advance/rework`);
+        }
+        const level = readConfirmedLevel(projectPath, change);
+        const state = {
+            version: 1,
+            change,
+            stage: "exploring",
+            level,
+            iteration: 0,
+            maxRework: DEFAULT_MAX_REWORK,
+            verdicts: { review: null, test: null },
+            openQuestions: [],
+            history: [
+                {
+                    at: nowIso(),
+                    from: "exploring",
+                    to: "exploring",
+                    op: "start",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, state);
+        return state;
+    }
+    const current = readHarness(projectPath, change);
+    if (!current) {
+        throw new Error(`no harness.json for "${change}" — run cortex start first`);
+    }
+    if (harnessOp === "advance") {
+        // Planner may pause for questions instead of advancing to implement.
+        if (current.stage === "planning" && args.pauseForQuestions) {
+            const questions = args.openQuestions ?? [];
+            if (questions.length === 0) {
+                throw new Error(`pauseForQuestions requires at least one openQuestions entry`);
+            }
+            const next = {
+                ...current,
+                stage: "questions",
+                openQuestions: questions,
+                history: [
+                    ...current.history,
+                    {
+                        at: nowIso(),
+                        from: "planning",
+                        to: "questions",
+                        op: "advance",
+                        note: args.note,
+                    },
+                ],
+            };
+            writeHarness(projectPath, change, next);
+            return next;
+        }
+        const to = allowedAdvance(current.stage, current.level, args.verdict ?? undefined);
+        const verdicts = { ...current.verdicts };
+        if (current.stage === "reviewing" && args.verdict)
+            verdicts.review = args.verdict;
+        if (current.stage === "testing" && args.verdict)
+            verdicts.test = args.verdict;
+        const next = {
+            ...current,
+            stage: to,
+            verdicts,
+            openQuestions: current.stage === "questions" ? [] : current.openQuestions,
+            history: [
+                ...current.history,
+                {
+                    at: nowIso(),
+                    from: current.stage,
+                    to,
+                    op: "advance",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, next);
+        return next;
+    }
+    if (harnessOp === "rework") {
+        if (current.stage !== "reviewing" && current.stage !== "testing") {
+            throw new Error(`rework only allowed from reviewing or testing (now ${current.stage})`);
+        }
+        if (args.verdict !== "FAIL") {
+            throw new Error(`rework requires verdict FAIL`);
+        }
+        if (current.iteration >= current.maxRework) {
+            throw new Error(`max rework (${current.maxRework}) reached — coordinator must ask the human before continuing`);
+        }
+        const verdicts = { ...current.verdicts };
+        if (current.stage === "reviewing")
+            verdicts.review = "FAIL";
+        if (current.stage === "testing")
+            verdicts.test = "FAIL";
+        const next = {
+            ...current,
+            stage: "implementing",
+            iteration: current.iteration + 1,
+            verdicts,
+            history: [
+                ...current.history,
+                {
+                    at: nowIso(),
+                    from: current.stage,
+                    to: "implementing",
+                    op: "rework",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, next);
+        return next;
+    }
+    throw new Error(`unknown harnessOp '${String(harnessOp)}'`);
+}
+/**
+ * Archive blockers derived from harness verdicts.
+ *
+ * // Covers: req~harness-archive-gate~1
+ */
+export function harnessArchiveBlockers(projectPath, change) {
+    const state = readHarness(projectPath, change);
+    if (!state) {
+        return [`missing harness.json — run \`speclaw cortex start --change ${change}\``];
+    }
+    const blockers = [];
+    if (state.verdicts.test !== "PASS") {
+        blockers.push(`harness test verdict is not PASS (got ${String(state.verdicts.test)})`);
+    }
+    if (state.level >= 1 && state.verdicts.review !== "PASS") {
+        blockers.push(`harness review verdict is not PASS (got ${String(state.verdicts.review)})`);
+    }
+    if (state.stage !== "archiving" && state.stage !== "done") {
+        blockers.push(`harness stage is ${state.stage} — advance to archiving before archive`);
+    }
+    return blockers;
+}

package/dist/modules/cortex/register.js

@@ -0,0 +1,49 @@
+/**
+ * Cortex MCP registration — One brain. Many agents.
+ *
+ * // Covers: req~cortex-module~1
+ */
+import { z } from "zod";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
+import { handleHarness, harnessOps, readHarness, } from "./harness.js";
+import { briefForStage } from "./brief.js";
+export const cortexActions = [...harnessOps, "brief"];
+/**
+ * Register the canonical `cortex` MCP tool.
+ *
+ * @param server - MCP server instance.
+ * @param opts - Exposure profile.
+ */
+export function registerCortex(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("cortex", "Cortex multi-agent loop: status, start, advance, rework, brief for a change.", {
+        projectPath: z.string(),
+        change: z.string(),
+        action: z.enum(cortexActions),
+        note: z.string().optional(),
+        verdict: z.enum(["PASS", "FAIL"]).optional(),
+        openQuestions: z.array(z.string()).optional(),
+        pauseForQuestions: z.boolean().optional(),
+    }, async ({ projectPath, change, action, note, verdict, openQuestions, pauseForQuestions }) => {
+        if (action === "brief") {
+            const state = readHarness(projectPath, change);
+            const brief = briefForStage(state?.stage ?? null);
+            return text(JSON.stringify({ state, ...brief }, null, 2));
+        }
+        return text(handleHarness({
+            projectPath,
+            change,
+            harnessOp: action,
+            note,
+            verdict: verdict ?? null,
+            openQuestions,
+            pauseForQuestions,
+        }));
+    });
+}

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

@@ -22,23 +22,30 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    after Compass returns nothing useful, the graph is missing (`compass_index`
    first), or the target isn't indexed code (stylesheets, config, logs). Cheat
    sheet: [`docs/compass.md`](docs/compass.md).
-3. **Follow the lawbook workflow** for every non-trivial change; archive
-   within the same PR. Rules:
+3. **Follow Cortex** (*One brain. Many agents.*) for every non-trivial change;
+   archive within the same PR. The primary agent is the **coordinator**
+   (`cortex` skill / `/lawbook/cortex`) — it MUST NOT implement
+   product code itself. It dispatches explorer → planner → implementer →
+   reviewer → tester → archiver (or adopts each role while obeying that
+   role's permission profile). Drive state with the `cortex` MCP tool or
+   `speclaw cortex`. Rules:
    [`docs/standards/lawbook.md`](docs/standards/lawbook.md).
 4. **Run the quality gates yourself** before declaring anything done — see
-   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md):
+   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md)
+   (owned by the **tester** role under Cortex):
    - 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.
+6. **Use the skills and role agents.** `ai-specs/` is the canonical home for
+   skills, commands, rules, and agents, mirrored to each IDE directory via
+   symlinks.
 7. **Ask before irreversible or outward-facing actions** — destructive commands;
    writing to a real data store (DB rows or files with real user data, including
    for tests — verify against an isolated/throwaway store); publishing
-   reviews/tickets/comments.
+   reviews/tickets/comments. Planner questions always go to the human.
 
 ## The standards (the law, in detail)
 

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

@@ -48,21 +48,24 @@ target is not indexed code — stylesheets, JSON/config, markdown, logs,
 generated files, lockfiles. Never skip Compass because grep "feels faster."
 See [`docs/compass.md`](docs/compass.md).
 
-## Rule 2 — Spec-driven, always
+## Rule 2 — Spec-driven Cortex loop, always
 
-No non-trivial change lands without a spec change (propose → implement →
-verify → archive). The rules are in
+No non-trivial change lands without a lawbook change (propose → implement →
+verify → archive) run through **Cortex** (*One brain. Many agents.*). You are the
+**coordinator** unless you were spawned as a role agent: use the `cortex`
+skill / `/lawbook/cortex` and the `cortex` MCP tool; do **not** implement product code yourself.
+Role agents live in `ai-specs/agents/`. The rules are in
 [`docs/standards/lawbook.md`](docs/standards/lawbook.md);
-the workflow skills live in `ai-specs/skills/` and the `/lawbook` commands wrap
-them. A change is not done until it is archived — archiving belongs in the PR.
+workflow skills live in `ai-specs/skills/` and `/lawbook` 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:
+The **tester** role runs them and reports real output. Never claim success you
+did not observe. Full rules:
 [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md).
 
 ## Rule 4 — Conventions
@@ -72,11 +75,11 @@ 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
+## Rule 5 — Skills and role agents 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.
+Skills, commands, rules, and agents live in `ai-specs/` (symlinked into
+`.claude/`, `.cursor/`, `.codex/`, `.agents/`). When a skill or role matches
+the task, use it — do not improvise a parallel process.
 
 ## Rule 6 — Stop conditions
 
@@ -85,3 +88,4 @@ schema drops), writing to a real data store (DB rows or files holding real user
 data — including to set up or tear down test data; verification runs against an
 isolated/throwaway store instead), publishing anything outward-facing (PR
 reviews, tickets, comments), or any action that contradicts a standard.
+Planner clarifying questions always go to the human via the coordinator.

package/dist/modules/foundation/assets/docs/standards/lawbook.template.md

@@ -6,38 +6,35 @@ mechanical steps are speclaw MCP tools).
 
 ## The loop
 
-No non-trivial change lands without a spec change:
-
-1. **explore** — think an idea through before committing (writes nothing).
-2. **draft** — create `lawbook/changes/<name>/`: `proposal.md`, delta specs under
-   `specs/<capability>/spec.md`, `design.md`, `tasks.md`, and a `reports/`
-   folder.
-3. **build** — implement the tasks in order, keeping code and spec in
-   agreement, and write the discipline reports under `reports/`.
-4. **sync** — reconcile the delta specs against what was actually built, then
-   promote them into the canonical `lawbook/specs/` (`lawbook_sync`). The tool
-   is a deterministic copy; the agent does the code↔spec reconciliation first.
-5. **archive** — finalize: reconcile, sync, then move the change to
-   `lawbook/changes/archive/` (`lawbook_archive`), **within the same PR** —
-   never a post-merge chore. The archive is gated (see below).
+No non-trivial change lands without a lawbook change. The default execution
+model is **Cortex** (*One brain. Many agents.*): the host primary agent is the
+**coordinator** (`cortex` skill / MCP `cortex`) and dispatches explorer → planner →
+implementer → reviewer → tester → archiver. State:
+`lawbook/changes/<name>/harness.json` (`speclaw cortex`). Lawbook owns specs
+and ceremony; Cortex owns the multi-agent loop.
+
+1. **explore** (explorer) — think an idea through before committing (writes nothing).
+2. **draft** / **quick** (planner) — create `lawbook/changes/<name>/` artifacts
+   for the confirmed ceremony level; questions go to the human via the
+   coordinator.
+3. **build** (implementer) — implement tasks; hand off before final gates.
+4. **review** (reviewer) — `reports/review.md` PASS/FAIL (skipped at level 0).
+5. **test** (tester) — quality gates, manual verification, discipline reports.
+6. **sync** / **archive** (archiver) — reconcile, sync when needed, archive
+   within the same PR. Gated on Cortex verdicts plus tasks/reports/sync.
 
 ## Mandatory task steps
 
 `tasks.md` MUST include the steps defined in `lawbook/config.yaml` and the
-`spec-tasks-mandatory-steps` rule: feature branch first, tests reviewed and
-run, manual verification executed by the agent, discipline reports produced,
-docs updated, archive within the PR. The agent performs the manual testing
-itself — never delegates it.
+`spec-tasks-mandatory-steps` rule. The **tester** role performs manual
+verification — never the user; the coordinator must not archive without a
+test PASS.
 
 ## Reports
 
-Every change carries a `reports/` folder. `build` writes one report per
-discipline it touched, named for that discipline — an open set (`backend.md`,
-`frontend.md`, `api.md`, `database.md`, `infra.md`, … — `api.md` required
-whenever the change touches an API surface) recording what was tested
-and the real results — unit, integration, and end-to-end as applicable — with
-the commands run and their output. It is evidence of testing that travels with
-the change; the archive is blocked until at least one discipline report exists.
+Every change carries a `reports/` folder. The tester writes discipline reports;
+the reviewer writes `review.md`. Archive is blocked until evidence and harness
+verdicts are complete.
 
 ## Delta specs
 
@@ -51,18 +48,8 @@ the change; the archive is blocked until at least one discipline report exists.
 ## Archiving discipline
 
 Always archive with the `archive` command / `lawbook_archive` tool, never a manual
-`mv` — the tool performs the spec promotion and validation a manual move skips.
-
-Before archiving, the agent runs a reconciliation review: it compares what was
-built against the delta specs and, when the code has drifted past the original
-contracts, shows short insights and reconciles the delta specs.
-
-`lawbook_archive` is then **gated in the engine** — it refuses to archive (and
-reports the reason) while any task is unchecked, while `reports/` holds no
-discipline report, or while the delta specs are not yet synced into the
-canonical specs. Because the gate covers both the tool and the CLI, a change
-reaches the archive only when it is genuinely complete: reconcile, `sync`, then
-archive.
+`mv`. The engine refuses archive while tasks are unchecked, reports are missing,
+specs are out of sync when required, or harness review/test verdicts are not PASS.
 
 ## Amendments to the law
 

package/dist/modules/foundation/assets/workflows/speclaw.yml

@@ -18,7 +18,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: ⚖️ Verify
-        uses: esneiderbravo/speclaw@v1
+        uses: esneiderbravo/speclaw@v2
       - name: 🛡️ Upload SARIF
         uses: github/codeql-action/upload-sarif@v4
         if: always()

package/dist/modules/foundation/context-budget.js

@@ -1,4 +1,5 @@
 import { registerCompass } from "../compass/register.js";
+import { registerCortex } from "../cortex/register.js";
 import { registerSpec } from "../lawbook/register.js";
 import { registerTools } from "../tools/register.js";
 import { registerFoundationCore } from "./register-core.js";
@@ -25,6 +26,7 @@ export function collectRegisteredTools(minimal) {
     registerFoundationCore(stub, opts);
     registerSpec(stub, opts);
     registerCompass(stub, opts);
+    registerCortex(stub, opts);
     registerTools(stub, opts);
     return tools;
 }

package/dist/modules/foundation/setup-tool.js

@@ -64,12 +64,13 @@ export function handleSpeclawSetup(args) {
             return {
                 instructions: [
                     "1. Analyze the repository at projectPath and fill profile fields from the real codebase.",
-                    "2. Call speclaw_setup with action configure-agent / add-pack as needed.",
+                    "2. Call speclaw_setup with action configure-agent as needed (packs catalog may be empty).",
                     "3. Run lawbook_change action init and compass_index when scaffold completes via CLI if needed.",
+                    "4. Non-trivial work uses Cortex: cortex skill / speclaw cortex (MCP tool cortex).",
                 ],
                 profileFields: profileFieldHelp,
                 packs: loadPacks(),
-                note: "Full scaffold runs via CLI: speclaw init — not MCP.",
+                note: "Full scaffold runs via CLI: speclaw init — not MCP. Role agents install with the lawbook workflow.",
             };
         case "configure-agent": {
             if (!args.agent)

package/dist/modules/lawbook/assets/agents/archiver.md

@@ -0,0 +1,19 @@
+---
+name: archiver
+description: Reconcile specs, sync, and archive a change when Cortex stage is archiving. No new feature implementation.
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_validate, mcp__speclaw__lawbook_sync, mcp__speclaw__lawbook_archive, mcp__speclaw__cortex
+---
+
+You are the **archiver** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Follow the `sync` then `archive` skills: reconcile delta specs to built code,
+`lawbook_change` action sync when needed, then archive. Advance Cortex to
+`done` after a successful archive.
+
+## Hard constraints
+
+- Do **not** start new feature work outside reconciliation.
+- If archive is gated, report blockers to the coordinator — do not bypass the
+  engine.

package/dist/modules/lawbook/assets/agents/explorer.md

@@ -0,0 +1,24 @@
+---
+name: explorer
+description: Read-only codebase investigation for a lawbook change. Use when the Cortex stage is exploring (or investigate for bugs). Compass-first; writes nothing under lawbook/ or src/.
+tools: Read, Grep, Glob, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__compass_index, mcp__speclaw__lawbook_investigate
+disallowedTools: Write, Edit, MultiEdit, Bash, NotebookEdit
+---
+
+You are the **explorer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Investigate the idea or bug with Compass **before** any grep/read. Produce a
+short brief for the planner: relevant symbols, blast radius, risks, and open
+questions. Do **not** draft change artifacts or edit source.
+
+## Skill
+
+Follow the `explore` skill (or `investigate` when `changeType` is bug).
+
+## Hard constraints
+
+- No Write / StrReplace / git writes / draft / archive / Cortex advance to
+  implementing.
+- When finished, return the brief to the coordinator and stop.

package/dist/modules/lawbook/assets/agents/implementer.md

@@ -0,0 +1,20 @@
+---
+name: implementer
+description: Implement drafted lawbook tasks in source and tests. Use when Cortex stage is implementing. Does not run final quality gates, review, sync, or archive.
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_index, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+disallowedTools: NotebookEdit
+---
+
+You are the **implementer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Work `tasks.md` in order using the `build` skill through implementation only.
+Keep code and delta specs in agreement. Check off completed tasks.
+
+## Hard constraints
+
+- Do **not** archive, push, or `laws accept`.
+- Do **not** skip the reviewer by "quietly fixing" after a FAIL — wait for
+  Cortex `rework` from the coordinator.
+- Stop after implementation hand-off; tester owns gates and discipline reports.

package/dist/modules/lawbook/assets/agents/planner.md

@@ -0,0 +1,27 @@
+---
+name: planner
+description: Draft lawbook change artifacts and ceremony level. Use when Cortex stage is planning. Asks clarifying questions via the coordinator; never edits src/.
+tools: Read, Grep, Glob, Write, Edit, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_level
+disallowedTools: Bash, NotebookEdit
+---
+
+You are the **planner** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Turn the explorer brief + user intent into a reviewable change under
+`lawbook/changes/<name>/` at the confirmed ceremony level. Prefer `draft` /
+`quick` skills.
+
+## Questions
+
+If anything material is ambiguous, **stop**. Return numbered questions to the
+coordinator (do not invent answers). The coordinator advances Cortex with
+`pauseForQuestions`. After human answers, continue drafting.
+
+## Hard constraints
+
+- May write only under `lawbook/changes/<name>/` (and related lawbook paths).
+- Do **not** edit `src/`, run archive, or implement code.
+- When the draft is complete, tell the coordinator to `cortex advance` toward
+  implementing.

package/dist/modules/lawbook/assets/agents/reviewer.md

@@ -0,0 +1,25 @@
+---
+name: reviewer
+description: Deep review of implemented change without patching code. Writes reports/review.md with PASS or FAIL. Use when Cortex stage is reviewing.
+tools: Read, Grep, Glob, Write, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+disallowedTools: Edit, MultiEdit, Bash, NotebookEdit
+---
+
+You are the **reviewer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Review the branch/diff against proposal, tasks, delta specs, and
+`docs/standards/*`. Write `lawbook/changes/<name>/reports/review.md` with:
+
+- Verdict: `PASS` or `FAIL`
+- Findings anchored to file paths / symbols
+- Rework guidance if FAIL
+
+You may create/overwrite **only** `reports/review.md` (and read everything else).
+
+## Hard constraints
+
+- Do **not** patch application source to "make it pass".
+- Return the verdict to the coordinator for `cortex advance` (PASS) or
+  `cortex rework` (FAIL).