@esneiderbravo/speclaw 0.1.0

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

@@ -0,0 +1,11 @@
+---
+description: Implement a drafted change, following its spec and the project's standards.
+---
+
+Implement the change: $ARGUMENTS
+
+Follow the `build` skill: read the change's `proposal.md`, `tasks.md`, and delta
+specs; create the feature branch first; work the tasks in order using
+`compass_explore` before editing; keep code and spec in agreement; run the
+quality gates (`{{test_commands}}`, `{{lint_commands}}`) and manual
+verification yourself; check off each task.

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

@@ -0,0 +1,12 @@
+---
+description: Draft a new spec-driven change (proposal, delta specs, tasks) before coding.
+---
+
+Draft a new change under `spec/changes/<name>/` for: $ARGUMENTS
+
+Follow the `draft` skill: ensure `spec/` exists (`spec_init`), investigate the
+code with `compass_explore`/`compass_recall`, read the governing
+`docs/standards/`, then write `proposal.md`, `specs/<capability>/spec.md`
+(normative `SHALL`/`MUST` + `#### Scenario:`), optional `design.md`, and
+`tasks.md` (with the mandatory steps from `spec/config.yaml`). Finish by
+running `spec_validate` and fixing every issue.

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

@@ -0,0 +1,10 @@
+---
+description: Enter explore mode — a thinking partner before or during a change.
+---
+
+Explore: $ARGUMENTS
+
+Follow the `explore` skill: use `compass_recall`/`compass_explore` to understand
+the code, ask sharp questions, check the relevant `docs/standards/`, weigh
+approaches with trade-offs, and give a recommendation. Write nothing to
+`spec/`; when the direction is clear, offer to `draft` the change.

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

@@ -0,0 +1,9 @@
+---
+description: Promote a change's delta specs into the canonical specs, without archiving.
+---
+
+Sync the change's specs into canonical: $ARGUMENTS
+
+Follow the `sync` skill: validate the change (`spec_validate`), then run
+`spec_sync` to promote each delta spec into `spec/specs/`. Report what was
+promoted; leave the change active.

package/dist/modules/spec/assets/rules/spec-tasks-mandatory-steps.md

@@ -0,0 +1,37 @@
+---
+description: Enforce the mandatory steps from spec/config.yaml when creating tasks.md, and ensure the agent executes all manual verification itself.
+alwaysApply: true
+---
+
+# Spec Tasks: Mandatory Steps
+
+When creating or updating a `tasks.md` inside a `spec/changes/<name>/`, you MUST:
+
+## 1. Read spec/config.yaml first
+
+Before writing tasks, read `spec/config.yaml` for the project's mandatory task
+steps, branch convention, and testing/documentation requirements.
+
+## 2. Include the mandatory steps, in order
+
+- **Step 0 — Create the feature branch (must be first).** Follow the repo's
+  branch pattern.
+- Review and update the affected tests.
+- Run the quality gates and verify they pass
+  (see `docs/standards/testing-standards.md`).
+- Perform manual verification of the behavior — **the agent executes this
+  itself, never the user.**
+- Update the technical documentation the change touches.
+- Archive the change within the same PR (the `archive` command / `spec_archive`
+  tool).
+
+## 3. Manual verification — the agent must execute it
+
+The coding agent performs all manual testing itself (exercise the endpoint, UI,
+or CLI). Never delegate it to the user. A task that requires verification is
+not complete until the agent has verified it.
+
+## 4. Archiving is part of the change
+
+A change is not done until it is archived with `spec_archive` (never a manual
+`mv`). The archive lands in the same PR that implements the change.

package/dist/modules/spec/assets/skills/archive/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: archive
+description: Finalize a completed change — sync its specs into canonical, then move it to the archive. Use when a change is done and merged-ready: "archive the change", "finalize X", "close out the change". Part of speclaw's spec module (draft → build → sync → archive). Archiving belongs in the same PR that implements the change.
+---
+
+# archive — Finalize and archive a change
+
+Close out a completed change: its delta specs become canonical and the change
+folder moves to `spec/changes/archive/`. This is part of the PR that
+implements the change, not a post-merge chore.
+
+## Steps
+
+1. Confirm the change is truly done: every task in `tasks.md` checked, quality
+   gates green, behavior verified.
+2. Run `spec_validate` for the change; resolve any issues first.
+3. Run the `spec_archive` tool with the change name and today's date
+   (`YYYY-MM-DD`). It syncs the delta specs into `spec/specs/` and then moves
+   `spec/changes/<name>/` to `spec/changes/archive/<date>-<name>/`.
+4. Report the archive path and the promoted specs. Never move the folder by
+   hand — always use `spec_archive`, which performs the sync and validation a
+   manual move would skip.

