wshobson-agents/ARCHITECTURE.md

Architecture

Top-level architectural map for the claude-agents marketplace. Detail lives in docs/architecture.md; this file is the index per the OpenAI harness-engineering pattern.

Invariants

1. Single source of truth. All agent / skill / command authoring happens under plugins/<name>/. Generated harness-specific artifacts (.codex/skills/, .codex/agents/, .opencode/, .copilot/, commands/, agents/, skills/ at extension root for Gemini) are produced by adapters and gitignored. The exception: small native-install registries (.agents/plugins/marketplace.json, plugins/*/.codex-plugin/plugin.json, .cursor-plugin/, .cursor/rules/, gemini-extension.json) are committed — they only point at the source plugins/, so the invariant holds. Never hand-edit generated files.

2. One canonical context file. AGENTS.md at repo root is the only context file authored directly. Claude Code reads CLAUDE.md, a symlink to AGENTS.md. Gemini CLI reads it via .gemini/settings.json context.fileName. Codex / Cursor / OpenCode read AGENTS.md natively.

3. Adapters own per-harness mechanics; source content stays portable. Authors write Claude-Code-quality markdown. Adapters under tools/adapters/ handle every harness-specific transform (frontmatter rewriting, model-alias mapping, body-size caps, tool-name remapping). Source files never carry harness conditional logic.

4. Mechanical enforcement with remediation hints. Every lint / validator finding ships with a concrete fix string. make validate, make garden, and the plugin-eval harness_portability dimension all follow this convention.

5. Progressive disclosure all the way down. Context files (AGENTS.md, CLAUDE.md, etc.) cap at ~150 lines. Skill bodies cap at ~8 KB (Codex's hard limit). Detail offloads to docs/ and references/details.md. Detail is loaded on demand, not pre-injected.

Component overview

claude-agents/
├── AGENTS.md                       # Canonical context file (committed)
├── CLAUDE.md                       # symlink → AGENTS.md (Claude-specific addenda live in AGENTS.md)
├── ARCHITECTURE.md                 # This file
├── README.md                       # User-facing GitHub landing page
├── GEMINI.md                       # Gemini-specific setup (auto-loaded by Gemini CLI)
├── CONTRIBUTING.md                 # Contributor entry point
├── .claude-plugin/marketplace.json # Plugin registry (source of truth)
├── .gemini/settings.json           # Gemini CLI → AGENTS.md redirect
├── plugins/                        # SOURCE OF TRUTH (82 local plugins; 2 externals in marketplace)
│   └── <name>/
│       ├── .claude-plugin/plugin.json
│       ├── agents/*.md
│       ├── commands/*.md
│       └── skills/<n>/{SKILL.md, references/, assets/}
├── tools/
│   ├── adapters/                   # Per-harness adapter framework
│   │   ├── base.py                 # Parser, HarnessAdapter ABC, helpers
│   │   ├── capabilities.py         # Capability matrix; consumed by every adapter
│   │   ├── codex.py / cursor.py / opencode.py / gemini.py / copilot.py
│   │   └── cursor_rules/           # Hand-curated .mdc rules
│   ├── generate.py                 # Unified CLI: `make generate HARNESS=<x>`
│   ├── validate_generated.py       # Structural validation
│   ├── doc_gardener.py             # Drift detection (per harness-engineering)
│   └── tests/                      # Adapter + behavioral + CLI smoke tests
└── docs/                           # Detailed reference docs
    ├── architecture.md             # Full architecture (this file is the map)
    ├── plugins.md / agents.md / agent-skills.md  # Catalogs
    ├── usage.md                    # User workflows
    ├── authoring.md                # Portable-content style guide
    ├── harnesses.md                # Cross-harness capability matrix
    ├── plugin-eval.md              # Quality evaluation framework
    └── round-trip-results.md       # Real-CLI verification recipes

Cross-harness adapter framework

Each adapter consumes the canonical plugins/ source and emits harness-native artifacts:

Adapter	Output	What it does
codex.py	committed .agents/plugins/marketplace.json + plugins/*/.codex-plugin/plugin.json; gitignored .codex/skills/, .codex/agents/*.toml	Marketplace + per-plugin manifests (point at source plugins/); Markdown → TOML transform, 8 KB body cap with references/ overflow, sandbox_mode heuristic, collision detection
cursor.py	.cursor-plugin/, .cursor/rules/*.mdc	Marketplace manifests + hand-curated rules. Cursor reads .claude/ directly for skills/agents
opencode.py	.opencode/agents/, .opencode/commands/, .opencode/skills/	Permission block from tools: allowlist (locked agents preserve intent); strict lowercase tool names; OpenCode-safe skill names
copilot.py	.copilot/agents/, .copilot/skills/, .copilot/commands/	Markdown agent profiles + SKILL.md skills + commands-as-skills; model maps to native Claude models
gemini.py	skills/, agents/, commands/*.toml at extension root	Native skills + April-2026 subagents; @{path} injection for large command bodies

Detail in docs/harnesses.md (capability matrix per harness) and docs/architecture.md (full design rationale).

Quality gates

Three mechanical gates, each runnable as a make target and wired into CI:

1. make validate — structural validation of every generated artifact. Errors block CI; warnings advisory.
2. make garden — drift detection (dead links, stale artifacts, oversize skills, marketplace orphans). Sorted by severity with per-kind summary.
3. make test — full pytest suite (386 tests: adapters + validators + gardener + real-source + round-trip + real-CLI smoke).

CI workflow: .github/workflows/validate.yml runs all three on every PR, plus a cli-smoke-test job that installs OpenCode + Gemini and exercises them against the generated artifacts.

Plugin component model

Each plugin is a directory under plugins/. Three component types, all auto-discovered:

• Agents (agents/<name>.md) — domain experts. Frontmatter: name, description ("Use PROACTIVELY when …"), model: opus|sonnet|haiku|inherit, optional tools:, optional color:.
• Skills (skills/<n>/SKILL.md) — modular knowledge with progressive disclosure. Frontmatter: name, description (must include a recognized trigger phrase like "Use when …"). Supporting material in references/, templates in assets/.
• Commands (commands/<n>.md) — slash commands. Frontmatter: description, argument-hint.

Full conventions in docs/authoring.md. Authoring for portability across all five harnesses is the main concern; the adapter framework handles per-harness mechanics.

Model tiers

Tier	Model	Use
1	Opus	Architecture, security, code review, production coding
2	inherit	Complex tasks — user chooses model (AI/ML, backend, specialized)
3	Sonnet	Docs, testing, debugging, support
4	Haiku	Fast ops, SEO, deployment, simple tasks

Per-harness adapter maps these aliases to native model IDs at generation time (see tools/adapters/capabilities.py:MODEL_ALIASES).

See also

• docs/architecture.md — full design rationale, file ownership, capability matrix detail
• OpenAI: Harness engineering — the practices this repo follows
• agents.md spec — the AGENTS.md convention this repo adopts