@esneiderbravo/speclaw 1.0.0 → 2.0.0

package/dist/modules/lawbook/assets/skills/cortex/steps/01-load-or-start.md

@@ -0,0 +1,25 @@
+# Load or start Cortex
+
+- Confirm the change name with the user (or draft/quick first if none exists).
+- Run the `cortex` MCP tool with `action: status` (or
+  `speclaw cortex status --change <name>`). Prefer `action: brief` when you
+  need the role + skill hints for the current stage.
+- If missing, `action: start`.
+- Read `ai-specs/agents/<role>.md` for the current stage's permission contract.
+- If the host can spawn subagents (Claude Task / Cursor Task), spawn that role
+  with the contract in the prompt. If not, **adopt the role** in this session
+  but obey its allow/deny list strictly.
+
+Stage → role:
+
+| Stage | Role |
+|-------|------|
+| exploring | explorer (`explore` / `investigate` for bugs) |
+| planning / questions | planner (`draft` / `quick`); questions always go to the human |
+| implementing | implementer (`build` through implement hand-off) |
+| reviewing | reviewer |
+| testing | tester |
+| archiving | archiver (`sync` + `archive`) |
+| done | stop — report success |
+
+Next: read `steps/02-dispatch-loop.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/02-dispatch-loop.md

@@ -0,0 +1,19 @@
+# Dispatch loop
+
+For the current Cortex stage (`cortex` action `brief` or `status`):
+
+1. Dispatch (spawn or adopt) the matching role with a clear handoff brief.
+2. On role completion, call the matching Cortex op:
+   - exploring → `advance`
+   - planning with questions → `advance` + `pauseForQuestions` + `openQuestions`
+   - questions after human answers → `advance` (back to planning)
+   - planning complete → `advance` (to implementing)
+   - implementing done → `advance` (reviewing, or testing at level 0)
+   - reviewing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
+   - testing PASS → `advance` + `verdict: PASS`; FAIL → `rework` + `verdict: FAIL`
+   - archiving success → `advance` (to done)
+3. Max rework is 3; if the engine rejects further rework, **ask the human**.
+4. Coordinator never edits `src/`, never archives, never pushes, never runs
+   `laws accept`.
+
+Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/03-complete.md

@@ -0,0 +1,10 @@
+# Complete
+
+When Cortex stage is `done` (or the human stops the run), summarize:
+
+- Change name and final stage
+- Review/test verdicts and iteration count
+- Archive path if archived
+- Anything still open for the human
+
+No further steps remain — Cortex workflow complete.

package/dist/modules/lawbook/assets/skills/test/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: test
+description: Run quality gates, manual verification, and discipline reports for a change. Used by the tester Cortex role after implementation. Use when Cortex stage is testing or the user asks to verify/test a change.
+---
+
+# test — Verify a change
+
+Run gates, manual verification, and write discipline reports. You may add
+missing tests; do not implement new features.
+
+Read `steps/01-quality-gates.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/{build/steps/04-quality-gates.md → test/steps/01-quality-gates.md}

@@ -7,4 +7,4 @@ Run the repo's gates from `docs/standards/testing-standards.md`:
 
 Run them yourself and report real output. A red gate blocks completion.
 
-Next: read `steps/05-manual-verification.md` and do only what it says.
+Next: read `steps/02-manual-verification.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/{build/steps/05-manual-verification.md → test/steps/02-manual-verification.md}

@@ -19,4 +19,4 @@ and proceed only after explicit authorization. A backup is not a substitute for
 authorization. Record in the report how verification stayed isolated (or the
 authorization you obtained).
 
-Next: read `steps/06-discipline-reports.md` and do only what it says.
+Next: read `steps/03-discipline-reports.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/{build/steps/06-discipline-reports.md → test/steps/03-discipline-reports.md}

@@ -35,10 +35,13 @@ the evidence trustworthy and reproducible, rather than left to improvisation:
    change, with proof it is pre-existing (e.g. it reproduces with the change
    stashed) — or state "none".
 6. **Pending manual steps** — anything not automated, stated plainly — or "none".
-7. **Verdict** — one line.
+7. **Verdict** — one line (`PASS` or `FAIL` for Cortex).
 
 If a test kind does not yet apply (e.g. no unit runner), the report says so in
 place of that evidence and records the gates and manual verification that stood
 in.
 
-Next: read `steps/07-hand-off.md` and do only what it says.
+Tell the coordinator the Cortex verdict so they can `advance` (PASS) or
+`rework` (FAIL).
+
+No further steps remain — test workflow complete.

