kaddo context

kaddo context

Assembles a context pack you can hand off to an LLM chat agent (Claude, ChatGPT, Cursor, Copilot, Windsurf…). It reads existing Kaddo artifacts and writes two files:

• .kaddo/context-pack.md — compact, LLM-friendly markdown to paste into a chat.
• .kaddo/context-pack.json — structured data for future tooling and automations.

Inputs

The command reads (each is optional except config):

.kaddo/config.yml          # required — run `kaddo init` first
.kaddo/scan.json           # scan baseline
.kaddo/modules.yml         # mapped multirepo modules (if any)
knowledge/inventory.md  # technical inventory
knowledge/knowledge.md  # current knowledge
knowledge/delivery/roadmap.md    # roadmap
knowledge/delivery/work-items/   # work item metadata (front matter only)

Missing files do not stop the command — their sections are marked under Missing Context so the LLM knows what is not yet available.

By default, the context pack includes only active Work Items: draft, ready, in-progress and blocked. completed and archived are historical knowledge and are excluded so old work does not dominate the LLM handoff.

External Knowledge

If you imported Knowledge Capsules (kaddo capsule add), the pack adds an ## External Knowledge section summarizing each external system (purpose · capabilities · contracts · owner · risks) — minimal context about systems you don’t map as multirepo.

Roadmap candidates vs materialized

When knowledge/delivery/roadmap.md is present, the ## Roadmap section reports candidates (parsed from any supported roadmap format), materialized work items, and remaining candidates. The JSON exposes a roadmap object (present, candidates, materialized, remaining) so the agent knows which candidates are still waiting to become Work Items.

Mapped modules (multirepo)

If the project has modules registered with kaddo modules map, the pack adds a ## Mapped Modules section (and a mappedModules array in the JSON) listing each module’s type, repo path, owner, capabilities and which knowledge/tech/modules/<id>/ artifacts exist. Kaddo reads .kaddo/modules.yml and the module artifacts only — it never scans the secondary repositories.

Knowledge graph summary

If you have run kaddo graph export, the pack adds a small ## Knowledge Graph summary (available, node/edge counts, active Work Items connected to code). It is only a summary — the full graph stays in .kaddo/graph.json / .kaddo/graph.mmd. context never generates the graph and never inlines it.

If kaddo graph export produced metadata hints, the pack also adds a short ## Graph Hints block (relationship quality, active hint count, the suggested graph-agent and a few hint lines) — not the whole graph-hints.md file.

Deterministic, no LLM

kaddo context does not call an LLM, require an API key, or interpret your system. It assembles metadata and summaries — never full source code. Interpretation is the agent’s job.

Operating rules (top of the pack)

The pack starts with an Operating Rules block that the implementing agent must follow — so a coding assistant you paste it into does not commit on its own. In particular: never git commit, push or merge without explicit human confirmation, create a branch before implementing a Work Item, and run kaddo scan / owners suggest / guard after significant changes. The Kaddo CLI never runs git.

Current phase

The pack opens with a Current Phase block derived from the real knowledge state (layers, roadmap, Work Items, ownership) — Discovery / Planning / Delivery Preparation / Active Delivery / Maintenance — with the reason and the recommended next agent. So the agent reading the pack sees what to do next based on reality, not just project.state:

## Current Phase
Phase: Active Delivery
Reason:
- Roadmap available
- 1 materialized work item(s)
Recommended next: implementation-agent
Next step: Start WI-014 — Create task (ready → in-progress)

The Recommended Agent Handoff and the Instructions for the LLM are driven by this real phase too (VS-052) — not by project.state — so the pack never recommends early-stage agents while the project is already in Active Delivery. The LLM instructions change per phase (e.g. Active Delivery / ready → “use the implementation-agent, suggest a branch name only, do not run git”; Active Delivery / draft → “refine draft Work Items, do not implement unless explicitly requested”).

State-aware handoff

The legacy state-based set still seeds early phases; recommendations adapt to the project state recorded by kaddo init:

State	Recommended handoff
new	roadmap-agent → architecture-agent
pre-ai	capability-agent → architecture-agent → roadmap-agent
legacy	legacy-agent → architecture-agent → capability-agent

scan vs context vs understand

• scan collects deterministic technical signals.
• context packages those signals (plus knowledge and work items) into an LLM-ready pack.
• understand ties it together: refreshes the pack and tells you which agent to run next, in what order, for your project state.

Flags

kaddo context                    # writes both .md and .json
kaddo context --format markdown  # only the markdown pack
kaddo context --format json      # only the JSON pack

Example

# Kaddo Context Pack

Generated by `kaddo context`.

## Project Metadata

- Name: dotear-web
- State: pre-ai
- Team size: indie
- Structure: monorepo

## Recommended Agent Handoff

Recommended agents for a pre-AI project:

1. capability-agent
2. architecture-agent
3. roadmap-agent

## Instructions for the LLM

- Use this context pack as the project baseline.
- Do not write code yet.
- First extract: system capabilities, architecture notes, risks, open questions and roadmap candidates.