# tomtastisch/agent-governance architecture

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

- Interactive diagram: https://gitdiagram.com/tomtastisch/agent-governance
- Repository: https://github.com/tomtastisch/agent-governance

## Overview

Agent Governance is a harness-neutral governance bundle and transactional installer, exposed through an interactive CLI and package APIs. The principal workflow is user-selected harness discovery, explicit target confirmation, install/update planning, reversible mutation, and verification. Separate public capabilities classify work items, persist and resolve resume checkpoints, and expose routing, command, discovery, and template registries. The sampled excerpts confirm parts of init and transaction handling; edges for unsampled modules are limited to documented capabilities and visible entry-point roles.

Main entry points: [`src/init/orchestrator.ts`](https://github.com/tomtastisch/agent-governance/blob/main/src/init/orchestrator.ts) (Init orchestrator), [`src/public-commands.ts`](https://github.com/tomtastisch/agent-governance/blob/main/src/public-commands.ts) (Public commands), [`src/transaction.ts`](https://github.com/tomtastisch/agent-governance/blob/main/src/transaction.ts) (Installer transaction), [`src/cli.ts`](https://github.com/tomtastisch/agent-governance/blob/main/src/cli.ts) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[cli.ts]"]
  node_public["Public commands<br/>[public-commands.ts]"]
  node_init["Init orchestrator<br/>[orchestrator.ts]"]
  node_prompt["Interactive prompts<br/>[prompt.ts]"]
  node_discovery["Harness discovery"]
end

subgraph group_install["Installation lifecycle"]
  node_bindings["Target bindings<br/>[bindings.ts]"]
  node_target["Target inspection<br/>[target.ts]"]
  node_transaction["Installer transaction<br/>[transaction.ts]"]
  node_context["Transaction context<br/>[context.ts]"]
  node_release["Release verification<br/>[release.ts]"]
  node_planner["Install planning<br/>[planner.ts]"]
  node_recovery["Recovery<br/>[recovery.ts]"]
  node_filesystem["Secure filesystem"]
end

subgraph group_governance["Governance catalogs"]
  node_routing["Governance routing<br/>[routing-catalog.ts]"]
  node_commands["Command catalog<br/>[command-catalog.ts]"]
  node_ssot["SSOT manifest<br/>[ssot-manifest.ts]"]
  node_templates["Template registry"]
  node_contract["Governance contract"]
end

subgraph group_state["Agent state APIs"]
  node_workitems["Work-item classification<br/>[work-items.ts]"]
  node_checkpoint["Resume checkpoints"]
  node_resume["Resume resolution<br/>[resume-resolve.ts]"]
  node_toon["TOON projection<br/>[resume-toon.ts]"]
end

subgraph group_integration["Harness integration"]
  node_provider["Microsoft toolkit bridge<br/>[provider.mjs]"]
end

node_user(("Developer"))

node_user -->|"runs"| node_cli
node_cli -->|"starts init"| node_init
node_cli -->|"dispatches"| node_public
node_init -->|"discovers harnesses"| node_discovery
node_init -->|"requests selection"| node_prompt
node_init -->|"resolves targets"| node_bindings
node_init -->|"creates transactions"| node_transaction
node_prompt -->|"returns choices"| node_init
node_transaction -->|"resolves context"| node_context
node_context -->|"inspects target"| node_target
node_context -->|"verifies release"| node_release
node_transaction -->|"plans operation"| node_planner
node_recovery -->|"uses secure operations"| node_filesystem
node_transaction -.->|"recovers mutation"| node_recovery
node_contract -->|"defines tool fields"| node_routing
node_public -->|"exposes API"| node_workitems
node_public -->|"exposes API"| node_checkpoint
node_public -->|"exposes API"| node_toon
node_resume -->|"resolves checkpoint"| node_checkpoint
node_toon -->|"projects checkpoint"| node_checkpoint
node_provider -.->|"loads verified policy"| node_contract

click node_cli "https://github.com/tomtastisch/agent-governance/blob/main/src/cli.ts"
click node_public "https://github.com/tomtastisch/agent-governance/blob/main/src/public-commands.ts"
click node_init "https://github.com/tomtastisch/agent-governance/blob/main/src/init/orchestrator.ts"
click node_prompt "https://github.com/tomtastisch/agent-governance/blob/main/src/init/prompt.ts"
click node_discovery "https://github.com/tomtastisch/agent-governance/blob/main/src/discovery-catalog.ts"
click node_bindings "https://github.com/tomtastisch/agent-governance/blob/main/src/init/bindings.ts"
click node_target "https://github.com/tomtastisch/agent-governance/blob/main/src/target.ts"
click node_transaction "https://github.com/tomtastisch/agent-governance/blob/main/src/transaction.ts"
click node_context "https://github.com/tomtastisch/agent-governance/blob/main/src/installer/context.ts"
click node_release "https://github.com/tomtastisch/agent-governance/blob/main/src/release.ts"
click node_planner "https://github.com/tomtastisch/agent-governance/blob/main/src/planner.ts"
click node_recovery "https://github.com/tomtastisch/agent-governance/blob/main/src/installer/recovery.ts"
click node_filesystem "https://github.com/tomtastisch/agent-governance/blob/main/src/native-filesystem.ts"
click node_routing "https://github.com/tomtastisch/agent-governance/blob/main/src/routing-catalog.ts"
click node_commands "https://github.com/tomtastisch/agent-governance/blob/main/src/command-catalog.ts"
click node_ssot "https://github.com/tomtastisch/agent-governance/blob/main/src/ssot-manifest.ts"
click node_templates "https://github.com/tomtastisch/agent-governance/blob/main/src/templates-catalog.ts"
click node_contract "https://github.com/tomtastisch/agent-governance/blob/main/src/governance-contract.ts"
click node_workitems "https://github.com/tomtastisch/agent-governance/blob/main/src/work-items.ts"
click node_checkpoint "https://github.com/tomtastisch/agent-governance/blob/main/src/resume-checkpoint.ts"
click node_resume "https://github.com/tomtastisch/agent-governance/blob/main/src/resume-resolve.ts"
click node_toon "https://github.com/tomtastisch/agent-governance/blob/main/src/resume-toon.ts"
click node_provider "https://github.com/tomtastisch/agent-governance/blob/main/integrations/microsoft-agent-governance-toolkit/bridge/provider.mjs"

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_cli,node_public,node_init,node_prompt,node_discovery toneBlue
class node_bindings,node_target,node_transaction,node_context,node_release,node_planner,node_recovery,node_filesystem toneAmber
class node_routing,node_commands,node_ssot,node_templates,node_contract toneMint
class node_workitems,node_checkpoint,node_resume,node_toon toneRose
class node_provider,node_user toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/tomtastisch/agent-governance/blob/main/src/cli.ts): `src/cli.ts`
- [Public commands](https://github.com/tomtastisch/agent-governance/blob/main/src/public-commands.ts): `src/public-commands.ts`
- [Init orchestrator](https://github.com/tomtastisch/agent-governance/blob/main/src/init/orchestrator.ts): `src/init/orchestrator.ts`
- [Interactive prompts](https://github.com/tomtastisch/agent-governance/blob/main/src/init/prompt.ts): `src/init/prompt.ts`
- [Harness discovery](https://github.com/tomtastisch/agent-governance/blob/main/src/discovery-catalog.ts): `src/discovery-catalog.ts`

### Installation lifecycle

- [Target bindings](https://github.com/tomtastisch/agent-governance/blob/main/src/init/bindings.ts): `src/init/bindings.ts`
- [Target inspection](https://github.com/tomtastisch/agent-governance/blob/main/src/target.ts): `src/target.ts`
- [Installer transaction](https://github.com/tomtastisch/agent-governance/blob/main/src/transaction.ts): `src/transaction.ts`
- [Transaction context](https://github.com/tomtastisch/agent-governance/blob/main/src/installer/context.ts): `src/installer/context.ts`
- [Release verification](https://github.com/tomtastisch/agent-governance/blob/main/src/release.ts): `src/release.ts`
- [Install planning](https://github.com/tomtastisch/agent-governance/blob/main/src/planner.ts): `src/planner.ts`
- [Recovery](https://github.com/tomtastisch/agent-governance/blob/main/src/installer/recovery.ts): `src/installer/recovery.ts`
- [Secure filesystem](https://github.com/tomtastisch/agent-governance/blob/main/src/native-filesystem.ts): `src/native-filesystem.ts`

### Governance catalogs

- [Governance routing](https://github.com/tomtastisch/agent-governance/blob/main/src/routing-catalog.ts): `src/routing-catalog.ts`
- [Command catalog](https://github.com/tomtastisch/agent-governance/blob/main/src/command-catalog.ts): `src/command-catalog.ts`
- [SSOT manifest](https://github.com/tomtastisch/agent-governance/blob/main/src/ssot-manifest.ts): `src/ssot-manifest.ts`
- [Template registry](https://github.com/tomtastisch/agent-governance/blob/main/src/templates-catalog.ts): `src/templates-catalog.ts`
- [Governance contract](https://github.com/tomtastisch/agent-governance/blob/main/src/governance-contract.ts): `src/governance-contract.ts`

### Agent state APIs

- [Work-item classification](https://github.com/tomtastisch/agent-governance/blob/main/src/work-items.ts): `src/work-items.ts`
- [Resume checkpoints](https://github.com/tomtastisch/agent-governance/blob/main/src/resume-checkpoint.ts): `src/resume-checkpoint.ts`
- [Resume resolution](https://github.com/tomtastisch/agent-governance/blob/main/src/resume-resolve.ts): `src/resume-resolve.ts`
- [TOON projection](https://github.com/tomtastisch/agent-governance/blob/main/src/resume-toon.ts): `src/resume-toon.ts`

### Harness integration

- [Microsoft toolkit bridge](https://github.com/tomtastisch/agent-governance/blob/main/integrations/microsoft-agent-governance-toolkit/bridge/provider.mjs): `integrations/microsoft-agent-governance-toolkit/bridge/provider.mjs`

### Other components

- **Developer**

## Connections

- Developer → CLI: runs
- CLI → Init orchestrator: starts init
- CLI → Public commands: dispatches
- Init orchestrator → Harness discovery: discovers harnesses
- Init orchestrator → Interactive prompts: requests selection
- Init orchestrator → Target bindings: resolves targets
- Init orchestrator → Installer transaction: creates transactions
- Interactive prompts → Init orchestrator: returns choices
- Installer transaction → Transaction context: resolves context
- Transaction context → Target inspection: inspects target
- Transaction context → Release verification: verifies release
- Installer transaction → Install planning: plans operation
- Recovery → Secure filesystem: uses secure operations
- Installer transaction → Recovery: recovers mutation
- Governance contract → Governance routing: defines tool fields
- Public commands → Work-item classification: exposes API
- Public commands → Resume checkpoints: exposes API
- Public commands → TOON projection: exposes API
- Resume resolution → Resume checkpoints: resolves checkpoint
- TOON projection → Resume checkpoints: projects checkpoint
- Microsoft toolkit bridge → Governance contract: loads verified policy