Visual Guide

This page is the visual map of Kaddo. It shows the implemented v2.6+ knowledge loop: what the deterministic CLI does, what your LLM agents do, how artifacts connect, and how Guard, multirepo and governance fit in. Click any diagram to open it full-screen.

These diagrams describe behavior that exists today. They do not imply any future automation — see What the diagrams do not mean.

Operating moments

Kaddo matures a project’s knowledge through four moments. See Operating Moments for the full breakdown.

flowchart TD
    A["Base — init · bootstrap · scan · add agents · context · understand"] -->
    B["Definition — business-agent · product-agent · capability-agent · codebase-agent"]
    B --> C["Projection — roadmap-agent · backlog-agent · create --from roadmap · work-item-agent"]
    C --> D["Execution — implementation-agent · scan · owners suggest · guard · explain"]

Knowledge layers (macro flow)

Kaddo frames the whole project as four macro layers under knowledge/. Each answers one question and stays connected to the one above it.

flowchart TD
    B[Business — why it exists] --> P[Product — what we build]
    P --> T[Tech — how we build it]
    T --> D[Delivery — how we evolve it]
    B --> B1[problem · users · constraints · business-rules]
    P --> P1[product-brief · capabilities]
    T --> T1[codebase · current-state · decisions · modules]
    D --> D1[roadmap · work-items]

kaddo bootstrap seeds the minimal base (Business + Product + tech/codebase.md); Delivery and decisions emerge later through agents and real work.

Repository Exploration Tax

Without structured knowledge, agents spend part of every session rediscovering the project. With Kaddo, they can start from a context pack built from explicit knowledge.

flowchart LR
    subgraph Without["Without Kaddo"]
        A[Repository] --> B[Search files]
        B --> C[Infer architecture]
        C --> D[Infer capabilities]
        D --> E[Infer roadmap]
    end

    subgraph With["With Kaddo"]
        F[Knowledge] --> G[Context Pack]
        G --> H[Agent]
    end

Knowledge maturity

Kaddo recognizes knowledge by front-matter type (not file name) and reports a maturity per layer. Knowledge grows from consolidated to traceable as the project earns it.

flowchart LR
    A[Consolidated<br/>business.md · product.md · codebase.md] --> B[Structured<br/>capabilities · current-state · ADRs]
    B --> C[Traceable<br/>roadmap · work-items · ownership]

Kaddo Knowledge Loop

The full loop, from a raw repo to an explained knowledge state. CLI steps are deterministic; the agent step happens in your own LLM chat.