package/dist/modules/spec/assets/skills/build/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: build
+description: Implement the tasks of a drafted change, following its spec and the project's standards. Use when the user wants to start or continue implementing a change: "build X", "implement the change", "work through the tasks", "continue X". Part of speclaw's spec module (draft → build → sync → archive).
+---
+
+# build — Implement a change
+
+Work through a change's `tasks.md` in order, keeping code, spec, and standards
+in lockstep.
+
+## Step 0 — Load the change
+
+- Read `spec/changes/<name>/proposal.md`, `tasks.md`, and the delta specs under
+  `specs/`. If unsure which change, run `spec_list`.
+- Read the governing standards in `docs/standards/` for the areas you'll touch.
+
+## Step 1 — Branch first
+
+Create the feature branch (the mandatory Step 0 in `tasks.md`), following the
+repo's branch pattern `{{branch_pattern}}`.
+
+## Step 2 — Implement task by task
+
+- Use `compass_explore` before editing to see a symbol's callers/callees and
+  blast radius; re-run `compass_index` after significant edits to keep the
+  graph fresh.
+- Make the smallest correct change; match the surrounding code.
+- The code must satisfy the delta spec exactly. If reality diverges from the
+  spec, update the spec in the change (not silently) — the two must agree.
+- Check off each task in `tasks.md` as you complete it.
+
+## Step 3 — Quality gates (mandatory)
+
+Run the repo's gates from `docs/standards/testing-standards.md`:
+
+- Tests: `{{test_commands}}`
+- Lint / type-check: `{{lint_commands}}`
+
+Run them yourself and report real output. A red gate blocks completion.
+
+## Step 4 — Manual verification (mandatory, agent executes)
+
+Exercise the behavior (endpoint/UI/CLI) yourself where feasible — do not
+delegate manual testing to the user. Record what you verified.
+
+## Step 5 — Hand off
+
+When every task is checked and gates are green, tell the user the change is
+ready to `sync` and `archive`.

package/dist/modules/spec/assets/skills/draft/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: draft
+description: Draft a new spec-driven change — proposal, delta specs, and tasks — before writing any code. Use when the user wants to start, plan, or propose a new feature, fix, or refactor: "draft a change for X", "propose X", "let's plan X", "spec out X", "new change". Part of speclaw's spec module (draft → build → sync → archive).
+---
+
+# draft — Draft a new change
+
+Turn a request into a complete, reviewable change under `spec/changes/<name>/`
+before any implementation. This is speclaw's own spec-driven workflow — no
+external CLI; the mechanical steps are speclaw MCP tools.
+
+## Step 0 — Ensure the workspace exists
+
+If `spec/` is missing, run the `spec_init` tool once to create it.
+
+## Step 1 — Understand the request and the code
+
+- Clarify what the user wants (feature / fix / refactor) and confirm scope.
+- Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
+  grep/read to locate the real code the change touches and its blast radius.
+  If the index is stale or missing, run `compass_index` first.
+- Read the governing standards in `docs/standards/` (architecture, backend,
+  frontend, testing) so the change complies with the project's law.
+
+## Step 2 — Pick a change name
+
+Kebab-case, action-oriented (e.g. `add-login`, `fix-shift-overlap`). This is
+the folder under `spec/changes/`.
+
+## Step 3 — Write the artifacts
+
+Create under `spec/changes/<name>/`:
+
+- **proposal.md** — the why, the what, non-goals, and whether migrations are
+  needed. Reference the tracker ticket ({{ticket_prefix}}-N) if there is one.
+- **specs/<capability>/spec.md** — the delta spec for each affected capability.
+  Use normative language and testable scenarios:
+  ```markdown
+  # <Capability>
+
+  ### Requirement: <name>
+  The system SHALL <requirement>.
+
+  #### Scenario: <name>
+  - Given <context>
+  - When <action>
+  - Then <observable outcome>
+  ```
+- **design.md** (optional) — for non-trivial changes: approach, alternatives,
+  trade-offs.
+- **tasks.md** — ordered, checkable steps. MUST include the mandatory steps
+  from `spec/config.yaml` (feature branch first; tests reviewed and run;
+  manual verification executed by the agent; docs updated; archive within the
+  PR).
+
+## Step 4 — Validate
+
+Run the `spec_validate` tool for the change and fix every issue it reports
+(missing artifacts, non-normative specs, missing scenarios) before handing off
+to implementation.
+
+## Step 5 — Hand off
+
+Summarize the change and tell the user it's ready to `build`.

