Architecture Overview

Design rationale for Apogee’s component model, dependency direction, and extension points.

Goals

  • Static-only: analyze repos without importing or executing their code.

  • Deterministic artifacts: stable ordering and predictable output shape.

  • Separation of concerns: generator produces extracted structure; AI/humans add constrained annotations.

  • Lifecycle governance: chains, gates, and proof harness enforce quality and compliance at lifecycle boundaries.

  • Guardrails by default: low extraction coverage restricts what can be safely regraded.

Non-goals

  • Runtime execution of target code.

  • Domain/architecture inference (e.g., labeling modules as “services/controllers”).

  • Framework-specific heuristics.

Component Map

Component

Path

Purpose

Skill library

skills/

Reusable lifecycle skills: workflows, tasks, repo init

Compiled skill runtime

src/skill_runtime/

Markdown skill compiler, generated Python modules, runtime registry

MCP server (Rust)

apogee-mcp/

Stdio MCP server for IDE skill discovery, manifest ops, chain execution, gate evaluation, and CPG query tools

Repo manager (Rust)

apogee-repo/

CLI for bootstrapping and managing Apogee-enabled repositories

Manifest generator (Rust)

manifest/generator/

Production Rust CLI for manifest generation (6-crate workspace)

CPG engine (Rust)

manifest/tree/

Clean-room Rust CPG library: tree-sitter parsing, model, visitors, DuckDB emitter

Proof harness (Rust)

proof/harness/

Proof runner, report builder, suite dispatch, assertion framework

Gate policy (Python)

src/apogee_engine/gate_policy.py

Policy-driven governance gate definitions (sole survivor of the former apogee_engine package)

Perigee

perigee/

BEAM-native chain execution runtime: supervised GenServer sessions with OTP crash recovery, checkpointing, and session state management

Dependency Direction

Dependencies flow inward: the MCP server depends on the graph library and skill registry; standalone tools have no downstream dependents.

apogee-mcp       ->  apogee-graph (manifest/generator/crates/),
                     skill_registry.json, Perigee (unix socket)
apogee-repo      ->  (standalone Rust CLI)
manifest/generator -> apogee-tree (manifest/tree/)
proof/harness    ->  (standalone Rust crate)
skill_runtime    ->  framework_common
framework_common ->  (stdlib only)
apogee-tree      ->  (standalone Rust crate)

apogee-mcp is the integration surface — it wires skill discovery, manifest operations, chain execution, gate evaluation, and CPG queries into a single MCP transport layer. Chain execution, checkpoint persistence, and session state are owned by Perigee (Elixir/OTP).

The manifest generator and proof harness are leaf components with no downstream dependents inside the framework.

Main Components

1) MCP server (apogee-mcp/)

The primary integration point for AI coding assistants. Rust binary communicating over stdio (MCP protocol). Exposes:

  • Resources (read-only state): workflow catalog, workflow detail, repo status, server status, gate status, constraint state, config health

  • Prompts: prepare_workflow, run_workflow

  • Tools (actions): route, find_skill, run_skill, suggest_next, set_constraint, define_chain, execute_chain, checkpoint_chain, resume_chain, generate_manifest, rescore_manifest, summarize_manifest, get_manifest_context, plus CPG query tools

Also contains Rust implementations of chain execution, gate evaluation, artifact inventory, and constraint routing (previously in src/apogee_engine/). Compatible with Claude Code, Cursor, and any MCP-capable host.

2) Gate policy (src/apogee_engine/gate_policy.py)

The sole surviving module from the former apogee_engine Python package. Defines policy-driven governance gate structures. Chain execution, gate evaluation, checkpoint state, artifact inventory, and all other lifecycle engine logic has been ported to Rust in apogee-mcp/.

3) Skill library (skills/)

104 compiled skills organized into collections:

  • skills/tasks/ – one-shot utilities (git, testing, audit, docs)

  • skills/workflows/ – ordered multi-step suites (feature design, implementation, review, porting)

  • skills/repo_init/ – project bootstrapping (manifest generation, regrade, install)

skills/CATALOG.md is the canonical index. For terminology definitions, see GLOSSARY.md.

Adaptive parallelism: every skill includes an “Adaptive parallelism safety gate” section. Read-only skills fan out 2-4 subagents for parallel exploration. Write-mode skills centralize all writes in the main agent. See CONTRIBUTING.md for the full convention.

