--- id: 901173 card_url: "https://mdrss.com/ai-agents/agent-design-and-orchestration/901173" permalink_url: "https://mdrss.com/m/901173" thread_url: "https://mdrss.com/s/ai-agents" markdown_url: "https://mdrss.com/ai-agents/agent-design-and-orchestration/901173/901173.md" title: "Architecture" annotation: "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. Use it to ground design choices in named patterns, trade-offs and examples." state: published thread: ai-agents domain: ai-agents category: agent-design-and-orchestration type: reference tags: ["ai-agent-systems", "agent-design-and-orchestration", "architecture", "component", "model", "agent", "design", "orchestration", "ai-agents", "collider-club"] ontology_terms: ["concept:agent-design-and-orchestration", "org:collider-club"] relation_terms: [] license: "MIT" version: 1 snapshot_at: "2026-08-04T16:17:00.000Z" source_url: "https://github.com/wshobson/agents" source_kind: "collider-club-curated" platform_scam_risk: 5 platform_evidence_score: 100 evidence_urls: - "https://github.com/wshobson/agents" - "https://raw.githubusercontent.com/wshobson/agents/c4b82b0ad771190355eb8e204b1329732a18449a/ARCHITECTURE.md" - "https://collider.club" - "https://opensource.org/licenses/MIT" --- # 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. Use it to ground design choices in named patterns, trade-offs and examples. > Editorial note: curated source snapshot published by [Collider.club](https://collider.club) under the MIT License. Source attribution is preserved in the front matter. ## Source snapshot # Architecture Top-level architectural map for the claude-agents marketplace. Detail lives in [`docs/architecture.md`](docs/architecture.md); this file is the index per the OpenAI [harness-engineering](https://openai.com/index/harness-engineering/) pattern. ## Invariants 1. **Single source of truth.** All agent / skill / command authoring happens under `plugins//`. 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 (87 local plugins; 3 externals in marketplace) │ └── / │ ├── .claude-plugin/plugin.json │ ├── agents/*.md │ ├── commands/*.md │ └── skills//{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=` │ ├── 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`](docs/harnesses.md) (capability matrix per harness) and [`docs/architecture.md`](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`](.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/.md`) — domain experts. Frontmatter: `name`, `description` ("Use PROACTIVELY when …"), `model: opus|sonnet|haiku|inherit`, optional `tools:`, optional `color:`. - **Skills** (`skills//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/.md`) — slash commands. Frontmatter: `description`, `argument-hint`. Full conventions in [`docs/authoring.md`](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`](docs/architecture.md) — full design rationale, file ownership, capability matrix detail - [OpenAI: Harness engineering](https://openai.com/index/harness-engineering/) — the practices this repo follows - [agents.md spec](https://agents.md/) — the AGENTS.md convention this repo adopts --- ## About Collider.club This card belongs to the curated knowledge base of **[Collider.club](https://collider.club)** — a closed business club for entrepreneurs, engineers, investors and domain experts building projects for international markets. Members work across DeFi, AI/ML, FinTech, Web3, banking, hardware and venture capital, and the club runs closed sessions on high-margin niches with anonymous speakers. - Club: - Collection: Collider.club curated card library (`mdrss-card/v2`) - Maintainer: Collider.club editorial team ## License MIT License — Copyright (c) 2026 Collider.club. Full text: [LICENSE](../../LICENSE) ·