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.mdhierarchy = canonical shared contractCLAUDE.mdhierarchy = 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 onlyscripts/agent_hooks/= shared hook implementation
Why¶
Claude Code and Codex have different default discovery behavior:
- Codex automatically reads
AGENTS.mdfiles. - Claude Code automatically reads
CLAUDE.mdfiles 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¶
- Shared rules live in
AGENTS.mdfiles, not only in.claude/rules/. CLAUDE.mdfiles stay small and import the matchingAGENTS.md..claude/rules/can preload or accelerate Claude behavior, but they do not own shared policy..claude/agents/can stay Claude-native, but they should point back to shared instructions instead of becoming a second knowledge base.- No copied instruction trees for Codex.
File Responsibilities¶
Shared Contract¶
AGENTS.mdras_commander/AGENTS.mdexamples/AGENTS.md- other subtree
AGENTS.mdfiles as needed
These files contain the durable shared instructions that both Claude and Codex must follow.
Claude Adapters¶
CLAUDE.md- subtree
CLAUDE.mdfiles .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.tomlenabling 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.mdis 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.mdhierarchy 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: trueandharness_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:
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 Tool Policy¶
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.mdhierarchy 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-cmdrin this repository or siblinggpt-cmdrrepositories. - 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:
Shared skills must be explicitly allowlisted:
Meaning:
- shared skill exposure must exclude any skill that is not explicitly marked
shared_corpus: true harness_scope: sharedis required for Codex bridge exposureharness_scope: claude_onlyindicates the skill exists to orchestrate Claude-native behavior or Claude-triggered provider delegationharness_scope: codex_onlyindicates 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_ownervalues aregpt-cmdr,anthropic, andopenai - accepted
security_reviewvalues areinternal,official-upstream, andaudited-reimplemented
Migration Rules¶
During the transition:
- Remove any statement that says
AGENTS.mdis only a compatibility shim. - Remove any statement that says
CLAUDE.mdis the canonical shared source of truth. - Keep
.claudeas Claude-native infrastructure, not the shared contract. - Prefer adding new local
AGENTS.mdfiles 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.mdfiles only. - A Claude session can follow the repo correctly by reading
CLAUDE.md, which imports the sameAGENTS.mdcontent. - 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.
Related Files¶
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.