domain-knowledge-kit 0.2.15 → 0.2.19

package/tools/dkk/claude/skills/dkk-story-analyst/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: dkk-story-analyst
+description: Generate, split, or reshape user stories and epics from the local Domain Knowledge Pack. Use when the user asks to write, draft, refine, or split a user story or epic for a feature that maps to a DKK flow or command.
+---
+
+# Story Analyst
+
+Use this skill whenever the user asks to **write, draft, generate, refine, or split a user story or epic** in a project that has a Domain Knowledge Pack (`.dkk/`).
+
+> **"User stories" and "epics" here are behavioral requirements derived from the local DDD/Event-Storming model in `.dkk/`.** Do not consult external trackers (Jira, GitHub Issues, Linear, Trello, etc.). The MCP `dkk` server (or the `dkk` CLI as fallback) is the only source of truth.
+
+## Preferred tools
+
+1. `mcp__dkk__story` — aggregate a flow's full context (actors, steps, policies, BDD examples, ADRs, downstream effects) in one call
+2. `mcp__dkk__list` filtered by `type: flow` — discover available flows
+3. `mcp__dkk__search` — locate a flow or command from a feature name
+4. `mcp__dkk__show` — fall back when no flow exists, to read a command directly
+5. `mcp__dkk__related` — to gather neighbours when working from a command instead of a flow
+
+Use the corresponding `dkk` shell commands only if the MCP server is unavailable.
+
+## Workflow
+
+1. **Identify the flow.** Normalize the id (`flow.<Name>` or bare `<Name>`). If the user gave a feature name instead, call `mcp__dkk__search` to locate a matching flow or root command.
+2. **Retrieve context.** Call `mcp__dkk__story` with the flow id. The response contains actors, ordered steps, triggered policies, BDD examples, ADRs, and downstream effects.
+3. **Clarify scope.** Ask **1–7 clarifying questions** before drafting. 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, 1 actor, no ambiguity). Target product behavior and story scope, e.g.:
+   - Which user-facing outcome matters most?
+   - Confirmation/feedback on success — how should it surface?
+   - On failure or rejection, what does the user experience?
+   - Optional steps that can be skipped, or strictly linear?
+   - Happy path only, or include edge cases?
+4. **Map to story format.**
+   - **As a** `<Actor from "Actors" section>`
+   - **I want to** `<Command description from Steps>`
+   - **So that** `<Flow description>`
+5. **Write acceptance criteria** from the policies and BDD examples in the output:
+   - Policies → Given/When/Then: *When [triggering event] → Then [consequent command]*
+   - BDD examples on commands and events are pre-written scenarios — use them directly or expand
+6. **Add an Architectural Constraints section** listing every ADR (`adr-NNNN — title — status`). Developers must respect these.
+7. **Add an Implementation Notes section** from the downstream effects: read models to update, secondary policies that fire.
+
+## Noun enforcement (mandatory)
+
+Use only the terminology in the `mcp__dkk__story` output. Do not:
+
+- Invent entity, command, or event names not present
+- Rename domain terms (if DKK says `OrderBasket`, the story says `OrderBasket`)
+- Reference bounded contexts not mentioned in the step refs
+- Pull names from external APIs or trackers
+
+If unsure whether a term is canonical, run `mcp__dkk__search` to verify.
+
+## Epic vs. story decision rules
+
+After retrieving the flow context:
+
+- **Single story** when the flow has ≤3 command steps and spans ≤1 bounded context.
+- **Epic with story slices** when the flow has >3 command steps **or** spans >1 bounded context. Slice by:
+  1. Group consecutive steps that share the same context prefix (all `ordering.*` steps → Story 1)
+  2. Each policy trigger becomes its own story ("As a system, when X happens, I want Y to be triggered, so that Z")
+  3. Each slice that produces an event consumed by a read model must include updating that read model in its scope or acceptance criteria
+
+When recommending an epic breakdown, present the slice boundaries and explain which downstream effects belong to each slice based on the model.
+
+## Story reshaping
+
+When asked to refine, split, or revise an existing story:
+
+1. Call `mcp__dkk__story` for the relevant flow to get current domain truth
+2. Compare the story's terminology to the output
+3. Flag mismatches: invented terms, missing actors, acceptance criteria that contradict policies
+4. Suggest corrections using exact DKK terminology
+5. Ensure the reshaped story still covers all downstream effects
+
+## Fallback: no flow exists
+
+If no flow has been modeled for the requested feature:
+
+1. Locate the most relevant command: `mcp__dkk__search` with `type: command`
+2. Get its full definition: `mcp__dkk__show`
+3. Get its neighbours: `mcp__dkk__related` with `depth: 2`
+4. Assemble the story from:
+   - Command `actor` → "As a..."
+   - Command `description` → "I want to..."
+   - Command `preconditions`, `rejections`, `examples` → acceptance criteria
+   - Neighbouring policies and read models → downstream effects
+5. Note in the story that no formal flow has been modeled, and recommend the team define one.
+
+## Output format
+
+```markdown
+## [Story Title]
+
+**As a** [Actor], **I want to** [action], **so that** [business value].
+
+### Acceptance Criteria
+
+- **Given** [precondition], **When** [command/event], **Then** [outcome]
+- (repeat for each policy rule and BDD example)
+
+### Architectural Constraints
+
+- [adr-NNNN]: [title] ([status])
+
+### Implementation Notes
+
+- [Downstream read models, secondary policy triggers, cross-context effects]
+```

