# nhangen/agent-harness architecture

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

- Interactive diagram: https://gitdiagram.com/nhangen/agent-harness
- Repository: https://github.com/nhangen/agent-harness

## Overview

agent-harness is a Claude Code–first configuration and enforcement harness: users provide rules, advisor personas, skills, and hooks that shape or block agent actions. A representative workflow is PR review: the review panel gathers and verifies findings, review-fix applies approved fixes and gates replies, and merge remains manual. The repository also includes rule evaluations, model benchmarking, and Obsidian-oriented session and commit capture. Relationships below follow README statements or shown imports; several skill and hook internals were not sampled.

Main entry points: [`agents`](https://github.com/nhangen/agent-harness/tree/main/agents) (Advisor personas), [`skills/review-panel`](https://github.com/nhangen/agent-harness/tree/main/skills/review-panel) (Review panel), [`skills/model-matrix`](https://github.com/nhangen/agent-harness/tree/main/skills/model-matrix) (Model benchmark), [`rules`](https://github.com/nhangen/agent-harness/tree/main/rules) (Behavior rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Agent configuration"]
  node_rules["Behavior rules"]
  node_agents["Advisor personas"]
  node_skills["Procedural skills"]
end

subgraph group_enforcement["Runtime enforcement"]
  node_hooks["Tool and turn hooks"]
  node_response_gate["Response gate"]
  node_auditor_gate["Auditor gate<br/>[auditor-gate.sh]"]
  node_identity_gate["Git identity gate"]
end

subgraph group_review["Review workflows"]
  node_review_panel["Review panel"]
  node_review_fix["Review fix"]
  node_convene["Advisor convening"]
end

subgraph group_evaluation["Evaluation"]
  node_skill_evals["Skill evaluations"]
  node_model_matrix["Model benchmark"]
  node_grade["Deterministic grader<br/>[grade.py]"]
  node_judge["Rubric judge<br/>[judge.py]"]
  node_common["Shared score helpers<br/>[mm_common.py]"]
  node_rank["Leaderboard ranking<br/>[rank.py]"]
  node_probe_gate["Trust gate<br/>[probe-gate.py]"]
end

subgraph group_memory["Memory and archive"]
  node_archive[("Obsidian archive")]
  node_commit_capture["Commit capture"]
  node_session_save["Session save"]
  node_vaultkeeper["Vault index upkeep"]
  node_advisor_ledgers["Advisor ledgers"]
end

node_user(("User"))
node_claude(("Claude Code"))

node_user -->|"uses"| node_claude
node_rules -->|"guides"| node_claude
node_agents -->|"advises"| node_claude
node_skills -->|"provides workflows"| node_claude
node_hooks -->|"intercepts actions"| node_claude
node_response_gate -->|"blocks replies"| node_claude
node_auditor_gate -->|"blocks turns"| node_claude
node_identity_gate -->|"checks commits"| node_claude
node_review_panel -->|"passes findings"| node_review_fix
node_review_panel -->|"presents verified findings"| node_user
node_review_fix -->|"gates replies for approval"| node_user
node_convene -->|"selects advisors"| node_agents
node_skill_evals -->|"evaluates behavior"| node_rules
node_model_matrix -.->|"scores outputs"| node_grade
node_model_matrix -.->|"judges responses"| node_judge
node_grade -->|"imports"| node_common
node_rank -->|"imports"| node_common
node_judge -->|"writes judgments"| node_probe_gate
node_commit_capture -->|"writes commit context"| node_archive
node_session_save -->|"saves session"| node_archive
node_vaultkeeper -->|"maintains index"| node_archive
node_agents -->|"maintain ledgers"| node_advisor_ledgers
node_advisor_ledgers -->|"stores notes in"| node_archive

click node_rules "https://github.com/nhangen/agent-harness/tree/main/rules"
click node_agents "https://github.com/nhangen/agent-harness/tree/main/agents"
click node_skills "https://github.com/nhangen/agent-harness/tree/main/skills"
click node_hooks "https://github.com/nhangen/agent-harness/tree/main/hooks"
click node_response_gate "https://github.com/nhangen/agent-harness/blob/main/hooks/response-shape-gate.sh"
click node_auditor_gate "https://github.com/nhangen/agent-harness/blob/main/hooks/auditor-gate.sh"
click node_identity_gate "https://github.com/nhangen/agent-harness/blob/main/hooks/git-identity-gate.sh"
click node_review_panel "https://github.com/nhangen/agent-harness/tree/main/skills/review-panel"
click node_review_fix "https://github.com/nhangen/agent-harness/tree/main/skills/review-fix"
click node_convene "https://github.com/nhangen/agent-harness/tree/main/skills/convene"
click node_skill_evals "https://github.com/nhangen/agent-harness/tree/main/skills/skill-evals"
click node_model_matrix "https://github.com/nhangen/agent-harness/tree/main/skills/model-matrix"
click node_grade "https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/grade.py"
click node_judge "https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/judge.py"
click node_common "https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/mm_common.py"
click node_rank "https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/rank.py"
click node_probe_gate "https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/probe-gate.py"
click node_commit_capture "https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-commit-capture.sh"
click node_session_save "https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-session-save.sh"
click node_vaultkeeper "https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-vaultkeeper-tick.sh"
click node_advisor_ledgers "https://github.com/nhangen/agent-harness/tree/main/agents"

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_rules,node_agents,node_skills,node_user toneBlue
class node_hooks,node_response_gate,node_auditor_gate,node_identity_gate toneAmber
class node_review_panel,node_review_fix,node_convene toneMint
class node_skill_evals,node_model_matrix,node_grade,node_judge,node_common,node_rank,node_probe_gate toneRose
class node_archive,node_commit_capture,node_session_save,node_vaultkeeper,node_advisor_ledgers,node_claude toneIndigo
```

## Components

### Agent configuration

- [Behavior rules](https://github.com/nhangen/agent-harness/tree/main/rules): `rules`
- [Advisor personas](https://github.com/nhangen/agent-harness/tree/main/agents): `agents`
- [Procedural skills](https://github.com/nhangen/agent-harness/tree/main/skills): `skills`

### Runtime enforcement

- [Tool and turn hooks](https://github.com/nhangen/agent-harness/tree/main/hooks): `hooks`
- [Response gate](https://github.com/nhangen/agent-harness/blob/main/hooks/response-shape-gate.sh): `hooks/response-shape-gate.sh`
- [Auditor gate](https://github.com/nhangen/agent-harness/blob/main/hooks/auditor-gate.sh): `hooks/auditor-gate.sh`
- [Git identity gate](https://github.com/nhangen/agent-harness/blob/main/hooks/git-identity-gate.sh): `hooks/git-identity-gate.sh`

### Review workflows

- [Review panel](https://github.com/nhangen/agent-harness/tree/main/skills/review-panel): `skills/review-panel`
- [Review fix](https://github.com/nhangen/agent-harness/tree/main/skills/review-fix): `skills/review-fix`
- [Advisor convening](https://github.com/nhangen/agent-harness/tree/main/skills/convene): `skills/convene`

### Evaluation

- [Skill evaluations](https://github.com/nhangen/agent-harness/tree/main/skills/skill-evals): `skills/skill-evals`
- [Model benchmark](https://github.com/nhangen/agent-harness/tree/main/skills/model-matrix): `skills/model-matrix`
- [Deterministic grader](https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/grade.py): `skills/model-matrix/scripts/grade.py`
- [Rubric judge](https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/judge.py): `skills/model-matrix/scripts/judge.py`
- [Shared score helpers](https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/mm_common.py): `skills/model-matrix/scripts/mm_common.py`
- [Leaderboard ranking](https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/rank.py): `skills/model-matrix/scripts/rank.py`
- [Trust gate](https://github.com/nhangen/agent-harness/blob/main/skills/model-matrix/scripts/probe-gate.py): `skills/model-matrix/scripts/probe-gate.py`

### Memory and archive

- **Obsidian archive**
- [Commit capture](https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-commit-capture.sh): `hooks/obsidian-commit-capture.sh`
- [Session save](https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-session-save.sh): `hooks/obsidian-session-save.sh`
- [Vault index upkeep](https://github.com/nhangen/agent-harness/blob/main/hooks/obsidian-vaultkeeper-tick.sh): `hooks/obsidian-vaultkeeper-tick.sh`
- [Advisor ledgers](https://github.com/nhangen/agent-harness/tree/main/agents): `agents`

### Other components

- **User**
- **Claude Code**

## Connections

- User → Claude Code: uses (evidence: `README.md`)
- Behavior rules → Claude Code: guides (evidence: `README.md`)
- Advisor personas → Claude Code: advises (evidence: `README.md`)
- Procedural skills → Claude Code: provides workflows (evidence: `README.md`)
- Tool and turn hooks → Claude Code: intercepts actions (evidence: `README.md`)
- Response gate → Claude Code: blocks replies (evidence: `README.md`)
- Auditor gate → Claude Code: blocks turns (evidence: `README.md`)
- Git identity gate → Claude Code: checks commits (evidence: `README.md`)
- Review panel → Review fix: passes findings (evidence: `README.md`)
- Review panel → User: presents verified findings (evidence: `README.md`)
- Review fix → User: gates replies for approval (evidence: `README.md`)
- Advisor convening → Advisor personas: selects advisors (evidence: `README.md`)
- Skill evaluations → Behavior rules: evaluates behavior (evidence: `README.md`)
- Model benchmark → Deterministic grader: scores outputs (evidence: `skills/model-matrix/scripts/grade.py`)
- Model benchmark → Rubric judge: judges responses
- Deterministic grader → Shared score helpers: imports (evidence: `skills/model-matrix/scripts/grade.py`)
- Leaderboard ranking → Shared score helpers: imports (evidence: `skills/model-matrix/scripts/rank.py`)
- Rubric judge → Trust gate: writes judgments (evidence: `skills/model-matrix/scripts/probe-gate.py`)
- Commit capture → Obsidian archive: writes commit context (evidence: `README.md`)
- Session save → Obsidian archive: saves session (evidence: `README.md`)
- Vault index upkeep → Obsidian archive: maintains index (evidence: `README.md`)
- Advisor personas → Advisor ledgers: maintain ledgers (evidence: `README.md`)
- Advisor ledgers → Obsidian archive: stores notes in (evidence: `README.md`)
