Skip to content

chore: add Claude Code <-> Codex CLI agent-context parity - #278

Merged
cofade merged 1 commit into
mainfrom
chore/agent-context-parity
Aug 31, 2026
Merged

cofade merged 1 commit into
mainfrom
chore/agent-context-parity

Conversation

@cofade

@cofade cofade commented Aug 31, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Ports the agent-compatibility mechanism from cofade/open-garden-planner's PR #300 into this repo, adapted to its own conventions rather than copied verbatim:

  • AGENTS.md (repo root) — byte-identical mirror of CLAUDE.md, so Codex CLI and Claude Code operate from the same rules.
  • .codex/config.toml — declares project_doc_max_bytes (no [mcp_servers.*] yet; no HiveHive equivalent of OGP's embedded MCP server exists).
  • .codex/agents/senior-reviewer.toml — Codex-native TOML mirror of .claude/agents/senior-reviewer.md.
  • .agents/skills/{analyze-pr,esp32-onboarding}/ — mirrors .claude/skills/.
  • scripts/check-agent-context.sh — new bash policy gate (matching every other scripts/check-*.sh, not Python like OGP's original, since this repo's Python floor is pinned to 3.10 for a documented historical reason) that keeps all of the above in sync. Wired into make check-agent-context, .husky/pre-push, and the repo-guards CI job.
  • CLAUDE.md trimmed of several sections that duplicated incident narrative already living in the arc42 docs (or now newly landed there), replaced with short pointers — freed up room for the byte-identical AGENTS.md mirror.
  • docs/09-architecture-decisions/adr-033-claude-codex-agent-context-parity.md — full rationale, including the known tradeoffs (byte budget above Codex's documented default, .md↔.toml extraction fragility, Claude-specific phrasing still present in the shared file).

Test plan

  • bash scripts/check-agent-context.sh passes; verified it actually catches drift by tampering with AGENTS.md, the .codex/agents/senior-reviewer.toml instructions, a malformed byte-budget value, a mid-line ''' inside the TOML body, and empty agent directories — each reproduced and confirmed the gate correctly fails before restoring.
  • .gitignore allow-list verified behaviorally (git add -A --dry-run tracks exactly the intended new files, nothing extra).
  • All pre-existing scripts/check-*.sh guards still pass unmodified.
  • bash scripts/check-doc-citations.sh passes clean.
  • .codex/agents/senior-reviewer.toml parses with Python's tomllib, and its developer_instructions matches .claude/agents/senior-reviewer.md's body byte-for-byte.
  • Two rounds of the mandatory senior-reviewer gate, each finding real issues that were verified by direct reproduction (not taken on faith) and fixed — content that had been trimmed from CLAUDE.md without a real home elsewhere was landed properly in chapter 11 / troubleshooting.md; several script edge cases (fail-open on a malformed byte budget, a TOML-validity gap, silently passing with zero agent files) were fixed and each one reproduced before and after.
  • Verified the core mechanism (project_doc_max_bytes in .codex/config.toml, .codex/agents/*.toml with name/description/developer_instructions) against real Codex CLI documentation (developers.openai.com) — confirmed accurate.
  • Not verified: an actual live Codex CLI session against this repo (no Codex CLI installation available in this environment). Worth a real smoke test if you have access.

🤖 Generated with Claude Code

Port the agent-compatibility mechanism from open-garden-planner's PR #300,
adapted to this repo's conventions: AGENTS.md kept byte-identical to
CLAUDE.md, .codex/config.toml + .codex/agents/senior-reviewer.toml mirror
the Claude agent, .agents/skills/ mirrors .claude/skills/, and a new bash
gate (scripts/check-agent-context.sh, not Python, matching every other
scripts/check-*.sh) enforces all three stay in sync via
make/.husky/pre-push/repo-guards CI. CLAUDE.md is trimmed of duplicated
incident narrative (relocated into chapter 11 and troubleshooting.md) to
make room for the mirror. See ADR-033 for the full rationale and known
tradeoffs.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@cofade
cofade merged commit 4e9a463 into main Aug 31, 2026
23 checks passed
@cofade
cofade deleted the chore/agent-context-parity branch August 31, 2026 21:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant