@kiwidata/grimoire 0.1.1

package/dist/utils/paths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Walk up from cwd to find a directory containing .grimoire/ or features/
+ */
+export declare function findProjectRoot(): Promise<string>;
+export declare function resolveChangePath(root: string, changeId: string): string;
+/**
+ * Resolve a path and verify it stays within the project root.
+ */
+export declare function safePath(root: string, filePath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAgBvD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM/D"}

package/dist/utils/paths.js

@@ -0,0 +1,35 @@
+import { join, resolve } from "node:path";
+import { fileExists } from "./fs.js";
+/**
+ * Walk up from cwd to find a directory containing .grimoire/ or features/
+ */
+export async function findProjectRoot() {
+    let dir = process.cwd();
+    const root = resolve("/");
+    while (dir !== root) {
+        if ((await fileExists(join(dir, ".grimoire"))) ||
+            (await fileExists(join(dir, "features")))) {
+            return dir;
+        }
+        dir = resolve(dir, "..");
+    }
+    // Fall back to cwd
+    return process.cwd();
+}
+export function resolveChangePath(root, changeId) {
+    if (/[/\\]/.test(changeId) || changeId === ".." || changeId.includes("..")) {
+        throw new Error(`Invalid change ID: ${changeId}`);
+    }
+    return join(root, ".grimoire", "changes", changeId);
+}
+/**
+ * Resolve a path and verify it stays within the project root.
+ */
+export function safePath(root, filePath) {
+    const resolved = resolve(root, filePath);
+    if (!resolved.startsWith(root + "/") && resolved !== root) {
+        throw new Error(`Path escapes project root: ${filePath}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=paths.js.map

package/dist/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACxB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE1B,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;QACpB,IACE,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;YAC1C,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EACzC,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,mBAAmB;IACnB,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,QAAgB;IAC9D,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAgB;IACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/spawn.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Spawn a command with stdin piped, avoiding sh -c shell interpretation.
+ */
+export declare function spawnWithStdin(command: string, args: string[], input: string, cwd: string): Promise<string>;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/utils/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/utils/spawn.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CA+BjB"}

package/dist/utils/spawn.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+/**
+ * Spawn a command with stdin piped, avoiding sh -c shell interpretation.
+ */
+export function spawnWithStdin(command, args, input, cwd) {
+    return new Promise((resolve, reject) => {
+        const parts = command.split(/\s+/);
+        const proc = spawn(parts[0], [...parts.slice(1), ...args], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 120_000,
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            if (code === 0 || stdout.trim()) {
+                resolve(stdout.trim());
+            }
+            else {
+                reject(new Error(stderr.trim() || `Command exited with code ${code}`));
+            }
+        });
+        proc.stdin.write(input);
+        proc.stdin.end();
+    });
+}
+//# sourceMappingURL=spawn.js.map

package/dist/utils/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/utils/spawn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAc,EACd,KAAa,EACb,GAAW;IAEX,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE;YACzD,GAAG;YACH,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YACtC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YACtC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,4BAA4B,IAAI,EAAE,CAAC,CAAC,CAAC;YACzE,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kiwidata/grimoire",
+  "version": "0.1.1",
+  "description": "Gherkin + MADR spec-driven development for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "grimoire": "./bin/grimoire.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist/",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "files": [
+    ".claude-plugin/",
+    "dist/",
+    "bin/",
+    "templates/",
+    "skills/",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "keywords": [
+    "gherkin",
+    "bdd",
+    "madr",
+    "adr",
+    "spec-driven",
+    "ai",
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "author": "Kiwi Data",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@cucumber/gherkin": "^39.0.0",
+    "@cucumber/messages": "^32.2.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.0",
+    "gray-matter": "^4.0.3",
+    "simple-git": "^3.33.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.1",
+    "@typescript-eslint/parser": "^8.58.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.0.0",
+    "jscpd": "^4.0.9",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/grimoire-apply/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: grimoire-apply
+description: Implement tasks from a planned grimoire change with strict red-green BDD. Use when tasks.md exists and is ready for implementation.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-apply
+
+Implement tasks from a planned grimoire change. Write production code AND tests. A task is not complete until its scenarios pass.
+
+## CRITICAL: Two Rules That Must Not Be Broken
+
+### 1. Do Not Re-Plan
+
+**`tasks.md` IS the plan. Do not enter plan mode. Do not create your own plan. Do not reorganize, re-derive, or "think through" the tasks before starting.**
+
+### 2. Do Not Implement All Tasks In One Context
+
+**Spawn a fresh subagent (or start a fresh session) for each task section.** The parent/orchestrator reads `tasks.md` and delegates — it does NOT write code itself. Context degrades after 3-4 tasks and the LLM starts making mistakes based on stale file contents. See "Session Management" below for the exact workflow.
+
+The plan was already created in the plan stage, reviewed by the user, and approved. Your job is to EXECUTE it, not to re-evaluate it. Read `tasks.md`, find the first unchecked task, and start working.
+
+If you believe a task is wrong, incomplete, or impossible — flag it to the user. Do not silently re-plan. Do not skip tasks. Do not reorder tasks unless the user asks.
+
+This applies to all LLMs: Claude, Codex, Cursor, Copilot, etc. The task list is the authority.
+
+## Triggers
+- User wants to implement a planned grimoire change
+- User asks to apply, implement, or build a grimoire change
+- Loose match: "apply", "implement", "build" with a change reference
+
+## Routing
+- No tasks.md exists → `grimoire-plan` first
+- Task seems wrong or impossible → flag to user; do NOT silently re-plan or skip
+- Implementation reveals the spec is wrong → STOP. Go back to `grimoire-draft`.
+- Fix is needed (not a planned change) → `grimoire-bug`
+
+## Prerequisites
+- A change exists in `.grimoire/changes/<change-id>/` with:
+  - `manifest.md`
+  - `tasks.md` (from plan stage)
+  - At least one `.feature` file or decision record
+
+## Workflow
+
+### 1. Select Change
+- List active changes in `.grimoire/changes/` that have `tasks.md`
+- If multiple, ask user which one to apply
+- If only one, confirm it
+- Read `tasks.md` and find the first unchecked `- [ ]` task — that's where you start
+- Skip any tasks already marked `- [x]` (resume from where a previous session left off)
+
+### 2. Choose Execution Mode
+Ask the user how they want to work through the task list:
+
+**Review mode (default):** Before each task, present what you plan to implement and which files you'll touch. Then for each file change:
+1. Show the proposed change (what you plan to write/edit and why)
+2. Wait for user approval before writing to that file
+3. If the user requests modifications, revise and re-present before writing
+
+After all file changes for a task are approved and written, run the tests and show results. Wait for user approval before moving to the next task. The user can request changes, ask questions, reorder, or skip tasks at any point.
+
+**Autonomous mode:** Work through the entire task list without pausing between tasks. Only stop if:
+- A test won't go green after reasonable attempts (you're stuck)
+- Implementation reveals the spec is wrong (needs to go back to draft)
+- You hit an external blocker (missing dependency, permissions, etc.)
+
+If the user doesn't specify, default to review mode.
+
+**Both modes:** Update `tasks.md` in real time as work progresses. Mark tasks `- [x]` the moment they pass. If a task is split, reordered, or new tasks are discovered during implementation, update `tasks.md` immediately so it always reflects the current state. The task list is the source of truth for progress — if the session is interrupted, the next agent should be able to read `tasks.md` and know exactly where to resume.
+
+### Stuck Detection & Recovery
+
+**You MUST track failed attempts per task.** If a test won't go green, count your attempts:
+
+- **Attempt 1:** Try the straightforward implementation from the task description.
+- **Attempt 2:** If attempt 1 failed, re-read the error carefully. Try a *different* approach — not the same code with minor tweaks. State what you're doing differently and why.
+- **Attempt 3 (final):** If attempt 2 failed, try one more *fundamentally different* approach. If the same error recurs, the problem is likely not in your implementation.
+
+**After 3 failed attempts on a single task, STOP.** Do not continue. Instead:
+1. Add a comment to `tasks.md` under the task: `<!-- BLOCKED: <summary of what was tried and what failed> -->`
+2. Present to the user:
+   - What the task requires
+   - What you tried (all 3 approaches, briefly)
+   - What error/failure persisted
+   - Your best guess at the root cause
+3. Wait for the user to decide: fix the task, provide guidance, skip it, or go back to plan.
+
+**What counts as a "different approach":**
+- Using a different library/API to achieve the same result
+- Restructuring the code (different function signature, different data flow)
+- Changing the test setup (different fixtures, different mocking strategy)
+
+**What does NOT count:**
+- Changing a variable name or adding a print statement
+- Adding a try/catch around the same failing code
+- Re-running the same code hoping for a different result
+
+**In autonomous mode:** This rule is especially critical. Without it, the agent will loop until the token budget is exhausted. After 3 failed attempts, switch to review mode for that task and ask the user.
+
+**Never silently retry the same approach.** If your implementation produced error X and you're about to write code that will produce error X again, stop and think about why. If you can't identify what would change the outcome, stop and ask.
+
+### Session Management — MANDATORY Fresh Context Per Section
+
+**Do NOT implement all tasks in a single conversation context.** Context accumulates across tasks and degrades output quality — the LLM starts hallucinating based on stale file contents it read 5 tasks ago. This is not a suggestion. Fresh context per task section is required.
+
+Each task section in `tasks.md` has a `<!-- context: ... -->` block listing the exact files needed. This is the loading list for that section's fresh context.
+
+#### Claude Code: Subagent Per Section
+
+The parent agent is the **orchestrator only** — it does NOT implement tasks itself. The workflow is:
+
+1. Parent reads `tasks.md`, finds the first unchecked section
+2. Parent spawns a **subagent** (Agent tool) with this prompt:
+   ```
+   You are implementing grimoire tasks. Read `.grimoire/changes/<change-id>/tasks.md`,
+   find section <N>, and implement all unchecked tasks in that section.
+   Follow the red-green BDD cycle for each task. Mark tasks [x] when done.
+   When the section is complete, write a <!-- SESSION: ... --> handoff note
+   under the last task and exit.
+   ```
+3. Subagent reads `tasks.md` and the context files for that section
+4. Subagent implements, marks tasks `[x]`, writes handoff note, exits
+5. Parent reads updated `tasks.md`, spawns next subagent for next section
+6. Repeat until all sections complete
+
+**The parent agent MUST NOT write production code or test code.** Its only jobs are: read `tasks.md`, spawn subagents, and check completion between sections. If the parent starts implementing tasks directly, context will degrade by section 3-4 and output quality will drop.
+
+#### Other Agents (Codex, Cursor, Windsurf, etc.)
+
+Start a **fresh session** for each task section. The resume mechanism via `tasks.md` checkboxes makes this seamless:
+
+1. Open a new session
+2. Tell the agent: "Run `/grimoire:apply` on change `<change-id>`"
+3. The agent reads `tasks.md`, finds the first `- [ ]`, reads that section's context block
+4. When the section is complete, end the session
+5. Start a new session for the next section
+
+This is the same pattern as the [Ralph Wiggum loop](https://ralph-wiggum.ai) — progress lives in files (`tasks.md` + git), not in the context window. Each session gets a clean slate and reads current file state.
+
+#### Handoff Notes
+
+Before exiting (subagent exit or session end), write a handoff note in `tasks.md`:
+
+```markdown
+- [x] 1.3 Implement TOTP verification
+<!-- SESSION: completed 1.1-1.3. auth middleware moved to middleware/auth.ts. pyotp added to requirements. Next section needs the new middleware import. -->
+```
+
+This gives the next session critical context (architectural decisions made, files created/moved, gotchas discovered) without requiring it to re-read everything.
+
+#### When to Force a Fresh Context Mid-Section
+
+Even within a section, break early if:
+- You needed 3 attempts on a task (stuck detection recovery)
+- You notice degraded output (repeating yourself, forgetting earlier context, making mistakes on things you got right earlier)
+- The section has more than 5 tasks
+
+Write a handoff note at the break point and start fresh.
+
+**Check `.grimoire/config.yaml`** for the configured coding agent — use `llm.coding.command` and `llm.coding.model` for implementation work.
+
+### 3. Create Feature Branch
+Before writing any code, ensure you're on a feature branch for this change:
+
+```
+git checkout -b <type>/<change-id>
+```
+
+Where `<type>` is `feat`, `fix`, `refactor`, or `chore` based on the change. If a branch already exists (resuming work), switch to it. Update the manifest's `branch:` field with the branch name.
+
+This links the git history to the grimoire change — `grimoire trace` and `grimoire log` depend on it.
+
+### 4. Load Context
+
+**Use the context blocks in `tasks.md`.** Each task section has a `<!-- context: ... -->` comment listing the exact files to load for that section. This was computed during planning with full codebase knowledge. Load those files — they include the relevant feature files, area docs, and source files you'll need.
+
+**Loading order:**
+1. `tasks.md` — your checklist (load once at start, find the current section)
+2. Read the `<!-- context: ... -->` block for the current section
+3. Load each file listed in the context block
+4. If a listed file doesn't exist, it may need to be created as part of the task — that's fine
+
+**If the context window fills up** (degraded output quality, forgotten context, repeated mistakes):
+1. Finish or pause the current task
+2. Summarize progress in `tasks.md` (mark completed tasks, add handoff note)
+3. Tell the user: "Context is getting large. I've updated tasks.md with progress. A fresh session can resume from here."
+
+### 5. Implement Tasks
+Work through `tasks.md` sequentially. **Every task follows the same cycle: code → test → green → next.**
+
+**For each task:**
+1. Announce which task you're working on
+2. Write the step definitions FIRST (the test that will verify this task)
+3. Run the step definitions — **they MUST FAIL (red)**
+4. If the test passes immediately, STOP. The test is broken — it's not actually testing anything. Fix the step definition so it makes a real assertion that fails without production code. Common causes:
+   - Empty step definition body (passes by default)
+   - Assertion against a mock/fixture that already satisfies the condition
+   - Step wired to wrong function or missing the actual check
+   - Overly broad assertion that matches anything
+5. Once confirmed red: write the production code to make it pass
+6. Run the step definitions again — they should PASS (green)
+7. If still red, fix the production code (not the test)
+8. **Test quality check:** Before marking done, verify your step definitions have strong assertions:
+   - Every Then step has a specific `assert` or `expect` with an exact expected value (not `assert True`, not `toBeDefined()`)
+   - No empty function bodies (`pass`, `...`, or no-op)
+   - Assertions check behavior, not just types or existence — "response status is 302 and redirect URL is /dashboard/" not "response is not None"
+   - If you wrote a test that would pass against a null/trivial implementation, strengthen it
+9. Mark complete: `- [ ]` → `- [x]`
+10. Move to next task
+
+**This is strict red-green BDD.** A test that has never been red has never proven it can catch a failure. The red step is NOT a formality — it is the proof that the test works. If you skip it or the test passes immediately, you have a false positive that provides zero safety.
+
+**Step definition rules:**
+- Organize by domain concept, not by feature file
+- Shared steps go in the project's common step location (check existing test setup)
+- Step definitions are the translation layer between Gherkin and code
+- Keep them thin — delegate to helper/support code
+- Every Given/When/Then step in a proposed `.feature` file MUST have a corresponding step definition
+
+**Architecture tasks:**
+- Follow the decision record's chosen option
+- Implement consequences noted in the ADR
+- If the ADR has a Confirmation section, write a test or check that validates it
+
+### 6. Verify
+When all implementation tasks are complete:
+- Run the BDD test suite (command from `config.tools.bdd_test`) — existing behavior must not break
+- All scenarios should pass — new AND existing
+- If new scenarios fail, fix the implementation (not the feature file — the feature is the spec)
+- If existing scenarios break, you've introduced a regression — fix it before proceeding
+- Check ADR confirmation criteria if applicable
+- Run the project's full test suite (`config.tools.unit_test`) if configured — grimoire tests don't replace existing tests
+
+**The verify step is not optional. Do not proceed to finalize with failing tests.**
+
+### 7. Finalize
+When all tests are green:
+1. Copy proposed `.feature` files from `.grimoire/changes/<change-id>/features/` to `features/` (replacing baseline)
+2. Move new decision records to `.grimoire/decisions/` with proper sequential numbering
+3. Update MADR status from `proposed` to `accepted` and set the date
+4. If `data.yml` exists, merge the changes into `.grimoire/docs/data/schema.yml` — apply adds/modifies/removes so the baseline schema stays current
+5. Move `manifest.md` to `.grimoire/archive/YYYY-MM-DD-<change-id>/`
+6. Remove the change directory from `.grimoire/changes/`
+
+### 8. Summary
+Present a brief summary:
+- What was implemented
+- Which features now pass (with test counts if available)
+- Which decisions were accepted
+- Any follow-up items
+
+## References
+
+**Before writing code**, read `../references/testing-contracts.md` — covers: verify-before-using rules (imports, packages, APIs), mocking strategy (HTTP boundary not client), fixture management, contract tests, and step definition quality checks.
+
+## Important
+- **Tests are not optional.** Every task produces both production code and passing step definitions. No exceptions.
+- **Red-green is mandatory, not aspirational.** A test must fail before it passes. If it doesn't fail, it's not a real test. Fix it before moving on.
+- **A test that always passes is worse than no test.** It gives false confidence. If you can't make a step definition fail, you don't understand what it's testing.
+- The feature file is the spec. If a test fails, fix the code, not the feature.
+- If implementation reveals that a scenario is wrong or missing, STOP and go back to draft. Don't silently change features.
+- Keep changes minimal and focused — only implement what's in tasks.md
+- If blocked, flag it rather than working around it
+- Commit frequently — one commit per logical task is ideal. Every commit during apply **MUST** include a `Change: <change-id>` git trailer for audit traceability. Use `/grimoire:commit` or manually add the trailer.
+- Existing tests must keep passing. A grimoire change that breaks existing behavior is not complete.
+
+## Done
+When all tasks are complete, tests pass, and artifacts are finalized, the workflow is complete. Present the summary and suggest:
+- `grimoire-verify` to confirm implementation matches specs
+- `grimoire-commit` to commit the changes

package/skills/grimoire-audit/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: grimoire-audit
+description: Audit an existing codebase to discover undocumented features and architecture decisions. Use when onboarding an existing project to grimoire.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-audit
+
+Audit an existing codebase to discover undocumented features and architecture decisions. Interview the user to collaboratively build out the grimoire baseline.
+
+## Triggers
+- User wants to onboard grimoire into an existing project
+- User asks to audit, discover, or document existing behavior
+- User asks "what features do we have?" or "what's not documented?"
+- Loose match: "audit", "discover", "onboard", "baseline", "inventory"
+
+## Routing
+- Want to map codebase structure, utilities, and patterns → `grimoire-discover` first
+- Want to add new functionality → `grimoire-draft`
+- Want to find code quality issues → `grimoire-refactor`
+
+## Workflow
+
+### 1. Determine Audit Scope
+Ask the user what to audit:
+- **Features** — find behavioral functionality that has no `.feature` file
+- **Decisions** — find implicit architecture decisions that have no ADR
+- **Both** — full audit (default)
+
+Check what's already documented:
+- Read all files in `features/` for existing behavioral specs
+- Read all files in `.grimoire/decisions/` for existing ADRs
+- This is your "already known" set — don't re-propose these
+
+### 2. Feature Discovery
+Scan the codebase for behavioral functionality. Look at:
+- **Routes / URL patterns** — each route implies user-facing behavior
+- **Views / Controllers** — what actions can users take?
+- **API endpoints** — what does the system expose?
+- **UI components / templates** — what do users see and interact with?
+- **Background tasks / jobs** — what happens automatically?
+- **Permissions / auth** — what access control exists?
+- **Email / notifications** — what does the system communicate?
+
+For each discovered behavior cluster, check if a corresponding `.feature` file exists. If not, note it as undocumented.
+
+### 3. Decision Discovery
+Scan for implicit architecture decisions:
+- **Dependencies** — what major libraries/frameworks are used and why? (requirements.txt, package.json, go.mod)
+- **Database** — what database(s), why, any extensions?
+- **Infrastructure patterns** — caching, queuing, search, file storage
+- **Auth patterns** — how is authentication/authorization implemented?
+- **API design** — REST? GraphQL? RPC? What conventions?
+- **Testing patterns** — what framework, what strategy?
+- **Deployment** — Docker, K8s, serverless? CI/CD pipeline?
+- **Data model** — multi-tenant? event-sourced? CQRS?
+
+For each pattern found, check if a corresponding ADR exists. If not, note it as undocumented.
+
+### 4. Interview the User
+Do NOT dump a massive list. Present findings in batches of 3-5, grouped by area, and ask the user about each:
+
+For features:
+> "I found a document review workflow with routes for `/dais/review/document/<id>/`. There's tab switching, error modals, and tag editing. I don't see a feature file covering this. Should I draft one?"
+
+For decisions:
+> "You're using PostgreSQL with pgvector for embeddings and Redis with Huey for task queuing. These seem like deliberate choices but I don't see ADRs for them. Want me to capture these?"
+
+Let the user:
+- **Confirm** — yes, draft it
+- **Skip** — not important enough to document
+- **Clarify** — provide context the code doesn't show
+- **Group** — "those three things are actually one feature"
+
+### 5. Draft Artifacts
+For confirmed items, create a grimoire change:
+- Change ID: `audit-<area>` (e.g., `audit-auth`, `audit-data-model`)
+- Draft `.feature` files for confirmed behavioral specs
+- Draft MADR records for confirmed decisions
+- Write manifest summarizing what was discovered and documented
+
+Group related items into single changes — don't create one change per discovery.
+
+### 6. Dead Feature Detection
+Check for documented features and decisions that may no longer be accurate:
+
+**Dead features** — feature files that describe behavior the code no longer implements:
+- Feature files with no step definitions: for each `.feature` file, grep the test directory for its step text patterns
+- Orphaned step definitions: grep step definition imports, check if referenced modules still exist on disk
+- Stub step definitions: `grep -rn 'pass$\|NotImplementedError\|\.\.\.$$' <test-dir>` (empty bodies)
+- Stale skips: `grep -rn '@skip\|@wip' features/` cross-referenced with `git blame` for age
+- Deleted routes: for each feature's endpoint, grep the codebase for the route — missing = dead
+
+**Stale decisions** — ADRs that describe choices no longer reflected in the code:
+- ADR says "use library X" but library X is no longer in dependencies
+- ADR is `accepted` but the pattern it describes isn't in the codebase
+- ADR references files or modules that no longer exist
+
+Present dead features and stale decisions to the user with the same interview approach — batches of 3-5:
+> "I found `features/billing/invoice.feature` with 4 scenarios, but there are no step definitions and the `InvoiceView` it would test was deleted 3 months ago. Should I create a removal change for this?"
+
+Options for the user:
+- **Remove** — create a grimoire removal change to clean it up
+- **Revive** — the feature should exist; create a change to re-implement it
+- **Update** — the feature exists but the spec is outdated; create a change to fix the spec
+- **Skip** — leave it for now
+
+### 7. Prioritize
+After the interview, summarize:
+- How many features are documented vs. undocumented
+- How many features are dead or stale
+- How many decisions are documented vs. undocumented
+- How many decisions are stale
+- Suggest which areas to address first (highest risk / most complex / most frequently changed)
+
+## Important
+- This is a COLLABORATIVE process, not a dump. Interview, don't lecture.
+- Present findings in small batches. Let the user guide priority.
+- The user knows things the code doesn't show — ask about intent, not just structure.
+- Some things legitimately don't need documentation. Respect "skip" answers.
+- Don't try to document everything in one session. It's ok to do multiple audit passes.
+- Features should describe WHAT the system does, not HOW the code works. Don't just translate code into Gherkin.
+- For decisions, focus on choices that were non-obvious or have alternatives. "We use Python" doesn't need an ADR. "We use Huey instead of Celery" probably does.
+
+## Done
+When the audit interview is complete and confirmed items are drafted as grimoire changes, the workflow is complete. Suggest next steps: `grimoire-plan` for approved changes, or another audit pass for uncovered areas.