Concepts

Kaddo has its own vocabulary. Understanding these terms is the difference between treating Kaddo as “another documentation tool” and using it as a living knowledge system close to the code.

Work Item

A Work Item is the smallest traceable unit of product evolution in Kaddo. It is not only a task.

It can represent a:

• feature
• hotfix
• bugfix
• spike
• architecture change
• migration
• incident follow-up
• capability improvement
• documentation or knowledge update

A Work Item captures:

• why the change exists
• what context is required
• what knowledge level applies
• what artifact/source produced it
• what code ownership it touches
• what learning should be preserved

It connects the whole loop:

roadmap candidate → implementation decision → code change → ownership → guard → learning

Knowledge Level

A Knowledge Level defines the minimum context required before acting. It exists to avoid bureaucracy: small changes do not need heavy documentation.

Level	Minimum context
K0	No formal knowledge required
K1	Problem + expected result
K2	Problem + expected result + impact + acceptance criteria
K3	Problem + impact + acceptance criteria + design
K4	Problem + impact + design + ADR + risks

Context Pack

A Context Pack is a deterministic package generated by the CLI (kaddo context → .kaddo/context-pack.md) to prepare input for the LLM. It is not the LLM output — it is the structured input you hand to your agent.

Agent Prompt Pack

An Agent Prompt Pack is a versionable Markdown prompt (installed with kaddo add agents into architecture/agents/*.md) that tells the LLM what role to assume, what input to use and what artifact to produce. Kaddo ships the prompts; it does not run them.

Ownership

Ownership is metadata that connects knowledge artifacts to code paths, declared in the artifact’s front matter:

code:
  - src/payments/**

No central mapping file — ownership lives next to the knowledge.

Knowledge Drift

Knowledge Drift is a possible divergence between the implementation and the knowledge artifacts that explain or govern it — code moved on, the knowledge did not.

Guard Lite

Guard Lite (kaddo guard) is a deterministic check that reads git diff, matches changed files against artifact code: globs, and shows a non-blocking FYI when the matching artifact was not updated in the same diff. It is silent when no artifacts declare ownership.

Explain

Explain (kaddo explain) summarizes what Kaddo currently knows about the project — state, stack, artifacts present, Work Items, ownership coverage and suggested next steps. It writes .kaddo/explain.md and .kaddo/explain.json.

---

Next: Prompt Workflow — what to do at each step.