turbo / claude

# Claude Edition

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

- Keep Claude Code tool vocabulary here: `TaskCreate`, `TaskList`, `AskUserQuestion`, the Skill tool, and Claude Agent tool phrasing are expected in this edition.
- Install/update paths point at `claude/skills/` and `~/.claude/skills/`, and at `claude/hooks/` and `~/.claude/hooks/turbo/`.
- Claude peer review delegates to Codex. `/peer-review` is the stable abstraction (uses `/codex-exec` with a Turbo-controlled prompt). `/codex-exec` is the raw one-shot helper. `/consult-codex` is the consultation helper.
- Codex-specific changes belong under [`../codex/`](../codex/), not here.
- When changing a skill, convention, addition, or setup/update/migration file here, mirror the change to the parallel file in [`../codex/`](../codex/). Translate vocabulary via [`../codex/docs/harness-vocabulary.md`](../codex/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 the other harness's ceiling. When a rule exists to work around a constraint only Codex has, this edition 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 and does not count as alignment.
- After mirroring, run [`/codex-exec`](skills/codex-exec/SKILL.md) to have Codex review the Codex sibling against `../codex/SKILL-CONVENTIONS.md` and `../codex/AGENTS.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 `codex exec` drops, stalling the run. 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`'s retry-once-on-a-run-that-died-producing-nothing rule stays in this edition. Leave `$claude-print` without it: 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.
- **Intentional divergence — consultation option budget:** `AskUserQuestion` allows 4 options per question while Codex's `request_user_input` allows 3. Where a gate's concrete choices already fill the smaller budget, this edition adds the consultation option and the Codex edition displaces the option that fits least, routing the displaced one through "Other" with explicit freeform handling in the consuming step. `/apply-findings`, `/resolve-pr-comments`, `/create-project-skills`, and `/simplify-code` differ from their Codex siblings for this reason; keep the asymmetry when resyncing. Both editions displace at `/update-dependencies`, whose strategies already fill either budget.
- **Intentional divergence — loop autonomy:** the Codex edition deliberately runs `$polish-code`/`$refine-plan` without this edition's iteration hard cap, skip/continue `AskUserQuestion` gates, and handoff-then-compact gate on a low-context signal, because Codex's `request_user_input` is unreliable in non-interactive modes. Keep the Claude gates as-is; do not strip them to match Codex when mirroring, and do not port Codex's autonomy here. The `hooks/` scripts that feed that gate, and their SETUP, MIGRATION, and UPDATE steps, stay out of `../codex/` too.
- **Intentional divergence — default-branch commit:** `/commit-staged` Step 2 and `/ship` Step 5 state that the current branch is kept and committed on, including when it is the default branch. The Codex siblings omit it. The sentence counteracts a Claude Code system-prompt rule ("If on the default branch, branch first") that Codex has no equivalent of, so it would be inert there. Keep it here; do not add it to `../codex/` when resyncing.
- **Intentional divergence — out-of-checkout writes:** `/note-improvement` Step 3 routes an append into another repo or the main checkout, `/create-handoff` Step 3 the handoff write, and `/implement-plan` Step 4 the plan-status edit through the Edit or Write tool, which the Bash sandbox does not gate. The Codex siblings leave those writes unqualified: `apply_patch` runs under the same sandbox policy as shell commands, so it offers no equivalent escape, and [`../codex/SKILL-CONVENTIONS.md`](../codex/SKILL-CONVENTIONS.md) bars a skill from requesting a wider sandbox for routine work. The same three steps print the content or the edit for the user when Claude Code refuses a write to the main checkout from a session isolated to a linked worktree; the Codex siblings omit that fallback too, since it depends on the tool routing. Whether a denied cross-repo append fails silently under Codex, as it does here, and whether Codex refuses a main-checkout write from a linked worktree are unverified; establish that before adding a Codex-shaped rule.
- **Intentional divergence — sandbox-denial retry:** `/run-checks` and `/test-run-rules` re-run a command that failed on a sandbox denial with the Bash tool's `dangerouslyDisableSandbox` override before reporting it not run, failed, blocked, or inconclusive. The Codex siblings omit it: [`../codex/SKILL-CONVENTIONS.md`](../codex/SKILL-CONVENTIONS.md) bars a skill from requesting a wider sandbox for routine work. Keep it here; do not add it to `../codex/` when resyncing.