# samartomar/ai-harness architecture

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

- Interactive diagram: https://gitdiagram.com/samartomar/ai-harness
- Repository: https://github.com/samartomar/ai-harness

## Overview

AIH is a cross-platform CLI and library for preparing developer environments and repositories for governed AI-assisted coding. Its principal workflow is: an operator invokes a command, AIH resolves organizational policy and selected capabilities, verifies pinned sources and evidence where required, then plans or applies managed configuration and produces reviewable verification evidence. Major branches include the policy workbench, capability and MCP management, skill governance, trust/evidence handling, and verification. The tree and sampled source support the named subsystems; several branch connections are documented in the README but their internal wiring was not sampled.

Main entry points: [`src/baseline-evidence/pipeline.ts`](https://github.com/samartomar/ai-harness/blob/main/src/baseline-evidence/pipeline.ts) (Baseline evidence), [`src/commands/index.ts`](https://github.com/samartomar/ai-harness/blob/main/src/commands/index.ts) (Command registry), [`src/ecc/pipeline.ts`](https://github.com/samartomar/ai-harness/blob/main/src/ecc/pipeline.ts) (ECC lifecycle), [`src/superpowers/pipeline.ts`](https://github.com/samartomar/ai-harness/blob/main/src/superpowers/pipeline.ts) (Superpowers lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command surface"]
  node_program["CLI program<br/>[program.ts]"]
  node_commands["Command registry<br/>[index.ts]"]
  node_runner["Plan runner<br/>[run.ts]"]
end

subgraph group_policy["Policy and selection"]
  node_orgpolicy["Organization policy<br/>[schema.ts]"]
  node_workbench["Policy workbench<br/>[main.ts]"]
  node_selection["Selection engine"]
  node_policycompile["Policy compiler<br/>[compile-policy.ts]"]
  node_policybinding["Policy binding<br/>[index.ts]"]
end

subgraph group_capabilities["Managed capabilities"]
  node_ecc["ECC lifecycle<br/>[pipeline.ts]"]
  node_superpowers["Superpowers lifecycle<br/>[pipeline.ts]"]
  node_mcp["MCP management<br/>[index.ts]"]
  node_skills["Skill governance<br/>[index.ts]"]
end

subgraph group_evidence["Trust and evidence"]
  node_baseline["Baseline evidence<br/>[pipeline.ts]"]
  node_trust["Trust sources<br/>[fetch.ts]"]
  node_catalog["Baseline catalogs<br/>[catalogs.ts]"]
end

subgraph group_verification["Verification and records"]
  node_verification["Verification pipeline<br/>[pipeline.ts]"]
  node_truth["Truth records<br/>[index.ts]"]
  node_report["Reports<br/>[index.ts]"]
end

node_operator(("Operator"))
node_external(("External source"))
node_localstate[("Repository state")]

node_operator -->|"invokes"| node_program
node_program -->|"registers commands"| node_commands
node_commands -->|"runs capability"| node_runner
node_workbench -->|"reduces actions"| node_selection
node_workbench -->|"projects policy"| node_policycompile
node_commands -.->|"opens workbench"| node_workbench
node_ecc -->|"reads policy"| node_orgpolicy
node_ecc -->|"selects catalog"| node_catalog
node_ecc -->|"executes plan"| node_runner
node_superpowers -->|"selects catalog"| node_catalog
node_superpowers -->|"resolves source"| node_trust
node_superpowers -->|"runs evidence gate"| node_baseline
node_baseline -->|"reads policy"| node_orgpolicy
node_baseline -->|"validates source"| node_trust
node_baseline -->|"executes plan"| node_runner
node_baseline -.->|"acquires source"| node_external
node_mcp -->|"evaluates policy"| node_orgpolicy
node_skills -->|"records approval lock"| node_localstate
node_policybinding -->|"binds policy"| node_localstate
node_verification -->|"summarizes results"| node_report
node_truth -->|"writes sidecar state"| node_localstate
node_commands -->|"exposes verification"| node_verification

click node_program "https://github.com/samartomar/ai-harness/blob/main/src/program.ts"
click node_commands "https://github.com/samartomar/ai-harness/blob/main/src/commands/index.ts"
click node_runner "https://github.com/samartomar/ai-harness/blob/main/src/commands/run.ts"
click node_orgpolicy "https://github.com/samartomar/ai-harness/blob/main/src/org-policy/schema.ts"
click node_workbench "https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/ui/main.ts"
click node_selection "https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/selection-engine.ts"
click node_policycompile "https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/compile-policy.ts"
click node_ecc "https://github.com/samartomar/ai-harness/blob/main/src/ecc/pipeline.ts"
click node_superpowers "https://github.com/samartomar/ai-harness/blob/main/src/superpowers/pipeline.ts"
click node_mcp "https://github.com/samartomar/ai-harness/blob/main/src/mcp/index.ts"
click node_skills "https://github.com/samartomar/ai-harness/blob/main/src/skill/index.ts"
click node_baseline "https://github.com/samartomar/ai-harness/blob/main/src/baseline-evidence/pipeline.ts"
click node_trust "https://github.com/samartomar/ai-harness/blob/main/src/trust/fetch.ts"
click node_catalog "https://github.com/samartomar/ai-harness/blob/main/src/baseline-evidence/catalogs.ts"
click node_verification "https://github.com/samartomar/ai-harness/blob/main/src/verification/pipeline.ts"
click node_truth "https://github.com/samartomar/ai-harness/blob/main/src/truth/index.ts"
click node_report "https://github.com/samartomar/ai-harness/blob/main/src/report/index.ts"
click node_policybinding "https://github.com/samartomar/ai-harness/blob/main/src/binding/index.ts"

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_program,node_commands,node_runner toneBlue
class node_orgpolicy,node_workbench,node_selection,node_policycompile,node_policybinding,node_localstate toneAmber
class node_ecc,node_superpowers,node_mcp,node_skills toneMint
class node_baseline,node_trust,node_catalog toneRose
class node_verification,node_truth,node_report,node_operator,node_external toneIndigo
```

## Components

### Command surface

- [CLI program](https://github.com/samartomar/ai-harness/blob/main/src/program.ts): `src/program.ts`
- [Command registry](https://github.com/samartomar/ai-harness/blob/main/src/commands/index.ts): `src/commands/index.ts`
- [Plan runner](https://github.com/samartomar/ai-harness/blob/main/src/commands/run.ts): `src/commands/run.ts`

### Policy and selection

- [Organization policy](https://github.com/samartomar/ai-harness/blob/main/src/org-policy/schema.ts): `src/org-policy/schema.ts`
- [Policy workbench](https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/ui/main.ts): `src/org-policy/workbench/ui/main.ts`
- [Selection engine](https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/selection-engine.ts): `src/org-policy/workbench/selection-engine.ts`
- [Policy compiler](https://github.com/samartomar/ai-harness/blob/main/src/org-policy/workbench/compile-policy.ts): `src/org-policy/workbench/compile-policy.ts`
- [Policy binding](https://github.com/samartomar/ai-harness/blob/main/src/binding/index.ts): `src/binding/index.ts`

### Managed capabilities

- [ECC lifecycle](https://github.com/samartomar/ai-harness/blob/main/src/ecc/pipeline.ts): `src/ecc/pipeline.ts`
- [Superpowers lifecycle](https://github.com/samartomar/ai-harness/blob/main/src/superpowers/pipeline.ts): `src/superpowers/pipeline.ts`
- [MCP management](https://github.com/samartomar/ai-harness/blob/main/src/mcp/index.ts): `src/mcp/index.ts`
- [Skill governance](https://github.com/samartomar/ai-harness/blob/main/src/skill/index.ts): `src/skill/index.ts`

### Trust and evidence

- [Baseline evidence](https://github.com/samartomar/ai-harness/blob/main/src/baseline-evidence/pipeline.ts): `src/baseline-evidence/pipeline.ts`
- [Trust sources](https://github.com/samartomar/ai-harness/blob/main/src/trust/fetch.ts): `src/trust/fetch.ts`
- [Baseline catalogs](https://github.com/samartomar/ai-harness/blob/main/src/baseline-evidence/catalogs.ts): `src/baseline-evidence/catalogs.ts`

### Verification and records

- [Verification pipeline](https://github.com/samartomar/ai-harness/blob/main/src/verification/pipeline.ts): `src/verification/pipeline.ts`
- [Truth records](https://github.com/samartomar/ai-harness/blob/main/src/truth/index.ts): `src/truth/index.ts`
- [Reports](https://github.com/samartomar/ai-harness/blob/main/src/report/index.ts): `src/report/index.ts`

### Other components

- **Operator**
- **External source**
- **Repository state**

## Connections

- Operator → CLI program: invokes
- CLI program → Command registry: registers commands
- Command registry → Plan runner: runs capability
- Policy workbench → Selection engine: reduces actions
- Policy workbench → Policy compiler: projects policy
- Command registry → Policy workbench: opens workbench
- ECC lifecycle → Organization policy: reads policy
- ECC lifecycle → Baseline catalogs: selects catalog
- ECC lifecycle → Plan runner: executes plan
- Superpowers lifecycle → Baseline catalogs: selects catalog
- Superpowers lifecycle → Trust sources: resolves source
- Superpowers lifecycle → Baseline evidence: runs evidence gate
- Baseline evidence → Organization policy: reads policy
- Baseline evidence → Trust sources: validates source
- Baseline evidence → Plan runner: executes plan
- Baseline evidence → External source: acquires source
- MCP management → Organization policy: evaluates policy
- Skill governance → Repository state: records approval lock
- Policy binding → Repository state: binds policy
- Verification pipeline → Reports: summarizes results
- Truth records → Repository state: writes sidecar state
- Command registry → Verification pipeline: exposes verification