package/tools/dkk/schema/actors.schema.json

@@ -37,7 +37,7 @@
           },
           "adr_refs": {
             "type": "array",
-            "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+            "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
             "uniqueItems": true,
             "description": "Related ADR identifiers"
           }

package/tools/dkk/schema/adr-frontmatter.schema.json

@@ -34,16 +34,16 @@
       "type": "array",
       "items": {
         "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
-        "description": "Domain item reference in context.Name format (e.g. ordering.OrderPlaced)"
+        "pattern": "^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+        "description": "Domain item reference in context.Name format (e.g. ordering.OrderPlaced, or service:context.Name for federated refs)"
       },
       "uniqueItems": true,
       "description": "Domain items related to this decision"
     },
     "superseded_by": {
       "type": "string",
-      "pattern": "^adr-\\d{4}$",
-      "description": "ID of the ADR that supersedes this one"
+      "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$",
+      "description": "ID of the ADR that supersedes this one (optionally service-qualified for peer ADRs)"
     }
   },
   "required": ["id", "title", "status", "date"],

package/tools/dkk/schema/aggregate.schema.json

@@ -48,7 +48,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/command.schema.json

@@ -66,7 +66,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/event.schema.json

@@ -56,7 +56,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/federation.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "federation.schema.json",
+  "title": "Federation Manifest",
+  "description": "Peer service manifest for multi-repo federation (.dkk/federation.yml). Each peer points at a filesystem path or a git URL+branch; the peer's `.dkk/` directory is loaded read-only alongside the local model.",
+  "type": "object",
+  "properties": {
+    "peers": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/peer" },
+      "description": "Peer services whose .dkk/ should be loaded alongside the local model."
+    }
+  },
+  "required": ["peers"],
+  "additionalProperties": false,
+  "definitions": {
+    "peer": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Kebab-case peer service name (must match the peer's own service.yml)."
+        },
+        "source": {
+          "oneOf": [
+            { "$ref": "#/definitions/localSource" },
+            { "$ref": "#/definitions/gitSource" }
+          ]
+        }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": false
+    },
+    "localSource": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "local" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute or repo-root-relative path to the peer's repository root."
+        }
+      },
+      "required": ["type", "path"],
+      "additionalProperties": false
+    },
+    "gitSource": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "git" },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Git URL (https or ssh)."
+        },
+        "branch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Branch to track."
+        },
+        "path": {
+          "type": "string",
+          "description": "Optional sub-path inside the peer repo where .dkk/ lives (default: repo root)."
+        }
+      },
+      "required": ["type", "url", "branch"],
+      "additionalProperties": false
+    }
+  }
+}

package/tools/dkk/schema/glossary.schema.json

@@ -23,7 +23,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers (e.g. adr-0001)"
     }

package/tools/dkk/schema/index.schema.json

@@ -46,8 +46,8 @@
               "properties": {
                 "ref": {
                   "type": "string",
-                  "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
-                  "description": "Domain item reference (context.Name)"
+                  "pattern": "^([a-z][a-z0-9-]*:)?[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+                  "description": "Domain item reference (context.Name, or service:context.Name for federated refs)"
                 },
                 "type": {
                   "type": "string",

package/tools/dkk/schema/policy.schema.json

@@ -43,7 +43,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/read-model.schema.json

@@ -43,7 +43,7 @@
     },
     "adr_refs": {
       "type": "array",
-      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "items": { "type": "string", "pattern": "^([a-z][a-z0-9-]*:)?adr-\\d{4}$" },
       "uniqueItems": true,
       "description": "Related ADR identifiers"
     }

package/tools/dkk/schema/service.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "service.schema.json",
+  "title": "Service Manifest",
+  "description": "Service identity for multi-repo federation (.dkk/service.yml). Declares this repo's service name and the bounded contexts it publishes for cross-repo consumption.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Kebab-case service identifier (e.g. \"ordering\"). Globally unique within an org."
+    },
+    "exports": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "uniqueItems": true,
+      "description": "Bounded-context names this service publishes for federation."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional human-readable description of the service."
+    }
+  },
+  "required": ["name", "exports"],
+  "additionalProperties": false
+}