@esneiderbravo/speclaw 0.1.0

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

@@ -0,0 +1,62 @@
+---
+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/spec-workflow.md`](../../docs/standards/spec-workflow.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

@@ -0,0 +1,56 @@
+---
+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`

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

@@ -0,0 +1,6 @@
+{
+  "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/modules/tools/packs.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assetsDir } from "../../shared/paths.js";
+import { copyRendered } from "../../shared/install.js";
+const ASSETS = assetsDir(import.meta.url);
+/**
+ * Load the tool-pack manifest from assets/packs.json.
+ *
+ * @returns A map of pack name to its {@link PackDef}.
+ */
+export function loadPacks() {
+    const raw = fs.readFileSync(path.join(ASSETS, "packs.json"), "utf8");
+    return JSON.parse(raw);
+}
+/**
+ * Install a pack's assets into a project's ai-specs/. A pack contains either
+ * subdirectories (skills/, commands/, rules/) mapped to ai-specs/<sub>, or
+ * loose agent .md files at its root mapped to ai-specs/agents/.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param name - Pack name to install (key in the manifest).
+ * @param vars - Template variables applied while copying the pack's assets.
+ * @param report - Mutated in place with the copy results.
+ * @throws If no pack with the given name exists in the manifest.
+ */
+export function installPack(projectPath, name, vars, report) {
+    const packs = loadPacks();
+    const def = packs[name];
+    if (!def) {
+        throw new Error(`Unknown pack "${name}". Available: ${Object.keys(packs).join(", ")}`);
+    }
+    const packRoot = path.join(ASSETS, "packs", def.path);
+    const aiSpecs = path.join(projectPath, "ai-specs");
+    for (const sub of fs.readdirSync(packRoot, { withFileTypes: true })) {
+        if (sub.isDirectory()) {
+            copyRendered(path.join(packRoot, sub.name), path.join(aiSpecs, sub.name), vars, report);
+        }
+        else if (sub.name.endsWith(".md")) {
+            // loose .md at pack root = agent definitions
+            copyRendered(packRoot, path.join(aiSpecs, "agents"), vars, report);
+            break;
+        }
+    }
+}

package/dist/modules/tools/register.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { text } from "../../shared/mcp.js";
+import { emptyReport } from "../../shared/install.js";
+import { refreshAgents } from "../../shared/agents.js";
+import { loadPacks, installPack } from "./packs.js";
+export { loadPacks, installPack };
+// ─── The tools module: opt-in packs of skills, agents, and commands ───
+/** Register the tools-module MCP tools (list_packs, add_pack). */
+export function registerTools(server) {
+    server.registerTool("list_packs", {
+        description: "List the available speclaw skill packs and what each contains.",
+        inputSchema: {},
+    }, async () => text(loadPacks()));
+    server.registerTool("add_pack", {
+        description: "Add a single pack to an already-initialized project, then refresh IDE symlinks. Pass template vars (organization, ticket_prefix, team_language, ...) if the pack needs them.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            pack: z.string().describe("Pack name (see list_packs)"),
+            vars: z.record(z.string()).optional().describe("Template variables for rendering"),
+        },
+    }, async ({ projectPath, pack, vars }) => {
+        const report = emptyReport();
+        installPack(projectPath, pack, vars ?? {}, report);
+        refreshAgents(projectPath, report); // link the new content into already-configured agents
+        return text(report);
+    });
+}

package/dist/server.js

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerCompass } from "./modules/compass/register.js";
+import { registerSpec } from "./modules/spec/register.js";
+import { registerFoundation } from "./modules/foundation/register.js";
+import { registerTools } from "./modules/tools/register.js";
+/** Build the speclaw MCP server with every module's tools registered. */
+export function buildServer() {
+    const server = new McpServer({ name: "speclaw", version: "0.1.0" });
+    // Each module contributes its own MCP tools. Adding a module = one line here.
+    registerFoundation(server); // init_project, scaffold, configure_agent, doctor
+    registerSpec(server); // spec_init, spec_validate, spec_sync, spec_archive, spec_list
+    registerCompass(server); // compass_index, explore, search, recall, impact, trace, watch
+    registerTools(server); // list_packs, add_pack
+    return server;
+}
+/** Start the MCP server over stdio (used by `speclaw mcp`). */
+export async function startMcpServer() {
+    const server = buildServer();
+    await server.connect(new StdioServerTransport());
+}

