Kaddo — Knowledge Driven Development

Prepare any codebase for AI-assisted evolution. Kaddo helps your repo remember why the code exists.

Kaddo is an open-source CLI and agent prompt toolkit that helps new, pre-AI and legacy projects build a living knowledge layer close to the code. The CLI prepares and structures the context; your LLM agents turn it into product understanding.

Kaddo reduces repository exploration by turning project knowledge into structured context. Token savings are a consequence, not the goal.

Knowledge Driven Development ≠ Kaddo. KDD is a prior concept in software engineering and knowledge management. Kaddo is a practical implementation of KDD principles for AI-assisted software development — it applies them; it did not invent them.

A practical toolkit for Knowledge Driven Development (KDD). It scans your repo, prepares context for your LLM, guides agent-based understanding, turns roadmap candidates into Work Items, declares ownership and warns when code changes may leave knowledge behind.

It works in two layers:

• The CLI does the deterministic work — no AI, no API key.
• Your LLM does the interpretation — using Kaddo agents in your chat (Claude, ChatGPT, Cursor, Copilot, Windsurf…).

Kaddo does not try to make the CLI "understand everything". The CLI collects and structures signals. The LLM agents turn those signals into product understanding.

Your code changes. Your project knowledge often does not.

Projects degrade because knowledge is scattered across meetings, chats, tickets and outdated docs. With AI, this gets worse: agents build on assumptions when they lack context. Kaddo keeps the minimum necessary context alive next to the code — without turning development into bureaucracy.

Kaddo does not optimize prompts. It does not compress context windows, summarize automatically, or remove tokens from a conversation.

Kaddo optimizes what the agent needs to discover. It makes Business, Product, Tech and Delivery knowledge explicit so an agent can start from a context pack instead of repeatedly searching the repository, inferring architecture, guessing capabilities and reconstructing ownership. Less repository exploration leads to better context, better decisions and lower token consumption as a side effect.

npx @kaddo/cli init
# or
npm install -g @kaddo/cli && kaddo --help

Kaddo matures a project's knowledge through four moments — Base → Definition → Projection → Execution — rather than a flat list of commands:

• Base — init · bootstrap · scan · add agents · context · understand (set up the workspace and knowledge structure).
• Definition — business-agent · product-agent · capability-agent · codebase-agent · architecture-agent (turn the idea into clear knowledge).
• Projection — roadmap-agent · backlog-agent · create --from roadmap · work-item-agent · ownership-agent (turn knowledge into a delivery plan).
• Execution — implementation-agent · scan · owners suggest · guard · explain (build, verify and keep knowledge in sync).

See Operating Moments for the full breakdown.

kaddo init                   # state: new | pre-ai | legacy, team size, structure
kaddo scan                   # deterministic technical inventory → .kaddo/scan.json
kaddo context                # LLM context pack → .kaddo/context-pack.md
kaddo add agents             # install agent prompt packs
kaddo understand             # guided CLI → LLM handoff plan
# ── use your LLM with the context pack + agents to create
#    capabilities, architecture and a roadmap ──
kaddo create --from roadmap  # turn a roadmap candidate into a Work Item
kaddo owners suggest         # declare code: ownership on the Work Item
kaddo guard                  # detect possible knowledge drift
kaddo explain                # summarize what Kaddo currently knows

The loop in one sentence: scan the repo → prepare context → use agents in your LLM → create roadmap-driven work items → connect knowledge to code → guard against drift → explain the state.

Prefer to see it first? The Visual Guide maps the whole loop, the CLI/LLM split, the artifact graph and Guard as diagrams.

Pick the guide closest to your situation:

• New project — start with structured knowledge from day one.
• Pre-AI project — prepare an existing repo for humans and LLM agents.
• Legacy project — understand before changing risky systems.
• Full workflow — the complete loop with expected artifacts.
• Project scope — exactly what Kaddo does and does not do.

How to actually operate Kaddo with prompts, traceability and team collaboration:

