1082-line design note covering:
- Empirical facts about Codex CLI 0.121.0 (invocation, streams,
resume semantics, known failure modes) with copy-pasteable
verification commands.
- Claude Code harness facts (Bash truncation, cwd drift, Opus
literal-interpretation tendencies).
- 12 design decisions in a uniform format: what, where in SKILL.md,
alternatives considered, why chosen, trade-offs accepted.
- Rejected ideas (marker files, per-round naming, $(pwd), etc.) with
reasons, so future contributors don't re-propose them.
- Prior diagnostic errors from a previous agent-auditor's dump that
turned out to be wrong when verified, kept as a methodological
lesson.
- Smoke-test protocol (§7) with concrete commands and expected
outputs so any maintainer can verify the Codex contract still holds
in minutes.
- Update protocol: when and how to revise this file, with a pointer
that future Opus generations interpret instructions more literally
and SKILL.md hardening must track that.
- Mermaid flow diagram of the round-trip.
Intended audiences: future Claude sessions resuming work on the skill,
human developers, and new contributors. The file is self-contained —
does not rely on conversation history that produced the current design.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ddadminandClaude Opus 4.7
3f0d1321ff