@kaddo/cli 3.113.0 → 3.114.0
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 +199 -452
- package/dist/core.js +26 -8
- package/dist/index.js +118 -84
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,558 +1,305 @@
|
|
|
1
|
+
<!-- Generated from /README.md by scripts/sync-npm-readme.mjs. Run `pnpm npm-readme:sync`; do not edit directly. -->
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src="https://raw.githubusercontent.com/Kaddo-kdd/kaddo/main/assets/banner.png" alt="Kaddo — Knowledge Driven Development Toolkit" width="100%" />
|
|
3
5
|
</p>
|
|
4
6
|
|
|
5
7
|
# Kaddo — Knowledge Driven Development
|
|
6
8
|
|
|
7
|
-
>
|
|
8
|
-
|
|
9
|
-
Kaddo is an open source CLI toolkit based on **Knowledge Driven Development (KDD)**. It helps teams keep the minimum necessary context alive next to the code — without turning development into bureaucracy.
|
|
10
|
-
|
|
11
|
-
## Why Kaddo
|
|
12
|
-
|
|
13
|
-
Projects fail or degrade because knowledge is scattered across meetings, chats, tickets, emails, and outdated documents. With AI, this problem gets worse: agents build on assumptions when they lack context.
|
|
9
|
+
> **Prepare any codebase for AI-assisted evolution.**
|
|
10
|
+
> Kaddo helps your repo remember why the code exists.
|
|
14
11
|
|
|
15
|
-
Kaddo
|
|
12
|
+
Kaddo is an open-source **Knowledge Driven Development (KDD) toolkit** for AI-assisted
|
|
13
|
+
software engineering. It scans your repo, structures product knowledge into four layers
|
|
14
|
+
(Business, Product, Tech, Delivery), manages the full Work Item lifecycle — from captured
|
|
15
|
+
intent through implementation handoff, evidence collection and verification — and keeps
|
|
16
|
+
knowledge alive as the system evolves.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## What Kaddo is not
|
|
20
|
-
|
|
21
|
-
- Not a code generator
|
|
22
|
-
- Not an agent framework
|
|
23
|
-
- Not a replacement for Jira, Linear, or documentation tools
|
|
24
|
-
- Not a platform
|
|
18
|
+
It works in two layers:
|
|
25
19
|
|
|
26
|
-
|
|
20
|
+
- **The CLI** does the deterministic work — no AI, no API key.
|
|
21
|
+
- **Your LLM** does the interpretation — using Kaddo agents in your chat (Claude, ChatGPT,
|
|
22
|
+
Cursor, Copilot, Windsurf…).
|
|
27
23
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
Agent frameworks
|
|
32
|
-
↓
|
|
33
|
-
Specifications
|
|
34
|
-
↓
|
|
35
|
-
Kaddo
|
|
36
|
-
↓
|
|
37
|
-
Product knowledge
|
|
38
|
-
```
|
|
24
|
+
> **Knowledge Driven Development ≠ Kaddo.** KDD is a prior concept in software engineering and
|
|
25
|
+
> knowledge management. Kaddo is a **practical implementation of KDD principles** — it applies
|
|
26
|
+
> them; it did not invent them.
|
|
39
27
|
|
|
40
|
-
##
|
|
28
|
+
## Quick Start
|
|
41
29
|
|
|
42
30
|
```bash
|
|
43
|
-
npx @kaddo/cli init
|
|
31
|
+
npx @kaddo/cli init # configure project state, structure & language (en/es)
|
|
32
|
+
kaddo bootstrap # new projects: seed Business → Product → Tech → Delivery knowledge
|
|
33
|
+
kaddo scan # deterministic technical inventory → .kaddo/scan.json
|
|
34
|
+
kaddo add agents # install agent prompt packs
|
|
35
|
+
kaddo context # LLM context pack → .kaddo/context-pack.md
|
|
36
|
+
kaddo understand # guided CLI → LLM handoff plan
|
|
44
37
|
```
|
|
45
38
|
|
|
46
|
-
|
|
39
|
+
Then use your LLM with the context pack and agents to extract capabilities, architecture and
|
|
40
|
+
a roadmap. Continue the delivery loop:
|
|
47
41
|
|
|
48
42
|
```bash
|
|
49
|
-
|
|
50
|
-
kaddo
|
|
43
|
+
kaddo create --from roadmap # roadmap candidate → Work Item draft
|
|
44
|
+
kaddo verify # evidence collection + AC verification
|
|
45
|
+
kaddo owners suggest # declare code: ownership
|
|
46
|
+
kaddo guard # detect possible knowledge drift
|
|
47
|
+
kaddo explain # summarize what Kaddo currently knows
|
|
51
48
|
```
|
|
52
49
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
### `kaddo init`
|
|
50
|
+
**Lost? Run `kaddo understand`** — it always answers *"What should I do now?"* from the
|
|
51
|
+
real state of your project.
|
|
56
52
|
|
|
57
|
-
|
|
53
|
+
## The Knowledge Model
|
|
58
54
|
|
|
59
|
-
|
|
60
|
-
kaddo init
|
|
61
|
-
```
|
|
55
|
+
Kaddo organizes project knowledge into four layers under `knowledge/`:
|
|
62
56
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
work-items/ ← one file per work item
|
|
70
|
-
.kaddo/
|
|
71
|
-
config.yml ← project config
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Asks for the project state (`new | pre-ai | legacy`), team size, repo structure and the
|
|
75
|
-
**project knowledge language** (`en | es`) — the language your knowledge artifacts are
|
|
76
|
-
written in; the CLI itself stays English.
|
|
57
|
+
| Layer | What it captures |
|
|
58
|
+
|---|---|
|
|
59
|
+
| **Business** | Problem, users, value proposition, constraints |
|
|
60
|
+
| **Product** | Capabilities, decisions, quality attributes |
|
|
61
|
+
| **Tech** | Architecture, stack, codebase foundation, ADRs, modules |
|
|
62
|
+
| **Delivery** | Roadmap, Work Items, build contract, evidence |
|
|
77
63
|
|
|
78
|
-
|
|
64
|
+
Each layer feeds the next. Agents don't guess — they read structured context.
|
|
79
65
|
|
|
80
|
-
|
|
66
|
+
## The Kaddo Lifecycle
|
|
81
67
|
|
|
82
|
-
|
|
68
|
+
Work Items follow the **Kaddo-native Build Contract** — a lifecycle that ensures every change
|
|
69
|
+
is traceable from intent to verified delivery:
|
|
83
70
|
|
|
84
|
-
```
|
|
85
|
-
|
|
71
|
+
```
|
|
72
|
+
Captured Intent → Refinement → Human Review → Ready
|
|
73
|
+
→ Implementation Handoff → Implementation
|
|
74
|
+
→ Evidence Collection → Verification → Completed → Learning
|
|
86
75
|
```
|
|
87
76
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
Kaddo works in two layers:
|
|
102
|
-
|
|
103
|
-
- **The CLI** handles deterministic work: initializing the knowledge repository,
|
|
104
|
-
scanning the codebase, creating work items, reading git diff and detecting possible
|
|
105
|
-
knowledge drift. No AI needed.
|
|
106
|
-
- **Your LLM** handles interpretation: using Kaddo agents to extract capabilities,
|
|
107
|
-
reconstruct architecture, identify risks and propose a roadmap from the project context.
|
|
108
|
-
|
|
109
|
-
> Kaddo does not try to make the CLI "understand everything". The CLI collects and
|
|
110
|
-
> structures signals. The LLM agents turn those signals into product understanding.
|
|
77
|
+
| Stage | What happens | Tool |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| **Captured Intent** | An idea becomes a Work Item draft | `kaddo create` / `kaddo work-item import` |
|
|
80
|
+
| **Refinement** | ACs, scope, affected modules, validation plan | work-item-agent |
|
|
81
|
+
| **Human Review** | A person reviews and approves the refined WI | — |
|
|
82
|
+
| **Ready** | WI moves from `draft/` to `ready/` | `kaddo mark-ready` |
|
|
83
|
+
| **Implementation Handoff** | Agent-agnostic context assembly + design deliberation | implementation-agent |
|
|
84
|
+
| **Implementation** | Code changes guided by the handoff | developer + agents |
|
|
85
|
+
| **Evidence** | Changed paths, validations, AC checks | `kaddo verify` |
|
|
86
|
+
| **Verification** | Evidence vs ACs, release gates, completion decision | `kaddo verify` |
|
|
87
|
+
| **Completed** | WI moves to `completed/` with learning capture | — |
|
|
88
|
+
| **Learning** | Friction and insights feed future work | — |
|
|
111
89
|
|
|
112
|
-
|
|
90
|
+
Work Items physically move between directories: `draft/` → `ready/` → `in-progress/` →
|
|
91
|
+
`completed/`. The lifecycle is enforced by convention — no lock-in, no platform dependency.
|
|
113
92
|
|
|
114
|
-
|
|
93
|
+
## Interfaces
|
|
115
94
|
|
|
116
|
-
Kaddo
|
|
117
|
-
project. For pre-AI and legacy projects, the next step is to turn that inventory into a
|
|
118
|
-
knowledge baseline using Kaddo agents in your preferred LLM chat (Claude, ChatGPT,
|
|
119
|
-
Cursor, Copilot, Windsurf…):
|
|
95
|
+
Kaddo exposes its capabilities through four interfaces:
|
|
120
96
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
-
|
|
125
|
-
|
|
126
|
-
|
|
97
|
+
| Interface | What it does |
|
|
98
|
+
|---|---|
|
|
99
|
+
| **CLI** (`@kaddo/cli`) | Deterministic commands: init, scan, context, create, guard, verify, explain. No LLM, no API key. |
|
|
100
|
+
| **MCP Server** (`@kaddo/mcp`) | [Model Context Protocol](https://modelcontextprotocol.io) server — exposes knowledge, Work Items, graph, lifecycle tools and agent prompts to MCP-compatible IDEs and agents. |
|
|
101
|
+
| **Admin** (`@kaddo/admin`) | Web UI for Work Item management, integration configuration, external work item discovery and import provenance. |
|
|
102
|
+
| **Agents** | LLM prompt packs installed with `kaddo add agents` — business, product, architecture, roadmap, work-item, implementation, graph, capsule and more. |
|
|
127
103
|
|
|
128
|
-
|
|
129
|
-
|
|
104
|
+
The MCP server is mostly read-only. Lifecycle tools (import, ready, handoff, evidence, verify)
|
|
105
|
+
can write under `knowledge/delivery/work-items/`; derived tools regenerate artifacts under
|
|
106
|
+
`.kaddo/`. Everything else is strictly read-only.
|
|
130
107
|
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
kaddo scan # deterministic technical inventory
|
|
134
|
-
kaddo context # assemble an LLM context pack for agent handoff
|
|
135
|
-
kaddo add agents # install agent prompt packs for your LLM chat
|
|
136
|
-
kaddo understand # guide the CLI → LLM handoff with a state-aware plan
|
|
137
|
-
# ── use your LLM with the context pack + agents to create the baseline + roadmap ──
|
|
138
|
-
kaddo create --from roadmap # turn a roadmap candidate into a real work item
|
|
139
|
-
kaddo owners suggest # declare code: ownership on the work item
|
|
140
|
-
kaddo guard # detect possible knowledge drift
|
|
141
|
-
kaddo explain # summarize what Kaddo currently knows
|
|
108
|
+
```json
|
|
109
|
+
{ "mcpServers": { "kaddo": { "command": "npx", "args": ["@kaddo/mcp"], "cwd": "/path/to/project" } } }
|
|
142
110
|
```
|
|
143
111
|
|
|
144
|
-
|
|
145
|
-
Items; Guard warns on drift; Explain summarizes the state. Kaddo does not call an LLM.
|
|
146
|
-
|
|
147
|
-
---
|
|
112
|
+
See the [MCP Server docs](https://kaddo.org/mcp-server/).
|
|
148
113
|
|
|
149
|
-
|
|
114
|
+
## Integrations
|
|
150
115
|
|
|
151
|
-
|
|
116
|
+
Kaddo connects to external work systems through the **Integration Adapter Foundation**:
|
|
152
117
|
|
|
153
|
-
```bash
|
|
154
|
-
kaddo context
|
|
155
118
|
```
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
- **`.kaddo/context-pack.md`** — compact, LLM-friendly markdown to paste into a chat.
|
|
162
|
-
- **`.kaddo/context-pack.json`** — structured data for future tooling and automations.
|
|
163
|
-
|
|
164
|
-
The pack is **deterministic**. Kaddo does not call an LLM, require an API key, or
|
|
165
|
-
interpret your system — it assembles metadata and summaries, marks any missing context
|
|
166
|
-
explicitly, and recommends which agents to use based on your project state:
|
|
167
|
-
|
|
168
|
-
| State | Recommended handoff |
|
|
169
|
-
|---|---|
|
|
170
|
-
| `new` | roadmap-agent → architecture-agent |
|
|
171
|
-
| `pre-ai` | capability-agent → architecture-agent → roadmap-agent |
|
|
172
|
-
| `legacy` | legacy-agent → architecture-agent → capability-agent |
|
|
173
|
-
|
|
174
|
-
> `scan` collects technical signals. `context` packages those signals (plus knowledge and
|
|
175
|
-
> work items) for an LLM. `understand` ties it together — it refreshes the pack and tells
|
|
176
|
-
> you which agent to run next, in what order, for your project state.
|
|
177
|
-
|
|
178
|
-
---
|
|
179
|
-
|
|
180
|
-
### `kaddo add agents`
|
|
181
|
-
|
|
182
|
-
Install Kaddo agent prompt packs — versionable Markdown prompts you use **in your LLM
|
|
183
|
-
chat** (Claude, ChatGPT, Cursor, Copilot, Windsurf…). Kaddo does not execute them.
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
kaddo add agents
|
|
119
|
+
External system (GitHub Issues, Jira, Azure DevOps…)
|
|
120
|
+
→ discovery: browse & filter external items
|
|
121
|
+
→ import: bring an item into Kaddo as a Work Item draft
|
|
122
|
+
→ refinement: enrich with ACs, scope, affected modules
|
|
187
123
|
```
|
|
188
124
|
|
|
189
|
-
|
|
125
|
+
Import is always human-confirmed — Kaddo never creates Work Items silently. Secrets are
|
|
126
|
+
managed through environment variables and never exposed. Configure integrations through the
|
|
127
|
+
Admin UI or `@kaddo/integrations` programmatically.
|
|
190
128
|
|
|
191
|
-
|
|
192
|
-
- `architecture-agent.md` — reconstruct the architecture baseline → `knowledge/tech/current-state.md`
|
|
193
|
-
- `roadmap-agent.md` — propose roadmap candidates → `knowledge/delivery/roadmap.md`
|
|
194
|
-
- `legacy-agent.md` — surface risks/unknowns before changing legacy code
|
|
195
|
-
- `adr-agent.md` — propose candidate architecture decisions
|
|
129
|
+
## Knowledge Capsules
|
|
196
130
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
`.kaddo/context-pack.md`.
|
|
200
|
-
|
|
201
|
-
**Workflow:**
|
|
131
|
+
For repos you can't (or don't want to) map as multirepo modules — other teams, restricted
|
|
132
|
+
access, integration-only context — exchange **Knowledge Capsules**:
|
|
202
133
|
|
|
203
134
|
```bash
|
|
204
|
-
kaddo
|
|
205
|
-
kaddo
|
|
206
|
-
kaddo add agents # → knowledge/agents/*.md
|
|
207
|
-
# then: paste context-pack.md + an agent prompt into your LLM chat
|
|
135
|
+
kaddo capsule export # share a minimal summary of this project
|
|
136
|
+
kaddo capsule add # import an external capsule into the context pack
|
|
208
137
|
```
|
|
209
138
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
| State | Order |
|
|
213
|
-
|---|---|
|
|
214
|
-
| `new` | roadmap-agent → architecture-agent |
|
|
215
|
-
| `pre-ai` | capability-agent → architecture-agent → roadmap-agent |
|
|
216
|
-
| `legacy` | legacy-agent → architecture-agent → capability-agent → roadmap-agent |
|
|
217
|
-
|
|
218
|
-
Existing agent files are never overwritten silently. `kaddo init` does not install agents —
|
|
219
|
-
add them only when you need them.
|
|
139
|
+
No multirepo mapping needed, no source access required. See the
|
|
140
|
+
[Knowledge Capsules docs](https://kaddo.org/knowledge-capsules/).
|
|
220
141
|
|
|
221
|
-
|
|
142
|
+
## Operating Moments
|
|
222
143
|
|
|
223
|
-
|
|
224
|
-
|
|
144
|
+
Kaddo matures a project's knowledge through four moments — **Base → Definition → Projection →
|
|
145
|
+
Execution**:
|
|
225
146
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
147
|
+
- **Base** — `init` · `bootstrap` · `scan` · `add agents` · `context` · `understand` (set up the
|
|
148
|
+
workspace and knowledge structure).
|
|
149
|
+
- **Definition** — business-agent · product-agent · capability-agent · codebase-agent ·
|
|
150
|
+
architecture-agent (turn the idea into clear knowledge).
|
|
151
|
+
- **Projection** — roadmap-agent · backlog-agent · `create --from roadmap` · work-item-agent ·
|
|
152
|
+
ownership-agent (turn knowledge into a delivery plan).
|
|
153
|
+
- **Execution** — implementation-agent · `verify` · `scan` · `owners suggest` · `guard` · `explain`
|
|
154
|
+
(build, verify and keep knowledge in sync).
|
|
229
155
|
|
|
230
|
-
|
|
231
|
-
suggested Knowledge Level (K1–K4), dependencies, and **candidate work items** (with type,
|
|
232
|
-
suggested knowledge level, expected value and notes), plus assumptions, suggested execution
|
|
233
|
-
order and the next recommended work item. Initiatives and work items are **candidates** for
|
|
234
|
-
human review — not final commitments — and priorities adapt to the project state. Turn a
|
|
235
|
-
candidate into a real Work Item with [`kaddo create --from roadmap`](#kaddo-create).
|
|
156
|
+
See [**Operating Moments**](https://kaddo.org/operating-moments/) for the full breakdown.
|
|
236
157
|
|
|
237
|
-
|
|
158
|
+
## Commands
|
|
238
159
|
|
|
239
|
-
|
|
160
|
+
Each command answers one question and has a clear next step.
|
|
240
161
|
|
|
241
|
-
|
|
162
|
+
| Command | Question answered | Suggested next |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| `kaddo init` | How do I start a Kaddo project? | `kaddo bootstrap` |
|
|
165
|
+
| `kaddo bootstrap` | What minimum knowledge should exist? | `kaddo add agents` → `kaddo context` |
|
|
166
|
+
| `kaddo scan` | What technical signals exist in the repo? | `kaddo explain` / `kaddo context` |
|
|
167
|
+
| `kaddo context` | What should I give to an LLM? | the recommended agent |
|
|
168
|
+
| `kaddo understand` | What should I do now? | the recommended action |
|
|
169
|
+
| `kaddo explain` | What does Kaddo know? | `kaddo understand` |
|
|
170
|
+
| `kaddo create --from roadmap` | How do roadmap candidates become Work Items? | work-item-agent |
|
|
171
|
+
| `kaddo verify` | Is the Work Item complete? | evidence + AC verification |
|
|
172
|
+
| `kaddo owners suggest` | Who owns this code? | `kaddo guard` |
|
|
173
|
+
| `kaddo guard` | Is knowledge drifting from code? | update the affected knowledge |
|
|
174
|
+
| `kaddo add agents` | Which agents are available? | `kaddo understand` |
|
|
175
|
+
|
|
176
|
+
Supporting commands: `kaddo status`, `kaddo learn`, `kaddo classify`, `kaddo history`,
|
|
177
|
+
`kaddo module`, `kaddo modules map|list`, `kaddo capsule export|add`, `kaddo graph export`,
|
|
178
|
+
`kaddo report impact`, `kaddo savings`, `kaddo guard --record`, `kaddo drift`, `kaddo questions`,
|
|
179
|
+
`kaddo ignore`, `kaddo add <module>`, `kaddo work-item import`, `kaddo adapters install|list|status`.
|
|
180
|
+
|
|
181
|
+
## Multirepo Modules & Global Artifacts
|
|
182
|
+
|
|
183
|
+
Map secondary repositories as living modules of one system:
|
|
242
184
|
|
|
243
185
|
```bash
|
|
244
|
-
kaddo
|
|
186
|
+
kaddo modules map # register a secondary repo as a module
|
|
187
|
+
kaddo modules list # list mapped modules
|
|
245
188
|
```
|
|
246
189
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
- **`.kaddo/context-pack.md`** / **`.kaddo/context-pack.json`** — the input for agents.
|
|
251
|
-
- **`.kaddo/understand.md`** — the step-by-step handoff guide (recommended flow, expected
|
|
252
|
-
outputs, copy/paste instructions).
|
|
253
|
-
|
|
254
|
-
`kaddo understand` is **deterministic** — it does not call an LLM, execute agents, or
|
|
255
|
-
auto-generate architecture artifacts. It works even when context is incomplete: if the scan
|
|
256
|
-
baseline or some agents are missing, it still produces a plan and tells you the next
|
|
257
|
-
concrete step (`kaddo scan` or `kaddo add agents`).
|
|
258
|
-
|
|
259
|
-
| State | Recommended flow |
|
|
260
|
-
|---|---|
|
|
261
|
-
| `new` | roadmap-agent → architecture-agent |
|
|
262
|
-
| `pre-ai` | capability-agent → architecture-agent → roadmap-agent |
|
|
263
|
-
| `legacy` | legacy-agent → architecture-agent → capability-agent → roadmap-agent |
|
|
264
|
-
|
|
265
|
-
---
|
|
266
|
-
|
|
267
|
-
### `kaddo create`
|
|
268
|
-
|
|
269
|
-
Create a Work Item with the minimum context for its Knowledge Level.
|
|
190
|
+
Per-module knowledge (`module-design`, `stack`, `security`, `standards`) is generated under
|
|
191
|
+
`knowledge/tech/modules/<id>/`. Global artifacts cover cross-cutting concerns:
|
|
270
192
|
|
|
271
193
|
```bash
|
|
272
|
-
kaddo
|
|
273
|
-
kaddo
|
|
274
|
-
kaddo
|
|
275
|
-
kaddo
|
|
276
|
-
kaddo create chore # K1: maintenance, tooling, config, infra
|
|
194
|
+
kaddo add standards # knowledge/tech/standards.md
|
|
195
|
+
kaddo add security # knowledge/tech/security.md
|
|
196
|
+
kaddo add stack # knowledge/tech/stack.md
|
|
197
|
+
kaddo add git-strategy # knowledge/tech/git-strategy.md + .kaddo/git.yml
|
|
277
198
|
```
|
|
278
199
|
|
|
279
|
-
|
|
280
|
-
(lifecycle: `draft → ready → in-progress → blocked → completed → archived`). Aliases like
|
|
281
|
-
`setup`, `tooling`, `maintenance`, `infrastructure` or `refactor` resolve to `chore`.
|
|
200
|
+
## Skills
|
|
282
201
|
|
|
283
|
-
**
|
|
202
|
+
**[Skills](https://kaddo.org/skills/)** standardize *how* agents do common things well
|
|
203
|
+
(writing an ADR, refining a Work Item, planning implementation, collecting evidence). Agents
|
|
204
|
+
orchestrate; skills standardize. Install with:
|
|
284
205
|
|
|
285
206
|
```bash
|
|
286
|
-
kaddo
|
|
287
|
-
kaddo
|
|
207
|
+
kaddo add skills # recommended (delivery + tech)
|
|
208
|
+
kaddo add skills --all # every skill
|
|
209
|
+
kaddo add skills --group tech # one group: delivery | tech | integration
|
|
288
210
|
```
|
|
289
211
|
|
|
290
|
-
|
|
291
|
-
…), and prefills the Work Item from the roadmap (title, type, suggested Knowledge Level,
|
|
292
|
-
expected value, notes, related capabilities/impact/risk/dependencies and the parent
|
|
293
|
-
initiative). It asks only for the required fields the candidate does not provide and keeps
|
|
294
|
-
source traceability in the front matter (`source: roadmap`, `source_id`, `source_initiative`).
|
|
295
|
-
This closes the loop `scan → context → agents → roadmap → work item`. If the roadmap is
|
|
296
|
-
missing or has no candidates, Kaddo shows a helpful message. No LLM is called.
|
|
212
|
+
## Adapters (AGENTS.md / CLAUDE.md)
|
|
297
213
|
|
|
298
|
-
|
|
214
|
+
Generate native instruction files so AI coding tools work inside a Kaddo repo:
|
|
299
215
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
216
|
+
```bash
|
|
217
|
+
kaddo adapters install codex # AGENTS.md for Codex
|
|
218
|
+
kaddo adapters install claude # CLAUDE.md for Claude Code
|
|
219
|
+
kaddo adapters install kiro # AGENTS.md for Kiro
|
|
220
|
+
kaddo adapters install opencode # AGENTS.md for OpenCode
|
|
221
|
+
kaddo adapters install antigravity # AGENTS.md for Antigravity
|
|
222
|
+
```
|
|
307
223
|
|
|
308
|
-
|
|
224
|
+
Both are compact projections of the project's knowledge map — Kaddo stays the source of truth.
|
|
225
|
+
See [Custom Adapters](https://kaddo.org/custom-adapters/) for the shared Adapter Contract.
|
|
309
226
|
|
|
310
|
-
|
|
227
|
+
## Kaddo Power
|
|
311
228
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
id: WI-001
|
|
316
|
-
code:
|
|
317
|
-
- src/payments/**
|
|
318
|
-
- src/shared/payment/**
|
|
319
|
-
---
|
|
320
|
-
```
|
|
229
|
+
The official [`kaddo-power/`](https://github.com/Kaddo-kdd/kaddo/blob/main/kaddo-power/README.md) packages Kaddo Skills, KDD workflow
|
|
230
|
+
guidance and `@kaddo/mcp` integration using the Agent Plugins specification. Kiro Powers is
|
|
231
|
+
the first supported consumer.
|
|
321
232
|
|
|
322
|
-
|
|
233
|
+
## Templates
|
|
323
234
|
|
|
324
|
-
|
|
235
|
+
Kaddo ships templates for its main artifacts — organized into six categories: **core**,
|
|
236
|
+
**business**, **architecture**, **module**, **operations** and **legacy**. Each carries a
|
|
237
|
+
purpose, when-to-use, output path and quality checklist. See the
|
|
238
|
+
[Templates docs](https://kaddo.org/templates/overview/).
|
|
325
239
|
|
|
326
|
-
|
|
240
|
+
## Examples
|
|
327
241
|
|
|
328
|
-
|
|
329
|
-
kaddo guard # checks staged + unstaged files
|
|
330
|
-
kaddo guard --staged # checks only staged files
|
|
331
|
-
```
|
|
242
|
+
The [`examples/`](https://github.com/Kaddo-kdd/kaddo/tree/main/examples) folder has reproducible demo repositories:
|
|
332
243
|
|
|
333
|
-
|
|
244
|
+
| Example | Scenario | State | Highlights |
|
|
245
|
+
|---|---|---|---|
|
|
246
|
+
| [Task Pilot](https://github.com/Kaddo-kdd/kaddo/tree/main/examples/new-project) | Greenfield app | `new` | Structured knowledge from day one; full loop |
|
|
247
|
+
| [Loyalty Lite](https://github.com/Kaddo-kdd/kaddo/tree/main/examples/pre-ai-project) | Existing app | `pre-ai` | `scan` + agents + Guard drift demo |
|
|
248
|
+
| [Old Orders](https://github.com/Kaddo-kdd/kaddo/tree/main/examples/legacy-project) | Legacy MVC app | `legacy` | Understand-before-change; legacy risks/unknowns |
|
|
249
|
+
| [Commerce Stack](https://github.com/Kaddo-kdd/kaddo/tree/main/examples/multirepo-workspace) | Many repos | `multirepo` | `modules map` + per-module artifacts |
|
|
334
250
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
- src/payments/payments.service.ts
|
|
338
|
-
|
|
339
|
-
⚠ Possible knowledge drift: WI-001 (feature, K2)
|
|
340
|
-
Changed code matching this artifact:
|
|
341
|
-
- src/payments/payments.service.ts
|
|
342
|
-
Declared ownership:
|
|
343
|
-
- src/payments/**
|
|
344
|
-
WI-001 was not updated in this diff.
|
|
345
|
-
Evidence: 1/1 globs matched · artifact K2 · domain: payments
|
|
346
|
-
Suggested action: review WI-001 and update it if the behavior changed,
|
|
347
|
-
or ignore this artifact below if the change does not affect the knowledge.
|
|
348
|
-
```
|
|
251
|
+
Each includes a `prompt-flow.md` with a Mermaid diagram, CLI↔LLM split and copy/paste prompt
|
|
252
|
+
handoffs. See the [Examples docs](https://kaddo.org/examples/).
|
|
349
253
|
|
|
350
|
-
|
|
351
|
-
and is **advisory/non-blocking** (it never fails your command or CI). If the artifact was
|
|
352
|
-
also changed in the same diff, no FYI is shown. Guard is **silent** when no artifacts declare
|
|
353
|
-
ownership. No noise on day one.
|
|
254
|
+
## Self-hosting
|
|
354
255
|
|
|
355
|
-
|
|
256
|
+
Kaddo builds Kaddo with Kaddo. The project uses its own lifecycle to manage Work Items,
|
|
257
|
+
collect evidence, verify ACs and capture learnings — the same workflow it provides to any
|
|
258
|
+
project. The `knowledge/` directory contains Kaddo's own product knowledge; `.kaddo/` holds
|
|
259
|
+
its derived artifacts. This self-hosting validates the lifecycle end-to-end and ensures that
|
|
260
|
+
friction encountered internally feeds back into improvements.
|
|
356
261
|
|
|
357
|
-
## How
|
|
262
|
+
## How Ownership and Guard Work
|
|
358
263
|
|
|
359
|
-
Ownership is declared in
|
|
264
|
+
Ownership is declared in artifact front matter — no central mapping file:
|
|
360
265
|
|
|
361
266
|
```yaml
|
|
362
267
|
---
|
|
363
268
|
type: feature
|
|
364
269
|
id: WI-001
|
|
365
270
|
title: "Add payment retry logic"
|
|
366
|
-
knowledge_level: K2
|
|
367
271
|
status: in-progress
|
|
368
272
|
code:
|
|
369
273
|
- src/payments/**
|
|
370
274
|
- src/shared/payment/**
|
|
371
|
-
summary: "Adds retry policy for failed payment attempts."
|
|
372
275
|
---
|
|
373
276
|
```
|
|
374
277
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
artifact → code globs → git diff intersection
|
|
379
|
-
```
|
|
278
|
+
`kaddo guard` reads `git diff`, finds artifacts whose `code:` globs match changed files, and
|
|
279
|
+
shows a **non-blocking FYI** when the artifact was not updated in the same diff. Guard is
|
|
280
|
+
**silent** when no artifacts declare ownership — no noise on day one.
|
|
380
281
|
|
|
381
|
-
|
|
282
|
+
## What Kaddo Does Not Do
|
|
382
283
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
It lists Work Items missing ownership, suggests candidate globs from `.kaddo/scan.json` and
|
|
391
|
-
the artifact's `domains`/`capabilities`, and lets you pick or type globs. It updates **only**
|
|
392
|
-
the front matter (the body is preserved), is fully **deterministic** (no LLM, no source
|
|
393
|
-
changes), and works with manual entry when no scan baseline exists.
|
|
394
|
-
|
|
395
|
-
```
|
|
396
|
-
create work item → kaddo owners suggest → kaddo guard
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
---
|
|
400
|
-
|
|
401
|
-
### `kaddo explain`
|
|
402
|
-
|
|
403
|
-
Summarize what Kaddo currently knows about the project — useful for onboarding,
|
|
404
|
-
handoff, project review or preparing an agent.
|
|
405
|
-
|
|
406
|
-
```bash
|
|
407
|
-
kaddo explain # project explanation (human-readable)
|
|
408
|
-
kaddo explain --for agent # compact structured JSON
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
Run without filters, it reports project metadata, detected stack (from
|
|
412
|
-
`.kaddo/scan.json`), knowledge status (inventory, context pack, capabilities,
|
|
413
|
-
architecture baseline, roadmap, agents), work items, **ownership coverage**, the
|
|
414
|
-
**missing knowledge** and **suggested next steps**. It also writes
|
|
415
|
-
`.kaddo/explain.md` and `.kaddo/explain.json`. No LLM is called.
|
|
416
|
-
|
|
417
|
-
`context` vs `explain`: `kaddo context` prepares input for an LLM agent;
|
|
418
|
-
`kaddo explain` summarizes what Kaddo already knows. The focused flags
|
|
419
|
-
(`--scope`, `--type`, `--since`) still explain a subset of artifacts.
|
|
420
|
-
|
|
421
|
-
---
|
|
422
|
-
|
|
423
|
-
### `kaddo capsule`
|
|
424
|
-
|
|
425
|
-
Share or consume minimal, portable knowledge about a system — a **Knowledge Capsule** —
|
|
426
|
-
without mapping it as multirepo or reading its source.
|
|
427
|
-
|
|
428
|
-
```bash
|
|
429
|
-
kaddo capsule export # → .kaddo/exports/<project>.capsule.md / .json
|
|
430
|
-
kaddo capsule add <path> # import an external capsule → knowledge/external/<id>.capsule.md
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
`export` builds a deterministic draft from `knowledge/` (purpose, capabilities, public
|
|
434
|
-
contracts, risks, ADRs, owners — never source code or secrets); refine it with the
|
|
435
|
-
`capsule-agent` before sharing. `add` registers the capsule in `.kaddo/external.yml`;
|
|
436
|
-
`kaddo context` then includes an **External Knowledge** section and `kaddo explain` lists
|
|
437
|
-
the capsules (warning when one looks stale). See the
|
|
438
|
-
[Knowledge Capsules guide](https://kaddo.org/knowledge-capsules/).
|
|
439
|
-
|
|
440
|
-
---
|
|
441
|
-
|
|
442
|
-
### `kaddo graph export`
|
|
443
|
-
|
|
444
|
-
Export the connections that already exist between your knowledge artifacts as a **lightweight,
|
|
445
|
-
file-based knowledge graph** — for onboarding, impact analysis and context selection.
|
|
446
|
-
|
|
447
|
-
```bash
|
|
448
|
-
kaddo graph export # → .kaddo/graph.json + .kaddo/graph.mmd
|
|
449
|
-
kaddo graph export --scope all # include every artifact (default: active)
|
|
450
|
-
kaddo graph export --format mermaid # mermaid only (or --format json)
|
|
451
|
-
```
|
|
452
|
-
|
|
453
|
-
Nodes come from knowledge layers, Work Items, code globs, capabilities, ADRs and Knowledge
|
|
454
|
-
Capsules; edges come from front matter (`code`, `capabilities`, `decisions`, `source_id`,
|
|
455
|
-
`source_initiative`) and the external registry. It never reads `src/`, never reads source code
|
|
456
|
-
and never calls an LLM. `kaddo explain` and `kaddo context` show a graph **summary** once it has
|
|
457
|
-
been exported (they never generate it).
|
|
458
|
-
|
|
459
|
-
Every export also rates **relationship quality** and writes non-blocking metadata hints
|
|
460
|
-
(`.kaddo/graph-hints.md` + `.json`) — detecting active Work Items without `code`/`capabilities`,
|
|
461
|
-
ADRs without governed `code`, capabilities/capsules with no Work Item link, and more. The
|
|
462
|
-
`graph-agent` turns those hints into precise front matter you confirm and apply. See the
|
|
463
|
-
[Knowledge Graph Export guide](https://kaddo.org/knowledge-graph-export/).
|
|
464
|
-
|
|
465
|
-
## Roadmap
|
|
284
|
+
- Not a code generator
|
|
285
|
+
- Not an agent execution framework (it ships agent *prompts*, it does not run them)
|
|
286
|
+
- Not a replacement for Jira, Linear or documentation tools
|
|
287
|
+
- Not a platform
|
|
288
|
+
- Does not call an LLM or require an API key
|
|
466
289
|
|
|
467
|
-
|
|
468
|
-
create --from roadmap → owners → guard → explain`.
|
|
290
|
+
## About the Author
|
|
469
291
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
| v2.1 | Semantic plugins: `prisma`, `openapi` |
|
|
478
|
-
| v2.2 | Domain Owners (`kaddo owners`) |
|
|
479
|
-
| v2.3 | Multirepo Module Descriptor (`kaddo module`) |
|
|
480
|
-
| v2.4–2.5 | Modules: `contracts`, `capabilities`, `guard-advanced`, `agents`, `skills` |
|
|
481
|
-
| v2.6 | Knowledge loop: `context`, `understand`, `add agents`, roadmap output, `create --from roadmap`, Guard Lite end-to-end, `owners suggest`, project `explain` |
|
|
482
|
-
| v2.6 | Multirepo modules (`modules map/list`), global `standards`/`security`/`stack`/`git-strategy` artifacts, six operational agents |
|
|
483
|
-
| v2.6 | Central template registry (23 templates, layer categories (business/product/tech/delivery)) |
|
|
484
|
-
| v2.6 | Demo example repositories, prompt flows and a diagram-first Visual Guide (docs) |
|
|
485
|
-
| v2.7 | Multirepo hardening: module artifacts from the template registry, module-aware `context`/`explain`, opt-in `guard --workspace` |
|
|
486
|
-
| v2.8 | `kaddo bootstrap` for new projects (Business → Product → Tech → Delivery); business templates + bootstrap agents |
|
|
487
|
-
| v3.0 | Knowledge-centric realignment: `architecture/` → `knowledge/` with layers Business → Product → Tech → Delivery; context/explain by layer (breaking) |
|
|
488
|
-
| v3.1 | Minimum Sufficient Knowledge: bootstrap one consolidated file per layer; progressive `add agents` by group (state default, `--all`, `--group`) |
|
|
489
|
-
| v3.2 | New-project flow hardening: agents in per-layer folders; `new` recommends capability+architecture agents; explain Work Item parser fix; intent vs reality (codebase vs current-state) |
|
|
490
|
-
| v3.3 | Work Item delivery lifecycle: `understand` shows branch → scan → ownership → guard → knowledge → commit for active Work Items (suggestions only; Kaddo never runs git) |
|
|
491
|
-
| v3.4 | Delivery protocol in the `work-item-agent`: branch first per the Git strategy, commit only with human confirmation (CLI never touches git) |
|
|
492
|
-
| v3.5 | Knowledge discovery by front-matter type with per-layer maturity (explain/understand/context); context pack carries Operating Rules so agents never commit without confirmation |
|
|
493
|
-
| v3.5.1 | Author attribution & knowledge identity: Kaddo as a practical implementation of KDD for AI-assisted development (docs/README) |
|
|
494
|
-
| v3.6 | Flexible roadmap parsing and roadmap candidate/materialized Work Item reporting |
|
|
495
|
-
| v3.7 | Work Item lifecycle active workspace (`draft`, `ready`, `in-progress`, `blocked`, `completed`, `archived`) |
|
|
496
|
-
| v3.7.1 | Context Efficiency positioning: Repository Exploration Tax and structured-knowledge narrative |
|
|
497
|
-
| v3.8 | Agent Trace & responsibility boundaries: every prompt declares Agent/Produced/Next; new `implementation-agent` (the only agent that may suggest a branch) |
|
|
498
|
-
| v3.9 | New `chore` Work Item type (+ aliases setup/tooling/maintenance/infra); explain Work Items by Type; context Delivery Mix |
|
|
499
|
-
| v3.9.1 | Unified knowledge artifact discovery: one service behind explain/context/owners/guard (fixes owners missing lifecycle subfolders) |
|
|
500
|
-
| v3.10 | State-aware recommendations: real phase model (Discovery → Planning → Delivery Preparation → Active Delivery → Maintenance) drives understand/context/explain |
|
|
501
|
-
| v3.11 | Command workflow clarity: official command matrix + "Question answered / Suggested next" footer on scan/context/explain/understand; `chore/` branch prefix |
|
|
502
|
-
| v3.13 | New `backlog-agent`: capture raw ideas into a Work Item draft or roadmap candidate (human decides the next step) |
|
|
503
|
-
| v3.14 | Project knowledge language (`project.language: en\|es`): knowledge in your language, CLI stays English; all agents respect it |
|
|
504
|
-
| v3.15 | Delivery context consistency: phase-based handoff + per-phase LLM instructions; assisted `owners suggest` (normalize/validate globs); new `ownership-agent`; guard untracked-files warning; duplicate Work Item detection |
|
|
505
|
-
| v3.16 | Knowledge Capsules: `kaddo capsule export/add`, External Knowledge in context/explain, new `capsule-agent` |
|
|
506
|
-
| v3.17 | Knowledge Graph Export: `kaddo graph export` (`.kaddo/graph.json` + `.mmd`, `--scope`/`--format`); graph summary in context/explain |
|
|
507
|
-
| v3.18 | Graph relationship quality & metadata hints: `graph-hints.md`/`.json`, quality levels, `graph-agent`; hints in context/explain/understand |
|
|
508
|
-
| v3.19 | Read-only MCP server `@kaddo/mcp` (resources, tools, prompts over stdio) |
|
|
509
|
-
| v3.20 | MCP derived tools: safe regeneration of context/explain/understand/graph/capsule-draft under `.kaddo/` |
|
|
510
|
-
| v3.21 | Reusable Skills layer (`kaddo add skills`); skills in context/explain/understand, agent prompts and MCP |
|
|
511
|
-
| v3.22 | Guard & graph scope semantics: graph scope metadata, contextual-empty messaging, Guard ownership scope (active + completed; `--include-archived`) |
|
|
512
|
-
| v3.22.1 | Guard project-root path normalization: matches `code:` globs when the project is a subfolder of the Git root |
|
|
513
|
-
| v3.23 | Knowledge Impact Report: `kaddo report impact` (Markdown/JSON, `--output`); evidence-first health/coverage/traceability/readiness/signals; MCP resource + tool |
|
|
514
|
-
| v3.23.1 | Impact report Actionable Gaps: per-Work-Item missing source/initiative/ownership/level/acceptance/DoD/validation, broad globs, overlaps; Work-Item-specific Suggested Actions + Score Breakdown |
|
|
515
|
-
| v3.23.2 | Impact report defaults to `all` scope (accumulated impact), graph built in memory; `--scope active`; `scope_source`/`default_scope` in JSON |
|
|
516
|
-
| v3.24 | Estimated Savings Model: `kaddo savings` (+ `savings init`, `.kaddo/savings.yml`); evidence-based time/value estimates, confidence; MCP resource + tool |
|
|
517
|
-
| v3.25 | Guard history & drift trend: `kaddo guard --record`, `kaddo drift`; feeds impact Guard Activity + savings Drift Prevention; MCP drift/guard-history resources + tool |
|
|
518
|
-
| v3.25.1 | Savings guard-history messaging fix: distinguishes "no history" from "history with 0 resolved warnings" (drift prevention available at 0 h) |
|
|
519
|
-
| v3.26 | Open-questions readiness gate: `kaddo questions`/`readiness`, blocking/important/deferred classification; MCP open-questions + roadmap-readiness resources + tool; roadmap/work-item/implementation/bootstrap agents check it |
|
|
520
|
-
| v3.27 | Codex adapter: `kaddo adapters install codex` (alias `kaddo export codex`) generates a compact `AGENTS.md` projection (`--dry-run`/`--force`) |
|
|
521
|
-
| v3.27.1 | Codex adapter command fallbacks: AGENTS.md tells Codex to try `corepack pnpm exec` / `pnpm exec` / `npx` kaddo when the global binary isn't on PATH |
|
|
522
|
-
| v3.27.2 | Codex adapter safe merge: `kaddo adapters install codex --inject` adds/updates only a delimited Kaddo block in an existing AGENTS.md, preserving team content |
|
|
523
|
-
| v3.27.3 | Codex adapter reference stabilization: package-manager-aware command fallbacks (lockfile detection) + Adapter Contract & Custom Adapters docs (reference for future adapters) |
|
|
524
|
-
| v3.28 | Claude Code adapter: `kaddo adapters install claude` (alias `kaddo export claude`) generates a `CLAUDE.md` projection reusing the shared adapter common core (`--dry-run`/`--force`) |
|
|
525
|
-
| v3.28.1 | Claude adapter safe merge: `--inject` works for `CLAUDE.md` too; adapter markers are now target-neutral (`KADDO ADAPTER`) and legacy Codex markers auto-migrate on update |
|
|
526
|
-
| v3.28.2 | Adapter inject guard: `--inject` on a fully Kaddo-generated AGENTS.md/CLAUDE.md does nothing (suggests `--force`), preventing duplicated Kaddo guidance |
|
|
527
|
-
| v3.29 | OpenCode adapter: `kaddo adapters install opencode` (alias `kaddo export opencode`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
|
|
528
|
-
| v3.30 | Antigravity adapter: `kaddo adapters install antigravity` (alias `kaddo export antigravity`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
|
|
529
|
-
| v3.31 | Kiro adapter: `kaddo adapters install kiro` (alias `kaddo export kiro`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
|
|
530
|
-
| v3.32 | Adapter discovery & status: `kaddo adapters list` (alias `ls`) and `kaddo adapters status` (alias `check`) — read-only catalog + per-adapter install state (missing/team-owned/injected/legacy-injected/full-generated/broken-markers), shared-`AGENTS.md` origin detection, `--json` |
|
|
531
|
-
| v3.33 | Open questions resolution tracking: mark questions `[open]`/`[resolved]`/`[assumed]`/`[deferred]` (EN+ES); only `open` blocks readiness, so assumed/resolved/deferred decisions stop false blocks. `kaddo questions` shows status counts + `resolution_status` in JSON |
|
|
532
|
-
| v3.34 | Pre-AI onboarding: `kaddo onboarding` (alias `onboard`) / `kaddo report onboarding` — read-only diagnosis of an existing project's readiness (scan/understand/knowledge/questions/roadmap/work-items/adapters) with a single recommended next step; `--json` |
|
|
533
|
-
| v3.35 | Folded onboarding into `kaddo explain`: removed `kaddo onboarding`/`onboard`/`report onboarding`; project readiness + single recommended next step now live in `kaddo explain` (human `## Project Readiness` + `readiness` in agent JSON) |
|
|
534
|
-
| v3.36 | State-aware bootstrap: `kaddo bootstrap` creates the full knowledge baseline for any `project.state` (new/pre-ai/legacy) with state-specific templates — no more new-only warning; idempotent, never overwrites, ensures `tech/decisions/` and `delivery/work-items/` |
|
|
535
|
-
| v3.37 | Placeholder-aware readiness: knowledge files are classified missing/placeholder/weak/useful; a bootstrap file isn't treated as ready knowledge. Layers downgrade to Placeholder/Weak, a new Knowledge Refinement phase recommends the right agent, and `create --from roadmap` is never suggested with 0 candidates |
|
|
536
|
-
| v3.37.1 | Unified next-step: one shared resolver (`core/next-step.ts`) powers `context`, `understand` and `explain` (Phase + Readiness) so they never diverge; agent JSON exposes `nextStepRecommendation`. Fixes duplicate `capabilities` line in explain |
|
|
537
|
-
| v3.38 | Open-question source locations: `kaddo questions` shows each question's `Source` (path:line), `Status`, `Severity`, `Note` + a copy/paste resolution example and localized how-to-resolve guide; JSON/report/MCP carry `sourcePath`, `line`, `raw`, `note` |
|
|
538
|
-
| v3.39 | Existing capability discovery: state-aware `capabilities.md` (pre-ai/legacy = evidence-backed Capability Inventory + Gaps + Roadmap Candidate Signals; legacy adds criticality/change-risk/modernization); capability-agent discovers with evidence, roadmap-agent treats capabilities as primary source |
|
|
539
|
-
| v3.39.1 | Domain-oriented capability inventory: pre-ai/legacy `capabilities.md` groups capabilities under `## Capability Domains` (functional domains, not technical folders); gaps/candidates name their `Domain`; roadmap-agent reads it as a domain map; work-item-agent recommends `related_domain` + `related_capability` |
|
|
540
|
-
| v3.40 | ADR materialization: `kaddo adr` (alias `decisions`) detects decision candidates + ADRs and hands off the ADR files to create; `tech_decisions` status (none/candidates/draft-adrs/accepted-adrs) surfaced in `explain`/`context`/`understand`; adr-writing skill formalized |
|
|
541
|
-
| v3.40.1 | ADR slug cleanup + MCP: suggested ADR filenames strip list/heading prefixes (no `ADR-001-1-…`) and normalize acronyms; new read-only MCP resource `kaddo://tech-decisions` sharing `buildTechDecisions` with `kaddo adr` |
|
|
542
|
-
| v3.41 | Tech knowledge structure: `knowledge/tech/discovery/` for architecture-notes/decision-candidates (core vs decisions vs discovery); `kaddo adr` reads discovery-first with legacy fallback; `kaddo tech organize` migrates safely; `explain` shows `## Tech Knowledge` |
|
|
543
|
-
| v3.42 | Agent & skill version metadata: installed agents/skills carry a `version:`; `kaddo agents status` / `kaddo skills status` classify up-to-date/outdated/unknown-version/modified/missing; `agents update` / `skills update` refresh outdated safely (never overwrite edits without `--force`); MCP `kaddo://installed-assets` |
|
|
544
|
-
| v3.43 | Capability-grounded roadmap: each `RM-xxx` candidate is graded on related domain / capability / source signals; `roadmap_quality` surfaced in `explain`/`context`/`understand`; `create --from roadmap` preserves `source_roadmap_candidate` + related metadata into the Work Item; roadmap-agent emits grounded fields (never materializes Work Items); MCP `kaddo://roadmap-quality` |
|
|
545
|
-
| v3.44 | Roadmap counting alignment + materialization quality: `explain`/`context` separate **Roadmap initiatives** from **Work Item candidates** (`## Roadmap Status`); two-level `roadmapQuality` (initiatives + work_item_candidates); `create --from roadmap` normalizes metadata — fills `domains` from `related_domain`, splits comma-joined `related_capabilities` into a real list, carries `source_roadmap_initiative`/`source_work_item_candidate`/`source_signals`/`decision_candidates`, improved Source + Context-From-Roadmap body + ADR warning; MCP `kaddo://work-item-candidates` |
|
|
546
|
-
| v3.45 | State-aware next step: `resolveNextStep` decides from the real delivery state (draft/ready/in-progress, ownership, ADRs, adapters) instead of always suggesting `create --from roadmap` — draft → work-item-agent, ready → adapter/implementation-agent, in-progress → guard; parallel **secondary** recommendations (ownership, ADRs, remaining candidates); `deliveryState` + recommendation in `explain`/`context`; MCP `kaddo://next-step` |
|
|
547
|
-
| v3.86 | Official Kaddo Agent Plugin: portable Agent Plugins 1.0 packaging, Kiro Power integration, canonical Skill synchronization, MCP boundary documentation and automated drift validation |
|
|
548
|
-
|
|
549
|
-
**Optional modules (installed with `kaddo add`):**
|
|
550
|
-
|
|
551
|
-
`adr` · `rfc` · `incident` · `migration` · `legacy` · `contracts` · `capabilities` · `guard-advanced` · `agents` · `skills` · `standards` · `security` · `stack` · `git-strategy`
|
|
292
|
+
Kaddo is created and maintained by **Julian Dario Luna Patiño** — Cloud Solutions Architect
|
|
293
|
+
Lead, AWS Community Builder and content creator at [TryCatch.tv](https://trycatch.tv). It is
|
|
294
|
+
the result of years designing software architectures, leading development teams and
|
|
295
|
+
documenting systems. Kaddo applies Knowledge Driven Development principles to AI-assisted
|
|
296
|
+
software development; it does not claim to have invented KDD.
|
|
297
|
+
[GitHub](https://github.com/judlup) · [LinkedIn](https://www.linkedin.com/in/judlup/) ·
|
|
298
|
+
[About](https://kaddo.org/about/).
|
|
552
299
|
|
|
553
300
|
## Contributing
|
|
554
301
|
|
|
555
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
302
|
+
See [CONTRIBUTING.md](https://github.com/Kaddo-kdd/kaddo/blob/main/CONTRIBUTING.md).
|
|
556
303
|
|
|
557
304
|
## License
|
|
558
305
|
|