package/dist/modules/spec/assets/skills/explore/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: explore
+description: Enter explore mode — a thinking partner for investigating an idea, a problem, or the codebase before or during a change. Use when the user wants to think something through, understand how something works, or clarify requirements before committing to a spec: "help me think through X", "how does X work", "explore X", "I'm not sure how to approach X". Part of speclaw's spec module.
+---
+
+# explore — Think it through
+
+A low-commitment mode for investigating ideas and the codebase before (or
+during) a change. Nothing is written to `spec/` here — the output is shared
+understanding and a recommended direction.
+
+## How to explore
+
+- **Understand the code first.** Use `compass_recall` to find relevant code by
+  meaning and `compass_explore` to read a symbol's source plus its callers and
+  callees — before grep/read. Run `compass_index` if the graph is missing.
+- **Ask sharp questions** to surface hidden assumptions, constraints, and edge
+  cases. Confirm scope and non-goals.
+- **Check the law.** Read the relevant `docs/standards/` so any direction you
+  propose already fits the project's architecture and conventions.
+- **Weigh approaches.** Lay out the viable options with trade-offs and give a
+  recommendation, not an exhaustive survey.
+
+## Output
+
+A concise summary: the problem as understood, the constraints, the recommended
+approach, and the open questions. When the direction is clear, offer to `draft`
+the change.

package/dist/modules/spec/assets/skills/sync/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: sync
+description: Promote a change's delta specs into the canonical specs, without archiving. Use when the user wants to update the source-of-truth specs from a change: "sync the specs", "update the canonical specs", "promote the specs". Part of speclaw's spec module (draft → build → sync → archive).
+---
+
+# sync — Promote delta specs to canonical
+
+Update the project's canonical specifications (`spec/specs/`) with a change's
+delta specs, without archiving the change. Use this when the specs should
+become the source of truth but the change isn't finished (e.g. multi-PR work).
+
+## Steps
+
+1. Confirm which change to sync (run `spec_list` if unsure).
+2. Run `spec_validate` for the change; do not sync a change whose specs are
+   invalid.
+3. Run the `spec_sync` tool for the change. It copies each
+   `spec/changes/<name>/specs/<capability>/spec.md` over the canonical
+   `spec/specs/<capability>/spec.md` and reports what it promoted.
+4. Report the promoted files to the user. The change stays active — `archive`
+   it when it's fully done.

package/dist/modules/spec/engine.js

