Refactor

---
name: refactor
description: "Refactoring pipeline: analyzes a target file or directory for code quality issues, plans safe incremental improvements, optionally writes tests first as a safety net, implements the changes, and reviews the result. Orchestrates refactor-planner → (test-writer) → parallel-task-orchestrator → code-reviewer."
argument-hint: "[--cross-review] <file, directory, or description of what to refactor>"
---

# Refactor Pipeline

You are orchestrating the full refactoring pipeline. Follow these steps strictly in order.

## Input

The refactoring target (file path, directory, or description of what to improve):

$ARGUMENTS

**Parse flags before proceeding:** If `$ARGUMENTS` contains `--cross-review`, set `CROSS_REVIEW=true` and strip it; otherwise `CROSS_REVIEW=false` (opt-in GPT/Codex second opinion on the diff — see Step 3.5). The remaining text is the refactoring target.

## Step 0.03: Cheap routing check — should this be `/claude-setup:refactor-lite`?

Before asking auto-commit, worktree, or orchestration questions, spend at most 2-3 minutes on a bounded read-only check:
- Identify the target file(s) or package.
- Use targeted `Glob`/`Grep`/bounded `Read` only where needed to estimate scope, callers, and whether independent parallel work exists.
- Do not launch planner/test-writer/reviewer/implementer agents in this step.

Route to `/claude-setup:refactor-lite` and stop this workflow if the refactor appears to be any of:
- 1-2 likely refactor tasks.
- A single target file/module, or mostly overlapping target files.
- A linear sequence such as rename → extract → simplify → verify.
- A cleanup where task isolation would force multiple agents to re-read the same code.
- Documentation/config-only cleanup.

Proceed with full `/claude-setup:refactor` only when the work likely needs 3+ independent refactor tasks that can run in parallel, or when the target is broad enough to exceed a single warm context.

If routing to lite, tell the user: "This looks cheaper and equally safe as `/claude-setup:refactor-lite` because <reason>. Switching to the lite workflow." Then immediately follow `skills/refactor-lite/SKILL.md` from Step 1 using the refactoring target as its input, skipping all remaining full `/claude-setup:refactor` steps. **`--cross-review` was already parsed and stripped above, so do not rely on the flag surviving in the text — carry the parsed value over directly: set `CROSS_REVIEW` in the lite workflow to the value you parsed here.** If `CROSS_REVIEW=true`, the lite pipeline runs its cross-model diff review. Plan convergence is always-on in the lite pipeline regardless.

## Step 0.1: Auto-commit opt-in

Ask: "Enable auto-commit and PR?" (Yes / No) → `AUTO_COMMIT`.

**If `AUTO_COMMIT=true`:**
1. Run `git rev-parse --abbrev-ref HEAD` to get `CURRENT_BRANCH`. If `CURRENT_BRANCH` is `main` or `master`: `BRANCH_ACTION=new`. Else ask: "Branch `<name>` exists — create new or commit here?" → `BRANCH_ACTION=new/current`.
2. Ask: "How should changes be committed?"
   - **Squash** — single commit at the end summarizing all changes
   - **Per-wave** — one commit per parallel execution wave (e.g., Wave 1: 3 tasks → 1 commit)
   - **Per-task at end** — full parallel run, then one atomic commit per task in order
   → `COMMIT_MODE=squash/per-wave/per-task-at-end`
3. Generate `refactor/<3-5-word-slug>` from `$ARGUMENTS` → `AUTO_COMMIT_BRANCH`.
4. **If `BRANCH_ACTION=new`:**
   - Run `git fetch origin` to get latest remote state.
   - Detect default branch: run `git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'`. If empty or error, default to `main`. Store as `DEFAULT_BRANCH`.
   - Ask: "Which branch should `<AUTO_COMMIT_BRANCH>` be based on?"
     - Option 1: `<DEFAULT_BRANCH>` (remote default)
     - Option 2: `<CURRENT_BRANCH>` (current branch)
     - Option 3: Other (enter branch name)
   - Store chosen base as `BASE_BRANCH`.
   - **Do not create the branch yet** — Step 0.1b performs the actual `git checkout -b` or `git worktree add -b` based on the worktree choice.

