Architecture

Apothem architecture overview — the shared profile, the harness-adapter abstraction, and how the source tree is organized.

Apothem is built around a single idea: one shared governance profile, materialized into every harness's native configuration format by a per-harness adapter. This section explains the structural pieces — the adapter protocol, the profile schema, the source-tree layout, and the install workflow that wires them together.

System overview

At a glance, Apothem is one pipeline: a single shared profile feeds the harness registry, which resolves every per-harness adapter; each adapter materializes its harness's native configuration surface, and a standing conformity gate checks every materialized surface.

%% provenance: hand-authored %%
%% verified: 2026-06-23 %%
%% cross-reference: src/apothem/lib/harness_registry.py (runtime registry) + src/apothem/harnesses/ (adapter sub-packages) + src/apothem/conformity/ (conformity gate) %%
flowchart TD
    accTitle: Apothem end-to-end materialization flow
    accDescr: One shared profile feeds the harness registry, which resolves seventeen per-harness adapters; each adapter runs its install, uninstall, update, and verify lifecycle, with four single-file-config adapters also rendering a native config file through a materializer, and writes the harness's own native configuration surface. A standing conformity gate checks every materialized surface.
    P["Shared profile<br/>~/.config/apothem/profile.yaml<br/>rules, skills, hooks, slash-commands, MCP servers"]
    R["Harness registry<br/>authoritative at runtime<br/>(resolves every adapter)"]
    A["17 per-harness adapters<br/>each: install / uninstall / update / verify<br/>+ materializer on 4 single-file-config adapters"]
    N["Each harness's native config surface<br/>Claude Code settings.json, Cursor .mdc,<br/>Gemini GEMINI.md, Copilot instructions.md, …"]
    G["Conformity gate<br/>pre-emission validators"]

    P --> R
    R --> A
    A --> N
    G -.->|standing check over every materialized surface| N

Pages

Page	Description
Harness adapter abstraction	The `HarnessAdapter` protocol — how adapters translate the shared profile into platform-native config.
Shared profile schema	The schema-backed YAML profile at `~/.config/apothem/profile.yaml` or `--profile PATH`.
Source layout	Why Apothem uses a `src/` layout and how the tree is organized.
Installation workflow	How `apothem install`, `update`, and `uninstall` work end-to-end.
Delegated workers	Repository-scoped instructions for multi-worker runtimes operating in this repo.
Self-contained runtime	How the engine runs from any checkout — vendored dependencies, the `PYTHONPATH=src` invocation model, and the plugin-tree bootstrap.
Dependency vendoring strategy	Which third-party packages Apothem vendors under `src/apothem/_vendor/`, which stay system prerequisites, and how vendored copies are refreshed.
Cohort packaging contract	The downstream-consumable contract that enumerates cohorts and resolves their per-harness native targets without re-deriving the mapping.
CI/CD pipeline diagram	A visual map of the build, test, lint, security, and publish workflow stages that gate every code change and release.

Architecture

System overview

Pages

On this page