@kaddo/cli 3.112.2 → 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.
Files changed (4) hide show
  1. package/README.md +199 -452
  2. package/dist/core.js +26 -41
  3. package/dist/index.js +117 -116
  4. 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
- > Observable knowledge for evolving software with humans and AI.
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 puts knowledge first, then lets AI help you build.
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
- **The central question:** *How does Kaddo know the right knowledge was impacted by this change?*
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
- Kaddo occupies a different layer:
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
- Execution tools
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
- ## Install
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
- Or install globally:
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
- npm install -g @kaddo/cli
50
- kaddo --help
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
- ## Commands
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
- Initialize Kaddo in the current project.
53
+ ## The Knowledge Model
58
54
 
59
- ```bash
60
- kaddo init
61
- ```
55
+ Kaddo organizes project knowledge into four layers under `knowledge/`:
62
56
 
63
- Creates:
64
- ```
65
- knowledge/
66
- knowledge.md ← current state of the product
67
- delivery/
68
- roadmap.md ← intentions and priorities
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
- ### `kaddo scan`
66
+ ## The Kaddo Lifecycle
81
67
 
82
- Detect your project stack deterministically.
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
- ```bash
85
- kaddo scan
71
+ ```
72
+ Captured Intent → Refinement → Human Review → Ready
73
+ → Implementation Handoff → Implementation
74
+ → Evidence Collection → Verification → Completed → Learning
86
75
  ```
87
76
 
88
- Detects language, framework, package manager, code dirs, migration dirs, contract files, infra and test dirs. Suggests domains for human confirmation — never assumes.
89
-
90
- It also persists a reusable baseline of the project:
91
-
92
- - **`.kaddo/scan.json`** — structured, machine-readable (for the CLI and future context-pack commands).
93
- - **`knowledge/inventory.md`** — human-readable inventory you can paste into an LLM chat.
94
-
95
- Scan detects signals and asks confirmation questions — it never claims to understand your business capabilities or architecture.
96
-
97
- ---
98
-
99
- ## CLI + LLM Agents
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
- ## From scan to knowledge baseline
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
- `kaddo scan` gives Kaddo a technical inventory. But inventory is not understanding.
93
+ ## Interfaces
115
94
 
116
- Kaddo does not start by creating tasks — it starts by understanding the state of the
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
- - capabilities
122
- - modules
123
- - risks and unknowns
124
- - ownership candidates
125
- - architecture notes
126
- - roadmap candidates
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
- Once the baseline exists and artifacts declare ownership, `create` and `guard` operate
129
- on real context instead of starting from scratch.
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
- ```bash
132
- kaddo init # state: new | pre-ai | legacy, team size, structure
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
- The CLI prepares context; your LLM interprets it; Kaddo turns understanding into Work
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
- ### `kaddo context`
114
+ ## Integrations
150
115
 
151
- Assemble an LLM context pack for handoff to a chat agent (Claude, ChatGPT, Cursor, Copilot, Windsurf…).
116
+ Kaddo connects to external work systems through the **Integration Adapter Foundation**:
152
117
 
153
- ```bash
154
- kaddo context
155
118
  ```
156
-
157
- Reads existing Kaddo artifacts — `.kaddo/config.yml`, `.kaddo/scan.json`,
158
- `knowledge/inventory.md`, `knowledge/knowledge.md`, `knowledge/delivery/roadmap.md` and
159
- work-item front matter — and writes two files:
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
- Creates `knowledge/agents/` with:
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
- - `capability-agent.md` — extract/propose system capabilities → `knowledge/product/capabilities.md`
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
- Each prompt declares its role, required input, expected output, constraints, output format,
198
- where to save the result, and a quality checklist. The primary input is always
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 scan # technical signals
205
- kaddo context # → .kaddo/context-pack.md
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
- Recommended agent order by project state:
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
- #### Roadmap agent output
142
+ ## Operating Moments
222
143
 
223
- The `roadmap-agent` is the bridge between understanding and execution. In your LLM chat it
224
- produces a **structured** `knowledge/delivery/roadmap.md`:
144
+ Kaddo matures a project's knowledge through four moments — **Base → Definition → Projection →
145
+ Execution**:
225
146
 
226
- ```txt
227
- context pack → roadmap agent → knowledge/delivery/roadmap.md → kaddo create --from roadmap
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
- Each initiative (`RM-001`, …) includes a goal, related capabilities, impact, risk, a
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
- ### `kaddo understand`
160
+ Each command answers one question and has a clear next step.
240
161
 