package/dist/shared/agents.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+/** 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"] },
+];
+/**
+ * Look up a known agent definition by its id.
+ *
+ * @param id - The agent identifier (e.g. `"claude"`, `"cursor"`).
+ * @returns The matching {@link AgentDef}, or `undefined` if no agent has that id.
+ */
+export function agentById(id) {
+    return AGENTS.find((a) => a.id === id);
+}
+const MCP_ENTRY = { type: "stdio", command: "npx", args: ["-y", "@esneiderbravo/speclaw", "mcp"] };
+/** True when `p` exists as a filesystem entry (including a symlink), without following it. */
+function isSymlink(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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) {
+    const mcpPath = path.join(projectPath, mcpFile);
+    let config = {};
+    if (fs.existsSync(mcpPath))
+        config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+    config.mcpServers = config.mcpServers ?? {};
+    if (config.mcpServers["speclaw"]) {
+        report.skipped.push(`${mcpPath} (speclaw already registered)`);
+        return;
+    }
+    config.mcpServers["speclaw"] = { ...MCP_ENTRY };
+    fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
+    fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
+    report.written.push(`${mcpPath} (speclaw MCP server)`);
+}
+/**
+ * Configure one agent: create its symlinks into ai-specs and register the MCP server.
+ *
+ * @param projectPath - Project root to configure.
+ * @param agentId - Id of a known agent (see {@link AGENTS}).
+ * @param report - Report mutated in place with created symlinks and written/skipped paths.
+ * @throws Error if `agentId` does not match any known agent.
+ */
+export function configureAgent(projectPath, agentId, report) {
+    const agent = agentById(agentId);
+    if (!agent)
+        throw new Error(`Unknown agent "${agentId}". Known: ${AGENTS.map((a) => a.id).join(", ")}`);
+    const ideRoot = path.join(projectPath, agent.ideDir);
+    for (const target of agent.linkTargets) {
+        const sourceDir = path.join(projectPath, "ai-specs", target);
+        if (!fs.existsSync(sourceDir))
+            continue;
+        fs.mkdirSync(ideRoot, { recursive: true });
+        const linkPath = path.join(ideRoot, target);
+        if (fs.existsSync(linkPath) || isSymlink(linkPath)) {
+            report.skipped.push(linkPath);
+            continue;
+        }
+        fs.symlinkSync(path.join("..", "ai-specs", target), linkPath);
+        report.symlinks.push(`${linkPath} -> ../ai-specs/${target}`);
+    }
+    if (agent.mcpFile)
+        writeMcpConfig(projectPath, agent.mcpFile, report);
+}
+/**
+ * List the agents already set up in this project (their IDE dir exists).
+ *
+ * @param projectPath - Project root to inspect.
+ * @returns The ids of agents whose IDE directory is present.
+ */
+export function detectConfiguredAgents(projectPath) {
+    return AGENTS.filter((a) => fs.existsSync(path.join(projectPath, a.ideDir))).map((a) => a.id);
+}
+/**
+ * Re-run configuration for every already-configured agent (e.g. after adding a pack).
+ *
+ * @param projectPath - Project root whose configured agents should be refreshed.
+ * @param report - Report mutated in place across all refreshed agents.
+ */
+export function refreshAgents(projectPath, report) {
+    for (const id of detectConfiguredAgents(projectPath))
+        configureAgent(projectPath, id, report);
+}

