@esneiderbravo/speclaw 0.1.0

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

@@ -0,0 +1,36 @@
+# Architecture — {{project_name}}
+
+The structural law of the project. Every change respects these boundaries —
+see [`../../LAWS.md`](../../LAWS.md). Use `compass_explore` to navigate the
+real code before editing.
+
+- **Overall shape**: {{architecture}}
+- **Stack**: {{stack_summary}}
+
+## Modules / bounded contexts
+
+<!-- speclaw init: list the real modules/bounded contexts of this repo, each
+with a one-line responsibility. Derive them from the actual directory layout
+(e.g. src/modules/*, apps/*), never invent them. Example:
+
+| Module | Responsibility |
+|--------|----------------|
+| planning | assignment engine, coverage, scheduling |
+| workforce | employees, skills, availability |
+-->
+{{modules_table}}
+
+## Layering
+
+<!-- speclaw init: describe the layers and their allowed dependencies, per the
+repo's real architecture. Keep the "strictly enforced" tone. Example for a
+hexagonal backend: Routes -> Controller -> Manager -> Domain, with the rules
+about what each layer may and may not do. -->
+{{layering_rules}}
+
+## Cross-boundary rules
+
+- Dependencies point inward: outer layers depend on inner, never the reverse.
+- Business logic never leaks into transport (HTTP handlers) or persistence.
+- A change that crosses a module boundary needs a spec change describing
+  the new contract.

package/dist/modules/foundation/assets/docs/standards/backend-standards.template.md

@@ -0,0 +1,50 @@
+# Backend Standards — {{project_name}}
+
+Rules for backend code. A law of the project — see [`../../LAWS.md`](../../LAWS.md).
+Architecture and layer boundaries: [`architecture.md`](architecture.md).
+
+## Layering — strictly enforced
+
+<!-- speclaw init: fill the layer table from the repo's real backend structure.
+Example (FastAPI):
+
+| Layer | File | Responsibility |
+|-------|------|----------------|
+| Routes | router.py | HTTP + schema validation. No business logic. |
+| Controller | controller.py | Business logic, use-case orchestration. |
+| Manager | manager.py | Data access, transactions. |
+| Domain | domain/ | Pure entities and rules. No I/O. |
+-->
+{{backend_layers}}
+
+- Never write business logic in the transport/routes layer.
+- Never write data-access code in the business layer.
+
+## Formatting & linting
+
+- Use the repo's configured linter/formatter. Run before committing.
+- Lint / type-check command: `{{lint_commands}}`
+
+## Docstrings — mandatory
+
+Required on every public module, class, and function/method, in the repo's
+documented style (e.g. Google-style `Args:`/`Returns:`/`Raises:` for Python).
+Write them as you code, not afterward. Dunder and test functions are exempt.
+Docstrings describe what and why — never ticket text.
+
+## Typing
+
+- Full signatures (arguments + return types) on public functions.
+- Code must pass the repo's type-checker in strict mode.
+
+## Tests
+
+- New behavior ships with tests. Tests mock external systems (DB, network) via
+  the project's fixtures — never hit a real database in unit tests.
+- Test command: `{{test_commands}}`
+
+## Migrations
+
+- Use the migration tool's CLI; never handcraft revision identifiers.
+- Keep a single linear head; rebase when the base branch moved.
+- Schema changes must match what the spec proposal declared.

package/dist/modules/foundation/assets/docs/standards/base-standards.template.md

@@ -0,0 +1,47 @@
+# Base Standards — {{project_name}}
+
+Cross-cutting rules that apply to **all** code in this repository, regardless
+of layer or language. This is a law of the project — see [`../../LAWS.md`](../../LAWS.md).
+
+## Languages
+
+- **Code, identifiers, comments, docstrings, commit messages, PR titles/bodies,
+  and technical docs**: the repo's artifact language (default English).
+- **User-facing product copy**: as the product requires.
+- **Agent ↔ human communication** (review comments, thread replies, ticket
+  bodies): the team's working language ({{team_language}}). Technical terms
+  stay in English within that prose — don't force-translate them.
+
+## Commits & branches
+
+- **Branch naming**: `{{branch_pattern}}`
+- **Commit style**: {{commit_style}}
+- One focused change per branch; the smallest correct diff. No drive-by
+  refactors mixed into a feature branch.
+
+## Comments & documentation
+
+- Comments state **constraints the code cannot express** (invariants, tricky
+  edge cases, "why"). They never narrate history, restate the next line, or
+  address the reviewer.
+- **Never** put ticket IDs, ticket text, or changelog narration
+  ("added for {{ticket_prefix}}-123", "fixed as part of…") in code or
+  docstrings. Traceability lives in the branch name, PR, and git history.
+
+## Dependencies
+
+- Any new dependency must be justified in the PR description. Unannounced
+  dependencies are a blocking finding.
+- Prefer the standard library and existing project utilities before adding a
+  package.
+
+## Engineering principles
+
+- Code reads like its neighbors (naming, structure, idioms).
+- Report outcomes faithfully: if a gate fails, say so with the output; never
+  claim a success you did not observe.
+- Ask before irreversible or outward-facing actions (destructive commands,
+  publishing reviews/tickets/comments).
+
+<!-- speclaw init: add any project-specific base rules the analysis surfaced. -->
+{{base_standards_extra}}

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

@@ -0,0 +1,31 @@
+# Conventions — {{project_name}}
+
+Naming, branching, PR, and tracking conventions. A law of the project — see
+[`../../LAWS.md`](../../LAWS.md).
+
+## Branches
+
+- Pattern: `{{branch_pattern}}`
+- Branches without a tracker ticket reference must not be merged (except
+  explicitly scoped chores).
+
+## Pull requests
+
+- Title and body in the repo's artifact language, following the PR template.
+- The body references the tracker ticket ({{ticket_prefix}}-N) so it links.
+- The ticket lives in the PR title/body only — never in the code.
+- CI must be green before requesting review.
+
+## Tracker
+
+- Ticket prefix: `{{ticket_prefix}}`
+- New behavior, endpoints, schema changes, or UI flows get a ticket and a
+  spec change; one-line fixes need not.
+- Ticket ↔ PR traceability is mandatory: closing a ticket attaches its PR
+  (see the `close-ticket` skill).
+
+## Versioning & releases
+
+<!-- speclaw init: describe the repo's versioning/release convention if it has
+one (semver tags, changelog, release branches). Otherwise leave a short note. -->
+{{versioning_rules}}

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

@@ -0,0 +1,50 @@
+# Documentation Standard — {{project_name}}
+
+The docstring/API-comment law of the project — see [`../../LAWS.md`](../../LAWS.md).
+One consistent convention per language, so every public API reads the same way.
+Comment *philosophy* (what a comment is for) lives in
+[`base-standards.md`](base-standards.md); this file defines the *format*.
+
+## Convention per language
+
+Defaults below are the idiomatic choice per language. During standardization,
+confirm each against what this repo actually uses and adjust if the team
+follows a different one (e.g. NumPy-style Python).
+
+| Language | Convention | Required sections |
+|----------|------------|-------------------|
+| Python | Google-style (PEP 257 base) | `Args:` · `Returns:` · `Raises:` |
+| TypeScript / JavaScript | TSDoc (superset of JSDoc) | `@param` · `@returns` · `@throws` · `@remarks` |
+| Java | Javadoc | `@param` · `@return` · `@throws` |
+| Kotlin | KDoc | `@param` · `@return` · `@throws` |
+| Go | godoc | full-sentence comment beginning with the identifier name; no tags |
+| Rust | rustdoc (`///`, markdown) | `# Examples` · `# Errors` · `# Panics` (when applicable) |
+| C# | XML doc comments | `<summary>` · `<param>` · `<returns>` |
+| Ruby | YARD | `@param` · `@return` |
+| PHP | PHPDoc | `@param` · `@return` · `@throws` |
+| Swift | Swift markup | `- Parameters:` · `- Returns:` · `- Throws:` |
+
+<!-- speclaw init: keep only the rows for languages this repo uses, and confirm
+the chosen convention matches the codebase. Add the actual style config file if
+the repo enforces one (e.g. a docstring linter). -->
+{{documentation_extra}}
+
+## Rules
+
+- **Required on every public API**: exported/public modules, classes,
+  functions, and methods. Internal helpers get a docstring when their intent
+  isn't obvious from the name.
+- **Write them as you code**, not afterward — a new or changed public symbol is
+  not done until it is documented.
+- **Describe intent and contract** (what and why, inputs/outputs, errors), not
+  a restatement of the syntax. No ticket text, no changelog narration.
+- **Exempt**: trivial dunders/accessors and test functions, unless they carry
+  non-obvious behavior.
+- **One style per language** — never mix conventions within the same language
+  in the repo.
+
+## Enforcement
+
+Prefer a docstring linter in the quality gates when the language has one
+(e.g. `ruff`'s pydocstyle rules for Python, `eslint-plugin-jsdoc` for TS/JS).
+List the concrete command in [`testing-standards.md`](testing-standards.md).

package/dist/modules/foundation/assets/docs/standards/frontend-standards.template.md

@@ -0,0 +1,46 @@
+# Frontend Standards — {{project_name}}
+
+Rules for frontend code. A law of the project — see [`../../LAWS.md`](../../LAWS.md).
+Architecture and layer boundaries: [`architecture.md`](architecture.md).
+
+## Layering — strictly enforced
+
+<!-- speclaw init: fill from the repo's real frontend structure. Example
+(hexagonal / vertical slices):
+
+| Layer | Location | Responsibility |
+|-------|----------|----------------|
+| Domain | domain/ | Pure entities, ports. No framework, no I/O. |
+| Application | application/use-cases/ | Orchestrate domain via ports. |
+| Infrastructure | infrastructure/ | HTTP, storage, providers. |
+| Presentation | presentation/ | Screens/components. No business logic, no I/O. |
+-->
+{{frontend_layers}}
+
+- Route entry files stay thin — they delegate to a screen/component.
+- Presentation never calls the network or storage directly; it goes through
+  the application layer.
+
+## Rendering & component boundaries
+
+- Respect the framework's server/client boundary rules.
+- Keep side effects and data fetching at the correct layer, not inside
+  presentational components.
+
+## State & data
+
+- Data access goes through typed clients/repositories, not ad-hoc fetches
+  scattered in components.
+- Follow the repo's BFF / API-access rule (browser calls same-origin routes
+  when the project uses a BFF).
+
+## i18n & UI
+
+- User-visible copy goes through the i18n layer; keep keys and types in sync.
+- Use the project's design system components and tokens — no hardcoded colors
+  when a token exists.
+
+## Formatting, linting, docs
+
+- TSDoc on exported functions and components (no ticket text).
+- Lint / type-check command: `{{lint_commands}}`

package/dist/modules/foundation/assets/docs/standards/spec-workflow.template.md

@@ -0,0 +1,46 @@
+# Spec Workflow — {{project_name}}
+
+The process law of the project — see [`../../LAWS.md`](../../LAWS.md). This
+repo is spec-driven through speclaw's **spec** module (no external CLI; the
+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 `spec/changes/<name>/`: `proposal.md`, delta specs under
+   `specs/<capability>/spec.md`, optional `design.md`, and `tasks.md`.
+3. **build** — implement the tasks in order, keeping code and spec in
+   agreement.
+4. **sync** — promote the change's delta specs into the canonical
+   `spec/specs/` (`spec_sync`).
+5. **archive** — finalize: sync + move the change to `spec/changes/archive/`
+   (`spec_archive`), **within the same PR** — never a post-merge chore.
+
+## Mandatory task steps
+
+`tasks.md` MUST include the steps defined in `spec/config.yaml` and the
+`spec-tasks-mandatory-steps` rule: feature branch first, tests reviewed and
+run, manual verification executed by the agent, docs updated, archive within
+the PR. The agent performs the manual testing itself — never delegates it.
+
+## Delta specs
+
+- Normative requirements use SHALL/MUST.
+- Requirement headers use `### Requirement:`.
+- Scenario headers use exactly `#### Scenario:`.
+- Acceptance criteria are testable without production integrations.
+- The implemented code must match what the delta spec promises. Validate with
+  the `spec_validate` tool before syncing or archiving.
+
+## Archiving discipline
+
+Always archive with the `archive` command / `spec_archive` tool, never a manual
+`mv` — the tool performs the spec promotion and validation a manual move skips.
+
+## Amendments to the law
+
+The standards in `docs/standards/` are amended like code: through a spec change
+reviewed by a human. An agent may propose an amendment; it may never silently
+ignore a standard.

package/dist/modules/foundation/assets/docs/standards/testing-standards.template.md

@@ -0,0 +1,34 @@
+# Testing & Quality Gates — {{project_name}}
+
+The quality law of the project — see [`../../LAWS.md`](../../LAWS.md). These
+gates are non-negotiable: an agent runs them itself and reports real output
+before declaring anything done.
+
+## Gates
+
+- **Tests**: `{{test_commands}}`
+- **Lint / type-check**: `{{lint_commands}}`
+
+A red gate blocks the task. Fix it or report it — never work around it by
+suppressing a linter or deleting a test.
+
+## What must be tested
+
+- Every new behavior ships with tests covering the happy path and at least one
+  edge/error case.
+- Bug fixes ship with a regression test that fails before the fix.
+- Permission/authorization paths are tested when the change touches them.
+
+## Test hygiene
+
+- Unit tests are deterministic and isolated — mock external systems via the
+  project's fixtures; never depend on a live database or network.
+- A test "fixed" by weakening its assertion is not fixed.
+
+## Manual & end-to-end verification
+
+- When a change affects runtime behavior and it's feasible, verify it works by
+  exercising the endpoint/UI — don't assume green CI covers everything.
+- The mandatory spec task steps
+  ([`spec-workflow.md`](spec-workflow.md)) define which manual checks
+  the agent must execute itself.

package/dist/modules/foundation/doctor.js

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AGENTS, detectConfiguredAgents } from "../../shared/agents.js";
+/**
+ * Run the speclaw installation health checks against a project: ai-specs and
+ * LAWS.md presence, agent contracts, the docs/standards set, per-agent IDE
+ * symlink health, the spec/ workflow, the Compass index, and .mcp.json wiring.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns One {@link Check} per verified item, each carrying a remediation hint.
+ */
+export function doctor(projectPath) {
+    const checks = [];
+    const has = (rel) => fs.existsSync(path.join(projectPath, rel));
+    checks.push({
+        name: "ai-specs directory",
+        ok: has("ai-specs"),
+        detail: has("ai-specs")
+            ? "present"
+            : "missing — run the scaffold tool first",
+    });
+    checks.push({
+        name: "LAWS.md constitution",
+        ok: has("LAWS.md"),
+        detail: has("LAWS.md") ? "present" : "missing — the project has no law",
+    });
+    for (const entry of ["CLAUDE.md", "AGENTS.md", "docs/compass.md"]) {
+        checks.push({
+            name: `${entry} agent contract`,
+            ok: has(entry),
+            detail: has(entry) ? "present" : "missing — scaffold writes it",
+        });
+    }
+    const standards = [
+        "base-standards",
+        "architecture",
+        "backend-standards",
+        "frontend-standards",
+        "testing-standards",
+        "documentation",
+        "conventions",
+        "spec-workflow",
+    ];
+    const missingStandards = standards.filter((s) => !has(path.join("docs/standards", `${s}.md`)));
+    checks.push({
+        name: "docs/standards/*",
+        ok: missingStandards.length === 0,
+        detail: missingStandards.length === 0
+            ? `all ${standards.length} standards present`
+            : `missing: ${missingStandards.join(", ")}`,
+    });
+    // Only check the agents the user actually configured — selection is opt-in.
+    const configured = AGENTS.filter((a) => detectConfiguredAgents(projectPath).includes(a.id));
+    if (configured.length === 0) {
+        checks.push({
+            name: "agents",
+            ok: false,
+            detail: "none configured — run `speclaw init` or `speclaw agent add <id>`",
+        });
+    }
+    for (const agent of configured) {
+        for (const target of agent.linkTargets) {
+            // only demand links for content that actually exists in ai-specs/
+            if (!has(path.join("ai-specs", target)))
+                continue;
+            const ideDir = agent.ideDir;
+            const linkPath = path.join(projectPath, ideDir, target);
+            let ok = false;
+            let detail = "missing";
+            try {
+                const stat = fs.lstatSync(linkPath);
+                if (stat.isSymbolicLink()) {
+                    ok = fs.existsSync(linkPath); // broken symlink -> false
+                    detail = ok ? `-> ${fs.readlinkSync(linkPath)}` : "broken symlink";
+                }
+                else {
+                    ok = true;
+                    detail = "real directory (not a symlink — consider migrating to ai-specs)";
+                }
+            }
+            catch {
+                // stays missing
+            }
+            checks.push({ name: `${ideDir}/${target}`, ok, detail });
+        }
+    }
+    checks.push({
+        name: "spec workflow",
+        ok: has("spec"),
+        detail: has("spec")
+            ? "spec/ present"
+            : "missing — run the `spec_init` tool",
+    });
+    checks.push({
+        name: "Compass index",
+        ok: has(".speclaw/index.db"),
+        detail: has(".speclaw/index.db")
+            ? ".speclaw/index.db present"
+            : "missing — run the `compass_index` tool",
+    });
+    checks.push({
+        name: ".mcp.json wiring",
+        ok: has(".mcp.json"),
+        detail: has(".mcp.json") ? "present" : "missing — scaffold writes it",
+    });
+    return checks;
+}

package/dist/modules/foundation/register.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { text } from "../../shared/mcp.js";
+import { scaffold } from "./scaffold.js";
+import { doctor } from "./doctor.js";
+import { loadPacks } from "../tools/packs.js";
+import { AGENTS, configureAgent } from "../../shared/agents.js";
+import { emptyReport } from "../../shared/install.js";
+const profileShape = {
+    project_name: z.string().describe("Short project name, e.g. the repo name"),
+    project_description: z.string().optional().describe("One-line description of what the project does"),
+    organization: z.string().optional().describe("Company/team name"),
+    stack_summary: z.string().optional().describe("e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'"),
+    architecture: z.string().optional().describe("e.g. 'hexagonal architecture with bounded contexts'"),
+    test_commands: z.string().optional().describe("Real commands, e.g. 'pytest backend/tests && npm run test'"),
+    lint_commands: z.string().optional().describe("Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'"),
+    branch_pattern: z.string().optional().describe("e.g. 'feature/<ticket-id>-<slug>'"),
+    commit_style: z.string().optional().describe("e.g. 'conventional commits, imperative, English'"),
+    custom_laws: z.string().optional().describe("Extra markdown appended to LAWS.md — project-specific binding rules the analysis surfaced"),
+    ticket_prefix: z.string().optional().describe("Ticket prefix in the team's tracker, e.g. 'FAR'"),
+    team_language: z.string().optional().describe("The team's working language for posted communication (reviews, replies, tickets), e.g. 'Spanish'. Repo artifacts stay in the repo's own language. Defaults to English."),
+    compass_hints: z.string().optional().describe("Markdown bullets with the repo's real entrypoints and common traces, inserted into docs/compass.md"),
+    base_standards_extra: z.string().optional().describe("Markdown with any project-specific cross-cutting rules, appended to docs/standards/base-standards.md"),
+    modules_table: z.string().optional().describe("Markdown table of the repo's real modules/bounded contexts + one-line responsibility, for docs/standards/architecture.md"),
+    layering_rules: z.string().optional().describe("Markdown describing the layers and their allowed dependencies, for docs/standards/architecture.md"),
+    backend_layers: z.string().optional().describe("Markdown layer table (Layer | File | Responsibility) from the real backend, for docs/standards/backend-standards.md"),
+    frontend_layers: z.string().optional().describe("Markdown layer table from the real frontend, for docs/standards/frontend-standards.md"),
+    versioning_rules: z.string().optional().describe("The repo's versioning/release convention, for docs/standards/conventions.md"),
+    documentation_extra: z.string().optional().describe("Repo-specific docstring notes (keep only the languages used, the enforced linter), appended to docs/standards/documentation.md"),
+};
+// ─── The foundation module: analyze the repo, then write the constitution ───
+/** Register the foundation MCP tools (init_project, scaffold, configure_agent, doctor). */
+export function registerFoundation(server) {
+    server.registerTool("init_project", {
+        description: "START HERE to initialize speclaw in a project. Returns the analysis questionnaire the agent must answer by reading the target repo, plus the available skill packs. Do NOT guess answers — investigate the codebase (package.json, pyproject.toml, CI config, existing docs) and confirm the pack selection with the user before calling scaffold.",
+        inputSchema: { projectPath: z.string().describe("Absolute path to the project to initialize") },
+    }, async () => {
+        const packs = loadPacks();
+        return text({
+            instructions: [
+                "1. Analyze the repository at projectPath and fill in every profile field below with REAL values from the codebase (read package.json / pyproject.toml / CI configs / README — do not invent).",
+                "2. The foundation is a set of GRANULAR standards under docs/standards/ (base, architecture, backend, frontend, testing, conventions, spec-workflow), bound by LAWS.md and referenced from CLAUDE.md/AGENTS.md. Fill their structured fields from the real repo: modules_table and layering_rules (architecture), backend_layers, frontend_layers, versioning_rules, and any base_standards_extra. Omit a field only when that standard genuinely doesn't apply to this stack.",
+                "3. Suggest packs: add stack packs whose 'detect' hints match dependencies you found; offer the rest. Ask the user which packs to install (the spec workflow is always installed).",
+                "4. If the 'workflow' pack is selected, ask the user for their tracker's ticket prefix and team working language.",
+                "5. Draft any custom_laws (extra binding rules for LAWS.md) from conventions you observed that the standard set doesn't cover.",
+                "6. Call the 'scaffold' tool with { projectPath, profile, packs }.",
+                "7. Follow the nextSteps returned by scaffold: complete the HTML-comment sections still left in docs/standards/*, then run the spec_init and compass_index tools (both built into speclaw — no external installs).",
+            ],
+            profileFields: Object.fromEntries(Object.entries(profileShape).map(([key, schema]) => [key, schema.description ?? ""])),
+            packs,
+        });
+    });
+    server.registerTool("scaffold", {
+        description: "Write the speclaw setup into a project: the foundation (LAWS.md constitution + granular docs/standards/* + CLAUDE.md + AGENTS.md + docs/compass.md), the spec workflow (always), the selected tool packs, multi-IDE symlinks (.claude/.cursor/.codex/.agents), .mcp.json wiring for speclaw, and .gitignore for .speclaw/. Never overwrites existing files. Call init_project first.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            profile: z.object(profileShape).describe("Project profile gathered by analyzing the repo"),
+            packs: z.array(z.string()).describe("Optional tool pack names (quality, workflow, agents)"),
+            agents: z.array(z.string()).optional().describe(`Agent ids to configure (symlinks + MCP): ${AGENTS.map((a) => a.id).join(", ")}. Usually the CLI handles this; omit to write content only.`),
+        },
+    }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
+    server.registerTool("configure_agent", {
+        description: "Configure one agent's integration in an already-scaffolded project: create its IDE symlinks into ai-specs and register the speclaw MCP server in its config. Re-runnable; add agents one at a time.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            agent: z.enum(AGENTS.map((a) => a.id)).describe("Agent id to configure"),
+        },
+    }, async ({ projectPath, agent }) => {
+        const report = emptyReport();
+        configureAgent(projectPath, agent, report);
+        return text(report);
+    });
+    server.registerTool("doctor", {
+        description: "Verify a speclaw installation: ai-specs presence, the foundation (LAWS.md + standards + agent contracts), IDE symlinks health, the spec/ workflow, the Compass index, and .mcp.json wiring. Returns a checklist with remediation hints.",
+        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
+    }, async ({ projectPath }) => {
+        const checks = doctor(projectPath);
+        const failed = checks.filter((c) => !c.ok);
+        return text({
+            healthy: failed.length === 0,
+            checks,
+            summary: failed.length === 0
+                ? "Everything is within the law."
+                : `${failed.length} check(s) failed — see details.`,
+        });
+    });
+}