**If `AUTO_COMMIT=false`:** `BRANCH_ACTION=none`, `COMMIT_MODE=none`.

## Step 0.1b: Worktree opt-in and branch creation

Ask: "Run workflow in a new git worktree? (enables running multiple pipelines in parallel in the same project)" (Yes / No) → `USE_WORKTREE`.

Store `WORKTREE_PATH=""` as the default. It is set to the new worktree's relative path only if one is created.

### If `USE_WORKTREE=false`:

- **If `AUTO_COMMIT=true` AND `BRANCH_ACTION=new`**: run `git checkout -b <AUTO_COMMIT_BRANCH> <BASE_BRANCH>`. On failure append `-2` to `AUTO_COMMIT_BRANCH`, retry once.
- Otherwise: take no action here. Continue to Step 0.2.

### If `USE_WORKTREE=true`:

1. **If `AUTO_COMMIT=true` AND `BRANCH_ACTION=current`**: worktrees require a fresh branch (git disallows two worktrees on the same branch). Ask: "Worktree needs a new branch. Switch to a new branch, or skip the worktree and commit on the current branch?"
   - **"Create new branch"** → set `BRANCH_ACTION=new`. Generate `AUTO_COMMIT_BRANCH=refactor/<3-5-word-slug>` from `$ARGUMENTS` if not already generated. Run the same base-branch Q&A as Step 0.1 step 4 to pick `BASE_BRANCH`.
   - **"Skip worktree"** → set `USE_WORKTREE=false` and fall through to the `USE_WORKTREE=false` branch above.

2. Resolve the worktree branch and base:
   - **If `AUTO_COMMIT=true`**: `WT_BRANCH=$AUTO_COMMIT_BRANCH`, `WT_BASE=$BASE_BRANCH` (both set in Step 0.1).
   - **If `AUTO_COMMIT=false`**:
     - Ask: "Branch name for the worktree?" Suggest `refactor/<3-5-word-slug>` derived from `$ARGUMENTS`. Store as `WT_BRANCH`.
     - Run `git fetch origin` and detect `DEFAULT_BRANCH` (same as Step 0.1 step 4).
     - Get `CURRENT_BRANCH` if not already set.
     - Ask: "Which branch should `<WT_BRANCH>` be based on?" with the same three options (default / current / other). Store as `WT_BASE`.

