Skip to content

Multi-Harness Agent Contract

This document records the accepted design for supporting Claude Code and Codex in the same repository without drifting into parallel instruction systems.

Status

  • Accepted on 2026-04-25.
  • This document is the architectural record for the migration away from a Claude-first compatibility-wrapper model.

Decision

The repository uses one shared instruction graph with harness-native entry points:

  • AGENTS.md hierarchy = canonical shared contract
  • CLAUDE.md hierarchy = Claude loaders and Claude-only notes
  • .claude/rules/ = Claude preload accelerators only
  • .claude/agents/ = Claude-native delegation roles
  • .claude/MANIFEST.md = Claude component registry
  • .agents/native-skills/ = Codex-native adapter skill sources
  • .codex/ = Codex-native hook configuration only
  • scripts/agent_hooks/ = shared hook implementation

Why

Claude Code and Codex have different default discovery behavior:

  • Codex automatically reads AGENTS.md files.
  • Claude Code automatically reads CLAUDE.md files and .claude/ infrastructure.

Trying to make both harnesses share one loader filename does not work. The only durable shared layer is the AGENTS.md hierarchy. The only duplication we accept is loader-level duplication such as CLAUDE.md importing AGENTS.md.

Design Principles

  1. Shared rules live in AGENTS.md files, not only in .claude/rules/.
  2. CLAUDE.md files stay small and import the matching AGENTS.md.
  3. .claude/rules/ can preload or accelerate Claude behavior, but they do not own shared policy.
  4. .claude/agents/ can stay Claude-native, but they should point back to shared instructions instead of becoming a second knowledge base.
  5. No copied instruction trees for Codex.

File Responsibilities

Shared Contract

  • AGENTS.md
  • ras_commander/AGENTS.md
  • examples/AGENTS.md
  • other subtree AGENTS.md files as needed

These files contain the durable shared instructions that both Claude and Codex must follow.

Claude Adapters

  • CLAUDE.md
  • subtree CLAUDE.md files
  • .claude/rules/
  • .claude/agents/
  • .claude/commands/
  • .claude/MANIFEST.md

These files exist because Claude has native discovery behavior that Codex does not share.

Explicit Boundaries

AGENTS.md

  • Canonical shared source of truth
  • Safe place for rules that both Claude and Codex need
  • Can be hierarchical and directory-scoped

CLAUDE.md

  • Must import the sibling AGENTS.md
  • May add only Claude-specific notes
  • Must not repeat full workflow documentation that also belongs to Codex

.claude/rules/

  • Claude auto-load helpers
  • Good for path-scoped preload behavior
  • Not acceptable as the only home of shared rules

.claude/MANIFEST.md

  • Inventory of Claude-native components
  • Useful for discovery
  • Not the shared source of truth

Hooks

Hooks are the one place where both harnesses need native config files:

  • Claude Code reads project hooks from .claude/settings.json.
  • Codex reads project hooks from .codex/hooks.json, with .codex/config.toml enabling hook support for the project.

To avoid drift, these files should stay as thin adapters. Shared hook behavior belongs in scripts/agent_hooks/, where it can be implemented once in cross-platform Python and called by both harnesses.

Hook adapters assume python and git are available on PATH; they avoid Bash-only or PowerShell-only policy logic.

Initial hook policy:

  • inject a short session-start reminder that AGENTS.md is the shared contract
  • block direct edits to generated .agents/skills/ bridge entries
  • block obviously destructive recursive deletion and hard reset commands

Hooks are guardrails, not a security boundary. Durable policy still belongs in AGENTS.md, code review, and explicit validation.

Codex Skill Exposure

Codex skill auto-discovery is provided through a generated local bridge.

Reason:

  • The current .claude/skills/ corpus still includes provider-specific orchestration skills.
  • The repository is running on Windows with core.symlinks=false, so a tracked no-copy mirror into .agents/skills/ is not safe.
  • Generated symlinks or Windows junctions avoid tracked duplicate skill content.

