domain-knowledge-kit 0.2.15 → 0.2.19

package/dist/shared/types/federation.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript interfaces for the multi-repo federation layer.
+ *
+ * `service.yml` declares this repo's service identity. `federation.yml`
+ * lists peer services whose `.dkk/` directories should be loaded
+ * alongside the local model (read-only).
+ *
+ * Aligns with JSON schemas under tools/dkk/schema/service.schema.json
+ * and federation.schema.json.
+ */
+export {};
+//# sourceMappingURL=federation.js.map

package/dist/shared/types/federation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.js","sourceRoot":"","sources":["../../../src/shared/types/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+export declare const pkgVersion: string;
+/** Name of the package on the npm registry. Used by `dkk update`. */
+export declare const pkgName = "domain-knowledge-kit";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,UAAU,QAEd,CAAC;AAEV,qEAAqE;AACrE,eAAO,MAAM,OAAO,yBAAyB,CAAC"}

package/dist/version.js

@@ -0,0 +1,15 @@
+/**
+ * Package version, read at runtime from `package.json`.
+ *
+ * Works in both dev (`src/version.ts`) and build (`dist/version.js`) because
+ * `package.json` is one level above either entrypoint. Computed once at
+ * module load.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../package.json");
+export const pkgVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+/** Name of the package on the npm registry. Used by `dkk update`. */
+export const pkgName = "domain-knowledge-kit";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,OAAO,GAAG,OAAO,CACrB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,iBAAiB,CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GACrB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CACzC,CAAC,OAAO,CAAC;AAEV,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-knowledge-kit",
-  "version": "0.2.15",
+  "version": "0.2.19",
   "description": "Domain Knowledge Pack — YAML + ADR links + deterministic search + generated docs",
   "type": "module",
   "repository": {
@@ -18,6 +18,7 @@
     "dist/",
     "tools/dkk/schema/",
     "tools/dkk/templates/",
+    "tools/dkk/claude/",
     ".github/skills/",
     "LICENSE",
     "README.md"
@@ -30,7 +31,7 @@
     "lint:fix": "eslint . --fix",
     "check": "npm run typecheck && npm run lint",
     "prepublishOnly": "npm run build",
-    "test": "tsx src/features/pipeline/tests/validate-schemas.test.ts && tsx src/shared/tests/loader.test.ts && tsx src/features/pipeline/tests/validator.test.ts && tsx src/shared/tests/graph.test.ts && tsx src/features/pipeline/tests/indexer.test.ts && tsx src/features/query/tests/searcher.test.ts && tsx src/features/pipeline/tests/renderer.test.ts && tsx src/shared/tests/verify-collision-fix.test.ts && tsx test/cli-integration.ts"
+    "test": "tsx src/features/pipeline/tests/validate-schemas.test.ts && tsx src/shared/tests/loader.test.ts && tsx src/shared/tests/refs.test.ts && tsx src/shared/tests/paths.test.ts && tsx src/features/federation/tests/loader.test.ts && tsx src/features/federation/tests/schema-load.test.ts && tsx src/features/federation/tests/git-fetcher.test.ts && tsx src/features/federation/tests/validator.test.ts && tsx src/features/federation/tests/phase5.test.ts && tsx src/features/pipeline/tests/validator.test.ts && tsx src/shared/tests/graph.test.ts && tsx src/features/pipeline/tests/indexer.test.ts && tsx src/features/query/tests/searcher.test.ts && tsx src/features/pipeline/tests/renderer.test.ts && tsx src/shared/tests/verify-collision-fix.test.ts && tsx test/cli-integration.ts"
   },
   "engines": {
     "node": ">=21.2.0"
@@ -38,7 +39,6 @@
   "keywords": [],
   "license": "Elastic-2.0",
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "eslint": "^10.0.1",
     "tsx": "^4.7.0",
@@ -47,12 +47,15 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/better-sqlite3": "^7.6.13",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^12.10.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.2",
     "handlebars": "^4.7.8",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "zod": "^4.4.3"
   }
 }

