domain-knowledge-kit 0.2.13 → 0.2.14

package/.github/skills/domain-knowledge/skill.md

@@ -0,0 +1,93 @@
+---
+name: domain-knowledge
+description: Portable Agent Skill for working with a Domain Knowledge Pack.
+---
+
+# Domain Knowledge Skill
+
+> Portable Agent Skill for working with a Domain Knowledge Pack.
+
+## Description
+
+This skill enables an AI agent to understand, query, and maintain a structured domain model defined in YAML with linked Architecture Decision Records (ADRs). The domain model follows Domain-Driven Design (DDD) patterns: bounded contexts, events, commands, policies, aggregates, read models, glossary terms, actors, and cross-context flows.
+
+## Canonical Model
+
+The domain model is stored as YAML files on disk:
+
+| Path | Content |
+|------|---------|
+| `domain/index.yml` | Registered bounded contexts and cross-context flows |
+| `domain/actors.yml` | Global actors (human, system, external) |
+| `domain/contexts/<name>.yml` | Bounded context: events, commands, policies, aggregates, read models, glossary |
+| `.dkk/adr/adr-NNNN.md` | Architecture Decision Records with YAML frontmatter linking to domain items |
+
+### Item Types
+
+| Type | Description | Key Fields |
+|------|-------------|------------|
+| **Event** | Something that happened in the domain | `name`, `description`, `fields`, `raised_by`, `adr_refs` |
+| **Command** | An instruction to change state | `name`, `description`, `fields`, `actor`, `handled_by`, `adr_refs` |
+| **Policy** | Reactive logic triggered by events | `name`, `description`, `when`, `then`, `adr_refs` |
+| **Aggregate** | Consistency boundary handling commands | `name`, `description`, `handles`, `emits`, `adr_refs` |
+| **Read Model** | Query-optimized projection | `name`, `description`, `subscribes_to`, `used_by`, `adr_refs` |
+| **Glossary** | Ubiquitous language term | `term`, `definition`, `aliases`, `adr_refs` |
+| **Actor** | Person or system interacting with the domain | `name`, `type`, `description`, `adr_refs` |
+| **Flow** | Cross-context sequence of steps | `name`, `description`, `steps[]` |
+
+### ID Conventions
+
+| Scope | Format | Example |
+|-------|--------|---------|
+| Context item | `<context>.<ItemName>` | `ordering.OrderPlaced` |
+| Actor | `actor.<Name>` | `actor.Customer` |
+| ADR | `adr-NNNN` | `adr-0001` |
+| Flow | `flow.<Name>` | `flow.OrderFulfillment` |
+| Context | `context.<name>` | `context.ordering` |
+
+## Retrieval Rules
+
+When answering questions about the domain, always query the model rather than guessing:
+
+1. **Search** — `npx tsx src/cli.ts search "<query>"` performs FTS5 full-text search with relevance ranking.
+2. **Show** — `npx tsx src/cli.ts show <id>` returns the full YAML definition of any item.
+3. **Related** — `npx tsx src/cli.ts related <id> --depth <n>` performs BFS graph traversal to find connected items.
+4. **List** — `npx tsx src/cli.ts list [--context <name>] [--type <type>]` enumerates items with optional filtering.
+5. **ADR links** — `npx tsx src/cli.ts adr related <id>` finds bidirectional ADR ↔ domain-item links.
+
+## Update Rules
+
+When modifying the domain model:
+
+1. **Edit YAML files directly** — never generate domain items from application code.
+2. **Maintain referential integrity:**
+   - `adr_refs` must point to existing ADRs in `.dkk/adr/`.
+   - `domain_refs` in ADR frontmatter must point to existing domain items.
+   - Cross-references (`handles`, `emits`, `triggers`, `subscribes_to`, `used_by`, `raised_by`, `handled_by`, `actor`) must resolve within the same context or to global actors.
+3. **Follow naming conventions:**
+   - Items: PascalCase (`OrderPlaced`, `PlaceOrder`).
+   - Contexts: kebab-case (`ordering`, `inventory-management`).
+   - ADR ids: `adr-NNNN` (zero-padded).
+4. **Run quality gates after every change:**
+   ```bash
+   npx tsx src/cli.ts validate   # Schema + cross-reference checks
+   npx tsx src/cli.ts render     # Validate → render docs → rebuild search index
+   ```
+5. **Update ADRs** when changes affect architectural decisions — add `domain_refs` to the ADR and `adr_refs` to the domain items.
+
+## Validation
+
+The validator checks:
+- **Schema conformance** — Each YAML file is validated against its JSON Schema (`tools/dkk/schema/`).
+- **Cross-references** — All item-to-item, item-to-ADR, and ADR-to-item references resolve correctly.
+- **Context registration** — Every context file in `domain/contexts/` is registered in `domain/index.yml`.
+
+## Generated Documentation
+
+Running `npx tsx src/cli.ts render` produces:
+- `.dkk/docs/index.md` — Top-level domain overview.
+- `.dkk/docs/<context>/index.md` — Per-context overview.
+- `.dkk/docs/<context>/<ItemName>.md` — Per-item detail page.
+- SQLite FTS5 search index for the `search` command.
+
+Do not edit files under `.dkk/docs/` by hand; they are regenerated on each render.

