Architecture

How akm is built: system overview, normative specs, decision history, and subsystem internals.

Architecture -- How akm's bundles, cache, index, and registries fit together
Core Principles -- Design principles and constraints
Adapters -- The BundleAdapter contract: what a bundle's files are, how they're indexed, linted, and written
Architecture: The Workflow Engine -- How a workflow compiles to a frozen plan, persists run/unit state, dispatches work, and resumes without replaying completed steps
Architecture: The Improvement Loop -- Purpose and boundary of the improvement loop
Runtime Boundary Design -- Isolating bun:sqlite/Bun.* from the core
Architecture Decision History -- ADR-style record of the major architecture rulings

Specs (`specs/`)

Normative specifications and binding conventions.

OKF format support -- OKF is a first-class format supported through the built-in okf adapter
0.9.0 surface decisions -- The decision record (D1-D12) behind the 0.9.0 breaking changes
Bundle & Adapter Spec (0.9.0) -- Normative spec for bundles, adapters, and bundle recognition
Ref Grammar Decision (0.9.0) -- The [bundle//]conceptId ref grammar
Ref Format -- Wire format for asset references
Format-Neutral Bundle Workspace Spec -- The format-neutral workspace model
Agent, Command, Engine, and Model Resolution -- Approved target semantics for native agent/command bundles, configuration cascading, model maps, and dispatch
0.9.2 Agent/Command/Task/Workflow Implementation Plan -- Sequenced work packages, GitHub milestone tracker, migration rules, support boundaries, and release evidence for the coherent execution MVP
Fact Asset Type -- The fact asset type
Bundle Conventions Code Spec -- Code-level bundle conventions
Bundle Organization Conventions -- How a bundle is laid out
DI Seams Plan -- Dependency-injection seams used by the test suite
Improve Collapse/Churn Detector -- Longitudinal collapse/churn detection design (§6.3 is the operator runbook referenced by akm health)

Historical review registers (0.9.0 release-review audit trail, kept for provenance, not normative going forward):

0.9.0 Docs–Code Drift Register -- Ruled record of places documentation and code disagreed, and open-intent questions (Q-01..Q-19)
0.9.0 Public API Issue Backlog -- Implementation-only findings from the CLI surface review
0.9.0 Release Surface Review -- Reconciled action list from the end-to-end user-facing surface sweep

Current-truth subsystem references.

Storage Locations -- Authoritative inventory of every on-disk read/write path
Search -- Hybrid search architecture and scoring
Indexing -- How the search index is built
Classification -- Matcher and renderer behavior
Improve Workflow -- akm improve command surface and pipeline reference
Health Advisories -- akm health advisory-to-action map for operators
Registry Network Boundary -- Outbound registry request inventory, destination policy, redirects, and DNS guarantees
Functional Contract Patterns -- Quick reference for contributor pipelines and small process contracts
Fresh-Host Rebuild Runbook -- Rebuild an akm install on a new machine
Persisted-Data Compatibility Contract -- What a reader owes data an earlier release wrote, per persisted format

Point-in-time architecture reviews of a specific subsystem question.

Runtime secret resolution for in-process source fetchers -- Why secret reads are injected as a SecretResolver capability instead of imported inside the fetcher subgraph

Workflow architecture: Claude Code workflows vs. akm workflows -- Full technical comparison of the Claude Code Workflow tool and akm workflows; see the short vendor-neutral guide for the decision-level version

Testing Workflow -- End-to-end, Docker, deployment, and upgrade validation, plus the coverage gap guide
Manual Testing Checklist -- Pre-release manual QA checklist
OKF v0.2 Conformance Re-Evaluation Runbook -- Acceptance procedure to re-run after changing adapters, indexing, refs, writes, or lint behavior