package/tools/dkk/claude/agents/dkk-domain-reviewer.md

@@ -0,0 +1,69 @@
+---
+name: dkk-domain-reviewer
+description: Review a code change, branch, or PR for impact on the local Domain Knowledge Pack. Identifies affected domain items, computes blast radius, flags ADR drift, and returns a single bounded report. Use when the user asks to review a diff, audit a PR, or check whether a change is domain-safe.
+tools: Read, Grep, Glob, Bash, mcp__dkk__search, mcp__dkk__show, mcp__dkk__summary, mcp__dkk__related, mcp__dkk__list, mcp__dkk__locate, mcp__dkk__stats, mcp__dkk__validate, mcp__dkk__story, mcp__dkk__prime
+---
+
+# DKK Domain Reviewer
+
+You review a code change for impact on the project's Domain Knowledge Pack. Your job is to surface domain risk that would be invisible from a syntactic diff review: broken cross-references, blast radius beyond the changed file, drift between code and ADR-recorded decisions.
+
+You return a **single bounded report**. You do not converse — caller invokes you, you investigate, you reply once.
+
+## Inputs
+
+The caller provides one of:
+
+- A list of changed files (relative paths)
+- A git diff range (e.g. `origin/main...HEAD`)
+- A PR number/URL — in which case run `gh pr diff <number>` to retrieve the diff
+
+If no input is provided, default to the working-tree diff: `git diff` and `git status` to enumerate changed files.
+
+## Investigation procedure
+
+1. **Enumerate changed files.** From the diff or file list, separate:
+   - Domain YAML changes under `.dkk/domain/**/*.yml`
+   - ADR changes under `.dkk/adr/*.md`
+   - Code changes that *might* implement a domain command, event, policy, aggregate, or read model
+2. **For each changed domain YAML file**: extract the item id (path → `<context>.<Name>`). Call `mcp__dkk__summary` for orientation, then `mcp__dkk__related` with `depth: 2` for blast radius. Note every neighbour whose definition file was *not* in the diff — those are the items most likely to break invariants.
+3. **For each changed ADR**: call `mcp__dkk__show` on the ADR id. List every item in `domain_refs`. For each, verify (via `mcp__dkk__show`) that the item's `adr_refs` still contains this ADR. Flag missing back-links.
+4. **For each code change**: grep the file for tokens that look like domain identifiers (PascalCase command/event names, `actor.<Name>`, etc.). For each match, call `mcp__dkk__search` with the token. If the token does not resolve to a model item, flag it as a possible drift (code references a name that the model doesn't know about, or vice versa).
+5. **Run `mcp__dkk__validate`** to check schema and cross-reference health on the post-change model. Include any errors or warnings verbatim in the report.
+6. **Spot-check ADR drift.** For each domain item touched by the change, look at its `adr_refs`. Read each referenced ADR via `mcp__dkk__show` and check whether the change is consistent with the ADR's *Decision* and *Consequences* sections. Flag any change that appears to contradict an Accepted ADR.
+
+## Report format
+
+Return one markdown report with these sections (omit a section if empty):
+
+```markdown
+## Domain Review
+
+### Changed domain items
+- `<id>` — <one-line summary> [<context>]
+
+### Blast radius (depth 2)
+- `<changed-id>` → affects <N> items not in this diff:
+  - `<neighbour-id>` (<kind>) — <relationship>
+
+### Cross-reference issues
+- <description>; <path or id>
+
+### ADR drift
+- `<adr-id>: <title>` — <how the change appears to deviate>
+
+### Validation
+- <verbatim errors / warnings, or "clean">
+
+### Recommendations
+- <ordered, actionable items>
+```
+
+If the diff has no domain impact, return: *"No domain-relevant changes detected."*
+
+## Constraints
+
+- Read-only. Do not edit files. Do not call `dkk render`, `dkk add`, `dkk rename`, `dkk rm`, or any write-side `dkk` command.
+- Do not run tests, builds, or arbitrary scripts. The Bash allowance is for `git`, `gh`, and read-only `dkk` queries only.
+- Stay focused on **domain** impact. General code review (style, performance, security) is out of scope — leave those for other reviewers.
+- If you cannot determine impact for some change with confidence, say so explicitly rather than guessing.

package/tools/dkk/claude/commands/dkk-adr.md

@@ -0,0 +1,11 @@
+---
+description: Draft a new Architecture Decision Record using the dkk-adr-author skill.
+argument-hint: <decision-topic>
+---
+
+Invoke the `dkk-adr-author` skill. The decision topic is `$ARGUMENTS`.
+
+- If `$ARGUMENTS` is empty, ask the user to describe the decision in one sentence before proceeding.
+- Otherwise, treat `$ARGUMENTS` as the topic and start the skill workflow at step 1 (search for prior ADRs covering this topic via `mcp__dkk__search` with `type: adr`).
+
+Follow the skill's workflow end to end, including the bidirectional `domain_refs` ↔ `adr_refs` linking and the final `dkk render` quality gate.

package/tools/dkk/claude/commands/dkk-impact.md

@@ -0,0 +1,34 @@
+---
+description: Show blast radius for a DKK item — summary, depth-3 graph neighbours, and linked ADRs.
+argument-hint: <item-id>
+allowed-tools: mcp__dkk__summary, mcp__dkk__related, mcp__dkk__show, mcp__dkk__locate
+---
+
+Compute and present the blast radius of `$ARGUMENTS`.
+
+1. Call `mcp__dkk__summary` with `id: $ARGUMENTS`. Report the item's name, kind, context, and one-line description.
+2. Call `mcp__dkk__related` with `id: $ARGUMENTS` and `depth: 3`. Group results by kind.
+3. From the summary, collect any `adr_refs`. For each, call `mcp__dkk__show` and report the ADR id, title, and status.
+4. Call `mcp__dkk__locate` and report the absolute path(s) where this item is defined.
+
+Format the output as:
+
+```markdown
+## Impact: <id>
+
+**<name>** (<kind>, <context>) — <description>
+
+### Source
+- <absolute path>
+
+### Direct neighbours (depth 1)
+- <kind>: <id>, <id>, ...
+
+### Extended blast radius (depth 2–3)
+- <kind>: <id>, <id>, ...
+
+### Linked ADRs
+- <adr-id>: <title> (<status>)
+```
+
+If the id does not resolve, list the closest candidates from `mcp__dkk__list` or `mcp__dkk__search` and stop.

package/tools/dkk/claude/commands/dkk-implement.md

@@ -0,0 +1,12 @@
+---
+description: Walk through framework-agnostic implementation of a DKK flow using the dkk-flow-implementer skill.
+argument-hint: <flow-id-or-feature-name>
+---
+
+Invoke the `dkk-flow-implementer` skill. The user's target is `$ARGUMENTS`.
+
+- If `$ARGUMENTS` is empty, ask the user which flow to implement, or list available flows via `mcp__dkk__list` (filter `type: flow`).
+- If `$ARGUMENTS` looks like a flow id (`flow.<Name>` or bare `<Name>`), pass it through to `mcp__dkk__story`.
+- Otherwise, run `mcp__dkk__search` with `$ARGUMENTS` first to identify the matching flow or root command, then proceed.
+
+Follow the skill's workflow: retrieve story, ask clarifying questions, present ADR constraints, generate the framework-agnostic checklist, and walk the user through items interactively.

package/tools/dkk/claude/commands/dkk-prime.md

@@ -0,0 +1,6 @@
+---
+description: Re-inject DKK agent context (domain principles, item types, CLI reference, current model summary). Use after compaction or topic drift.
+allowed-tools: mcp__dkk__prime
+---
+
+Call `mcp__dkk__prime` with default arguments and read the response. After loading, briefly confirm the number of contexts, items, and ADRs currently in the model. Do not summarize the prime content itself — the user just needs the agent to be re-primed.

package/tools/dkk/claude/commands/dkk-review.md

@@ -0,0 +1,12 @@
+---
+description: Review the current change for DKK domain impact. Delegates to the dkk-domain-reviewer subagent in an isolated context.
+argument-hint: [pr-number | git-range]
+---
+
+Invoke the `dkk-domain-reviewer` subagent. Pass through `$ARGUMENTS` as the input scope:
+
+- If `$ARGUMENTS` is empty, instruct the subagent to review the working-tree diff (`git status` + `git diff`).
+- If `$ARGUMENTS` looks like a number or `#NNN`, instruct it to run `gh pr diff <number>` and review that PR.
+- Otherwise, treat `$ARGUMENTS` as a git range (e.g. `origin/main...HEAD`) and pass it through.
+
+Wait for the subagent's report. Display it verbatim to the user. Do not perform the review yourself.

package/tools/dkk/claude/commands/dkk-story.md

@@ -0,0 +1,12 @@
+---
+description: Generate a user story or epic from a DKK flow using the dkk-story-analyst skill.
+argument-hint: <flow-id-or-feature-name>
+---
+
+Invoke the `dkk-story-analyst` skill. The user's target is `$ARGUMENTS`.
+
+- If `$ARGUMENTS` is empty, ask the user which flow to draft a story for, or list available flows via `mcp__dkk__list` (filter `type: flow`).
+- If `$ARGUMENTS` looks like a flow id (`flow.<Name>` or bare `<Name>`), pass it through to `mcp__dkk__story`.
+- Otherwise, run `mcp__dkk__search` with `$ARGUMENTS` first to identify the matching flow or root command, then proceed.
+
+Follow the skill's workflow end to end, including clarifying questions and acceptance-criteria mapping.

package/tools/dkk/claude/hooks/post-edit-validate.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — auto-validate after edits to domain YAML.
+ *
+ * When Claude Code edits or writes a file under `.dkk/domain/`, run
+ * `dkk validate` so any broken cross-references or schema violations
+ * surface back into the agent loop immediately, before the next step.
+ *
+ * Stays silent for unrelated edits (no-op, exit 0).
+ */
+import { spawnSync } from "node:child_process";
+
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath =
+    payload?.tool_input?.file_path ??
+    payload?.tool_input?.notebook_path ??
+    "";
+
+  // Only act on domain YAML edits.
+  const isDomainYaml = /\.dkk\/domain\/.*\.ya?ml$/.test(filePath);
+  if (!isDomainYaml) process.exit(0);
+
+  const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+  const res = spawnSync("dkk", ["validate", "--json", "--minify"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  // Tooling problem (dkk not on PATH, spawn error, etc.) — surface a clear
+  // setup error to the user, but don't block the agent with a phantom
+  // "validation failure" it has no way to fix.
+  if (res.error?.code === "ENOENT") {
+    process.stderr.write(
+      "dkk post-edit hook: 'dkk' CLI not found on PATH — install with `npm i -g domain-knowledge-kit` to enable auto-validation.\n",
+    );
+    process.exit(1);
+  }
+  if (res.error) {
+    process.stderr.write(
+      `dkk post-edit hook: failed to invoke validator — ${res.error.message}\n`,
+    );
+    process.exit(1);
+  }
+
+  // If validate fails, surface the JSON output to the model via stderr (exit 2
+  // makes Claude Code feed stderr back as a tool-result correction signal).
+  if (res.status !== 0) {
+    const body =
+      res.stdout ||
+      res.stderr ||
+      "(validator exited non-zero with no output — likely a tooling/wiring problem, not a domain issue)";
+    process.stderr.write(
+      `dkk validate failed after edit to ${filePath}:\n${body}\n`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+});

package/tools/dkk/claude/hooks/pre-edit-block-generated.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook — block writes to generated/derived directories.
+ *
+ * `.dkk/docs/` is regenerated from YAML by `dkk render`. Edits there are
+ * always lost on the next render, so we block the tool call up-front and
+ * tell the agent to edit the source YAML instead.
+ *
+ * Same treatment for `dist/` (TypeScript build output).
+ */
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = payload?.tool_input?.file_path ?? "";
+  if (!filePath) process.exit(0);
+
+  if (/\.dkk\/docs\//.test(filePath)) {
+    process.stderr.write(
+      `Blocked: ${filePath} is generated by \`dkk render\`. Edit the YAML under .dkk/domain/ and re-render instead.\n`,
+    );
+    process.exit(2);
+  }
+
+  if (/\/dist\//.test(filePath)) {
+    process.stderr.write(
+      `Blocked: ${filePath} is build output. Edit the source under src/ and run \`npm run build\`.\n`,
+    );
+    process.exit(2);
+  }
+
+  process.exit(0);
+});

package/tools/dkk/claude/hooks/session-start-prime.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook — pipe `dkk prime` output into Claude Code's context.
+ *
+ * The hook prints the agent context document (item types, retrieval/update
+ * workflows, current domain summary) to stdout, which Claude Code surfaces
+ * as additional context for the session. Any errors fall through silently
+ * so a missing domain model never blocks session start.
+ */
+import { spawnSync } from "node:child_process";
+
+const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+const res = spawnSync("dkk", ["prime"], { cwd: repoRoot, encoding: "utf8" });
+if (res.status === 0 && res.stdout) {
+  process.stdout.write(res.stdout);
+}
+// Always exit 0 — never block session start over a missing `dkk` binary or
+// an empty/absent domain model. Priming is a best-effort context boost.
+process.exit(0);

package/tools/dkk/claude/hooks/stop-validate.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — final validation gate before the agent ends a turn.
+ *
+ * Runs `dkk validate`. If the domain model is invalid, returns exit code 2
+ * with the JSON error report on stderr. Claude Code feeds that back so the
+ * agent must fix the broken model before declaring the work complete.
+ *
+ * `stop_hook_active` is honoured to prevent infinite loops if Claude tries
+ * to stop again after the hook already fired once.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+let raw = "";
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  if (payload?.stop_hook_active) {
+    process.exit(0);
+  }
+
+  const repoRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+  // No domain model? Nothing to gate on.
+  if (!existsSync(resolve(repoRoot, ".dkk/domain"))) process.exit(0);
+
+  const res = spawnSync("dkk", ["validate", "--json", "--minify"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  // Tooling problem (dkk not on PATH, spawn error, etc.) — surface a clear
+  // setup error to the user, but don't block the agent with a phantom
+  // "domain failure" it has no way to fix.
+  if (res.error?.code === "ENOENT") {
+    process.stderr.write(
+      "dkk stop hook: 'dkk' CLI not found on PATH — install with `npm i -g domain-knowledge-kit` to enable the domain validation gate.\n",
+    );
+    process.exit(1);
+  }
+  if (res.error) {
+    process.stderr.write(
+      `dkk stop hook: failed to invoke validator — ${res.error.message}\n`,
+    );
+    process.exit(1);
+  }
+
+  if (res.status !== 0) {
+    const body =
+      res.stdout ||
+      res.stderr ||
+      "(validator exited non-zero with no output — likely a tooling/wiring problem, not a domain issue)";
+    process.stderr.write(
+      `Domain validation failed — fix these before ending the turn:\n${body}\n`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+});

package/tools/dkk/claude/settings.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(dkk list:*)",
+      "Bash(dkk show:*)",
+      "Bash(dkk summary:*)",
+      "Bash(dkk search:*)",
+      "Bash(dkk related:*)",
+      "Bash(dkk graph:*)",
+      "Bash(dkk locate:*)",
+      "Bash(dkk story:*)",
+      "Bash(dkk validate:*)",
+      "Bash(dkk stats:*)",
+      "Bash(dkk prime:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-prime.mjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit-block-generated.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-validate.mjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validate.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/tools/dkk/claude/skills/dkk-adr-author/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: dkk-adr-author
+description: Draft a new Architecture Decision Record grounded in the local Domain Knowledge Pack. Use when the user wants to record an architectural decision, capture a trade-off, document a tech choice, or formalize a discussion as an ADR.
+---
+
+# ADR Author
+
+Use this skill whenever the user wants to **record an architectural decision, draft an ADR, or capture a trade-off** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **The DKK model is the single source of truth.** Every ADR must link to the domain items it constrains, bidirectionally. Skipping that link is the most common failure mode this skill prevents.
+
+## Preferred tools
+
+1. `mcp__dkk__search` (with `type: adr`) — find related existing ADRs
+2. `mcp__dkk__show` — read those ADRs in full
+3. `mcp__dkk__search` and `mcp__dkk__related` — identify which domain items the decision affects
+4. `mcp__dkk__locate` — get absolute paths to edit the linked items
+5. `mcp__dkk__validate` — final correctness check
+6. `dkk new adr "<title>"` (Bash) — scaffold the file with the right number and frontmatter
+7. `dkk render` (Bash) — refresh docs and search index after the ADR is finished
+
+Use the equivalent `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Search prior ADRs first.** Call `mcp__dkk__search` with the topic and `type: adr`. Read every related ADR via `mcp__dkk__show`. If a *current* ADR already covers the decision, do not create a new one — update the existing record (with `superseded_by` if direction has changed). If a *deprecated* ADR is relevant, surface its rationale to the user; do not relitigate without acknowledging it.
+2. **Identify affected domain items.** From the user's description, search the model and use `mcp__dkk__related` to find aggregates, events, commands, policies, and read models the decision constrains. Confirm the list with the user.
+3. **Clarify the decision.** Ask **2–5 targeted questions** before drafting. Derive each question and its options from the search results and the user's stated motivation. Skip questions only when the decision is fully specified and uncontroversial. Examples (only if relevant):
+   - What problem prompted the decision? (constraint / incident / new requirement / cleanup)
+   - What alternatives were considered, and why were they rejected?
+   - Which domain items are constrained by this decision?
+   - What is the status — Proposed (needs review), Accepted (in effect), or Deprecated (recording history)?
+   - Does this supersede a prior ADR? If yes, which one?
+4. **Scaffold via the CLI.** Run `dkk new adr "<title>"` — this auto-increments the number and creates the file with valid frontmatter and the canonical section structure. Do not hand-create the file.
+5. **Fill the body.** The canonical sections are *Context*, *Decision*, *Consequences*, and *Alternatives Considered*. Use precise domain terminology — match every name to the items returned by `mcp__dkk__search` and `mcp__dkk__show`.
+6. **Set the bidirectional links.** Both sides must agree:
+   - In the ADR frontmatter, set `domain_refs:` to the list of affected item ids (e.g. `ordering.OrderPlaced`, `actor.Customer`).
+   - On every linked domain item's YAML, append the new ADR id to its `adr_refs:` list. Use `mcp__dkk__locate` to find each file.
+7. **Run quality gates.** The post-edit hook runs `mcp__dkk__validate` automatically; before declaring the work done, also run `dkk render` to refresh `.dkk/docs/` and rebuild the search index.
+
+## Status discipline
+
+- **Proposed** — newly drafted, awaiting team review. The decision is not in effect yet.
+- **Accepted** — the decision is in effect; new code must comply.
+- **Deprecated** — no longer in effect, but kept as project memory. If a successor exists, set `superseded_by: adr-NNNN` in the frontmatter.
+
+Never delete an ADR. Even superseded ones are institutional memory.
+
+## Don'ts
+
+- Don't draft an ADR that doesn't reference at least one domain item (the bidirectional link is what makes ADRs queryable).
+- Don't invent domain terms in the ADR body — every name must exist in the model.
+- Don't hand-edit the ADR filename or number; let `dkk new adr` assign it.
+- Don't skip searching for prior ADRs — relitigating a decided question without referencing the prior ADR is the worst failure mode.

package/tools/dkk/claude/skills/dkk-flow-implementer/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: dkk-flow-implementer
+description: Guide a developer through framework-agnostic implementation of a DKK flow. Use when the user asks to implement, build, or code a flow or feature that maps to a flow in the local Domain Knowledge Pack.
+---
+
+# Flow Implementer
+
+Use this skill whenever the user asks to **implement, build, or code a flow / feature** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **Source of truth is local.** Do not look for or reference external trackers (Jira, GitHub Issues, Linear, Trello, etc.) for requirements. The local DKK model — accessed through the MCP `dkk` server or the `dkk` CLI — is authoritative.
+
+## Preferred tools
+
+Call MCP tools rather than shelling out, in this order of preference:
+
+1. `mcp__dkk__story` — full flow context (actors, ordered steps, policies, BDD examples, ADRs, downstream effects) in one call
+2. `mcp__dkk__list` — to discover available flows when the user hasn't named one
+3. `mcp__dkk__search` — to locate a flow when the user gives a feature name instead of an id
+4. `mcp__dkk__related` — to extend blast radius beyond the immediate flow
+5. `mcp__dkk__show` — to read the full definition of a specific item
+6. `mcp__dkk__validate` — final correctness check after edits
+
+Fall back to the equivalent `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Identify the flow.** If the user gave an id, normalize it (`flow.<Name>` or bare `<Name>`). Otherwise call `mcp__dkk__list` filtered by `type: flow`, or `mcp__dkk__search` on the feature name to find a candidate flow or root command.
+2. **Retrieve full context.** Call `mcp__dkk__story` with the flow id. Read the actors, ordered steps, triggered policies, BDD examples, ADRs, and downstream effects.
+3. **Clarify scope.** Ask **1–7 clarifying questions** before generating any checklist. Derive every question, its options, and your recommended default from the actual story output and the project's conventions — never use a fixed list. Each question must offer concrete options with one marked as recommended. **Skip the questions entirely** for trivial flows (≤2 steps, no cross-context effects, no ambiguity). Questions should target implementation behavior and UX, e.g.:
+   - What should the user see immediately after this command succeeds?
+   - How should validation errors surface (inline / toast / page-level)?
+   - Optimistic UI or wait-for-confirmation?
+   - Concurrency: can two users trigger this simultaneously?
+   - Is there an undo path, or one-way?
+4. **Present architectural constraints.** List every ADR returned in the story output (`adr-NNNN — title — status`). Ask the user to acknowledge these before implementation begins. If the agent identifies any ADR conflict with the user's stated approach, surface it before proceeding.
+5. **Generate a framework-agnostic checklist.** Group by domain role:
+   - **Aggregates** — entities, state transitions, invariants
+   - **Commands** — handlers, preconditions, validations
+   - **Events** — what to publish on success
+   - **Policies** — reactive logic triggered by events
+   - **Read models** — projections to update on events
+6. **Walk through interactively.** Ask the user which checklist item they want to tackle first. Guide on the **domain logic** — invariants, policies, transitions — not framework boilerplate. Only emit framework-specific code if the user explicitly asks or `AGENTS.md` / `CLAUDE.md` directs otherwise.
+7. **Use the canonical nouns.** Whatever names appear in the `mcp__dkk__story` output are the only allowed names. Do not rename `OrderBasket` to `ShoppingCart`.
+8. **Validate and render after structural changes.** When the user's implementation requires new or modified domain items, use the DKK CLI commands (`dkk add`, `dkk rename`, `dkk rm`) for structural changes and edit YAML directly only for content. The post-edit hook will run `mcp__dkk__validate` automatically; before declaring the work done, also run `dkk render` to refresh docs and the search index.
+
+## Interaction rules
+
+- Do not generate full boilerplate up front. Wait for the user to request code for a specific checklist item.
+- Confirm with the user before moving to the next checklist item.
+- If the user asks for a framework-specific implementation, defer to `AGENTS.md` or `CLAUDE.md` conventions.
+- Never invent domain terms. If a needed concept is missing from the model, surface it as a gap and propose adding it via `dkk add` rather than coding around it.