Architecture notes

Internal architecture and design notes for Spec Kitty subsystems. These pages capture design rationale and models; they are working engineering material rather than end-user documentation. This index enumerates every page in docs/architecture/ (see README.md for the boundary rule and layout). The active release cycle is 4.0.0; see the 4.0.0 milestone roadmap.

Living architecture (current + forward)

Architecture — the corpus landing page: the decisions-vs-consumption boundary rule, living pages, and frozen history.
Architecture Vision (living) — current and future forward intent, including the 4.x forward signal.
Architecture Diagrams (living C4) — the living C4 model and how its modules map onto the enforced layer packages.
Diagrams: System Context (living) — C4 level 1, including Team Kitty and the Zeitgeist relay.
Diagrams: Containers (living) — C4 level 2.
Diagrams: Runtime/Execution Domain (living) — C4 level 2 container detail.
Diagrams: Components (living) — C4 level 3.
System Landscape (living) — C4 level 0: domain containers and the packages that implement them.
Implementation Mapping (living) — C4 level 4: where each architecture concept lives in the source tree.
Core Code Patterns Applied in the Codebase — recurring implementation idioms mapped to components.

Explanations

Explanation — the Divio "understanding-oriented" hub for this section.
Spec-driven development — the core methodology.
Mission system — how missions and work packages relate.
Mission-type resolution — the doctrine → charter → core seam.
Execution lanes — the lane-based parallel execution model.
Git worktrees — what worktrees share and keep separate.
Git workflow: who does what — infrastructure git vs content git.
Multi-agent orchestration — coordinating work across agents.
Zeitgeist publisher and lease identity — logical agents, SaaS leases, and relay session references.
Kanban workflow — the nine lanes and their transitions.
Mission transition gates — the declarative, asset-backed, trust-gated model for the checks that guard lane transitions.
The runtime loop — how spec-kitty next inverts control.
AI agent architecture — how Spec Kitty stays agent-agnostic across the 17 supported agents.
Why the Divio documentation system? — tutorials/how-to/reference/explanation mapping.
Doctrine relationships — DRG relation types as typed graph edges.
Understanding the org doctrine layer — built-in/org/project doctrine resolution.
Understanding Charter: synthesis, DRG, and governed context.
Understanding governed profile invocation — standalone dispatch under governance.
Profile-load reliability — why squads stopped loading charter agent profiles, and the stabilization design (partly shipped in 3.2.6; the rest is on 4.x Work).
Charter backend service (future) — preliminary backlog design for a deployable charter/doctrine resolution endpoint.
Documentation Mission Guide — the Documentation Kitty mission.
Understanding the retrospective learning loop — the four-category model.
The Artifact Placement Seam — the layer model deciding which physical tree a mission artifact resolves to, and where callers bypass it.
Post-merge partition authority — one model for the write half (which bytes win per artifact on squash) and the read half (which surface a post-merge reader trusts).
Branch-target routing — which git branch receives each type of change.
WP runtime-state eviction — evicting runtime-mutable state into the event log.
Doctrine artifact kinds — what each of the eight doctrine artifact kinds is for, with a built-in example of each.
SPDD and the REASONS Canvas — the opt-in Structured-Prompt-Driven Development doctrine pack and its change-intent canvas.
Team Kitty and Zeitgeist — the live hosted model: CLI → per-team Zeitgeist relay → Team Kitty Pulse, with the lane-transition sequence diagram.

Status, trail & workflow models

Status model (operator reference) — the append-only event-log lane state machine, the --mission selector, and mission_id ULID identity.
Trail model — how every standalone dispatch writes an auditable JSONL trail for accountability and provenance.
Host-surface parity matrix — how each supported host surface teaches the governance-injection contract, with per-surface parity status.
Spec Kitty mission workflow (canonical authority) — the nine-phase end-to-end mission workflow and the focused-PR path.

Connector & installation decisions

Connector auth / binding separation — separating connector authentication from binding.
GitHub App installation authority — installation-authority model for the GitHub App.

Assessments

Code as a Crime Scene — High-Level Overview — pedagogical overview of the CaaCS auditing technique (durable methodology explainer; the dated 2026-05 forensic run itself lives under docs/archive/plans/engineering-notes/architecture-audits/).

Calibration reports

Calibration Report Template — the per-mission-type DRG context calibration template: does context resolution return what each step needs, and nothing irrelevant?
Calibration Report: documentation.
Calibration Report: erp-custom.
Calibration Report: research.
Calibration Report: software-dev.

Ownership & charter models

Unified Charter Bundle — the single-file authoritative charter.yaml model.
Charter Pack Usage Journey — the apply → generate two-step and the empty-charter dispatch safety net.

Templates & reference

ADR template — the shared ADR authoring template used by all eras.
Pip vs pipx vs uv — which installer to use for the Spec Kitty CLI.

Historical / prior cycle

Kept as records; not maintained as current.

Vision history slot — 3.x — the prior era's settled vision, including the 2026-08-12 forward signal.
Vision history slot — 2.x — per-era vision record for 2.x.
Vision history slot — 1.x — per-era vision record for 1.x.
2.x System Context — frozen 2.x C4 level 1 snapshot.
2.x Containers — frozen 2.x C4 level 2 snapshot.
2.x Runtime/Execution Domain — frozen 2.x C4 level 2 container detail.
2.x Components — frozen 2.x C4 level 3 snapshot.
Functional Ownership Map (demoted) — superseded narrative; module boundaries are owned by the enforced pyproject package list and layer rules.
Architecture: centralized feature detection — the v0.14.0 centralized mission-selection design, superseded by mission_id identity.
Launch-readiness behavior (coming soon) — superseded pre-Zeitgeist launch plan built on the retired sync gate.
Team Kitty (SaaS): the hosted-sync flow — the deleted sync transport, kept as a record.
Gap analysis: connector installation model — point-in-time 2026-03 gap analysis against the pre-convergence code.
Architecture Documentation Guide — retired 2.x-era guide; redirects to the documentation home and llms.txt.
Architecture Navigation Guide — retired 2.x-era guide; redirects to the documentation home and llms.txt.