Architecture notes

Internal architecture and design notes for Spec Kitty subsystems. These pages capture design rationale and gap analyses; they are working engineering material rather than end-user documentation. This index enumerates every page in docs/architecture/ (the section's curated-complete index — see README.md for the boundary rule and layout).

Living architecture (current + forward)

Architecture — the canonical corpus landing page: the architecture/ vs docs/ boundary rule and living-at-top / versioned-history-beneath model.
Architecture Vision (living) — current and future forward intent, above versioned history.
Architecture Diagrams (living C4) — the living C4 model for the current 3.x architecture.
Diagrams: 3.x System Context — living C4 level 1.
Diagrams: 3.x Containers — living C4 level 2.
Diagrams: 3.x Runtime/Execution Domain — living C4 level 2 container detail.
Diagrams: 3.x Components — living C4 level 3.

Versioned history — 3.x

3.x — vision (history slot) — the 3.x era's settled vision history.

Versioned history — 2.x

2.x — vision (history slot) — per-era vision record for 2.x.
2.x System Landscape — C4 level 0 historical snapshot.
2.x System Context — C4 level 1 historical record.
2.x Containers — C4 level 2 historical decomposition.
2.x Runtime/Execution Domain — C4 level 2 historical container detail.
2.x Components — C4 level 3 historical breakdown.
2.x Implementation Mapping — C4 level 4 historical link from components to code.
Core Code Patterns Applied in the Codebase — recurring implementation idioms mapped to components (2.x-era record).

Versioned history — 1.x

1.x — vision (history slot) — per-era vision record for 1.x.

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.
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 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 3.2.6 stabilization design.
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.
Branch-target routing — which git branch receives each type of change.
WP runtime-state eviction — evicting runtime-mutable state into the event log.
Launch-readiness behavior (coming soon) — pre-launch Teamspace design intent.
Architecture: centralized feature detection — how Spec Kitty detects project frameworks and capabilities.
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 (SaaS): the end-to-end hosted-sync flow — opt-in/consent → project-store migration → admission/delivery-target → auth → history disclosure → sync now, with the full-flow interaction 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 notes

Gap analysis: connector installation model — open gaps in the installation-link-mapping-override connector model.
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/plans/engineering-notes/architecture-audits/, see FR-002 verdict below).

Calibration reports

Calibration Report Template — the §4.5.1 inequality-check template, created/updated by WP10.
Calibration Report: documentation.
Calibration Report: erp-custom.
Calibration Report: research.
Calibration Report: software-dev.

Ownership & charter models

Functional Ownership Map — which code slices own which functional areas.
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 tracks.
Pip vs pipx vs uv — which installer to use for the Spec Kitty CLI.

Retired / redirect guides

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.