@@ -0,0 +1,227 @@
+import fs from "node:fs";
+import path from "node:path";
+// 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
+// affected capability, and sync promotes those into the canonical specs/.
+const SPEC_DIR = "spec";
+function specRoot(projectPath) {
+    return path.join(projectPath, SPEC_DIR);
+}
+/**
+ * Report whether the spec workspace (spec/) has been initialized for a project.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns True if the spec/ directory exists.
+ */
+export function specExists(projectPath) {
+    return fs.existsSync(specRoot(projectPath));
+}
+const CONFIG_YAML = `# speclaw spec module configuration
+# The spec-driven workflow: draft -> build -> sync -> archive (explore anytime).
+
+# Mandatory steps every change's tasks.md must include, in order.
+mandatory_task_steps:
+  - "Step 0: Create the feature branch (must be first)."
+  - "Review and update the affected tests."
+  - "Run the quality gates and verify they pass (see docs/standards/testing-standards.md)."
+  - "Perform manual verification of the behavior — the agent executes this itself, never the user."
+  - "Update the technical documentation touched by the change."
+  - "Archive the change within the same PR (spec:archive)."
+
+# A change is required for new behavior, endpoints, schema changes, or UI flows;
+# one-line fixes need not have one.
+`;
+const README_MD = `# spec/ — the spec-driven workflow (speclaw)
+
+This directory is managed by speclaw's **spec** module.
+
+- \`specs/\` — the canonical specifications (the current source of truth).
+- \`changes/<name>/\` — an in-flight change: \`proposal.md\`, \`tasks.md\`,
+  optional \`design.md\`, and \`specs/<capability>/spec.md\` delta specs.
+- \`changes/archive/\` — completed, archived changes.
+- \`config.yaml\` — mandatory task steps and workflow rules.
+
+## Workflow
+
+1. \`spec:draft\` — describe the change; generates proposal, delta specs, tasks.
+2. \`spec:build\` — implement the tasks.
+3. \`spec:sync\` — promote the change's delta specs into \`specs/\`.
+4. \`spec:archive\` — sync + move the change to \`changes/archive/\`.
+5. \`spec:explore\` — think through an idea before or during a change.
+`;
+/**
+ * Initialize the spec/ workspace, creating the specs/, changes/, and archive
+ * directories plus config.yaml and README. Idempotent — existing files and
+ * directories are left untouched.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns The paths created and whether the workspace already existed.
+ */
+export function specInit(projectPath) {
+    const root = specRoot(projectPath);
+    const created = [];
+    const alreadyExisted = fs.existsSync(root);
+    const ensure = (rel, content) => {
+        const abs = path.join(root, rel);
+        if (content === undefined) {
+            if (!fs.existsSync(abs)) {
+                fs.mkdirSync(abs, { recursive: true });
+                created.push(rel + "/");
+            }
+        }
+        else if (!fs.existsSync(abs)) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, content);
+            created.push(rel);
+        }
+    };
+    ensure("specs");
+    ensure("changes");
+    ensure("changes/archive");
+    ensure("config.yaml", CONFIG_YAML);
+    ensure("README.md", README_MD);
+    return { created, alreadyExisted };
+}
+/** Recursively collect every .md file under a change's specs/ directory. */
+function deltaSpecFiles(changeDir) {
+    const specsDir = path.join(changeDir, "specs");
+    if (!fs.existsSync(specsDir))
+        return [];
+    const out = [];
+    const walk = (dir) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(full);
+            else if (e.name.endsWith(".md"))
+                out.push(full);
+        }
+    };
+    walk(specsDir);
+    return out;
+}
+/**
+ * Validate a change's artifacts: proposal.md and tasks.md must be present, and
+ * each delta spec must use normative language (SHALL/MUST), a "### Requirement:"
+ * header, and a "#### Scenario:" acceptance criterion.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (folder under spec/changes/).
+ * @returns The validation verdict and the list of issues to fix; never throws
+ *   for a missing change — it is reported as an issue with `valid: false`.
+ */
+export function specValidate(projectPath, change) {
+    const changeDir = path.join(specRoot(projectPath), "changes", change);
+    const issues = [];
+    if (!fs.existsSync(changeDir)) {
+        return { change, valid: false, issues: [`change "${change}" not found under spec/changes/`], deltaSpecs: [] };
+    }
+    if (!fs.existsSync(path.join(changeDir, "proposal.md")))
+        issues.push("missing proposal.md");
+    const tasksPath = path.join(changeDir, "tasks.md");
+    if (!fs.existsSync(tasksPath))
+        issues.push("missing tasks.md");
+    const deltas = deltaSpecFiles(changeDir);
+    if (deltas.length === 0)
+        issues.push("no delta specs under specs/ (a change should specify what it changes)");
+    for (const file of deltas) {
+        const rel = path.relative(changeDir, file);
+        const content = fs.readFileSync(file, "utf8");
+        if (!/\b(SHALL|MUST)\b/.test(content)) {
+            issues.push(`${rel}: no normative requirement (use SHALL/MUST)`);
+        }
+        if (!/^####\s+Scenario:/m.test(content)) {
+            issues.push(`${rel}: no "#### Scenario:" acceptance criteria`);
+        }
+        if (!/^###\s+Requirement:/m.test(content)) {
+            issues.push(`${rel}: no "### Requirement:" header`);
+        }
+    }
+    return { change, valid: issues.length === 0, issues, deltaSpecs: deltas.map((f) => path.relative(projectPath, f)) };
+}
+/**
+ * Promote a change's delta specs into the canonical specs/, overwriting the
+ * file for each affected capability.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (folder under spec/changes/).
+ * @returns The change name and the list of promoted spec paths.
+ * @throws If the change directory does not exist.
+ */
+export function specSync(projectPath, change) {
+    const root = specRoot(projectPath);
+    const changeDir = path.join(root, "changes", change);
+    if (!fs.existsSync(changeDir))
+        throw new Error(`change "${change}" not found`);
+    const changeSpecs = path.join(changeDir, "specs");
+    const promoted = [];
+    if (!fs.existsSync(changeSpecs))
+        return { change, promoted };
+    const walk = (dir) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(full);
+            else if (e.name.endsWith(".md")) {
+                const rel = path.relative(changeSpecs, full);
+                const dest = path.join(root, "specs", rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.copyFileSync(full, dest);
+                promoted.push(path.join("spec/specs", rel));
+            }
+        }
+    };
+    walk(changeSpecs);
+    return { change, promoted };
+}
+/**
+ * Finalize a change: promote its delta specs (via {@link specSync}), then move
+ * it to changes/archive/<date>-<name>/.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @param change - Change name (folder under spec/changes/).
+ * @param date - Archive date prefix, formatted YYYY-MM-DD.
+ * @returns The promoted specs and the archive destination path.
+ * @throws If the change does not exist, or the archive target already exists.
+ */
+export function specArchive(projectPath, change, date) {
+    const root = specRoot(projectPath);
+    const changeDir = path.join(root, "changes", change);
+    if (!fs.existsSync(changeDir))
+        throw new Error(`change "${change}" not found`);
+    const { promoted } = specSync(projectPath, change);
+    const archiveDir = path.join(root, "changes", "archive", `${date}-${change}`);
+    fs.mkdirSync(path.dirname(archiveDir), { recursive: true });
+    if (fs.existsSync(archiveDir))
+        throw new Error(`archive target already exists: ${archiveDir}`);
+    fs.renameSync(changeDir, archiveDir);
+    return { change, promoted, archivedTo: path.relative(projectPath, archiveDir) };
+}
+/**
+ * List the spec workspace: active changes, archived changes, and canonical
+ * capabilities.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns The workspace snapshot; `initialized` is false when spec/ is absent.
+ */
+export function specList(projectPath) {
+    const root = specRoot(projectPath);
+    if (!fs.existsSync(root)) {
+        return { initialized: false, activeChanges: [], archivedChanges: [], capabilities: [] };
+    }
+    const dirsIn = (rel) => {
+        const abs = path.join(root, rel);
+        if (!fs.existsSync(abs))
+            return [];
+        return fs.readdirSync(abs, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name !== "archive")
+            .map((e) => e.name);
+    };
+    return {
+        initialized: true,
+        activeChanges: dirsIn("changes"),
+        archivedChanges: dirsIn("changes/archive"),
+        capabilities: dirsIn("specs"),
+    };
+}

