# wshobson/agents architecture

> Architecture diagram of the GitHub repository wshobson/agents, 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/wshobson/agents
- Repository: https://github.com/wshobson/agents

## Overview

This repository packages shared agents, skills, and commands for multiple AI coding harnesses. Its main workflow is to maintain plugin components in a common Markdown-based source, then expose them natively or generate harness-specific artifacts through adapters. A separate plugin-eval tool parses and scores skills. The README documents capabilities beyond the sampled code, including native marketplace routes and experimental LLM evaluation; those documented branches are represented without assuming unsampled implementation details. Edges reflect README statements or SOURCE INDEX references, which do not establish every runtime detail.

Main entry points: [`tools/generate.py`](https://github.com/wshobson/agents/blob/main/tools/generate.py) (Generation CLI), [`tools/adapters/base.py`](https://github.com/wshobson/agents/blob/main/tools/adapters/base.py) (Source models), [`plugins/plugin-eval/src/plugin_eval/engine.py`](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/engine.py) (Evaluation engine), [`tools/adapters/capabilities.py`](https://github.com/wshobson/agents/blob/main/tools/adapters/capabilities.py) (Harness capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Shared components"]
  node_plugin_source["Plugin components"]
  node_native_routes["Native marketplaces"]
end

subgraph group_generation["Harness generation"]
  node_generator["Generation CLI<br/>[generate.py]"]
  node_source_models["Source models<br/>[base.py]"]
  node_capability_matrix["Harness capabilities<br/>[capabilities.py]"]
  node_codex_adapter["Codex adapter<br/>[codex.py]"]
  node_cursor_adapter["Cursor adapter<br/>[cursor.py]"]
  node_opencode_adapter["OpenCode adapter<br/>[opencode.py]"]
  node_copilot_adapter["Copilot adapter<br/>[copilot.py]"]
  node_antigravity_adapter["Antigravity adapter<br/>[antigravity.py]"]
  node_pi_adapter["Pi adapter<br/>[pi.py]"]
end

subgraph group_evaluation["Plugin evaluation"]
  node_eval_cli["Evaluation CLI<br/>[cli.py]"]
  node_eval_engine["Evaluation engine<br/>[engine.py]"]
  node_eval_config["Evaluation models<br/>[models.py]"]
  node_skill_parser["Skill parser<br/>[parser.py]"]
  node_eval_reporter["Result reporter<br/>[reporter.py]"]
  node_eval_corpus["Evaluation corpus<br/>[corpus.py]"]
end

subgraph group_eval_layers["Evaluation layers"]
  node_static_layer["Static analysis<br/>[static.py]"]
  node_portability["Harness portability"]
  node_judge_layer["LLM judge<br/>[judge.py]"]
  node_sdk_helper["LLM SDK helper<br/>[_sdk.py]"]
  node_monte_carlo["Monte Carlo<br/>[monte_carlo.py]"]
  node_eval_stats["Evaluation statistics<br/>[stats.py]"]
end

node_maintainer(("Plugin maintainer"))
node_harnesses(("Coding harnesses"))

node_maintainer -->|"authors"| node_plugin_source
node_plugin_source -->|"feeds native installs"| node_native_routes
node_native_routes -->|"installs components"| node_harnesses
node_maintainer -->|"runs generation"| node_generator
node_generator -->|"reads source"| node_plugin_source
node_generator -->|"dispatches"| node_codex_adapter
node_generator -->|"dispatches"| node_cursor_adapter
node_generator -->|"dispatches"| node_opencode_adapter
node_generator -->|"dispatches"| node_copilot_adapter
node_generator -->|"dispatches"| node_antigravity_adapter
node_generator -->|"dispatches"| node_pi_adapter
node_codex_adapter -->|"uses"| node_source_models
node_cursor_adapter -->|"uses"| node_source_models
node_opencode_adapter -->|"uses"| node_source_models
node_copilot_adapter -->|"uses"| node_source_models
node_antigravity_adapter -->|"uses"| node_source_models
node_pi_adapter -->|"uses"| node_source_models
node_source_models -->|"reads capabilities"| node_capability_matrix
node_codex_adapter -->|"uses capabilities"| node_capability_matrix
node_opencode_adapter -->|"uses capabilities"| node_capability_matrix
node_copilot_adapter -->|"uses capabilities"| node_capability_matrix
node_antigravity_adapter -->|"uses capabilities"| node_capability_matrix
node_pi_adapter -->|"uses capabilities"| node_capability_matrix
node_codex_adapter -->|"emits artifacts"| node_harnesses
node_cursor_adapter -->|"emits artifacts"| node_harnesses
node_opencode_adapter -->|"emits artifacts"| node_harnesses
node_copilot_adapter -->|"emits artifacts"| node_harnesses
node_antigravity_adapter -->|"emits artifacts"| node_harnesses
node_pi_adapter -->|"emits artifacts"| node_harnesses
node_maintainer -->|"invokes scoring"| node_eval_cli
node_eval_cli -->|"runs evaluation"| node_eval_engine
node_eval_cli -->|"loads corpus"| node_eval_corpus
node_eval_cli -->|"formats results"| node_eval_reporter
node_eval_engine -->|"parses skills"| node_skill_parser
node_eval_engine -->|"runs analysis"| node_static_layer
node_eval_engine -->|"runs assessment"| node_judge_layer
node_eval_engine -->|"runs simulations"| node_monte_carlo
node_eval_engine -->|"builds results"| node_eval_config
node_eval_corpus -->|"parses entries"| node_skill_parser
node_eval_reporter -->|"formats models"| node_eval_config
node_static_layer -->|"scores portability"| node_portability
node_judge_layer -->|"queries SDK"| node_sdk_helper
node_monte_carlo -->|"queries SDK"| node_sdk_helper
node_monte_carlo -->|"runs simulations"| node_judge_layer
node_monte_carlo -->|"computes statistics"| node_eval_stats

click node_plugin_source "https://github.com/wshobson/agents/tree/main/plugins"
click node_generator "https://github.com/wshobson/agents/blob/main/tools/generate.py"
click node_source_models "https://github.com/wshobson/agents/blob/main/tools/adapters/base.py"
click node_capability_matrix "https://github.com/wshobson/agents/blob/main/tools/adapters/capabilities.py"
click node_codex_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/codex.py"
click node_cursor_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/cursor.py"
click node_opencode_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/opencode.py"
click node_copilot_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/copilot.py"
click node_antigravity_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/antigravity.py"
click node_pi_adapter "https://github.com/wshobson/agents/blob/main/tools/adapters/pi.py"
click node_eval_cli "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/cli.py"
click node_eval_engine "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/engine.py"
click node_eval_config "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/models.py"
click node_skill_parser "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/parser.py"
click node_eval_reporter "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/reporter.py"
click node_static_layer "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/static.py"
click node_portability "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/harness_portability.py"
click node_judge_layer "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/judge.py"
click node_sdk_helper "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/_sdk.py"
click node_monte_carlo "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py"
click node_eval_stats "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/stats.py"
click node_eval_corpus "https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/corpus.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_plugin_source,node_native_routes toneBlue
class node_generator,node_source_models,node_capability_matrix,node_codex_adapter,node_cursor_adapter,node_opencode_adapter,node_copilot_adapter,node_antigravity_adapter,node_pi_adapter toneAmber
class node_eval_cli,node_eval_engine,node_eval_config,node_skill_parser,node_eval_reporter,node_eval_corpus toneMint
class node_static_layer,node_portability,node_judge_layer,node_sdk_helper,node_monte_carlo,node_eval_stats toneRose
class node_maintainer,node_harnesses toneIndigo
```

## Components

### Shared components

- [Plugin components](https://github.com/wshobson/agents/tree/main/plugins): `plugins`
- **Native marketplaces**

### Harness generation

- [Generation CLI](https://github.com/wshobson/agents/blob/main/tools/generate.py): `tools/generate.py`
- [Source models](https://github.com/wshobson/agents/blob/main/tools/adapters/base.py): `tools/adapters/base.py`
- [Harness capabilities](https://github.com/wshobson/agents/blob/main/tools/adapters/capabilities.py): `tools/adapters/capabilities.py`
- [Codex adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/codex.py): `tools/adapters/codex.py`
- [Cursor adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/cursor.py): `tools/adapters/cursor.py`
- [OpenCode adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/opencode.py): `tools/adapters/opencode.py`
- [Copilot adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/copilot.py): `tools/adapters/copilot.py`
- [Antigravity adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/antigravity.py): `tools/adapters/antigravity.py`
- [Pi adapter](https://github.com/wshobson/agents/blob/main/tools/adapters/pi.py): `tools/adapters/pi.py`

### Plugin evaluation

- [Evaluation CLI](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/cli.py): `plugins/plugin-eval/src/plugin_eval/cli.py`
- [Evaluation engine](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/engine.py): `plugins/plugin-eval/src/plugin_eval/engine.py`
- [Evaluation models](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/models.py): `plugins/plugin-eval/src/plugin_eval/models.py`
- [Skill parser](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/parser.py): `plugins/plugin-eval/src/plugin_eval/parser.py`
- [Result reporter](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/reporter.py): `plugins/plugin-eval/src/plugin_eval/reporter.py`
- [Evaluation corpus](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/corpus.py): `plugins/plugin-eval/src/plugin_eval/corpus.py`

### Evaluation layers

- [Static analysis](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/static.py): `plugins/plugin-eval/src/plugin_eval/layers/static.py`
- [Harness portability](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/harness_portability.py): `plugins/plugin-eval/src/plugin_eval/layers/harness_portability.py`
- [LLM judge](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/judge.py): `plugins/plugin-eval/src/plugin_eval/layers/judge.py`
- [LLM SDK helper](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/_sdk.py): `plugins/plugin-eval/src/plugin_eval/layers/_sdk.py`
- [Monte Carlo](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py): `plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py`
- [Evaluation statistics](https://github.com/wshobson/agents/blob/main/plugins/plugin-eval/src/plugin_eval/stats.py): `plugins/plugin-eval/src/plugin_eval/stats.py`

### Other components

- **Plugin maintainer**
- **Coding harnesses**

## Connections

- Plugin maintainer → Plugin components: authors (evidence: `README.md`)
- Plugin components → Native marketplaces: feeds native installs (evidence: `README.md`)
- Native marketplaces → Coding harnesses: installs components (evidence: `README.md`)
- Plugin maintainer → Generation CLI: runs generation (evidence: `README.md`)
- Generation CLI → Plugin components: reads source (evidence: `tools/generate.py`)
- Generation CLI → Codex adapter: dispatches (evidence: `tools/generate.py`)
- Generation CLI → Cursor adapter: dispatches (evidence: `tools/generate.py`)
- Generation CLI → OpenCode adapter: dispatches (evidence: `tools/generate.py`)
- Generation CLI → Copilot adapter: dispatches (evidence: `tools/generate.py`)
- Generation CLI → Antigravity adapter: dispatches (evidence: `tools/generate.py`)
- Generation CLI → Pi adapter: dispatches (evidence: `tools/generate.py`)
- Codex adapter → Source models: uses (evidence: `tools/adapters/codex.py`)
- Cursor adapter → Source models: uses (evidence: `tools/adapters/cursor.py`)
- OpenCode adapter → Source models: uses (evidence: `tools/adapters/opencode.py`)
- Copilot adapter → Source models: uses (evidence: `tools/adapters/copilot.py`)
- Antigravity adapter → Source models: uses (evidence: `tools/adapters/antigravity.py`)
- Pi adapter → Source models: uses (evidence: `tools/adapters/pi.py`)
- Source models → Harness capabilities: reads capabilities (evidence: `tools/adapters/base.py`)
- Codex adapter → Harness capabilities: uses capabilities (evidence: `tools/adapters/codex.py`)
- OpenCode adapter → Harness capabilities: uses capabilities (evidence: `tools/adapters/opencode.py`)
- Copilot adapter → Harness capabilities: uses capabilities (evidence: `tools/adapters/copilot.py`)
- Antigravity adapter → Harness capabilities: uses capabilities (evidence: `tools/adapters/antigravity.py`)
- Pi adapter → Harness capabilities: uses capabilities (evidence: `tools/adapters/pi.py`)
- Codex adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- Cursor adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- OpenCode adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- Copilot adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- Antigravity adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- Pi adapter → Coding harnesses: emits artifacts (evidence: `README.md`)
- Plugin maintainer → Evaluation CLI: invokes scoring (evidence: `README.md`)
- Evaluation CLI → Evaluation engine: runs evaluation (evidence: `plugins/plugin-eval/src/plugin_eval/cli.py`)
- Evaluation CLI → Evaluation corpus: loads corpus (evidence: `plugins/plugin-eval/src/plugin_eval/cli.py`)
- Evaluation CLI → Result reporter: formats results (evidence: `plugins/plugin-eval/src/plugin_eval/cli.py`)
- Evaluation engine → Skill parser: parses skills (evidence: `plugins/plugin-eval/src/plugin_eval/engine.py`)
- Evaluation engine → Static analysis: runs analysis (evidence: `plugins/plugin-eval/src/plugin_eval/engine.py`)
- Evaluation engine → LLM judge: runs assessment (evidence: `plugins/plugin-eval/src/plugin_eval/engine.py`)
- Evaluation engine → Monte Carlo: runs simulations (evidence: `plugins/plugin-eval/src/plugin_eval/engine.py`)
- Evaluation engine → Evaluation models: builds results (evidence: `plugins/plugin-eval/src/plugin_eval/engine.py`)
- Evaluation corpus → Skill parser: parses entries (evidence: `plugins/plugin-eval/src/plugin_eval/corpus.py`)
- Result reporter → Evaluation models: formats models (evidence: `plugins/plugin-eval/src/plugin_eval/reporter.py`)
- Static analysis → Harness portability: scores portability (evidence: `plugins/plugin-eval/src/plugin_eval/layers/static.py`)
- LLM judge → LLM SDK helper: queries SDK (evidence: `plugins/plugin-eval/src/plugin_eval/layers/judge.py`)
- Monte Carlo → LLM SDK helper: queries SDK (evidence: `plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py`)
- Monte Carlo → LLM judge: runs simulations (evidence: `plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py`)
- Monte Carlo → Evaluation statistics: computes statistics (evidence: `plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py`)