package/dist/modules/foundation/scaffold.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assetsDir } from "../../shared/paths.js";
+import { render } from "../../shared/render.js";
+import { emptyReport, ensureGitignore } from "../../shared/install.js";
+import { configureAgent } from "../../shared/agents.js";
+import { installWorkflow } from "../spec/register.js";
+import { installPack, loadPacks } from "../tools/packs.js";
+const ASSETS = assetsDir(import.meta.url);
+// Every {{var}} the foundation templates may reference. Ones the agent didn't
+// provide default to empty so a bare `scaffold` never leaves a raw {{tag}}.
+const FOUNDATION_DEFAULTS = {
+    custom_laws: "",
+    compass_hints: "",
+    base_standards_extra: "",
+    modules_table: "",
+    layering_rules: "",
+    backend_layers: "",
+    frontend_layers: "",
+    versioning_rules: "",
+    documentation_extra: "",
+    team_language: "English",
+};
+/**
+ * Render the foundation: walk the module's assets/, mirror its structure into
+ * the project, stripping the `.template` marker (foo.template.md -> foo.md).
+ * Directory-driven — adding a standard is dropping a file, no code change.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param vars - Template variables substituted into each `.template.md`.
+ * @param report - Mutated in place with written/skipped paths and any
+ *   unresolved template variables. Existing destination files are skipped.
+ */
+function renderFoundation(projectPath, vars, report) {
+    const walk = (relDir) => {
+        for (const entry of fs.readdirSync(path.join(ASSETS, relDir), { withFileTypes: true })) {
+            const rel = path.join(relDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(rel);
+                continue;
+            }
+            if (!entry.name.endsWith(".template.md"))
+                continue;
+            const destPath = path.join(projectPath, rel.replace(/\.template\.md$/, ".md"));
+            if (fs.existsSync(destPath)) {
+                report.skipped.push(destPath);
+                continue;
+            }
+            const { output, unresolved } = render(fs.readFileSync(path.join(ASSETS, rel), "utf8"), vars);
+            unresolved.forEach((v) => {
+                if (!report.unresolvedVars.includes(v))
+                    report.unresolvedVars.push(v);
+            });
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.writeFileSync(destPath, output);
+            report.written.push(destPath);
+        }
+    };
+    walk(".");
+}
+/**
+ * Write the speclaw content into a project: the foundation (constitution +
+ * standards), the spec workflow (always), the selected tool packs, .gitignore,
+ * and — for each agent id passed — that agent's symlinks + MCP config. Agent
+ * selection is what the CLI drives interactively; omit it to write content only.
+ * Never overwrites existing files.
+ *
+ * @param projectPath - Absolute path to an existing project root.
+ * @param profile - Project identity and conventions for template rendering.
+ * @param packNames - Tool pack names to install (the spec workflow is always installed).
+ * @param agents - Agent ids to configure with symlinks + MCP; empty writes content only.
+ * @returns The install report augmented with the ordered next steps to run.
+ * @throws If `projectPath` does not exist, or any pack name is unknown.
+ */
+export function scaffold(projectPath, profile, packNames, agents = []) {
+    if (!fs.existsSync(projectPath)) {
+        throw new Error(`projectPath does not exist: ${projectPath}`);
+    }
+    const packs = loadPacks();
+    const unknown = packNames.filter((n) => !packs[n]);
+    if (unknown.length)
+        throw new Error(`Unknown packs: ${unknown.join(", ")}`);
+    const report = { ...emptyReport(), nextSteps: [] };
+    const vars = { ...FOUNDATION_DEFAULTS, ...profile };
+    renderFoundation(projectPath, vars, report);
+    installWorkflow(projectPath, vars, report); // spec module — always
+    for (const name of packNames)
+        installPack(projectPath, name, vars, report); // tools module
+    ensureGitignore(projectPath, ".speclaw/", "speclaw local code Compass (never commit)", report);
+    for (const id of agents)
+        configureAgent(projectPath, id, report); // only the chosen agents
+    report.nextSteps = [
+        "Run the `spec_init` tool to set up the spec-driven workflow (creates spec/). No external CLI needed — it's built into speclaw.",
+        "Run the `compass_index` tool to build the local code graph (.speclaw/). No install, no LLM — it's built into speclaw. Re-run it after significant edits.",
+        "Analyze the repo's real entrypoints and core flows, then fill in the 'Project-specific starting points' section of docs/compass.md (or pass compass_hints in the profile) so agents know where to start querying.",
+        "Fill in the per-standard sections left as HTML comments in docs/standards/* (architecture module table, backend/frontend layer tables, versioning) by analyzing the real repo. These are the granular laws CLAUDE.md, AGENTS.md and the dev agents reference.",
+        "Read the generated LAWS.md, CLAUDE.md, AGENTS.md and docs/standards/* with the user and refine any standard that does not match how the team actually works.",
+        report.unresolvedVars.length
+            ? `Fill in the unresolved template variables (${report.unresolvedVars.join(", ")}) by editing the affected files or re-running scaffold with a more complete profile.`
+            : "",
+    ].filter(Boolean);
+    return report;
+}

package/dist/modules/spec/assets/commands/archive.md

@@ -0,0 +1,10 @@
+---
+description: Finalize a completed change — sync specs into canonical, then archive it.
+---
+
+Archive the completed change: $ARGUMENTS
+
+Follow the `archive` skill: confirm every task is done and gates are green,
+run `spec_validate`, then `spec_archive` with today's date (YYYY-MM-DD). It
+syncs the specs and moves the change to `spec/changes/archive/`. Never move
+the folder by hand.