package/dist/modules/lawbook/change-tool.js

@@ -3,6 +3,7 @@ import { specInit, specValidate, specSync, specArchive, specList } from "./engin
 import { handleLevel } from "./quick.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
+import { handleHarness, harnessOps } from "../cortex/harness.js";
 export const lawbookChangeActions = [
     "init",
     "list",
@@ -12,6 +13,7 @@ export const lawbookChangeActions = [
     "level",
     "coverage",
     "drift",
+    "harness",
 ];
 export const lawbookChangeSchema = {
     projectPath: z.string(),
@@ -31,6 +33,11 @@ export const lawbookChangeSchema = {
     capability: z.string().optional(),
     includeReverse: z.boolean().optional(),
     maxItems: z.number().int().min(1).max(50).optional(),
+    harnessOp: z.enum(harnessOps).optional(),
+    verdict: z.enum(["PASS", "FAIL"]).optional(),
+    openQuestions: z.array(z.string()).optional(),
+    pauseForQuestions: z.boolean().optional(),
+    note: z.string().optional(),
 };
 function requireField(args, field) {
     const v = args[field];
@@ -84,6 +91,21 @@ export function handleLawbookChange(args) {
                 return report;
             return renderDriftAgent(report, args.maxItems ?? 10);
         }
+        case "harness": {
+            // Deprecated alias — prefer MCP tool `cortex` / `speclaw cortex`.
+            if (!args.harnessOp) {
+                throw new Error(`lawbook_change: action 'harness' requires 'harnessOp'`);
+            }
+            return handleHarness({
+                projectPath: args.projectPath,
+                change: requireField(args, "change"),
+                harnessOp: args.harnessOp,
+                verdict: args.verdict ?? null,
+                openQuestions: args.openQuestions,
+                pauseForQuestions: args.pauseForQuestions,
+                note: args.note ?? args.reason,
+            });
+        }
         default:
             throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);
     }

package/dist/modules/lawbook/engine.js

@@ -5,6 +5,7 @@ import { sealCapability } from "./anchors.js";
 import { classifyEars, diagnoseEars, extractNormativeBody, loadEarsConfig, splitRequirementBlocks, } from "./ears.js";
 import { artifactNeeds, confirmedLevel, countUncheckedTasks, gatherSignals, hasDisciplineReport, loadCeremonyConfig, proposeLevel, readChangeType, readCeremonyRecord, } from "./levels.js";
 import { inferBugResolution, preventionRequiresDelta, validateBugfixContent } from "./bugfix.js";
+import { harnessArchiveBlockers } from "../cortex/harness.js";
 // speclaw's own spec-driven workflow engine. Inspired by OpenSpec's model
 // (proposals, delta specs, changes, archive) but implemented from scratch and
 // deliberately simpler: a change's specs/ holds the full intended spec for each
@@ -430,6 +431,9 @@ export function specArchivePreconditions(projectPath, change) {
     }
     // 4. Opt-in coverage gate: only when the change's delta specs declare ids.
     blockers.push(...coverageArchiveBlockers(projectPath, change));
+    // 5. Multi-agent harness: review/test PASS and stage archiving|done.
+    // Covers: req~harness-archive-gate~1
+    blockers.push(...harnessArchiveBlockers(projectPath, change));
     return blockers;
 }
 /**

package/dist/modules/lawbook/levels.js

@@ -462,7 +462,13 @@ export function hasDisciplineReport(changeDir) {
     const reportsDir = path.join(changeDir, "reports");
     if (!fs.existsSync(reportsDir))
         return false;
-    return fs
-        .readdirSync(reportsDir)
-        .some((n) => n.endsWith(".md") && n.toLowerCase() !== "readme.md");
+    return fs.readdirSync(reportsDir).some((n) => {
+        if (!n.endsWith(".md"))
+            return false;
+        const lower = n.toLowerCase();
+        // README scaffold and reviewer harness verdict are not discipline evidence.
+        if (lower === "readme.md" || lower === "review.md")
+            return false;
+        return true;
+    });
 }

package/dist/modules/lawbook/register.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { defineTool, defineAliasTool, text } from "../../shared/mcp.js";
@@ -17,6 +18,12 @@ export function installWorkflow(projectPath, vars, report, opts) {
     copyRendered(path.join(ASSETS, "skills"), path.join(aiSpecs, "skills"), vars, report, opts);
     copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "lawbook"), vars, report, opts);
     copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report, opts);
+    // Role agents (explorer/planner/implementer/reviewer/tester/archiver) — always on.
+    // Covers: req~role-agents-default~1
+    const agentsSrc = path.join(ASSETS, "agents");
+    if (fs.existsSync(agentsSrc)) {
+        copyRendered(agentsSrc, path.join(aiSpecs, "agents"), vars, report, opts);
+    }
 }
 /** Register the spec workflow MCP tools. */
 export function registerSpec(server, opts = {}) {

package/dist/modules/tools/assets/packs.json

@@ -1,6 +1 @@
-{
-  "agents": {
-    "description": "Subagent definitions rendered with the project profile: backend-developer, frontend-developer, product-strategy-analyst. They read the project's standards (docs/standards/*) for the stack, so they stay accurate as the standards are filled.",
-    "path": "agents"
-  }
-}
+{}

package/dist/server.js

@@ -1,10 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerCompass } from "./modules/compass/register.js";
+import { registerCortex } from "./modules/cortex/register.js";
 import { registerSpec } from "./modules/lawbook/register.js";
 import { registerFoundation } from "./modules/foundation/register.js";
 import { registerTools } from "./modules/tools/register.js";
 import { isMinimalMode } from "./shared/exposure.js";