Implication:

  • Codex uses the AGENTS.md hierarchy immediately.
  • Codex can use native skill discovery after running python scripts/agent_framework/sync_codex_skill_bridge.py.
  • .agents/skills/* entries are generated and ignored by git.
  • Shared skill sources remain .claude/skills/.
  • Codex-native provider handoff sources live in .agents/native-skills/.
  • The bridge is fail-closed: shared skills must be explicitly marked shared_corpus: true and harness_scope: shared.
  • The bridge must also require accepted source and review metadata before exposing a skill to Codex.

Codex-Native Adapter Skills

Some workflows are not shared domain skills but are still first-class Codex adapter capabilities. The initial example is dev_invoke_claude-code, which lets Codex invoke Claude Code as an independent read-only QAQC reviewer.

These skills live in .agents/native-skills/ and are exposed through generated links in .agents/skills/. They must be explicitly marked:

YAML
shared_corpus: false
harness_scope: codex_only
source_owner: gpt-cmdr
security_review: internal

Codex-native adapter skills are allowed because they do not duplicate shared repo policy. They only describe how Codex should call another supported harness.

Recommended agent tooling must stay specific and first-party or strongly maintained:

  • Claude Code is supported through CLAUDE.md, .claude/agents/, .claude/skills/, .claude/rules/, and .claude/commands/.
  • Codex is supported through the AGENTS.md hierarchy and the generated .agents/skills/ bridge.
  • Cross-harness QAQC is supported in both directions: Claude can invoke Codex through a Claude-native adapter, and Codex can invoke Claude Code through a Codex-native adapter.
  • Codex Browser Use may be recommended for local browser inspection of generated docs or future UI surfaces when it is available in the user's Codex environment.
  • GitHub's official CLI or MCP tooling may be recommended for repository issues, pull requests, and release work.

Do not add generic recommendation lists. Do not recommend Gemini, Context7, or a second copied agent-framework tree as part of this repository's standard setup.

External Tool And Plugin Supply Chain

Agent-facing external tools, plugins, and skills must follow the repository owner's supply-chain policy:

  • Prefer components written and maintained by gpt-cmdr in this repository or sibling gpt-cmdr repositories.
  • Official Anthropic or OpenAI repositories are acceptable upstream sources for harness-native plugins, skills, or examples.
  • Third-party external plugins or skills from outside gpt-cmdr, Anthropic, or OpenAI must be treated as untrusted until reviewed.
  • If a third-party component is useful, thoroughly security-audit it and re-implement the needed behavior inside this repository rather than linking to it as an external plugin or skill dependency.
  • Do not add repo-standard guidance that asks agents to install opaque third-party agent plugins, skills, MCP servers, or command wrappers.

Skill Classification Metadata

During the migration, provider-orchestration skills should be marked in frontmatter:

YAML
shared_corpus: false
harness_scope: claude_only

Shared skills must be explicitly allowlisted:

YAML
shared_corpus: true
harness_scope: shared
source_owner: gpt-cmdr
security_review: internal

Meaning:

  • shared skill exposure must exclude any skill that is not explicitly marked shared_corpus: true
  • harness_scope: shared is required for Codex bridge exposure
  • harness_scope: claude_only indicates the skill exists to orchestrate Claude-native behavior or Claude-triggered provider delegation
  • harness_scope: codex_only indicates the skill exists to orchestrate Codex-native behavior or Codex-triggered provider delegation
  • absence of these fields means the skill is not eligible for bridge exposure
  • accepted source_owner values are gpt-cmdr, anthropic, and openai
  • accepted security_review values are internal, official-upstream, and audited-reimplemented

Migration Rules

During the transition:

  1. Remove any statement that says AGENTS.md is only a compatibility shim.
  2. Remove any statement that says CLAUDE.md is the canonical shared source of truth.
  3. Keep .claude as Claude-native infrastructure, not the shared contract.
  4. Prefer adding new local AGENTS.md files in active subtrees instead of stuffing more shared guidance into .claude/rules/.

Invariants

The repository should continue to satisfy these rules:

  • A Codex session can follow the repo correctly by reading AGENTS.md files only.
  • A Claude session can follow the repo correctly by reading CLAUDE.md, which imports the same AGENTS.md content.
  • No shared rule exists only in .claude/rules/.
  • No new copied instruction hierarchy is introduced for a second harness.
  • Shared architectural changes update this record.

Portable workflow distribution

Selected shared skills can be assembled into a skills-only portable plugin with python scripts/agent_framework/build_plugin.py --output <new-disposable-destination>. The allowlist and independent plugin identity live in .claude/plugin/package.json. The generator bundles supporting files, follows transitive local Markdown references, rebases targets within the package, and records source/distribution hashes. Canonical instructions remain under .claude/skills/; generated distributions are artifacts.

Shared API discovery and HMS–RAS integration policy reside in their domain skills, with thin native adapters for host delegation. Discover current installed/released contracts and required dependencies rather than relying on a model hierarchy, frozen signature table, drive path, or unsupported Task import.

Importing a skill does not grant Python, local project access, engine installation, or subagent tool isolation. Project MCP remains bounded read-only text information; client configuration must expose it only to the child worker. Servers enforce the data/operation boundary separately. A client without child tool routing uses a scoped Python workflow or reports the limitation. No host-wide activation claim follows from packaging alone; demonstrate discovery, routing, bounded delegation, and handoff in that host before marketing the experience.

Release maintenance records current stable PyPI metadata and proposes update PRs. It does not install into user environments, change pins, widen compatibility ranges, merge, or publish. Metadata observation is separate from minimum/latest contract and packaging qualification. See the repository .claude/plugin/README.md for assembly, refresh, host prerequisites, and GitHub Actions permission limits. Editorial standards apply to maintained repository/package instructions, not external user deliverables.

Capability workflows and sustained research

HEC-RAS boundary conditions, meteorological forcings, gridded precipitation, mapping, land-surface inputs, and cloud-native exports have shared skills under .claude/skills/ras-*. Claude role definitions load these skills; Codex discovers the same sources through the approved bridge. Canonical ras2cng and native-backend guidance stays with its owning package.

flood-science-research supplies the sustained investigation workflow and durable task template. Hydraulics, hydrometeorology, and inundation research adapters select a scientific lens, then use the shared workflow to delegate bounded implementation and experiment tasks. Coordinator-owned task/state records and worker-owned experiment receipts support resumption across sessions. Creating these instructions does not start a research campaign or grant background execution.

During planning, the HEC reference scout and planning references identify version-specific methodology. Library contracts and actual experiment evidence establish automation coverage and findings; HEC links do not establish approval or backend parity.

Agent, skill, and reference responsibilities

An agent owns a bounded independent question, artifact, review, or isolated tool context. A shared skill owns reusable workflow decisions and validation. A reference carries conditional method/backend details and notebook evidence. A dataset, backend, model name, or file format alone does not justify another agent. Preserve compatibility entry points as thin routes to one canonical workflow.

The coordinator chooses one task route without loading all domain references. A specialist reads its skill and the selected reference sections, discovers the actual installed API, and returns concise findings plus source/artifact locators. Keep arrays, complete notebooks, and full logs out of coordinator messages. Research lenses are optional perspectives; they do not require an extra coordinator tier.

flowchart TD
    I[Intake and authorization] --> R[Choose one workflow]
    R --> A[Bounded specialist context]
    A --> S[Selected skill]
    S --> F[Relevant reference section]
    F --> E[Evidence and artifacts]
    E --> C[Concise result to coordinator]
    C --> V[Independent review when needed]

The flood-science workflow defaults to constructive adversarial review: challenge the baseline, test alternative explanations, preserve objections and negative results, and use the scientist for consequential direction. Broad agency covers the agreed study and resource envelope, including scoped method/performance improvements; it does not imply deployment, publication, or unrestricted compute. Profile and establish numerical/semantic parity before adopting a Rust rewrite.

Terrain, HMS integration and consequences extend operational routing without copying the canonical hms-commander, ras2cng or consequences-engine API contracts. See the capability roadmap for the commit-based gap assessment and proposed follow-on roles.

Specification-first model revisions

The root contract and directly invoked capability/research skills carry the specification cardinal rule. One canonical reference under .claude/references/model-revisions/specification.md defines the professional visual-specification workflow, engineer deferral, research approval envelope, figure register, actual visual review, and ras2cng reporting. Portable packaging follows these local links so direct skill use retains the same rule.