flowchart TD
    A[Repo / Project] --> B[kaddo init]
    B --> C[kaddo scan]
    C --> D[scan.json + inventory.md]
    D --> E[kaddo context]
    E --> F[context-pack.md]
    F --> G[kaddo understand]
    G --> H[understand.md]
    H --> I[LLM Chat + Kaddo Agents]
    I --> J[capabilities.md]
    I --> K[current-state.md]
    I --> L[roadmap.md]
    L --> M[kaddo create --from roadmap]
    M --> N[work-items/draft/*.md]
    N --> O[kaddo owners suggest]
    O --> P[front matter code: globs]
    P --> Q[Code changes]
    Q --> R[kaddo guard]
    R --> S{Possible drift?}
    S -->|Yes| T[Review / update artifact]
    S -->|No| U[Continue]
    T --> V[kaddo explain]
    U --> V
    V --> W[explain.md]

Agent flow & responsibility boundaries

Each agent produces knowledge and hands off to the next. Only the implementation-agent may suggest a Git branch — and only by respecting the project Git strategy. The roadmap-agent and work-item-agent never suggest branches or commits.

flowchart TD
    A[business-agent] --> B[product-agent]
    B --> C[codebase-agent]
    C --> D[architecture-agent]
    D --> E[roadmap-agent]
    E --> F[kaddo create --from roadmap]
    F --> G[work-item-agent]
    G --> H[implementation-agent]
    H --> I[kaddo scan]
    I --> J[kaddo owners suggest]
    J --> K[kaddo guard]
    K --> L[kaddo explain]
    H -. only this agent suggests a branch .-> H

Backlog capture (idea → structured work)

The backlog-agent turns any raw idea, note or transcript into a Work Item draft or a roadmap candidate. It never refines, implements or auto-runs the next agent — a human always decides what happens next.

flowchart TD
    I[Idea / notes / transcript] --> BL[backlog-agent]
    BL --> D[Work Item draft]
    BL --> RC[Roadmap candidate]
    BL --> M[Multiple items - split]
    D --> H{Human decides}
    RC --> H
    M --> H
    H --> WI[work-item-agent]
    WI --> R[ready] --> IMPL[implementation-agent]

Idea	backlog-agent output
”Export tasks to CSV”	a Work Item draft
”A complete authentication system”	a roadmap candidate
”Login · Reports · Notifications”	3 backlog items

Command roles: scan · context · explain · understand

Each command has a distinct role. understand recommends the next step from the real knowledge state, not just the configured project.state.

flowchart LR
    S[scan<br/>detect signals] --> X[explain<br/>what Kaddo knows]
    S --> C[context<br/>package for LLM]
    C --> U[understand<br/>what to do now]
    X -.inspect anytime.-> U
    U --> A[recommended agent]

Every command follows the same shape — and scan/context/explain/understand print the last two lines as a footer:

Question  →  Command  →  Output  →  Next action

Question	Command	Output	Next
What exists in the repo?	scan	scan.json · inventory	explain / context
What does Kaddo know?	explain	explain.md	understand
What do I give an LLM?	context	context-pack.md	recommended agent
What should I do now?	understand	understand.md + recommendation	the recommended action

Project knowledge language

The project language (en/es, set at kaddo init) flows into everything Kaddo generates — but not the CLI, which stays English.

flowchart LR
    L[project.language] --> T[Templates]
    T --> K[Knowledge]
    K --> A[Agent outputs]
    L -. never changes .-> C[CLI · commands · flags · file names]

Unified knowledge discovery

Every command discovers knowledge artifacts through one shared service, so explain, context, understand, owners suggest and guard always agree on what exists. Work Items are discovered recursively across lifecycle subfolders.

flowchart TD
    K[knowledge/ artifacts<br/>recursive · front-matter aware] --> D[Unified discovery service]
    D --> E[explain]
    D --> C[context]
    D --> U[understand]
    D --> O[owners suggest]
    D --> G[guard]

CLI vs LLM

Kaddo works in two layers. The CLI is deterministic and never calls an LLM; your LLM chat (with Kaddo agent prompts) does the interpretation. The Knowledge Repository is the shared ground between them.

flowchart LR
    subgraph CLI["Kaddo CLI · deterministic"]
        A[init]
        B[scan]
        C[context]
        D[understand]
        E[create --from roadmap]
        F[owners suggest]
        G[guard]
        H[explain]
    end
    subgraph LLM["LLM Chat + Kaddo Agents · interpretation"]
        I[capability-agent]
        J[architecture-agent]
        K[roadmap-agent]
        L[legacy-agent]
        M[adr-agent]
        N[operational agents]
    end
    subgraph Repo["Knowledge Repository"]
        O[.kaddo/]
        P[knowledge/]
        Q[work-items]
        R[ownership globs]
    end
    B --> O
    C --> O
    D --> I
    D --> J
    D --> K
    I --> P
    J --> P
    K --> P
    P --> E
    E --> Q
    Q --> F
    F --> R
    R --> G
    G --> H

Human ↔ CLI ↔ LLM

The operational handoff. The human runs every command and saves every reviewed artifact — Kaddo never calls the LLM for you.

sequenceDiagram
    participant H as Human
    participant CLI as Kaddo CLI
    participant Repo as Knowledge Repo
    participant LLM as LLM Chat + Agents
    H->>CLI: kaddo init
    CLI->>Repo: .kaddo/config.yml
    H->>CLI: kaddo scan
    CLI->>Repo: scan.json + inventory.md
    H->>CLI: kaddo context
    CLI->>Repo: context-pack.md
    H->>CLI: kaddo add agents
    CLI->>Repo: knowledge/agents/*.md
    H->>CLI: kaddo understand
    CLI->>Repo: understand.md
    H->>LLM: context-pack + selected agent
    LLM-->>H: proposed artifact
    H->>Repo: save reviewed artifact
    H->>CLI: kaddo create --from roadmap
    CLI->>Repo: work item
    H->>CLI: kaddo owners suggest
    CLI->>Repo: code globs in front matter
    H->>CLI: kaddo guard
    CLI-->>H: non-blocking FYI
    H->>CLI: kaddo explain
    CLI->>Repo: explain.md

Artifact graph

How each artifact feeds the next, from config.yml to explain.md.

flowchart LR
    A[config.yml] --> B[scan.json]
    B --> C[inventory.md]
    B --> D[context-pack.md]
    D --> E[capabilities.md]
    E --> F[current-state.md]
    F --> G[roadmap.md]
    G --> H[work-items/state/*.md]
    H --> I[code: globs]
    I --> J[guard]
    J --> K[drift FYI]
    E --> L[explain.md]
    F --> L
    G --> L
    H --> L

Project states

kaddo init records the project state. The state changes which agents you reach for first, but the loop and artifacts are the same.

flowchart TD
    A[Project] --> B{State}
    B -->|new| C[Start with lightweight knowledge]
    B -->|pre-AI| D[Prepare existing repo for LLM-assisted evolution]
    B -->|legacy| E[Understand before changing]
    C --> F[roadmap-agent + architecture-agent]
    D --> G[capability-agent + architecture-agent + roadmap-agent]
    E --> H[legacy-agent + architecture-agent + capability-agent]
    F --> I[Roadmap + Work Items]
    G --> I
    H --> I
    I --> J[Ownership]
    J --> K[Guard]
    K --> L[Explain]

Multirepo map

From the architecture repo you map secondary repos as modules; each gets its own knowledge structure. Existing files are never overwritten.

flowchart TD
    A[Architecture Repo] --> B[.kaddo/modules.yml]
    A --> C[knowledge/tech/modules/]
    B --> D[frontend repo]
    B --> E[backend repo]
    B --> F[worker repo]
    B --> G[infra repo]
    C --> H[frontend/module-design.md]
    C --> I[backend/module-design.md]
    C --> J[worker/module-design.md]
    C --> K[infra/module-design.md]
    H --> H1["stack · security · standards · diagrams · adrs"]
    I --> I1["stack · security · standards · diagrams · adrs"]
    J --> J1["stack · security · standards · diagrams · adrs"]
    K --> K1["stack · security · standards · diagrams · adrs"]

Knowledge Capsules (external context)

A project exports a Knowledge Capsule; another imports it as external context — no multirepo mapping, no source access.

flowchart LR
    R[External repo] --> E[kaddo capsule export]
    E --> CAP[Knowledge Capsule]
    CAP --> A[kaddo capsule add]
    A --> CTX["External Knowledge in context-pack"]
    CTX --> L[LLM agent]

Knowledge graph export

kaddo graph export turns the relationships already declared in your knowledge into a lightweight, file-based knowledge graph — for onboarding, impact analysis and context selection. No graph database, no source reads.

flowchart LR
    M["Markdown + front matter"] --> GX[kaddo graph export]
    GX --> J["graph.json + graph.mmd"]
    J --> U["Onboarding / Impact analysis / Context selection"]

Scopes differ by intent:

Active graph: current delivery context (draft, ready, in-progress, blocked)
All graph:    full knowledge map (+ completed; archived excluded by default)
Guard:        active + completed ownership (archived excluded by default)

Each export also rates relationship quality and writes graph-hints.md — non-blocking suggestions to enrich front matter. The graph-agent turns hints into precise metadata you confirm and apply:

flowchart LR
    GX[kaddo graph export] --> H["graph-hints.md"]
    H --> GA[graph-agent]
    GA --> C{Human confirms}
    C --> FM["Better front matter"]
    FM --> GX

Skills (reusable capabilities)

Agents orchestrate the flow; skills standardize how to do common things well. An agent applies one or more skills to produce consistent output.

flowchart LR
    K[Knowledge] --> C[Context Pack]
    C --> A[Agent]
    A --> S[Skill]
    S --> O[Structured output]

MCP server (read-only)

Agents and IDEs can read curated Kaddo knowledge directly through the read-only @kaddo/mcp server — no manual copy/paste, no source scanning.

flowchart LR
    A["MCP client / IDE / agent"] --> M["@kaddo/mcp (read-only)"]
    M --> K[".kaddo/ + knowledge/ + external/"]
    K --> O["context · explain · understand · graph · work items · capsules · prompts"]

Ownership: agent-assisted

The ownership-agent proposes precise code: globs; you confirm and apply them. owners suggest is the manual/override tool (with glob normalization and path validation).

flowchart LR
    S[kaddo scan] --> C[kaddo context]
    C --> O[ownership-agent]
    O --> H{Human confirms}
    H --> A[kaddo owners suggest / apply]
    A --> G[kaddo guard]

Ownership flow

Ownership is proposed from scan signals by an agent and confirmed by a human before it is recorded on the artifact. code: accepts multiple globs.

flowchart LR
    A[kaddo scan] --> B[kaddo owners suggest]
    B --> C[agent interprets signals]
    C --> D[human confirms]
    D --> E[ownership recorded on artifact: code: globs]
    E --> F[kaddo guard relates code changes]

Roadmap → Candidates → Materialized Work Items

A roadmap lists candidates, not Work Items. The roadmap-agent (in your LLM chat) writes the roadmap in any supported format; the Kaddo CLI parses candidates deterministically; you materialize them into real Work Items with kaddo create --from roadmap. explain and understand report the gap (remaining candidates).

flowchart LR
    A[roadmap-agent in LLM chat] --> B[knowledge/delivery/roadmap.md<br/>table · bullet · checklist · mixed]
    B --> C[Parsed candidates<br/>WI-001, WI-002, …]
    C -->|kaddo create --from roadmap| D[Materialized Work Items<br/>knowledge/delivery/work-items/draft/]
    C -.remaining candidates.-> E[explain · understand<br/>candidates vs materialized]
    D -.-> E

Work Item lifecycle workspace

Work Items are an active workspace organized by lifecycle state. Phase and initiative remain front matter metadata; they do not create folders.

Each Work Item has a type — feature, bugfix, hotfix, spike or chore — that flows through the same lifecycle. chore keeps maintenance/tooling/config/infra work from being mislabeled as a feature.

flowchart TD
    T["type: feature · bugfix · hotfix · spike · chore"] --> A
    A[Roadmap Candidate] --> B[Draft]
    B --> C[Ready]
    C --> D[In Progress]
    D --> E[Completed]
    E --> F[Archived]
    D --> G[Blocked]
    G --> C

Work Item delivery lifecycle

From a Work Item to a commit, with knowledge kept in sync. The Kaddo CLI never touches git: the implementing agent (work-item-agent) creates the branch and commits only with your confirmation.

flowchart TD
    A[Roadmap] --> B[Create Work Item]
    B --> C[Branch — agent, per git strategy]
    C --> D[Implementation]
    D --> E[kaddo scan]
    E --> F[kaddo owners suggest → human confirms]
    F --> G[kaddo guard before commit]
    G --> H[Update knowledge: ADR · capabilities · current-state]
    H --> I[Review human]
    I --> J[Commit e.g. feat scope: message]

Guard Lite

Guard reads git diff, matches changed files against declared code: globs, and emits a non-blocking FYI only when an owning artifact was not updated in the same diff. It is silent when no artifact declares ownership.

flowchart TD
    A[git diff] --> B[Changed files]
    C[Artifacts with front matter] --> D[code: globs]
    B --> E[Match files vs globs]
    D --> E
    E --> F{Match?}
    F -->|No| G[No warning]
    F -->|Yes| H{Artifact also changed?}
    H -->|Yes| I[No warning]
    H -->|No| J[Possible Knowledge Drift FYI]
    J --> K[Human reviews]
    K --> L[Update artifact or confirm no impact]

Governance levels

Governance scales by team size. Kaddo never enforces it — review happens by exception.

flowchart TD
    A[Kaddo Project] --> B{Team size}
    B -->|Indie| C[No formal owner]
    B -->|Small team| D[Review in PR]
    B -->|Medium team| E[Tech Lead by exception]
    B -->|Enterprise| F[Domain Owners]
    C --> G[Minimum sufficient knowledge]
    D --> G
    E --> G
    F --> G
    G --> H[Work Items by Knowledge Level]
    H --> I[Guard as non-blocking signal]

Kaddo at a glance

A high-level map of commands, agents, artifacts, templates and principles.

mindmap
  root((Kaddo))
    CLI
      init
      scan
      context
      understand
      create
      owners
      guard
      explain
      modules
    Agents
      capability
      architecture
      roadmap
      legacy
      adr
      work-item
      git-strategy
      security
      standards
      stack
      module-design
    Artifacts
      .kaddo
      architecture
      work-items
      modules
    Templates
      core
      architecture
      module
      operations
      legacy
    Principles
      CLI deterministic
      No LLM calls
      Human confirms
      Guard non-blocking
      Ownership in front matter

What the diagrams do not mean

To keep expectations honest, these diagrams do not imply that:

• Kaddo calls an LLM — you run agents in your own chat.
• Guard blocks — it is always a non-blocking FYI.
• Ownership is inferred — code: globs are declared and human-confirmed.
• Kaddo scans remote repos or calls Git/GitHub APIs.
• Kaddo generates these diagrams automatically — they are authored docs.

---

Next: walk the same loop with real artifacts in the Examples, or read the step-by-step Prompt Workflow.