• Concepts — Work Item, Knowledge Level, Context Pack, Ownership, Knowledge Drift and more.
• Prompt Workflow — CLI input → prompt/agent → expected output → where to save it.
• Work Item Traceability — roadmap → work item → ownership → guard → learning.
• Examples with Other Tools — GitHub Issues, Jira/Linear, OpenSpec, agent frameworks, LLM chats.
• Collaboration Guide — governance by exception, roles and a lightweight PR checklist.

Kaddo does not call an LLM by default, require API keys, generate code automatically, replace human review, or replace Jira / Linear / GitHub Issues.

Each command answers one question and has a clear next step. Lost? Run kaddo understand — it always answers "What should I do now?" from the real state of your project.

scan, context, explain and understand print a Question answered / Suggested next footer so the next step is always one glance away.

Supporting commands: kaddo status, kaddo learn, kaddo classify, kaddo history, kaddo module, kaddo modules map|list, kaddo capsule export|add, kaddo graph export, kaddo report impact, kaddo savings, kaddo guard --record, kaddo drift, kaddo questions, kaddo ignore, kaddo add <module>.

Map secondary repositories as living modules of one system from the architecture repo:

kaddo modules map    # register a secondary repo (frontend/backend/infra…) as a module
kaddo modules list   # list mapped modules

This records the module in .kaddo/modules.yml and generates a per-module knowledge structure under knowledge/tech/modules/<id>/ (module-design.md, stack.md, security.md, standards.md, diagrams/, adrs/). Existing files are never overwritten.

For repos you can't (or don't want to) map — other teams, restricted access, integration-only context — exchange Knowledge Capsules instead: kaddo capsule export shares a minimal summary of this project, kaddo capsule add imports an external one into the context pack's External Knowledge.

Install global artifacts for the whole system on demand:

kaddo add standards    # knowledge/tech/standards.md
kaddo add security     # knowledge/tech/security.md  (documents concerns — no scanning)
kaddo add stack        # knowledge/tech/stack.md
kaddo add git-strategy # knowledge/tech/git-strategy.md + .kaddo/git.yml

Git strategy default is GitHub Flow + Conventional Commits + SemVer, customizable via .kaddo/git.yml — Kaddo recommends, it does not enforce. Six operational agents (work-item, git-strategy, security, standards, stack, module-design) ship with kaddo add agents to refine these artifacts in your LLM. Kaddo never scans repos, calls a Git/GitHub API, or runs a security scan.

The companion package @kaddo/mcp is a read-only Model Context Protocol server that exposes a project's curated Kaddo knowledge — context pack, explain, understand, graph, hints, Work Items, roadmap, capsules and agent prompts — to MCP-compatible agents and IDEs, so they get structured context instead of scanning the whole repo.

{ "mcpServers": { "kaddo": { "command": "npx", "args": ["@kaddo/mcp"], "cwd": "/path/to/project" } } }

It never writes files, runs git, calls an LLM or reads source code. See the MCP Server docs and examples/mcp/.

Skills are reusable capability definitions that standardize how agents do common things well (writing an ADR, refining a Work Item, proposing ownership) — reducing duplicated instructions across prompts. Agents orchestrate; skills standardize. A skill never executes anything: no git, no LLM, no file changes.

kaddo add skills                  # recommended (delivery + tech)
kaddo add skills --all            # every skill
kaddo add skills --group tech     # one group: delivery | tech | integration