package/.github/skills/flow-implementer/skill.md

@@ -0,0 +1,40 @@
+---
+name: flow-implementer
+description: Portable Agent Skill for guiding developers through framework-agnostic implementation of a flow based on a Domain Knowledge Pack.
+---
+
+# Flow Implementer Skill
+
+> Portable Agent Skill for guiding developers through framework-agnostic implementation of a flow based on a Domain Knowledge Pack.
+
+## Description
+
+This skill enables an AI agent to guide developers through implementing a specific predefined flow. It uses the `dkk story` command to gather the full domain context, checks architectural constraints, and provides step-by-step, framework-agnostic guidance checklists. It focuses on domain invariants, policies, and behavior rather than generating rigid application boilerplate code.
+
+## Primary Command
+
+```bash
+dkk story <flow-id>        # Aggregate full story context (markdown)
+dkk story <flow-id> --json # Machine-readable output for agents
+```
+
+## Implementation Guidance Workflow
+
+When asked to implement, build, or code a flow/feature:
+
+1. **Identify the flow** — Ask the user for the relevant flow ID if not provided, or search for it: \`dkk list --type flow\`.
+2. **Retrieve full context** — Run \`dkk story <flow-id>\` or \`dkk story <flow-id> --json\` to obtain domain rules.
+3. **Present Architectural Constraints** — Before any implementation begins, output the ADRs (Architecture Decision Records) from the context. Ask the user to acknowledge these constraints before proceeding.
+4. **Generate Implementation Checklist** — Create a logical, framework-agnostic checklist of work needed. Typical buckets include:
+   - **Domain/Aggregates**: Entities, state transitions, and invariants to model.
+   - **Commands/Controllers**: Handlers for incoming commands, preconditions, and validations.
+   - **Events**: Domain events to be explicitly published upon successful command validation.
+   - **Policies**: Side-effects and reactive logic that triggers when events occur.
+   - **Read Models**: Projections that need to be updated in response to events.
+5. **Interactive Step-by-step Delivery** — Ask the user which checklist item they want to tackle first. Guide them through the logic without writing framework-specific boilerplate initially (unless explicitly requested by the user's overarching project instructions). Keep guidance focused on the domain logic, invariants, and policies defined in the \`dkk story\` output.
+6. **Noun Enforcement (MANDATORY)** — You MUST use the exact terminology defined in the DKK output. Do not invent new names for entities, commands, or events.
+
+## Interaction Rules
+- Do NOT generate full boilerplate application code initially. Wait for the user to request code generation for a specific checklist item.
+- DO ask the user for confirmation before moving to the next checklist item.
+- DO reference project-level \`.github/copilot-instructions.md\` if the user asks for framework-specific implementations later on.

package/.github/skills/story-analyst/skill.md

@@ -0,0 +1,105 @@
+---
+name: story-analyst
+description: Portable Agent Skill for generating, splitting, and reshaping user stories from a Domain Knowledge Pack.
+---
+
+# Story Analyst Skill
+
+> Portable Agent Skill for generating, splitting, and reshaping user stories from a Domain Knowledge Pack.
+
+## Description
+
+This skill enables an AI agent to generate accurate, domain-grounded user stories, epics, and acceptance criteria by leveraging the structured domain model managed by DKK. It uses the `dkk story` command to aggregate a flow's complete context in a single call, then maps that context onto standard Agile story formats.
+
+## Primary Command
+
+```bash
+dkk story <flow-id>        # Aggregate full story context (markdown)
+dkk story <flow-id> --json # Machine-readable output for agents
+```
+
+Accepts both `flow.Name` and bare `Name` (auto-prefixes `flow.`).
+
+## Story Generation Workflow
+
+When asked to write, draft, or generate a user story:
+
+1. **Identify the flow** — Ask the user for the relevant flow ID, or search for it: `dkk list --type flow`. If the user provides a feature name, run `dkk search "<feature>"` to locate the matching flow or command.
+2. **Retrieve full context** — Run `dkk story <flow-id>`. This returns actors, ordered steps, triggered policies, BDD examples, ADRs, and downstream effects in one call.
+3. **Map to story format** using the output:
+   - **As a** `[Actor from "Actors" section]`
+   - **I want to** `[Command description from Steps]`
+   - **So that** `[Flow description]`
+4. **Write acceptance criteria** from the "Policies" and "BDD Examples" sections:
+   - Policies provide the **Given/When/Then** structure: When [triggering event] → Then [consequent command]
+   - BDD Examples from commands and events are pre-written scenarios — use them directly or expand them
+5. **Add an Architectural Constraints section** listing all ADRs from the output. Developers must respect these when implementing the story.
+6. **Add an Implementation Notes section** from "Downstream Effects": read models that must be updated, secondary policies that will fire.
+
+## Noun Enforcement (MANDATORY)
+
+Only use terminology present in the `dkk story` output. Never:
+- Invent entity names, command names, or event names not in the output
+- Rename domain terms (if DKK says `OrderBasket`, the story must not say `ShoppingCart`)
+- Reference bounded contexts not mentioned in the step refs
+
+If you are uncertain whether a term is canonical, run `dkk search "<term>"` to verify.
+
+## Epic vs. Story Decision Rules
+
+After retrieving the flow context, apply these rules:
+
+- **Single story:** Flow has ≤3 command steps and spans ≤1 bounded context.
+- **Epic with story slices:** Flow has >3 command steps OR spans >1 bounded context. Slice by:
+  1. Group consecutive steps that share the same bounded context prefix (e.g., all `ordering.*` steps → Story 1)
+  2. Each policy trigger becomes an explicit 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 explicitly 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.
+
+## Story Reshaping Workflow
+
+When asked to refine, split, or revise an existing story:
+
+1. Run `dkk story <flow-id>` for the relevant flow to get the current domain truth
+2. Compare the story's entities and terminology against the DKK output
+3. Flag any 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 (read models, secondary policies)
+
+## Fallback: No Flow Exists
+
+If no flow has been defined for the requested feature:
+
+1. Locate the most relevant command: `dkk search "<feature>" --type command`
+2. Get its full definition: `dkk show <command-id>`
+3. Get its graph neighbors: `dkk related <command-id> --depth 2`
+4. Assemble the story from:
+   - Command `actor` field → "As a..."
+   - Command `description` → "I want to..."
+   - Command `preconditions`, `rejections`, `examples` → acceptance criteria
+   - Neighboring policies and read models → downstream effects
+5. Note in the story that no formal flow has been modeled for this feature and recommend the team define one
+
+## Output Format
+
+Use this markdown structure for generated stories:
+
+```markdown
+## [Story Title]
+
+**As a** [Actor], **I want to** [action], **so that** [business value].
+
+### Acceptance Criteria
+
+- **Given** [precondition], **When** [command/event], **Then** [expected 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-knowledge-kit",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "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/",
+    ".github/skills/",
     "LICENSE",
     "README.md"
   ],