4) Compiled skill runtime (src/skill_runtime/)

Active skill execution goes through a compiled runtime boundary:

  • src/skill_runtime/compiler/ parses Markdown skills, validates metadata, and emits deterministic Python modules plus src/skill_runtime/generated/registry.py

  • src/skill_runtime/generated/ is the active runtime registry for MCP-facing skill lookup and prompt preparation

  • Canonical skill_id is the runtime identity; MCP presents the wire-level field name workflow_id as a 1:1 alias

  • Raw skills/**/*.md files remain the authoring format but are not the runtime execution registry

  • Optional org/team/user source layers (APOGEE_ORG_SKILLS, APOGEE_TEAM_SKILLS, APOGEE_USER_SKILLS) are build-time compiler inputs merged in that order

5) Shared framework helpers (src/framework_common/)

Pure helper modules with no dependency on mcp_server or skill_runtime:

  • placeholder_resolver.py – placeholder parsing, PromptInputSpec, template resolution

  • repo_context_discovery.py – repo-derived context inputs for skill preparation

  • artifact_scanner.py – feature/implementation-order scanning

  • env_constants.py – environment variable name constants for layered skill configuration

  • git_utils.py – git subprocess helpers for repo metadata

6) Rust CPG engine (manifest/tree/, manifest/generator/)

Clean-room Rust implementation for structural CPG extraction:

  • manifest/tree/ – core library: tree-sitter parsing, CPG model, visitor framework, DuckDB emitter

  • manifest/generator/ – production Rust CLI for manifest generation (6-crate workspace: core, analyze, graph, subsystems, fragment, cli)

The Rust engine is the production manifest generator for all codebases.

7) Repo manager (apogee-repo/)

Standalone Rust CLI for bootstrapping and managing Apogee-enabled repositories. Handles project initialization, configuration updates, and status reporting.

8) Manifest schema + templates (spec/)

spec/manifest_schema.md defines the manifest structure, ownership model, and determinism requirements.

The manifest is split into:

  • Generator-owned sections (meta, ownership, inventory, syntax, relationships, scores, ai_regrade_prompt): recomputable, should not be hand-edited except to fix extraction mistakes with evidence

  • AI-owned section (regraded): annotations plus structured overrides (symbol_overrides, relationship_overrides) that feed back into scoring via --rescore-only

9) Proof harness (proof/harness/)

Release verification framework implemented as a standalone Rust crate:

  • report.rs – structured proof report builder conforming to spec/proof_report_contract.md

  • suite.rs – test suite definition and loading

  • dispatch.rs – proof runner dispatch and orchestration

  • assertions.rs – assertion framework for proof steps

Reports include trust evaluation, surface coverage tracking, and manual follow-up items.

10) Perigee (perigee/)

BEAM-native chain execution runtime built on Elixir/OTP. Owns session state, wave state, and checkpoint persistence. Provides supervised GenServer sessions with OTP crash recovery and checkpointing. Communicates with apogee-mcp via Unix socket transport.

Ownership Model

Each component has a clear owner surface. Cross-component changes require understanding both sides of the boundary. The MCP server is the integration surface – it wires components together but does not own their internal logic.

The manifest separates generator-owned structure from AI-owned annotations to prevent “quiet drift” where human edits overwrite generated structure and become impossible to regenerate or validate.

Score Gates and the Regrade Loop

When extraction coverage is low, the system prioritizes reading gap files and extracting symbols/relationships into structured overrides. Evidence (file path + byte span) is required for all overrides to ensure dedup compatibility. After writing overrides, --rescore-only merges them into scoring without re-parsing.

The iterative extraction loop (driven by skills/repo_init/regrade_manifest.md) converges when overall_score >= 95, score delta < 2, or 5 iterations are reached.

Extending Safely

When changing cross-cutting behavior (schema, scoring, guardrails, skill conventions), keep these files aligned:

  • spec/manifest_schema.md

  • spec/project_ai_instructions.template.json

  • skills/repo_init/regrade_manifest.md

  • manifest/generator/ (Rust manifest crates)

  • apogee-mcp/src/gate.rs (gate evaluation logic)

  • src/apogee_engine/gate_policy.py (gate policy definitions)

  • src/framework_common/git_utils.py (when Git metadata behavior changes)

See Also