package/dist/shared/install.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { render } from "./render.js";
+/** Create a fresh, empty {@link InstallReport} to accumulate results into. */
+export function emptyReport() {
+    return { written: [], skipped: [], symlinks: [], unresolvedVars: [] };
+}
+/**
+ * Recursively copy a source tree into a destination, rendering {{var}}
+ * placeholders in .md/.mdc files and copying everything else verbatim. Existing
+ * destination files are never overwritten (recorded as skipped).
+ *
+ * @param srcDir - Source directory tree to copy from.
+ * @param destDir - Destination directory (created if missing).
+ * @param vars - Placeholder values used to render `.md`/`.mdc` files.
+ * @param report - Report mutated in place with written, skipped, and unresolved-var entries.
+ */
+export function copyRendered(srcDir, destDir, vars, report) {
+    fs.mkdirSync(destDir, { recursive: true });
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const src = path.join(srcDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyRendered(src, dest, vars, report);
+            continue;
+        }
+        if (fs.existsSync(dest)) {
+            report.skipped.push(dest);
+            continue;
+        }
+        if (entry.name.endsWith(".md") || entry.name.endsWith(".mdc")) {
+            const { output, unresolved } = render(fs.readFileSync(src, "utf8"), vars);
+            unresolved.forEach((v) => {
+                if (!report.unresolvedVars.includes(v))
+                    report.unresolvedVars.push(v);
+            });
+            fs.writeFileSync(dest, output);
+        }
+        else {
+            fs.copyFileSync(src, dest);
+        }
+        report.written.push(dest);
+    }
+}
+/**
+ * Append an entry to the project's .gitignore if not already present.
+ *
+ * @param projectPath - Project root containing (or receiving) the `.gitignore`.
+ * @param entry - The ignore pattern to ensure is present.
+ * @param comment - Comment line written above the entry when it is added.
+ * @param report - Report mutated in place; the appended entry is recorded under `written`.
+ */
+export function ensureGitignore(projectPath, entry, comment, report) {
+    const gitignorePath = path.join(projectPath, ".gitignore");
+    let content = "";
+    if (fs.existsSync(gitignorePath)) {
+        content = fs.readFileSync(gitignorePath, "utf8");
+        if (content.split(/\r?\n/).some((l) => l.trim() === entry))
+            return;
+        if (!content.endsWith("\n"))
+            content += "\n";
+    }
+    content += `\n# ${comment}\n${entry}\n`;
+    fs.writeFileSync(gitignorePath, content);
+    report.written.push(`${gitignorePath} (${entry})`);
+}

package/dist/shared/mcp.js

@@ -0,0 +1,16 @@
+/**
+ * Wrap a value as an MCP text tool-result.
+ *
+ * @param value - Payload to return; strings are emitted verbatim, other values are pretty-printed as JSON.
+ * @returns An MCP result object with a single text content block.
+ */
+export function text(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}

package/dist/shared/paths.js

@@ -0,0 +1,10 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+/**
+ * The `assets/` directory that sits next to a compiled module file. Each module
+ * calls this with its own `import.meta.url` to locate its bundled markdown/data
+ * (copied into dist/ by the build's copy-assets step).
+ */
+export function assetsDir(importMetaUrl) {
+    return path.join(path.dirname(fileURLToPath(importMetaUrl)), "assets");
+}

package/dist/shared/render.js

@@ -0,0 +1,21 @@
+const VAR_RE = /\{\{([a-z_]+)\}\}/g;
+/**
+ * Replace {{var}} placeholders with values from `vars`. Unknown placeholders
+ * are left untouched and reported so the agent can fill them in later.
+ *
+ * @param content - Template text containing `{{name}}` placeholders.
+ * @param vars - Lookup of placeholder names to values; `undefined` values are treated as unresolved.
+ * @returns The rendered output alongside the set of placeholder names that could not be resolved.
+ */
+export function render(content, vars) {
+    const unresolved = new Set();
+    const output = content.replace(VAR_RE, (match, name) => {
+        const value = vars[name];
+        if (value === undefined) {
+            unresolved.add(name);
+            return match;
+        }
+        return value;
+    });
+    return { output, unresolved };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@esneiderbravo/speclaw",
+  "version": "0.1.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 workflow (Spec), and opt-in skill packs (Tools). No external CLIs, no LLM to install.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "spec-driven-development",
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "code-graph",
+    "skills"
+  ],
+  "author": "Esneider Bravo",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "speclaw": "dist/cli/index.js"
+  },
+  "main": "dist/server.js",
+  "files": [
+    "dist",
+    "ATTRIBUTION.md"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "start": "node dist/cli/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "picocolors": "^1.1.1",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.25.10",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}