---
name: sync
description: Migrate the latest Claude Builder release into Codex Builder, verify the adapted features, and release the Codex package. Use when asked to sync Builder, catch up with Claude, or sync and release.
---

# Sync Claude Builder into Codex

This is the maintainer workflow. Claude remains the source of new product features; Codex retains its native implementation. Do the migration, not only a version bump. `$sync` means adapt, verify, commit and publish the Codex release; `$sync --no-release` stops after verified local adaptation. `$sync --check` is read-only. Explicit user instructions override these defaults.

Resolve the maintained Builder repository from the user's working directory or explicit path. An installed cache is never the source to edit. Confirm `.claude-plugin/plugin.json`, `codex/plugin.json`, `.agents/plugins/marketplace.json`, and the Git remote identify Builder. Default upstream is local `main`; fetch origin only when asked to sync remote/latest published changes. Keep the selected upstream commit immutable throughout the migration.

1. Read `codex/upstream.json` and `codex/README.md`. Run `node codex/scripts/sync.mjs plan --ref main` (or the explicit upstream ref). For `--check`, use `check` instead and report the result without writes. The plan names its exact base/target, diff and decisions file. If there are no upstream changes and check is green, do not create a new release. Never overwrite dirty work or change existing worktree identity. For new work use Builder's isolated feature worktree; preserve project commit policies.
2. Read the complete upstream diff, changelog, changed skills and script contracts. For every changed file, identify the behavior and its Codex implementation. `copy-shared` copies only five shared helpers and refuses local adaptations. Other files require semantic adaptation. New skills, flags, config keys, fixes and deletions all need dispositions. Do not blindly replace Codex references with Claude prose or invoke Claude subprocesses. Retain Codex's early worktree isolation, durable specs at every size, configuration precedence, native session-owned workers, immutable target and exact candidate verification.
3. Implement the changes and focused observable tests. Keep runtime-specific exclusions documented in README. In the generated decisions JSON, fill every row as `adapted`, `equivalent`, or `claude-only`, with a concrete reason and existing `codex/...` evidence paths for adapted/equivalent changes. A feature cannot be excluded merely because porting it is inconvenient. Explain true runtime exclusions. Deleted upstream behavior must be retired or justified explicitly.
4. Obtain independent review of the assembled migration and resolve findings. Run `node codex/scripts/sync.mjs finish --ref <pinned-sha> --report <decisions-file>`. It checks coverage, aligns the version, runs the complete Codex tests and records a package digest only on success. A failed finish leaves the baseline unchanged. This is a coordinator assertion backed by tests and review, not automatic proof of semantic equivalence.
5. Unless `--no-release`, read RELEASING.md, commit only reviewed migration paths, land the verified change locally, run `node codex/scripts/release.mjs --dry-run`, then `node codex/scripts/release.mjs --publish`. This request authorizes publication of this Builder migration. Never include unrelated dirty work, force tags, or bypass failed verification. Publication creates the separate `builder-codex--v<version>` tag and GitHub release; Claude's tags remain independent. Report the release URL and install commands. Local rollout is `$update-local` when requested.

If upstream introduced a consequential product decision that cannot be inferred, ask only about that decision while continuing independent work. On interruption preserve decisions, pinned source, pending changes and exact next command in the feature handoff. Never claim sync is done while adaptations or required checks remain unfinished.