Multirepo modules

Kaddo represents not only the main architecture repo, but also the secondary repos (frontend, backend, workers, infra…) as living modules of the same system.

Multirepo vs Knowledge Capsules. Map a repo as a module when you have access and it is in scope. When a repo belongs to another team, is access-restricted, or you only need integration context, import a Knowledge Capsule instead — no mapping, no source.

Two levels of descriptor

• kaddo module --init writes knowledge/module.yml — a repo describing itself as a module (name, domains, contracts it exposes/consumes). Use this inside a secondary repo.
• kaddo modules map writes .kaddo/modules.yml in the architecture repo — the system view, where each secondary repo is registered and given a knowledge structure under knowledge/tech/modules/<id>/.

kaddo modules map    # register a secondary repo as a module (interactive)
kaddo modules list   # list mapped modules

Mapping a module

kaddo modules map asks for a name, repository path (relative to the architecture repo), type (frontend · backend · worker · mobile · library · infrastructure · data · unknown), main technology, owner and related capabilities. It then:

1. Records the module in .kaddo/modules.yml (upsert by id — re-mapping updates in place, never duplicates).
2. Generates a knowledge structure from the central template registry (existing files are never overwritten — they are reported as kept):

knowledge/tech/modules/<id>/
  module-design.md
  stack.md
  security.md
  standards.md
  diagrams/.gitkeep
  adrs/.gitkeep

The generated .md files use the official module-design, module-stack, module-security and module-standards templates, with front matter prefilled from the module metadata — including a code: glob (<repoPath>/**):

---
type: module-design
module: storefront-web
name: Storefront Web
status: draft
owner: web-team
repoPath: ../frontend
moduleType: frontend
mainTechnology: Next.js
capabilities:
  - checkout
code:
  - ../frontend/**
---

The code: globs declare ownership consistently. Default kaddo guard still reads only the current repo’s git diff, but the opt-in kaddo guard --workspace also checks local mapped module repos and matches their changes against these globs — see guard → Workspace mode. It never clones or calls remote APIs.

Context efficiency

In a multirepo system, the Repository Exploration Tax multiplies: an agent has to discover which repo owns which capability, where contracts live and which standards apply globally. Kaddo reduces that exploration by mapping each repository as a module, keeping module knowledge under knowledge/tech/modules/<id>/ and surfacing the module map through context and explain.

Example: architecture-repo + frontend + backend + infra

# in the architecture repo
kaddo init
kaddo modules map   # Frontend  → ../frontend   (frontend, Next.js)
kaddo modules map   # Backend   → ../backend    (backend,  NestJS)
kaddo modules map   # Infra     → ../infra      (infrastructure, Terraform)
kaddo modules list

Result:

.kaddo/modules.yml
knowledge/tech/modules/
  frontend/{module-design,stack,security,standards}.md  diagrams/  adrs/
  backend/ {module-design,stack,security,standards}.md  diagrams/  adrs/
  infra/   {module-design,stack,security,standards}.md  diagrams/  adrs/

The generated templates are deliberately thin — refine each one with the matching Kaddo agent (module-design-agent, stack-agent, security-agent, standards-agent) in your LLM, using .kaddo/context-pack.md as input. The front matter and quality checklist come from the template registry, so module artifacts stay consistent with the rest of Kaddo.

Global vs module-level artifacts

• Global (whole system): kaddo add standards|security|stack|git-strategy writes knowledge/tech/<topic>.md once for the system. See Standards, security & stack and Git strategy.
• Module-level (per repo): knowledge/tech/modules/<id>/*.md, generated by kaddo modules map.

Kaddo never scans the secondary repos, never calls a Git/GitHub API, and never runs a security scan. It maps structure deterministically; your LLM agents do the interpretation.