# ganyuanran/aegis architecture

> Architecture diagram of the GitHub repository ganyuanran/aegis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ganyuanran/aegis
- Repository: https://github.com/ganyuanran/aegis

## Overview

Aegis is a cross-host method pack for AI coding agents, combining reusable workflow skills with host-specific activation and workspace helpers. Its principal workflow is to orient and plan against the project baseline, make appropriately scoped changes, then verify and communicate completion with evidence. The repository also includes optional Codex record/final-response reconciliation. The README describes capabilities and installation behavior; source excerpts establish adapter and reconciliation links. Unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`skills/using-aegis/SKILL.md`](https://github.com/ganyuanran/aegis/blob/main/skills/using-aegis/SKILL.md) (Aegis routing), [`extensions/codex-reconciliation/hook.py`](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/hook.py) (Codex integration), [`extensions/codex-reconciliation/profile.py`](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/profile.py) (Codex profile), [`extensions/codex-reconciliation/review.py`](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/review.py) (Record review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Engineering methods"]
  node_context["Project context<br/>[SKILL.md]"]
  node_using["Aegis routing<br/>[SKILL.md]"]
  node_brainstorm["Brainstorming<br/>[SKILL.md]"]
  node_planning["Planning<br/>[SKILL.md]"]
  node_execution["Plan execution<br/>[SKILL.md]"]
  node_tdd["Test-driven development<br/>[SKILL.md]"]
  node_debugging["Systematic debugging<br/>[SKILL.md]"]
  node_review["Code review<br/>[SKILL.md]"]
  node_verification["Completion verification<br/>[SKILL.md]"]
  node_governance["Complexity governance<br/>[SKILL.md]"]
  node_ui_governance["UI/UX governance<br/>[SKILL.md]"]
end

subgraph group_host["Host activation"]
  node_claude["Claude integration<br/>[hooks.json]"]
  node_codex["Codex integration<br/>[hook.py]"]
  node_dsh["DSH integration<br/>[index.js]"]
  node_dsh_bootstrap["DSH bootstrap<br/>[bootstrap.js]"]
  node_shared_bootstrap["Pi/OMP bootstrap<br/>[aegis-bootstrap.ts]"]
  node_pi_adapter["Pi adapter<br/>[index.ts]"]
  node_omp_adapter["OMP adapter<br/>[index.ts]"]
end

subgraph group_workspace["Workspace support"]
  node_workspace_tool["Workspace manager<br/>[aegis-workspace.py]"]
  node_doctor["Install doctor<br/>[aegis-doctor.py]"]
  node_updater["Aegis updater<br/>[aegis-update.py]"]
  node_deferred_ledger["Deferred ledger"]
end

subgraph group_reconcile["Codex reconciliation"]
  node_profile["Codex profile<br/>[profile.py]"]
  node_record_review["Record review<br/>[review.py]"]
  node_transport["Assessor transport<br/>[transport.py]"]
end

node_developer(("Developer"))
node_coding_agent(("Coding agent"))

node_developer -->|"requests work"| node_coding_agent
node_coding_agent -->|"routes methods"| node_using
node_using -->|"aligns baseline"| node_context
node_using -->|"frames design"| node_brainstorm
node_using -->|"plans changes"| node_planning
node_using -->|"guides execution"| node_execution
node_using -->|"supports TDD"| node_tdd
node_using -->|"guides diagnosis"| node_debugging
node_using -->|"requests review"| node_review
node_using -->|"proves completion"| node_verification
node_using -->|"tracks retirement"| node_governance
node_using -->|"applies UI rules"| node_ui_governance
node_coding_agent -.->|"activates methods"| node_claude
node_coding_agent -.->|"activates methods"| node_codex
node_coding_agent -.->|"activates methods"| node_dsh
node_dsh -->|"installs bootstrap"| node_dsh_bootstrap
node_coding_agent -.->|"activates methods"| node_pi_adapter
node_coding_agent -.->|"activates methods"| node_omp_adapter
node_pi_adapter -->|"delegates to"| node_shared_bootstrap
node_omp_adapter -->|"delegates to"| node_shared_bootstrap
node_developer -.->|"manages workspace"| node_workspace_tool
node_developer -->|"verifies install"| node_doctor
node_developer -->|"requests update"| node_updater
node_codex -.->|"uses profile"| node_profile
node_codex -->|"calls assessment"| node_record_review
node_codex -->|"runs assessor"| node_transport
node_profile -->|"imports review"| node_record_review
node_profile -->|"imports transport"| node_transport
node_record_review -->|"uses transport"| node_transport

click node_context "https://github.com/ganyuanran/aegis/blob/main/skills/establishing-project-context/SKILL.md"
click node_using "https://github.com/ganyuanran/aegis/blob/main/skills/using-aegis/SKILL.md"
click node_brainstorm "https://github.com/ganyuanran/aegis/blob/main/skills/brainstorming/SKILL.md"
click node_planning "https://github.com/ganyuanran/aegis/blob/main/skills/writing-plans/SKILL.md"
click node_execution "https://github.com/ganyuanran/aegis/blob/main/skills/executing-plans/SKILL.md"
click node_tdd "https://github.com/ganyuanran/aegis/blob/main/skills/test-driven-development/SKILL.md"
click node_debugging "https://github.com/ganyuanran/aegis/blob/main/skills/systematic-debugging/SKILL.md"
click node_review "https://github.com/ganyuanran/aegis/blob/main/skills/requesting-code-review/SKILL.md"
click node_verification "https://github.com/ganyuanran/aegis/blob/main/skills/verification-before-completion/SKILL.md"
click node_governance "https://github.com/ganyuanran/aegis/blob/main/skills/anti-entropy-governance/SKILL.md"
click node_ui_governance "https://github.com/ganyuanran/aegis/blob/main/skills/ui-ux-governance/SKILL.md"
click node_claude "https://github.com/ganyuanran/aegis/blob/main/hooks/hooks.json"
click node_codex "https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/hook.py"
click node_dsh "https://github.com/ganyuanran/aegis/blob/main/extensions/dsh/index.js"
click node_dsh_bootstrap "https://github.com/ganyuanran/aegis/blob/main/extensions/dsh/bootstrap.js"
click node_shared_bootstrap "https://github.com/ganyuanran/aegis/blob/main/extensions/shared/aegis-bootstrap.ts"
click node_pi_adapter "https://github.com/ganyuanran/aegis/blob/main/extensions/pi/index.ts"
click node_omp_adapter "https://github.com/ganyuanran/aegis/blob/main/extensions/omp/index.ts"
click node_workspace_tool "https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-workspace.py"
click node_doctor "https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-doctor.py"
click node_updater "https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-update.py"
click node_deferred_ledger "https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-deferred-ledger.py"
click node_profile "https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/profile.py"
click node_record_review "https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/review.py"
click node_transport "https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/transport.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_context,node_using,node_brainstorm,node_planning,node_execution,node_tdd,node_debugging,node_review,node_verification,node_governance,node_ui_governance toneBlue
class node_claude,node_codex,node_dsh,node_dsh_bootstrap,node_shared_bootstrap,node_pi_adapter,node_omp_adapter toneAmber
class node_workspace_tool,node_doctor,node_updater,node_deferred_ledger toneMint
class node_profile,node_record_review,node_transport toneRose
class node_developer,node_coding_agent toneIndigo
```

## Components

### Engineering methods

- [Project context](https://github.com/ganyuanran/aegis/blob/main/skills/establishing-project-context/SKILL.md): `skills/establishing-project-context/SKILL.md`
- [Aegis routing](https://github.com/ganyuanran/aegis/blob/main/skills/using-aegis/SKILL.md): `skills/using-aegis/SKILL.md`
- [Brainstorming](https://github.com/ganyuanran/aegis/blob/main/skills/brainstorming/SKILL.md): `skills/brainstorming/SKILL.md`
- [Planning](https://github.com/ganyuanran/aegis/blob/main/skills/writing-plans/SKILL.md): `skills/writing-plans/SKILL.md`
- [Plan execution](https://github.com/ganyuanran/aegis/blob/main/skills/executing-plans/SKILL.md): `skills/executing-plans/SKILL.md`
- [Test-driven development](https://github.com/ganyuanran/aegis/blob/main/skills/test-driven-development/SKILL.md): `skills/test-driven-development/SKILL.md`
- [Systematic debugging](https://github.com/ganyuanran/aegis/blob/main/skills/systematic-debugging/SKILL.md): `skills/systematic-debugging/SKILL.md`
- [Code review](https://github.com/ganyuanran/aegis/blob/main/skills/requesting-code-review/SKILL.md): `skills/requesting-code-review/SKILL.md`
- [Completion verification](https://github.com/ganyuanran/aegis/blob/main/skills/verification-before-completion/SKILL.md): `skills/verification-before-completion/SKILL.md`
- [Complexity governance](https://github.com/ganyuanran/aegis/blob/main/skills/anti-entropy-governance/SKILL.md): `skills/anti-entropy-governance/SKILL.md`
- [UI/UX governance](https://github.com/ganyuanran/aegis/blob/main/skills/ui-ux-governance/SKILL.md): `skills/ui-ux-governance/SKILL.md`

### Host activation

- [Claude integration](https://github.com/ganyuanran/aegis/blob/main/hooks/hooks.json): `hooks/hooks.json`
- [Codex integration](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/hook.py): `extensions/codex-reconciliation/hook.py`
- [DSH integration](https://github.com/ganyuanran/aegis/blob/main/extensions/dsh/index.js): `extensions/dsh/index.js`
- [DSH bootstrap](https://github.com/ganyuanran/aegis/blob/main/extensions/dsh/bootstrap.js): `extensions/dsh/bootstrap.js`
- [Pi/OMP bootstrap](https://github.com/ganyuanran/aegis/blob/main/extensions/shared/aegis-bootstrap.ts): `extensions/shared/aegis-bootstrap.ts`
- [Pi adapter](https://github.com/ganyuanran/aegis/blob/main/extensions/pi/index.ts): `extensions/pi/index.ts`
- [OMP adapter](https://github.com/ganyuanran/aegis/blob/main/extensions/omp/index.ts): `extensions/omp/index.ts`

### Workspace support

- [Workspace manager](https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-workspace.py): `scripts/aegis-workspace.py`
- [Install doctor](https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-doctor.py): `scripts/aegis-doctor.py`
- [Aegis updater](https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-update.py): `scripts/aegis-update.py`
- [Deferred ledger](https://github.com/ganyuanran/aegis/blob/main/scripts/aegis-deferred-ledger.py): `scripts/aegis-deferred-ledger.py`

### Codex reconciliation

- [Codex profile](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/profile.py): `extensions/codex-reconciliation/profile.py`
- [Record review](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/review.py): `extensions/codex-reconciliation/review.py`
- [Assessor transport](https://github.com/ganyuanran/aegis/blob/main/extensions/codex-reconciliation/transport.py): `extensions/codex-reconciliation/transport.py`

### Other components

- **Developer**
- **Coding agent**

## Connections

- Developer → Coding agent: requests work (evidence: `README.md`)
- Coding agent → Aegis routing: routes methods (evidence: `README.md`)
- Aegis routing → Project context: aligns baseline (evidence: `README.md`)
- Aegis routing → Brainstorming: frames design (evidence: `README.md`)
- Aegis routing → Planning: plans changes (evidence: `README.md`)
- Aegis routing → Plan execution: guides execution (evidence: `README.md`)
- Aegis routing → Test-driven development: supports TDD (evidence: `README.md`)
- Aegis routing → Systematic debugging: guides diagnosis (evidence: `README.md`)
- Aegis routing → Code review: requests review (evidence: `README.md`)
- Aegis routing → Completion verification: proves completion (evidence: `README.md`)
- Aegis routing → Complexity governance: tracks retirement (evidence: `README.md`)
- Aegis routing → UI/UX governance: applies UI rules (evidence: `README.md`)
- Coding agent → Claude integration: activates methods
- Coding agent → Codex integration: activates methods
- Coding agent → DSH integration: activates methods
- DSH integration → DSH bootstrap: installs bootstrap (evidence: `extensions/dsh/index.js`)
- Coding agent → Pi adapter: activates methods
- Coding agent → OMP adapter: activates methods
- Pi adapter → Pi/OMP bootstrap: delegates to (evidence: `extensions/pi/index.ts`)
- OMP adapter → Pi/OMP bootstrap: delegates to (evidence: `extensions/omp/index.ts`)
- Developer → Workspace manager: manages workspace
- Developer → Install doctor: verifies install (evidence: `README.md`)
- Developer → Aegis updater: requests update (evidence: `README.md`)
- Codex integration → Codex profile: uses profile (evidence: `extensions/codex-reconciliation/hook.py`)
- Codex integration → Record review: calls assessment (evidence: `extensions/codex-reconciliation/hook.py`)
- Codex integration → Assessor transport: runs assessor (evidence: `extensions/codex-reconciliation/hook.py`)
- Codex profile → Record review: imports review (evidence: `extensions/codex-reconciliation/profile.py`)
- Codex profile → Assessor transport: imports transport (evidence: `extensions/codex-reconciliation/profile.py`)
- Record review → Assessor transport: uses transport (evidence: `extensions/codex-reconciliation/review.py`)