package/dist/modules/spec/register.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { z } from "zod";
+import { text } from "../../shared/mcp.js";
+import { assetsDir } from "../../shared/paths.js";
+import { copyRendered } from "../../shared/install.js";
+import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
+const ASSETS = assetsDir(import.meta.url);
+/**
+ * Install the spec module's workflow interface into a project's ai-specs/:
+ * the draft/build/sync/archive/explore skills, the /spec commands, and the
+ * mandatory-task-steps rule. Always installed — it's the core workflow.
+ */
+export function installWorkflow(projectPath, vars, report) {
+    const aiSpecs = path.join(projectPath, "ai-specs");
+    copyRendered(path.join(ASSETS, "skills"), path.join(aiSpecs, "skills"), vars, report);
+    copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "spec"), vars, report);
+    copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report);
+}
+// ─── The spec module: speclaw's own spec-driven workflow (no external OpenSpec) ───
+// Mechanical operations behind the draft/build/sync/archive/explore commands.
+/** Register the spec workflow MCP tools (init, list, validate, sync, archive). */
+export function registerSpec(server) {
+    server.registerTool("spec_init", {
+        description: "Initialize speclaw's spec-driven workflow in a project: creates spec/ (specs/, changes/, changes/archive/, config.yaml, README). Idempotent — never overwrites existing files.",
+        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
+    }, async ({ projectPath }) => text(specInit(projectPath)));
+    server.registerTool("spec_list", {
+        description: "List the spec workspace: active changes, archived changes, and canonical capabilities under spec/.",
+        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
+    }, async ({ projectPath }) => text(specList(projectPath)));
+    server.registerTool("spec_validate", {
+        description: "Validate a change's artifacts: proposal.md and tasks.md present, and delta specs use normative language (SHALL/MUST), '### Requirement:' headers, and '#### Scenario:' acceptance criteria. Returns the issues to fix. Used by the draft/build commands before proceeding.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            change: z.string().describe("Change name (folder under spec/changes/)"),
+        },
+    }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
+    server.registerTool("spec_sync", {
+        description: "Promote a change's delta specs into the canonical spec/specs/ (per capability), without archiving. Backs the `sync` command.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            change: z.string().describe("Change name (folder under spec/changes/)"),
+        },
+    }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
+    server.registerTool("spec_archive", {
+        description: "Finalize a change: sync its delta specs into spec/specs/, then move it to spec/changes/archive/<date>-<name>/. Backs the `archive` command. Pass today's date as YYYY-MM-DD.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            change: z.string().describe("Change name (folder under spec/changes/)"),
+            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("Today's date, YYYY-MM-DD"),
+        },
+    }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
+}

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

@@ -0,0 +1,61 @@
+---
+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/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 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.