Codex Refactor

---
name: codex-refactor
description: |
  Codex-powered refactoring that applies changes across a codebase while
  keeping tests green. Trigger on "refactor", "rename across the
  codebase", "migrate API", "upgrade dependency", "codemod",
  "large refactor".
allowed-tools:
  - Bash(codex exec *)
  - Bash(npm test *)
  - Bash(pnpm test *)
  - Bash(git *)
  - Read
  - Write
  - Edit
---

# Codex Refactor

Use Codex sandboxed execution to perform multi-file refactors (renames,
API migrations, dependency upgrades) while verifying the test suite
stays green at every step. Produces a clean, reviewable diff.

## Prerequisites

- Codex CLI installed (`codex --version`)
- Test suite that runs in under 5 minutes
- Clean working tree (`git status` reports no changes)

## Steps

1. **Snapshot the baseline.** Record current test pass count and a
   short description of what must remain true after the refactor.
   ```bash
   git checkout -b refactor/${SLUG}
   npm test -- --reporter=json > /tmp/before.json
   ```

2. **Write a refactor spec.** One paragraph describing the before and
   after state, plus a bulleted list of files or patterns to touch.
   Save it to `REFACTOR.md`.

3. **Dispatch to Codex with the spec.**
   ```bash
   codex exec "$(cat REFACTOR.md)" --mode refactor --verify "npm test"
   ```
   Codex edits files, runs tests, and rolls back on red.

4. **Review the diff in chunks.** Break the PR into logical commits:
   one for the codemod, one for call site updates, one for test
   fixture changes. Use `git add -p` to stage selectively.

5. **Run the full suite plus lint and type-check.** A refactor that
   only passes unit tests is not done.
   ```bash
   npm test && npm run lint && npm run typecheck
   ```

6. **Compare the baseline.** Pass count must match or increase. Any
   newly skipped tests are a red flag.

7. **Document the migration** in CHANGELOG.md with before/after
   examples so downstream consumers can update.

## Anti-patterns

- Refactoring and adding features in the same PR
- Skipping tests that break instead of fixing them
- Committing Codex output without reading the diff yourself

## Output

- Single feature branch with logical commits
- All tests green, lint clean, types pass
- CHANGELOG entry with migration notes
- Refactor spec preserved in git history