3. Sanitize `$WT_BRANCH` into a filesystem-safe path segment (same rules as Step 0a's `SANITIZED`): replace `/` with `-`, strip non-`[A-Za-z0-9._-]`, trim leading/trailing dashes. Store as `WT_PATH_SEG`.

4. Create the worktree and branch atomically:
   ```bash
   git worktree add -b "$WT_BRANCH" ".claude-worktrees/$WT_PATH_SEG" "$WT_BASE"
   ```
   On failure (branch or path already exists), append `-2` to both `$WT_BRANCH` and `$WT_PATH_SEG` and retry once. If it still fails, abort with a clear error to the user. **If the retry succeeds and `AUTO_COMMIT=true`, set `AUTO_COMMIT_BRANCH=$WT_BRANCH`** so downstream commit/push/PR/report steps target the renamed branch.

5. `cd ".claude-worktrees/$WT_PATH_SEG"`. All subsequent steps run inside the worktree.

6. Set `WORKTREE_PATH=".claude-worktrees/$WT_PATH_SEG"` for the final report.

## Step 0.2: Orchestration Mode Selection

Check for a saved orchestration mode preference:
- Run: `cat ~/.claude/user-preferences.json 2>/dev/null`
- Parse the file safely. If it is missing, unreadable, or invalid JSON, continue to the prompt below.
- If `"orchestrationMode"` is `parallel` or `agent-teams`:
  - Log: "Using saved orchestration mode: `<value>`"
  - Set `ORCHESTRATION_MODE` to the saved value
  - Skip the rest of this step and proceed to Step 0.
- If `"orchestrationMode"` exists but has any other value, warn that the saved value is invalid and continue to the prompt below.

If no saved preference, ask the user which orchestration mode to use:

Use `AskUserQuestion` with:
- Question: "How should tasks be implemented?"
- Options:
  - **Default (Recommended)**: Use `parallel-task-orchestrator` — proven sub-agent approach with wave-based parallel execution
  - **Agent Teams (Beta)**: Use Claude Code's native Agent Teams feature — separate sessions coordinating via shared task list

Store the result as `ORCHESTRATION_MODE` (`parallel` or `agent-teams`).

Then ask: "Save this as your default orchestration mode?" (Yes / No).

If Yes: run this command, replacing `<ORCHESTRATION_MODE>` with the actual value (`parallel` or `agent-teams`):
```bash
MODE=<ORCHESTRATION_MODE> python3 -c "
import json, os
path = os.path.expanduser('~/.claude/user-preferences.json')
prefs = json.load(open(path)) if os.path.exists(path) else {}
prefs['orchestrationMode'] = os.environ['MODE']
json.dump(prefs, open(path, 'w'), indent=2)
"
```

## Step 0: Resolve TASKS_DIR + clean up

### Step 0a: Resolve TASKS_DIR

Run the following in Bash to determine the branch-scoped task directory:

```bash
RAW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
if [ -z "$RAW_BRANCH" ] || [ "$RAW_BRANCH" = "HEAD" ]; then
  SHORT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "")
  RAW_BRANCH=${SHORT_SHA:+detached-$SHORT_SHA}
fi
if [ -z "$RAW_BRANCH" ]; then
  echo "Warning: not a git repo — using tasks/ as task directory" >&2
  TASKS_DIR="tasks"
else
  SANITIZED=$(echo "$RAW_BRANCH" | tr '/' '-' | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-*//; s/-*$//')
  [ -z "$SANITIZED" ] && SANITIZED="unknown-branch"
  TASKS_DIR="tasks/$SANITIZED"
fi
```

Store `TASKS_DIR` as a session variable — use it everywhere below.

### Step 0b: Clean up stale task files

Use Bash to run `rm -rf "$TASKS_DIR"` to clear only this branch's task directory.

## Step 1: Plan — Two-phase planning with user Q&A

### Step 1a: Discovery — Analyze code & surface questions

Launch the `refactor-planner` agent using the Task tool with:
- `subagent_type: "refactor-planner"`
- Prompt: `MODE: DISCOVERY\n\nTarget: <target from $ARGUMENTS>\nTASKS_DIR=$TASKS_DIR`
- Tell it to output questions to `$TASKS_DIR/refactor-questions.md`

Wait for it to complete. **Save the returned agent ID** — you will resume this agent in Step 1c.

### Step 1b: User Q&A — Present questions and collect answers

1. Read `$TASKS_DIR/refactor-questions.md`
2. Present the code audit summary and each question to the user using `AskUserQuestion`
3. Collect all answers — pay special attention to:
   - Whether the user wants tests written first (Step 1.5 gate)
   - Scope and backward compatibility constraints

### Step 1c: Generate — Resume planner with answers

Resume the **same** refactor-planner agent (using the agent ID from Step 1a) with:
- `resume: "<agent-id-from-step-1a>"`
- Provide all user answers in the prompt, formatted clearly
- Prepend `MODE: GENERATE` to the prompt
- Tell it to generate the refactoring task files and `$TASKS_DIR/refactor-plan.md` in `$TASKS_DIR/`
- Include `TASKS_DIR=$TASKS_DIR` in the resume prompt

Wait for it to complete. Confirm that task files were created in `$TASKS_DIR/`.

### Step 1d: Task review — Present plan and get approval

This step always runs. Do not skip it.

1. Read all `task-*.md` files from `$TASKS_DIR/`. For each, extract:
   - Task number and title
   - Objective
   - Dependencies

2. Present the full refactoring plan to the user:
   ```
   ## Refactoring Plan (N tasks)

   1. task-01-name — [Objective]
      Dependencies: None
   2. task-02-name — [Objective]
      Dependencies: task-01
   ...
   ```
   Then add: "You can also open and edit any file in `$TASKS_DIR/` directly before proceeding."

3. Use `AskUserQuestion` with a single question: "How would you like to proceed?"
   - **"Looks good — start refactoring"** — continue to Step 1d.5
   - **"Regenerate with feedback"** — user provides feedback via the "Other" field

4. **If user approves**: proceed to Step 1d.5.

5. **If user requests regeneration**: resume the **same** refactor-planner agent (from Step 1a) with:
   - `resume: "<agent-id-from-step-1a>"`
   - Prompt: `MODE: GENERATE\n\nTASKS_DIR=$TASKS_DIR\n\nUser feedback on the refactoring plan:\n<feedback>\n\nPlease regenerate the task files incorporating this feedback.`
   - Wait for it to complete, then **loop back to the top of Step 1d**.
   - **Iteration cap**: max 3 regeneration cycles. If the user requests a 4th, stop looping — surface the stuck state and ask whether to abort the workflow or proceed to Step 1d.5 with the current plan.

## Step 1d.5: Plan convergence — Codex adversarial cross-check (always-on)

This step always runs. It is a **read-only, fail-soft** second opinion on the refactoring *plan* (not the code) from a decorrelated model — GPT via the Codex CLI — before any changes begin. The `refactor-planner` stays authoritative; Codex only challenges. It never mutates files and never hard-blocks: if Codex is unavailable the step logs SKIPPED and continues.

1. **Resolve the review helper** (run in Bash, store as `CODEX_REVIEW`):
   ```bash
   CODEX_REVIEW="$HOME/.claude/scripts/codex-review.sh"
   [ -f "$CODEX_REVIEW" ] || CODEX_REVIEW="scripts/codex-review.sh"
   ```
   If neither path exists, log "Plan convergence skipped — codex-review.sh not installed" and proceed to Step 1.5.

2. **Build the prompt.** Write `$TASKS_DIR/codex-plan-prompt.md` containing, in order:
   - The full contents of `$TASKS_DIR/refactor-plan.md`.
   - A compact task list: each task's number, `## Objective`, and `## Dependencies`.
   - This adversarial-reviewer instruction verbatim:
     > You are an adversarial refactoring reviewer with different training than the planner. Do NOT rewrite the plan or produce code. Challenge it specifically on: whether each step preserves observable behavior, the soundness of the decomposition (are steps truly independent and safely ordered?), and regression risk per step. Also flag missing safety nets and simpler/safer sequencing. Rank every finding as BLOCKER, MAJOR, or MINOR. If the plan is sound, say so explicitly. Be concise.

3. **Run the review** (read-only, fail-soft):
   ```bash
   bash "$CODEX_REVIEW" "$TASKS_DIR/codex-plan-review.md" "$TASKS_DIR/codex-plan-prompt.md"
   ```

4. **Act on the result.** Read `$TASKS_DIR/codex-plan-review.md`:
   - If it starts with `SKIPPED:` — note "Plan convergence: SKIPPED (<reason>)" and proceed to Step 1.5. Do not block.
   - If it contains any **BLOCKER** or **MAJOR** findings — summarize them to the user, then resume the **same** `refactor-planner` agent (ID from Step 1a) with `MODE: GENERATE\n\nTASKS_DIR=$TASKS_DIR\n\nA second-opinion plan review (GPT) raised these issues:\n<BLOCKER/MAJOR findings verbatim>\n\nRevise the task files to address them where valid; note any you deliberately reject and why.`, wait for it, then **loop back to Step 1d** to re-present and re-approve the revised plan.
   - If it contains only **MINOR** findings (or none) — surface them as advisory notes and proceed to Step 1.5.

   The user may always override and approve the current plan as-is.

   **Iteration cap:** run plan convergence at most twice. On a second pass, treat any remaining findings as advisory and proceed to Step 1.5 regardless.

## Step 1.5: Safety net — Write missing tests (if requested)

**Skip this step if the user did not ask for tests to be written first.**

If the user answered yes to writing tests before refactoring:

Launch the `test-writer` agent using the Task tool with:
- `subagent_type: "test-writer"`
- Prompt: `Write tests for <target> to create a safety net before refactoring. Focus on covering the behavior that the refactoring tasks will touch.`

Wait for it to complete, then read the test-writer's final output. It reports whether the tests it wrote pass. If all tests pass, proceed to Step 1.6. If any test fails, do NOT proceed — surface the failures to the user and ask whether to abort or to fix the failing tests first.

## Step 1.6: Fast-path detection — Should we skip the orchestrator?

Read all `$TASKS_DIR/task-*.md` files and classify `FAST_PATH=true` if ANY of:
- 2 or fewer tasks (regardless of dependencies)
- All tasks are sequential: linear dependency chain OR all tasks touch overlapping files (no parallelism possible)
- Only 1 task out of 3+ could run in parallel (orchestrator adds overhead for negligible parallelism)

Otherwise `FAST_PATH=false`.

Refactoring task files often have linear dependency chains (rename → extract → simplify → decompose) and tend toward fast-path more than feature builds.

## Step 2: Implement

### Fast path (`FAST_PATH=true`) — Direct implementation

If `ORCHESTRATION_MODE=agent-teams`: inform the user "Fast-path detected — using direct implementation instead of Agent Teams; orchestration overhead is not justified for simple refactors." Skip the env-var setup from Step 0.2.

Implement tasks yourself, sequentially, in the current session. For each task file in order: (1) read the task file fully, (2) read any referenced tests, (3) apply the refactor, (4) run **the project test command** (the same one Step 1.5 used to write the safety net, or whichever command the task file specifies) to verify behavior is preserved — refactor tasks rarely have their own per-task test commands; the safety net is the verification surface, (5) write `$TASKS_DIR/notes/task-NN.md` with notes on what was changed and why, plus anything risky for review (Decisions / Deviations / Trade-offs / Risks). After all tasks: concatenate `$TASKS_DIR/notes/task-*.md` (sorted) into `$TASKS_DIR/implementation-notes.md` with a `# Implementation Notes` header.

Commit handling: if `COMMIT_MODE=per-wave`, after each task run `git add -A && git diff --staged --quiet || git commit -m "refactor: <task-objective>"`. If `COMMIT_MODE=per-task-at-end`, skip — commits happen in Step 2.5b.

Fast-path keeps continuous session context across tasks (no cold reads) and avoids the orchestrator overhead, which is rarely justified for refactors with sequential dependencies.

### Full path (`FAST_PATH=false`) — Run orchestrator

**If `ORCHESTRATION_MODE=parallel`** (default):

Launch the `parallel-task-orchestrator` agent using the Task tool with:
- `subagent_type: "parallel-task-orchestrator"`
- Tell it to read and execute all tasks from `$TASKS_DIR/`
- Include `TASKS_DIR=$TASKS_DIR` in the launch prompt
- Tell it to batch same-wave tasks that share module/directory context when safe, and to keep sub-agent returns short because detailed notes must be written to `$TASKS_DIR/notes/`.
- **If `COMMIT_MODE=per-wave`**: Include `COMMIT_MODE=per-wave` in the launch prompt so the orchestrator commits after each wave.
- **If `COMMIT_MODE=squash`, `per-task-at-end`, or `AUTO_COMMIT=false`**: Launch normally with no additional commit instructions.

Wait for it to complete. Note any issues reported.

**If `ORCHESTRATION_MODE=agent-teams`** (Beta):

First, enable the required env var by finding the user's settings file (check `.claude/settings.local.json`, then `.claude/settings.json`, then `~/.claude/settings.json`) and adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to the `env` object, preserving all existing settings. If no settings file exists, create `.claude/settings.local.json` with the env var.

Do NOT spawn a sub-agent. Instead, execute Agent Teams orchestration directly in this session:
1. Read `agents/agent-teams-orchestrator.md`
2. Follow those instructions directly in this session to orchestrate tasks using Agent Teams teammates, passing `TASKS_DIR=$TASKS_DIR` as session context
3. Produce the same outputs: `$TASKS_DIR/implementation-notes.md` and `$TASKS_DIR/execution-metrics.md`

Note: Per-wave commits in Agent Teams mode are handled by the agent-teams-orchestrator when `COMMIT_MODE=per-wave` is passed in the session context. Per-task-at-end commits are handled by the skill layer in Step 2.5b (runs after Agent Teams execution completes).

After Agent Teams execution completes (whether successful or not), **clean up the env var**: read the settings file that was modified above, remove `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` from the `env` object, and write it back. If the `env` object is now empty, remove it entirely. This prevents the beta env var from persisting across future sessions.

## Step 2b: Build check — Verify the project compiles

Run a quick build/lint check to catch obvious breakage:
- Look for a `package.json`, `Makefile`, `Cargo.toml`, or similar build config
- Run the appropriate build command (e.g., `npm run build`, `pnpm build`, `make`, `cargo check`)
- If the build fails, report to the user and ask whether to proceed or fix first
- If no build system is detected, skip this step

## Step 2c: Test verification — Confirm behavior is preserved

This step is especially critical for refactoring — the primary success criterion is that all existing tests still pass.

- Run the full test suite (e.g., `npm test`, `pnpm test`, `pytest`, `go test ./...`, `cargo test`)
- If tests fail: report the failures and ask whether to fix, proceed anyway, or stop
- If no test suite exists, note this prominently — behavior preservation cannot be verified automatically

## Step 2d: Simplify — Final polish pass (opt-in, one pass)

The refactor tasks already did the structural work (rename/extract/decompose). A `/simplify` pass is an optional final polish that catches local cleanups the tasks introduced. It **mutates code**, so behavior preservation must be re-verified — the same primary success criterion as the refactor itself.

**Guard:** Only offer this step if Step 2c passed with no regressions. If tests failed or there is no test suite to verify against, **skip this step entirely** — never apply unverifiable cleanups on top of a refactor. Set `SIMPLIFY_RAN=false`.

1. Use `AskUserQuestion`: "Run a `/simplify` polish pass on the refactored code before review?"
   - **"Yes — simplify"** — run the polish pass
   - **"No — skip"** → set `SIMPLIFY_RAN=false` and proceed to Step 2.5

2. **If "Yes"**: invoke the `simplify` skill via the Skill tool. Tell it to scope to the full branch diff against the base branch, so changes already committed in `per-wave`/`per-task-at-end` modes are covered — not just uncommitted edits. Wait for it to finish.

3. **Re-verify behavior preservation**: re-run the Step 2b build check and the full test suite from Step 2c.
   - If any test that passed before now fails, the cleanup broke behavior: report the regressions and ask whether to (a) keep simplify's changes and continue, (b) revert the simplify changes (`git checkout -- <files>` / `git restore`) and continue, or (c) stop. Do not silently proceed — behavior preservation is the contract.
   - If green, set `SIMPLIFY_RAN=true`.

Simplify's edits are left uncommitted and flow into the existing Step 2.5b commit logic.

## Step 2.5: Auto-commit and PR

**Skip if `AUTO_COMMIT=false`.**

**2.5a Safety:** Run `git rev-parse --abbrev-ref HEAD`. If `main`/`master`: abort ("Auto-commit aborted: on main/master. Commit manually.") → proceed to Step 3.

**2.5b Commit:**

- **`COMMIT_MODE=squash`**: Read all `$TASKS_DIR/task-*.md` files. Extract the `## Objective` line from each. Run:
  ```bash
  git add -A
  git commit -m "refactor: <$ARGUMENTS summary>" -m "$(cat <<'EOF'
  - <objective from task-01>
  - <objective from task-02>
  - <objective from task-03>
  ... (one bullet per task, no cap)
  EOF
  )"
  ```
  Subject line: 72-char max. Body: one bullet per task objective, all listed (no 3-bullet cap).

- **`COMMIT_MODE=per-wave`**: Commits were made by the orchestrator during execution. Run `git add -A` to catch any unstaged changes left after the final wave, then commit any remainder:
  ```bash
  git add -A
  git diff --staged --quiet || git commit -m "refactor: post-run cleanup"
  ```
  If nothing is staged after `git add -A`, skip the final commit.

- **`COMMIT_MODE=per-task-at-end`**: Full parallel run is complete. Now create one commit per task in task-file order:
  1. Run `git add -A` to stage all changes.
  2. Read each `$TASKS_DIR/task-NN-*.md` file in numerical order.
  3. For each task, extract its `## Objective` line and the list of files it touched (from the `## Target Files` section).
  4. Use `git restore --staged .` to unstage everything, then selectively stage only the files for this task using `git add <file1> <file2> ...`, then commit:
     ```bash
     git restore --staged .
     git add <files for this task>
     git commit -m "refactor: <task objective>"
     ```
  5. Repeat for each task in order.
  6. After all per-task commits, run `git add -A && git diff --staged --quiet || git commit -m "refactor: miscellaneous changes"` to catch any files not covered by the task-file manifests.

**2.5d Push:** `git push -u origin <branch-name>`. On failure, show manual command and continue.

**2.5e PR:** Run `gh auth status 2>/dev/null && echo GH_OK || echo GH_UNAVAILABLE`.
- `GH_OK`: Create PR body (1-2 sentence summary + "## Changes" task bullets + "## Behavior Preservation" noting test results). Run `gh pr create --title "refactor: <desc>" --body "<body>" --base main`. Display URL.
- `GH_UNAVAILABLE`: Display ready-to-copy `gh pr create` command.

**2.5f Report:** `Branch: <name> | Commits: <N> | Push: ok/failed | PR: <url or manual>`

## Step 3: Review — Run code-reviewer

Check if `$TASKS_DIR/implementation-notes.md` and `$TASKS_DIR/execution-metrics.md` exist (produced by the orchestrator).

Before launching the reviewer, gather a compact review packet:
- If `DEFAULT_BRANCH` is not set, resolve it: `DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')` (fallback `main` if empty or error).
- Capture `git diff --stat "$DEFAULT_BRANCH"...HEAD`, `git diff --name-only "$DEFAULT_BRANCH"...HEAD`, and `git log --oneline "$DEFAULT_BRANCH"..HEAD`.
- Capture build/test commands run in Steps 2b/2c and their pass/fail summaries. Do not paste full logs unless failures need specific excerpts.

Launch the `code-reviewer` agent using the Task tool with:
- `subagent_type: "code-reviewer"`
- Tell it to review all changes against `$TASKS_DIR/refactor-plan.md`
- **If `$TASKS_DIR/implementation-notes.md` exists**, tell it to read this file for implementer decision context
- Tell it to write the review report to `$TASKS_DIR/refactor-review-report.md`
- Include `TASKS_DIR=$TASKS_DIR` in the launch prompt
- Include the compact review packet in the prompt. Tell it to review diff-scoped changes first, reading changed files and requirement files as needed, and to expand to unchanged files only when required to verify behavior, contracts, or conventions.
- Include these refactor-specific review criteria in the prompt:
  - Is behavior preserved? Are there any logic changes that shouldn't be there?
  - Do all existing tests still pass?
  - Is the code measurably cleaner, simpler, or more maintainable than before?
  - Are the changes minimal and focused — no unrelated modifications?
  - If the scope included public APIs, are signatures preserved (or are breaking changes intentional and documented)?
- **If `SIMPLIFY_RAN=true`**: append `A /simplify polish pass already ran on these changes — do NOT re-flag reuse, simplification, efficiency, or altitude items as Minor issues. Focus on behavior preservation, correctness, and whether the code is measurably cleaner.` so the report stays signal-dense.

Wait for it to complete.

## Step 3.5: Second-opinion diff review — Codex (conditional)

A decorrelated second reviewer (GPT via the Codex CLI) over the refactor diff. **Read-only and fail-soft** — never mutates code, never hard-blocks. Claude's `code-reviewer` (Step 3) remains the PRIMARY reviewer; this only augments it.

**Run this step if** `CROSS_REVIEW=true` **OR** the diff touches sensitive areas (authentication/authorization, payments/billing, cryptography or secrets, concurrency/locking/async, database migrations or schema changes, or external I/O). If none apply and `CROSS_REVIEW=false`, skip directly to Step 4.

1. **Resolve the helper** (same as Step 1d.5):
   ```bash
   CODEX_REVIEW="$HOME/.claude/scripts/codex-review.sh"
   [ -f "$CODEX_REVIEW" ] || CODEX_REVIEW="scripts/codex-review.sh"
   ```
   If neither exists, log "Cross-review skipped — codex-review.sh not installed" and proceed to Step 4.

2. **Capture the diff and build the prompt.** Capture the full branch diff (`git diff "$DEFAULT_BRANCH"...HEAD` plus any uncommitted `git diff`). If empty, log "Cross-review skipped — empty diff" and proceed to Step 4. Otherwise write `$TASKS_DIR/codex-diff-prompt.md` containing the diff text followed by this instruction verbatim:
   > You are a second reviewer of a refactor, with different training than the primary reviewer. Review ONLY the diff below. A refactor must preserve observable behavior — focus on any change in observable behavior, public API/contract changes, lost edge cases, and regression risk. Do NOT suggest cosmetic or stylistic changes. Rank each finding BLOCKER, MAJOR, or MINOR with a file:line reference. If behavior is preserved, say so explicitly. Be concise.

3. **Run the review** (read-only, fail-soft):
   ```bash
   bash "$CODEX_REVIEW" "$TASKS_DIR/codex-diff-review.md" "$TASKS_DIR/codex-diff-prompt.md"
   ```

4. **Merge findings.** Read `$TASKS_DIR/codex-diff-review.md`:
   - If it starts with `SKIPPED:` — note it and proceed to Step 4. Do not block.
   - Otherwise, append a `## Second-opinion (GPT) findings` section to `$TASKS_DIR/refactor-review-report.md` with the Codex findings, **excluding** any that duplicate an issue Claude already raised (dedupe by `file:line` + topic).
   - Surface every non-overlapping **BLOCKER** or **MAJOR** finding prominently to the user in Step 4 (the refactor pipeline has no auto-fix loop) so they can be addressed before merge. Leave MINOR findings as advisory.

Then proceed to Step 4.

## Step 4: Report

Summarize the full refactoring run to the user:

Check if `$TASKS_DIR/execution-metrics.md` exists (produced by the orchestrator in full-path mode). If not (fast-path mode), generate equivalent metrics inline from your own execution.

```
## Refactor Complete

### Target
- [What was refactored]

### Changes Made
- [N tasks completed]
- [Key improvements: what's better now]

### Build Check
- [passed / failed / skipped]

### Tests
- [all passed / N regressions / no test suite]

### Simplify
- [ran — behavior preserved / ran — broke X, user chose Y / skipped / not offered (no green baseline)]

### Execution Metrics
- Tasks: [completed/total] | Waves: [N] | Retries: [N]
- Implementation notes: [see $TASKS_DIR/implementation-notes.md]

### Review
- [compliance score]
- [behavior preserved: yes/no]
- [critical issues if any]
- Plan convergence (Codex): [findings routed back / advisory only / SKIPPED]
- Cross-model diff review (Codex): [ran — N findings (list BLOCKER/MAJOR) / not triggered / SKIPPED]

### Auto-Commit
- [skipped — not enabled]
  OR
- Branch: <branch-name>
- PR: <url or "manual command displayed">

### Worktree
- [omit this section entirely if `WORKTREE_PATH` is empty]
  OR
- Path: <WORKTREE_PATH>
- Cleanup: `git worktree remove <WORKTREE_PATH>` (run from the original repo root)

### Next Steps
- [e.g., review the changes, run manual tests, address any regressions]
```

## Rules
- Run steps **sequentially** — each depends on the previous
- If Step 1 fails (no tasks created), stop and report the issue
- If Step 2c finds regressions, escalate to the user before proceeding to review
- Always run Step 3 — never skip the review
- Behavior preservation is the primary success criterion — a refactor that breaks tests is a failure