241
- Guide the handoff from the CLI (deterministic context) to your LLM (interpretation).
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 understand
186
+ kaddo modules map # register a secondary repo as a module
187
+ kaddo modules list # list mapped modules
245
188
  ```
246
189
 
247
- It refreshes the context pack, recommends which agents to use — in what order — based on
248
- your project state, flags any agents not yet installed, and writes a reusable guide:
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 create feature # K2: delivers a user-facing capability
273
- kaddo create bugfix # K2: fixes a known defect
274
- kaddo create hotfix # K1: urgent fix on a released version
275
- kaddo create spike # K3: exploratory / reduce uncertainty
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
- New Work Items land in `knowledge/delivery/work-items/draft/` with `status: draft`
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
- **From a roadmap candidate:**
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 create --from roadmap # pick a candidate from knowledge/delivery/roadmap.md
287
- kaddo create feature --from roadmap # same, with a default type
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
- Reads `knowledge/delivery/roadmap.md`, lets you select a candidate work item (`WI-CANDIDATE-001`,
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
- **Knowledge Levels:**
214
+ Generate native instruction files so AI coding tools work inside a Kaddo repo:
299
215
 
300
- | Level | When | Questions |
301
- |---|---|---|
302
- | K0 | Trivial change | None |
303
- | K1 | Hotfix / simple fix | Problem + expected result |
304
- | K2 | Feature or bugfix with functional impact | + impact + acceptance criteria |
305
- | K3 | Capability or significant change | + design |
306
- | K4 | Architecture change or migration | + risks |
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
- The generated file includes front matter, Definition of Done, and a Learning section.
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
- **To activate Guard Lite**, add code globs to the `code:` field of the generated front matter:
227
+ ## Kaddo Power
311
228
 
312
- ```yaml
313
- ---
314
- type: feature
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
- ### `kaddo guard`
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
- Check if modified code has related artifacts that were not updated.
240
+ ## Examples
327
241
 
328
- ```bash
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
- Guard Lite reads `git diff`, finds artifacts with matching `code:` globs, and shows a **non-blocking FYI** if the artifact was not updated in the same diff.
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
- Touched files:
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
- Guard acts only on **declared ownership** (the `code:` globs) — it performs **no inference**
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 ownership works
262
+ ## How Ownership and Guard Work
358
263
 
359
- Ownership is declared in the front matter of each artifact — no central mapping file.
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
- Kaddo builds a simple Knowledge Graph from these front matters at runtime:
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
- ### Declaring ownership with the assistant
282
+ ## What Kaddo Does Not Do
382
283
 
383
- You don't have to edit YAML by hand. The ownership assistant proposes `code:` globs and
384
- updates the front matter for you:
385
-
386
- ```bash
387
- kaddo owners suggest
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
- The full knowledge loop ships today: `scan → context → agents → understand → roadmap →
468
- create --from roadmap → owners → guard → explain`.
290
+ ## About the Author
469
291
 
470
- | Version | What shipped |
471
- |---|---|
472
- | v1.0 | `init`, `scan`, `create`, `guard` (Guard Lite) |
473
- | v1.1 | `explain`, `status`, `learn`, Evidence Score |
474
- | v1.2 | `classify` (Classification Drift), `history` |
475
- | v1.4 | `guard --ci` (JSON output for CI/PR) |
476
- | v2.0 | Optional module system (`kaddo add`) |
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