+import { pkgVersion } from "./shared/version.js";
 /**
  * Build the speclaw MCP server with every module's tools registered.
  *
@@ -12,11 +14,12 @@ import { isMinimalMode } from "./shared/exposure.js";
  */
 export function buildServer(opts = {}) {
     const minimal = opts.minimal ?? isMinimalMode();
-    const server = new McpServer({ name: "speclaw", version: "0.1.0" });
+    const server = new McpServer({ name: "speclaw", version: pkgVersion() });
     const reg = { minimal };
     registerFoundation(server, reg);
     registerSpec(server, reg);
     registerCompass(server, reg);
+    registerCortex(server, reg);
     registerTools(server, reg);
     return server;
 }

package/dist/shared/agents.js

@@ -15,21 +15,21 @@ export const AGENTS = [
         id: "cursor",
         label: "Cursor",
         ideDir: ".cursor",
-        linkTargets: ["skills", "commands", "rules"],
+        linkTargets: ["skills", "commands", "rules", "agents"],
         mcpFile: ".cursor/mcp.json",
     },
     {
         id: "codex",
         label: "Codex",
         ideDir: ".codex",
-        linkTargets: ["skills", "commands"],
+        linkTargets: ["skills", "commands", "agents"],
         mcpFile: ".codex/mcp.json",
     },
     {
         id: "windsurf",
         label: "Windsurf",
         ideDir: ".windsurf",
-        linkTargets: ["skills", "commands"],
+        linkTargets: ["skills", "commands", "agents"],
         mcpFile: ".windsurf/mcp.json",
     },
     {

package/dist/shared/exposure.js

@@ -4,8 +4,8 @@ import { fileURLToPath } from "node:url";
 import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
- * discovery + law loop: compass_explore/find/diff_context, lawbook_change.
- * Deprecated aliases are never registered in minimal mode.
+ * discovery + law loop: compass_explore/find/diff_context, lawbook_change,
+ * cortex. Deprecated aliases are never registered in minimal mode.
  */
 export const MINIMAL_OMIT = new Set([
     "compass_index",

package/dist/shared/tool-catalog.js

@@ -4,12 +4,13 @@ export const CANONICAL_TOOLS = [
     "compass_find",
     "compass_diff_context",
     "compass_index",
+    "cortex",
     "lawbook_change",
     "lawbook_investigate",
     "speclaw_setup",
     "speclaw_check",
 ];
-export const MAX_CANONICAL_TOOLS = 8;
+export const MAX_CANONICAL_TOOLS = 9;
 /** Retired MCP names → canonical replacement hint for deprecation notices. */
 export const ALIAS_TARGETS = {
     compass_search: "compass_find (mode: exact)",
@@ -35,7 +36,7 @@ export const ALIAS_TARGETS = {
 };
 export const ALIAS_NAMES = Object.keys(ALIAS_TARGETS);
 const ALIAS_SET = new Set(ALIAS_NAMES);
-/** True when `name` is one of the eight canonical tools. */
+/** True when `name` is one of the nine canonical tools. */
 export function isCanonicalTool(name) {
     return CANONICAL_TOOLS.includes(name);
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Where specs become law. A self-contained MCP suite that turns any repo into a spec-driven, agent-ready project: its own constitution (foundation), its own local code graph (Compass), its own spec-driven workflow (Lawbook), and opt-in skill packs (Tools). No external CLIs, no LLM to install.",
+  "description": "Where specs become law. A self-contained MCP suite that turns any repo into a spec-driven, multi-agent-ready project: its own constitution (Foundation), local code graph (Compass), spec workflow (Lawbook), and multi-agent brain (Cortex). No external CLIs, no LLM to install.",
   "keywords": [
     "mcp",
     "mcp-server",

package/dist/modules/lawbook/assets/skills/build/steps/07-hand-off.md

@@ -1,9 +0,0 @@
-# Hand off
-
-When every task is checked and gates are green, tell the user the change is
-ready to `sync` and `archive`. Keep the delta specs current as you build, but
-know that `sync` formally reconciles the delta specs against what was actually
-built — so behavior that drifted past the original spec is caught there, not
-left to chance.
-
-No further steps remain — build workflow complete.

package/dist/modules/tools/assets/packs/agents/backend-developer.md

@@ -1,61 +0,0 @@
----
-name: backend-developer
-description: Use this agent for backend planning, reviews, and refactors in this repository. Focus on the backend source and test trees, migration wiring, and the service/workflow boundaries documented in `AGENTS.md` and `LAWS.md`.
-model: sonnet
-color: red
----
-
-You are a senior backend architect for this project. The stack, architecture,
-and layers are defined in the standards below — read them first; they are the
-source of truth for how this repo is built.
-
-## Goal
-
-Create a concrete implementation plan only (do not implement code directly).
-
-Output path:
-
-- `docs/agent_outputs/{feature_name}/backend.md`
-
-## Standards to apply (read before planning)
-
-- [`docs/standards/backend-standards.md`](../../docs/standards/backend-standards.md) — layers, docstrings, typing, tests, migrations
-- [`docs/standards/architecture.md`](../../docs/standards/architecture.md) — modules and layer boundaries
-- [`docs/standards/testing-standards.md`](../../docs/standards/testing-standards.md) — quality gates
-- [`docs/standards/lawbook.md`](../../docs/standards/lawbook.md) — spec-driven workflow
-- [`docs/standards/base-standards.md`](../../docs/standards/base-standards.md) — cross-cutting rules
-
-Use `compass_explore` to locate the real entrypoints, routers, schemas,
-config, and DB wiring. Repo entry points: `AGENTS.md` and `LAWS.md`.
-
-## Planning rules
-
-1. Plan with small, ordered steps and explicit file paths.
-2. Include API contract impacts, validation impacts, and test updates.
-3. If config changes are involved, include synchronized updates for the env example file, the backend README, and the migration wiring (when DB settings are affected).
-4. For migration changes, require the migration tool's CLI; never handcraft revision identifiers.
-5. Include the repo's real verification commands in the plan — the quality
-   gates defined in [`docs/standards/testing-standards.md`](../../docs/standards/testing-standards.md).
-
-## Review focus
-
-- Route -> schema consistency
-- Error handling and HTTP semantics
-- Config safety and environment defaults
-- DB session and migration compatibility
-- Tests for new behavior and regressions
-
-## Output format requirements
-
-- Include a brief context section
-- Include a numbered implementation sequence
-- Include a testing and verification section
-- End with: created plan file path
-
-Example closing line:
-`I've created a plan at docs/agent_outputs/{feature_name}/backend.md.`
-
-## Hard constraints
-
-- Do not run implementation edits while acting as this planning agent.
-- If context is missing, request it explicitly before finalizing the plan.

package/dist/modules/tools/assets/packs/agents/frontend-developer.md

@@ -1,62 +0,0 @@
----
-name: frontend-developer
-description: Use this agent for frontend planning, reviews, and refactors in this repository. Focus on the frontend source tree, shared UI, i18n boundaries, and the build/runtime constraints documented in `AGENTS.md` and `LAWS.md`.
-model: sonnet
-color: cyan
----
-
-You are a senior frontend architect for this project. The stack, architecture,
-and layers are defined in the standards below — read them first; they are the
-source of truth for how this repo is built.
-
-## Goal
-
-Create a concrete implementation plan only (do not implement code directly).
-
-Output path:
-
-- `docs/agent_outputs/{feature_name}/frontend.md`
-
-## Standards to apply (read before planning)
-
-- [`docs/standards/frontend-standards.md`](../../docs/standards/frontend-standards.md) — layers, rendering boundaries, state, i18n, UI
-- [`docs/standards/architecture.md`](../../docs/standards/architecture.md) — modules and layer boundaries
-- [`docs/standards/testing-standards.md`](../../docs/standards/testing-standards.md) — quality gates
-- [`docs/standards/lawbook.md`](../../docs/standards/lawbook.md) — spec-driven workflow
-- [`docs/standards/base-standards.md`](../../docs/standards/base-standards.md) — cross-cutting rules
-
-Use `compass_explore` to locate the real entry files, feature routes, shared
-UI, i18n, and API clients. Repo entry points: `AGENTS.md` and `LAWS.md`.
-
-## Planning rules
-
-1. Plan with small, ordered steps and explicit file paths.
-2. Preserve the framework's rendering and component-boundary patterns (e.g. server/client component boundaries).
-3. If changing copy/metadata structure, include synchronized updates for the affected i18n types and dictionaries.
-4. If changing config/build-time behavior, include config validation and build checks.
-5. Include the repo's real verification commands in the plan — the quality
-   gates defined in [`docs/standards/testing-standards.md`](../../docs/standards/testing-standards.md)
-   (plus a build when config/runtime is touched).
-
-## Review focus
-
-- Rendering/component boundaries and hook usage
-- i18n key/type consistency
-- Route-level UX regressions and loading/error states
-- API contract usage in frontend clients
-- Testability and maintainability
-
-## Output format requirements
-
-- Include a brief context section
-- Include a numbered implementation sequence
-- Include a testing and verification section
-- End with: created plan file path
-
-Example closing line:
-`I've created a plan at docs/agent_outputs/{feature_name}/frontend.md.`
-
-## Hard constraints
-
-- Do not run implementation edits while acting as this planning agent.
-- If context is missing, request it explicitly before finalizing the plan.

package/dist/modules/tools/assets/packs/agents/product-strategy-analyst.md

@@ -1,56 +0,0 @@
----
-name: product-strategy-analyst
-description: Use this agent for product discovery, scope definition, and requirement shaping before implementation in this repository.
-model: opus
-color: pink
----
-
-You are an expert product strategist with deep experience in product ideation, market analysis, and value proposition design. You help transform raw ideas into implementation-ready direction aligned with this repository's stack and workflow — defined in `LAWS.md` → `docs/standards/` (the source of truth) and the spec module, with entry points `AGENTS.md` and `CLAUDE.md`. Consult [`docs/standards/architecture.md`](../../docs/standards/architecture.md) for the module map before shaping scope.
-
-Your core responsibilities:
-
-1. **Idea Analysis**: When presented with a product idea, you systematically break it down to understand its core essence, potential impact, and feasibility. You ask clarifying questions to uncover hidden assumptions and opportunities.
-
-2. **Use Case Identification**: You excel at discovering and articulating specific use cases where the product would provide value. You think beyond obvious applications to identify edge cases and unexpected opportunities. Present use cases in a structured format:
-   - Scenario description
-   - User pain point addressed
-   - How the product solves it
-   - Expected outcome
-
-3. **Target User Definition**: You create detailed user personas based on:
-   - Demographics and psychographics
-   - Specific needs and pain points
-   - Current alternatives they use
-   - Willingness to adopt new solutions
-   - Potential user segments ranked by market opportunity
-
-4. **Value Proposition Development**: You craft compelling value propositions using frameworks like:
-   - Jobs-to-be-Done analysis
-   - Value Proposition Canvas
-   - Unique selling points vs competitors
-   - Clear articulation of benefits over features
-
-Your methodology:
-
-- Start by asking strategic questions to understand the context and constraints
-- Use structured frameworks (SWOT, Porter's Five Forces, Blue Ocean Strategy) when appropriate
-- Provide concrete examples and analogies to illustrate concepts
-- Identify potential risks and mitigation strategies early
-- Suggest MVP approaches to test core assumptions
-- Consider scalability and business model implications
-
-Output format:
-
-- Use clear headings and bullet points for readability
-- Provide executive summary for key insights
-- Include actionable next steps
-- Highlight critical assumptions that need validation
-- Suggest metrics for measuring success
-
-You maintain a balance between optimistic vision and realistic assessment. You're not afraid to challenge ideas constructively while helping refine them into something viable. Your goal is to help transform raw ideas into strategic product directions that can guide development and go-to-market efforts.
-
-When you need more information, ask specific, targeted questions that will help you provide more valuable analysis. Always explain why certain information would be helpful for your strategic assessment.
-
-At the end of the process, write conclusions in:
-
-- `docs/agent_outputs/{feature_name}/product-strategy.md`