domain-knowledge-kit 0.2.9 → 0.2.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -139
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,147 +1,42 @@
|
|
|
1
1
|
# Domain Knowledge Kit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
EOF
|
|
29
|
-
|
|
30
|
-
# One file per domain item
|
|
31
|
-
cat > .dkk/domain/contexts/ordering/events/OrderPlaced.yml << 'EOF'
|
|
32
|
-
name: OrderPlaced
|
|
33
|
-
description: Raised when a customer order is confirmed.
|
|
34
|
-
raised_by: Order
|
|
35
|
-
EOF
|
|
36
|
-
|
|
37
|
-
cat > .dkk/domain/contexts/ordering/commands/PlaceOrder.yml << 'EOF'
|
|
38
|
-
name: PlaceOrder
|
|
39
|
-
description: Submit a new customer order.
|
|
40
|
-
handled_by: Order
|
|
41
|
-
EOF
|
|
42
|
-
|
|
43
|
-
cat > .dkk/domain/contexts/ordering/aggregates/Order.yml << 'EOF'
|
|
44
|
-
name: Order
|
|
45
|
-
description: Manages order state and invariants.
|
|
46
|
-
handles:
|
|
47
|
-
commands:
|
|
48
|
-
- PlaceOrder
|
|
49
|
-
emits:
|
|
50
|
-
events:
|
|
51
|
-
- OrderPlaced
|
|
52
|
-
EOF
|
|
53
|
-
|
|
54
|
-
# Register it in .dkk/domain/index.yml
|
|
55
|
-
# Add "- name: ordering" to the contexts array
|
|
56
|
-
|
|
57
|
-
# Validate and render
|
|
58
|
-
dkk validate
|
|
59
|
-
dkk render
|
|
60
|
-
|
|
61
|
-
# Explore
|
|
62
|
-
dkk search "order"
|
|
63
|
-
dkk show ordering.OrderPlaced
|
|
64
|
-
dkk related ordering.Order
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
→ **[Full Getting Started Guide](docs/getting-started.md)** — step-by-step walkthrough with examples.
|
|
3
|
+
> *Humans design the domain. AI agents align the codebase.*
|
|
4
|
+
|
|
5
|
+
## Philosophy
|
|
6
|
+
|
|
7
|
+
### AI agents love structure
|
|
8
|
+
|
|
9
|
+
Large language models thrive with well-structured, unambiguous context. A flat codebase gives them syntax; a structured domain model gives them **meaning**. DKK makes your domain a first-class, machine-readable citizen of your repository.
|
|
10
|
+
|
|
11
|
+
### Humans can define domain events easily
|
|
12
|
+
|
|
13
|
+
You don't need a diagram tool or a modeling session. Writing `OrderPlaced` in a YAML file — with a one-line description and a reference to the aggregate that emits it — is how humans naturally think in DDD. Defining events, commands, and policies in plain YAML reveals the bigger picture without drowning in implementation details.
|
|
14
|
+
|
|
15
|
+
### Reading domain models beats reading code
|
|
16
|
+
|
|
17
|
+
Business logic spread across services, handlers, and database schemas is hard to reason about holistically. A domain model is a curated, intentional view of *what your system does and why* — not *how* it does it. DKK keeps that view always up-to-date and always searchable.
|
|
18
|
+
|
|
19
|
+
### Keeping ADRs, even deprecated ones, preserves project memory
|
|
20
|
+
|
|
21
|
+
Architectural decisions aren't born in a vacuum. Understanding *why* a choice was made matters as much as knowing *what* the choice was. Deprecated ADRs aren't noise — they are the institutional memory that prevents teams (and AI agents) from relitigating past decisions.
|
|
22
|
+
|
|
23
|
+
### Easy-to-reach, detailed, colocated knowledge for AI agents
|
|
24
|
+
|
|
25
|
+
Knowledge that lives next to the code is knowledge that gets used. DKK colocates your domain model, ADRs, and generated docs inside the repository itself. AI agents can discover, query, and traverse this knowledge without leaving the codebase — making every interaction domain-aware.
|
|
26
|
+
|
|
27
|
+
---
|
|
68
28
|
|
|
69
29
|
## Documentation
|
|
70
30
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
|
74
|
-
|
|
75
|
-
| **[
|
|
76
|
-
| **[
|
|
77
|
-
| **[
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
dkk validate # Schema + cross-reference validation
|
|
83
|
-
dkk render # Validate → render docs → rebuild search index
|
|
84
|
-
dkk search "payment" # Full-text search with ranking
|
|
85
|
-
dkk show ordering.Order # Display full item definition
|
|
86
|
-
dkk related ordering.Order # Graph traversal of connected items
|
|
87
|
-
dkk list --type event # List all events across contexts
|
|
88
|
-
dkk init # Set up AI agent onboarding
|
|
89
|
-
dkk prime # Output agent context to stdout
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
→ **[Full CLI Reference](docs/cli-reference.md)**
|
|
93
|
-
|
|
94
|
-
## AI Agent Integration
|
|
95
|
-
|
|
96
|
-
DKK has first-class support for AI coding agents. Two commands get you set up:
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
dkk init # Add a DKK section to AGENTS.md (idempotent)
|
|
100
|
-
dkk prime # Output full domain context for AI consumption
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Agents can then search, show, and traverse your domain model — making domain-aware decisions when writing, reviewing, or refactoring code. DKK also ships with GitHub Copilot instructions, reusable agent prompts, and a portable agent skill.
|
|
104
|
-
|
|
105
|
-
→ **[AI Agent Integration Guide](docs/ai-agent-integration.md)**
|
|
106
|
-
|
|
107
|
-
## Directory Layout
|
|
108
|
-
|
|
109
|
-
```
|
|
110
|
-
.dkk/ # Domain model + generated + managed
|
|
111
|
-
domain/ # Domain model (YAML)
|
|
112
|
-
index.yml # Contexts + flows
|
|
113
|
-
actors.yml # Global actors
|
|
114
|
-
contexts/ # Bounded contexts (one dir each)
|
|
115
|
-
<name>/ # Context directory
|
|
116
|
-
context.yml # Context metadata + glossary
|
|
117
|
-
events/ # One .yml file per event
|
|
118
|
-
commands/ # One .yml file per command
|
|
119
|
-
aggregates/ # One .yml file per aggregate
|
|
120
|
-
policies/ # One .yml file per policy
|
|
121
|
-
read-models/ # One .yml file per read model
|
|
122
|
-
adr/ # Architecture Decision Records
|
|
123
|
-
docs/ # Generated docs (do not edit)
|
|
124
|
-
src/ # Source code (vertical slices)
|
|
125
|
-
tools/dkk/ # Schemas + templates
|
|
126
|
-
schema/ # JSON Schemas for validation
|
|
127
|
-
templates/ # Handlebars templates for rendering
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
## Contributing / Local Development
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
npm install
|
|
134
|
-
|
|
135
|
-
# Run directly via tsx (no build step needed)
|
|
136
|
-
npm run dev -- validate
|
|
137
|
-
npm run dev -- render
|
|
138
|
-
|
|
139
|
-
# Or build first
|
|
140
|
-
npm run build
|
|
141
|
-
npx dkk validate
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
The source code uses **vertical feature slices** — each feature (`query`, `adr`, `pipeline`, `agent`) owns its commands, logic, and tests. Cross-cutting infrastructure lives in `shared/`.
|
|
31
|
+
All technical details, CLI references, and integration guides live in the [`docs/`](docs/) folder.
|
|
32
|
+
|
|
33
|
+
| Guide | What It Covers |
|
|
34
|
+
|-------|----------------|
|
|
35
|
+
| **[Getting Started](docs/getting-started.md)** | Installation, first context, quality gates |
|
|
36
|
+
| **[Domain Modeling](docs/domain-modeling.md)** | YAML structure, item types, naming conventions |
|
|
37
|
+
| **[CLI Reference](docs/cli-reference.md)** | Every command and flag |
|
|
38
|
+
| **[ADR Guide](docs/adr-guide.md)** | Writing, linking, and querying ADRs |
|
|
39
|
+
| **[AI Agent Integration](docs/ai-agent-integration.md)** | Onboarding agents, context-efficient retrieval |
|
|
145
40
|
|
|
146
41
|
## License
|
|
147
42
|
|