AGENTS.md@codex git:20260831.4f7d884A

Immutable. This exact content is served forever at /api/v1/blob/c98393467f99fefe.

# Codex Edition

This directory is the Codex edition of Turbo. The root [`AGENTS.md`](../AGENTS.md) covers project-wide context; this file adds edition-specific rules.

- Read [`SKILL-CONVENTIONS.md`](SKILL-CONVENTIONS.md) before editing any skill or doc in this tree — it has the prescriptive rules. Harness facts live in [`skills/create-skill/references/harness.md`](skills/create-skill/references/harness.md).
- Use Codex-native vocabulary and tool contracts. Do not introduce Claude Code control primitives such as `TaskCreate`, `TaskList`, `AskUserQuestion`, or Claude Agent tool instructions except inside explicit mapping docs.
- Install/update paths point at `codex/skills/` (source) and `~/.agents/skills/` (user-scope install location per Codex's `core-skills` loader).
- `$peer-review` is the stable abstraction; in this edition it delegates to Claude through `$claude-print`.
- Claude-specific changes belong under [`../claude/`](../claude/), not here.
- When changing a skill, convention, addition, or setup/update/migration file here, mirror the change to the parallel file in [`../claude/`](../claude/). Translate vocabulary via [`../claude/docs/harness-vocabulary.md`](../claude/docs/harness-vocabulary.md). The two editions track each other behaviorally; vocabulary differs but principles stay aligned. Drift between editions is the most common failure mode. A capability one harness lacks is not drift: mirror the principle, never this harness's ceiling. When a rule exists to work around a constraint only Codex has, the Claude sibling keeps the unconstrained form and the difference is recorded as an intentional divergence below. Narrowing a Claude gate, option set, or loop to match a Codex limit costs a real behavior there and does not count as alignment.
- After mirroring, run [`$claude-print`](skills/claude-print/SKILL.md) to have Claude review the Claude sibling against `../claude/SKILL-CONVENTIONS.md` and `../claude/CLAUDE.md`. Instruct it to read those conventions and the changed files and report findings directly, the way `$create-skill` reviews a skill, without invoking `/review-code` or any other skill. Review skills carry user-input gates that a non-interactive run drops, stalling it. Independent cross-edition eyes catch vocabulary leaks and behavioral drift the same-edition reviewer cannot see. Treat findings the same as a same-edition review (evaluate, apply).
- **Intentional divergence — crash retry:** `/codex-exec` in the Claude edition retries once when a run dies producing no output. `$claude-print` has no such rule. The evidence is codex-process-specific, and `$claude-print` Step 3 polls a shell session rather than observing a process, so a retry trigger there would license the premature give-up that Step 3 exists to prevent. Add one only if a `claude -p` crash-without-output is actually observed.
- **Intentional divergence — plan continuation:** child skills here restate a parent workflow's remaining steps in their own `update_plan` call and close with a plain `update_plan` line, where the Claude edition calls `TaskList`. `update_plan` is write-only and replaces the whole list, so a child that lists only its own steps erases the parent's and nothing can read them back; `TaskList` retrieves real stored state, so the Claude form has neither problem. Do not "resync" these to the `TaskList` phrasing when mirroring.
- **Intentional divergence — consultation option budget:** `request_user_input` allows 3 options per question while the Claude edition's `AskUserQuestion` allows 4. Where a gate's concrete choices already fill the budget, this edition presents the consultation option in place of whichever option fits least and gives the displaced option an explicit freeform path in the step that consumes it; the Claude edition simply adds a fourth option. `$apply-findings`, `$draft-plan`, `$discuss-change`, `$resolve-pr-comments`, `$create-project-skills`, and `$simplify-code` differ from their Claude siblings for this reason. Both editions displace at `$update-dependencies`, whose strategies already fill either budget. Do not "resync" these to the Claude form when mirroring.
- **Intentional divergence — loop autonomy:** `$polish-code` and `$refine-plan` run their re-run loops to natural convergence, without the iteration hard cap or the skip/continue `request_user_input` gates the Claude edition keeps; `skills/create-skill/references/workflows.md` and `skills/create-skill/references/tools.md` teach the autonomous form to match. This is deliberate — `request_user_input` does not reliably reach the user in Codex's non-interactive modes, so these loops rely on their own convergence signal instead. Do not "resync" them to the capped/gated Claude form when mirroring.
- **Intentional divergence — gate fallback:** `$discuss-change` stops and states which decisions are unresolved when one of its `request_user_input` gates cannot reach the user, rather than continuing to implementation. `$smoke-test` and `$investigate` write nothing and report the approval as unresolved when their external-write gates cannot reach the user. The Claude sibling has no such rule: `AskUserQuestion` always reaches the user from the main conversation, while Codex drops `request_user_input` in non-interactive modes, and those gates are the only thing standing between an unaligned request and edited code or an unapproved write to a shared system. Do not mirror this rule into `../claude/`, and do not strip it here when resyncing.
- **Intentional divergence — goal, ledger, and workflow-state anchoring:** `$polish-code` and `$refine-plan` carry a Loop State section (`.turbo/loops/<slug>.md` ledgers), and `$implement`, `$implement-plan`, `$finalize`, and `$turboplan` create goals via `create_goal` and maintain one pipeline checklist per goal at `.turbo/workflows/<slug>.md`, mirroring every `update_plan` call into it. The Claude siblings have none of this: Codex compaction drops `update_plan` state and loop history, while a goal's objective is re-injected every turn from storage; Claude Code task state survives in its harness and its loops keep iteration caps and `AskUserQuestion` gates. Do not mirror the goal, ledger, or workflow-state steps into `../claude/`, and do not strip them here when resyncing.
- **Intentional divergence — default-branch commit:** `$commit-staged` Step 2 and `$ship` Step 5 omit the Claude edition's statement that the current branch is kept and committed on, including when it is the default branch. That sentence counteracts a Claude Code system-prompt rule ("If on the default branch, branch first"); Codex has no equivalent, so it would be inert here. Do not mirror it into this edition when resyncing.
- **Intentional divergence — shared auto memory:** Setup writes the global `codex.sharedClaudeAutoMemory = true` contract only after validating the shared Claude Code memory integration, and `$self-improve` trusts that saved value for every project while resolving the source path instead of repeating setup or project-readiness checks; otherwise it uses a harness-approved memory update target or skips Auto memory. The Claude sibling writes the auto-memory directory its own harness exposes directly. Keep imported Codex extension resources read-only, preserve the Codex preference and discovery branch during resyncing, and do not add them to the Claude sibling.
- **Intentional divergence — cross-repo backlog writes:** `$note-improvement` Step 3 leaves an append into another repo unqualified. The Claude sibling routes it through the Edit or Write tool, which its Bash sandbox does not gate; `apply_patch` runs under the same sandbox policy as shell commands here, so it offers no equivalent escape, and [`SKILL-CONVENTIONS.md`](SKILL-CONVENTIONS.md) bars a skill from requesting a wider sandbox for routine work. Whether a denied cross-repo append fails silently here, as it does under Claude Code, is unverified; establish that before adding a rule. Do not mirror the Claude tool guidance into this edition.