Skills install into knowledge/skills/<id>/skill.md; kaddo context/explain/understand summarize them, installed agent prompts reference the skills they should apply, and the @kaddo/mcp server exposes them (kaddo://skills, kaddo_list_skills/kaddo_get_skill).

Generate a native instruction file so an AI coding tool works inside a Kaddo repo without manual context pasting — AGENTS.md for Codex, OpenCode, Antigravity and Kiro, CLAUDE.md for Claude Code:

kaddo adapters install codex            # write AGENTS.md (alias: kaddo export codex)
kaddo adapters install claude           # write CLAUDE.md (alias: kaddo export claude)
kaddo adapters install opencode         # write AGENTS.md for OpenCode (alias: kaddo export opencode)
kaddo adapters install antigravity      # write AGENTS.md for Antigravity (alias: kaddo export antigravity)
kaddo adapters install kiro             # write AGENTS.md for Kiro (alias: kaddo export kiro)
kaddo adapters install <adapter> --dry-run  # preview
kaddo adapters install <adapter> --inject   # add/update only the Kaddo block in a team-owned file
kaddo adapters install <adapter> --force    # overwrite
kaddo adapters list                         # the supported adapters (alias: ls)
kaddo adapters status                       # install state of each adapter in this project (alias: check)

Both are compact, generated projections of the project's knowledge map, operating rules, readiness gates, package-manager-aware command fallbacks, installed agents/skills and useful commands — Kaddo stays the source of truth. See Custom Adapters for the shared Adapter Contract.

Kaddo ships templates for its main artifacts — Work Items, roadmaps, capabilities, business definition (product brief, problem, users…), architecture baselines, quality attributes, codebase foundation, ADRs, multirepo modules, security, standards, stack, Git strategy, incidents, runbooks and legacy risks/unknowns/modernization candidates. They live in a central registry (packages/cli/src/templates/registry.ts) and are organized into six categories: core, business, architecture, module, operations and legacy.

Templates are designed to capture minimum sufficient knowledge without creating documentation theater — they are guides, not mandatory forms. Each carries a purpose, when-to-use, output path, related command/agent and a quality checklist. See the Templates docs.

The examples/ folder has reproducible demo repositories — open one and see how Kaddo turns a project into operative knowledge, with committed .kaddo/ and knowledge/ artifacts so you can inspect the output without running anything:

Each example also ships a prompt-flow.md — a Mermaid diagram, the CLI↔LLM split, an input/output table and copy/paste prompt handoffs — so you can reproduce the full loop without guessing which prompt to use. CLI artifacts are exactly what kaddo writes; agent outputs are clearly marked as illustrative. See the Examples docs.

Ownership is declared in the front matter of each artifact — no central mapping file:

---
type: feature
id: WI-001
title: "Add payment retry logic"
status: in-progress
code:
  - src/payments/**
  - src/shared/payment/**
---

Guard Lite reads git diff, finds artifacts whose code: globs match the changed files, and shows a non-blocking FYI when the artifact was not updated in the same diff:

  ⚠ Possible knowledge drift: WI-001 (feature, K2)
    Changed code matching this artifact:
      - src/payments/payments.service.ts
    WI-001 was not updated in this diff.

Guard is silent when no artifacts declare ownership — no noise on day one. Run kaddo owners suggest to declare globs without editing YAML by hand.

• Not a code generator
• Not an agent execution framework (it ships agent prompts, it does not run them)
• Not a replacement for Jira, Linear or documentation tools
• Not a platform
• Does not call an LLM or require an API key

Optional modules (installed with kaddo add): adr · rfc · incident · migration · legacy · contracts · capabilities · guard-advanced · agents · skills · standards · security · stack · git-strategy

Projects degrade because knowledge is scattered across meetings, chats, tickets and outdated docs. With AI this gets worse: agents build on assumptions when they lack context. Kaddo keeps the minimum sufficient knowledge alive next to the code and packages it deterministically for LLMs and agents — so software evolves with humans and AI, and critical decisions stay human.

Kaddo is created and maintained by Julian Dario Luna Patiño — Cloud Solutions Architect Lead, AWS Community Builder and content creator at TryCatch.tv. It is the result of years designing software architectures, leading development teams and documenting systems. Kaddo applies Knowledge Driven Development principles to AI-assisted software development; it does not claim to have invented KDD. GitHub · LinkedIn · About.

See CONTRIBUTING.md.

MIT