refactor-deep

Project Refactor (Deep)

Orchestrate /optimus:refactor in an iterative cleanup loop. Each iteration runs in a fresh subagent context. All state lives in .claude/refactor-deep-progress.json. The orchestrator dispatches subagents, parses their structured output, and uses the harness_common.cli helper to apply fixes, run tests, bisect failures, and decide termination.

Step 1: Parse Arguments and Guard Against Re-entry

Re-entry guard

If your invocation prompt body already contains HARNESS_MODE_INLINE, stop immediately with: "Deep mode cannot run inside deep mode."

Parse invocation arguments

Extract from the user's arguments:

1. --resume flag (present/absent)
2. --no-commit flag (present/absent)
3. --yes flag (present/absent) — auto-confirm the Step 3 prompt; required when invoked under claude -p or any other non-interactive session that cannot answer AskUserQuestion.
4. --max-iterations N (optional, default 8, hard cap 20)
5. Focus keyword: testability or guidelines (the same detection rules as /optimus:refactor) — match only standalone unquoted tokens, case-insensitive; keywords inside quotes stay in the scope text; if both keywords appear as standalone tokens, use the first one and warn: "Multiple focus keywords detected — using '[first]'. Run separate passes for each focus."
6. --allow-red-baseline flag (present/absent) — proceed even if the Step 4 pre-loop baseline finds the suite already failing
7. Everything else → scope text (an existing path scopes the refactor to that path; other text is recorded as intent only and does not filter). With no path scope, iteration 1 covers the feature-branch diff when one exists, otherwise the full project; scope then widens per iteration only to files with active findings and newly modified files.

Examples:

• /optimus:refactor-deep → feature-branch diff (full project when no diff exists), 8 iterations, balanced focus
• /optimus:refactor-deep testability → focus on testability barriers
• /optimus:refactor-deep guidelines src/backend → guidelines focus, scoped to an existing path
• /optimus:refactor-deep --max-iterations 12 → 12 iterations
• /optimus:refactor-deep --resume → continue from existing progress file
• /optimus:refactor-deep --no-commit → skip per-iteration checkpoint commits
• claude -p "/optimus:refactor-deep --yes testability" → headless / CI usage; skips the Step 3 confirmation prompt

Step 2: Pre-flight Checks

Plugin root

Resolve plugin_root (the absolute path to the installed plugin) and keep it for every CLI call and subagent dispatch below — the env var does not persist across separate Bash tool calls and reads empty on some platforms (notably Windows):

1. Run echo $CLAUDE_PLUGIN_ROOT via Bash. If it is non-empty and <value>/scripts/harness_common exists (test -d), use it.
2. Otherwise derive the root from the "Base directory for this skill:" line in your invocation context — strip the trailing /skills/... segment (this skill's own directory) — and use it if <derived>/scripts/harness_common exists.
3. If neither candidate contains scripts/harness_common, stop: "Cannot resolve plugin root — ensure optimus-claude is installed via the Claude Code plugin system."

Wherever the steps below (and orchestrator-loop-*.md) write $CLAUDE_PLUGIN_ROOT, use this resolved plugin_root; if echo $CLAUDE_PLUGIN_ROOT was empty, substitute the absolute path literally.

Documentation prerequisites

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/prerequisite-check.md and apply the prerequisite check. If .claude/CLAUDE.md is missing, stop: "Deep mode requires /optimus:init to set up project context first."

Test command

Read .claude/CLAUDE.md and capture the documented test command verbatim — store the exact string (e.g. npm test, pytest) as test_command. If none is documented, stop and recommend /optimus:init to set one up first. You pass this captured command to init in Step 4 via --test-command; init can also parse .claude/CLAUDE.md itself, but its parser is stricter than a human read, so passing the command you just read avoids a spurious "No test command found" failure on a command the CLI can't parse.

Git state

On a fresh (non---resume) run, refuse to proceed if the working tree has uncommitted changes unless --no-commit is passed. On --resume, the existing progress file's _snapshot.pre_head is the recovery anchor.

Step 3: User Confirmation

Skip this step entirely when --resume is given, or when --yes is given (headless / CI: the caller has pre-approved the run).

Warn the user with:

Deep refactor runs up to [N] iterative refactor passes. Each iteration spawns a fresh subagent — credit and time consumption multiplies with iteration count. Fixes are applied automatically at each iteration without per-change approval. Low test coverage increases the chance of undetected breakage; consider running /optimus:unit-test first to strengthen the safety net. Press Esc twice to interrupt — state is saved per-iteration; resume with /optimus:refactor-deep --resume.

Test command: [test command] Focus: [focus or "balanced"]

Mid-iteration interrupts may leave the working tree inconsistent; clean iterations are fully recoverable via --resume.

Use AskUserQuestion — header "Deep refactor", question "Proceed with deep refactor?":

• Proceed — "Run iterative refactor until clean (max [N] iterations)"
• Cancel — "Don't run deep mode"

If the user selects Cancel, stop.

Step 4: Initialize or Resume Progress

Read $CLAUDE_PLUGIN_ROOT/references/harness-init-resume.md and apply its shared init/resume semantics — the resume invocation and cap raising, init error recovery (a prior run is discarded by re-invoking init with --force), --no-commit persistence, and .done.json archival — with these parameters:

• <progress-path> = .claude/refactor-deep-progress.json
• <cap-flag> = --max-iterations

On fresh run

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli init \
    --skill refactor \
    --max-iterations [N] \
    --test-command "<test_command>" \
    [--focus testability | --focus guidelines] \
    [--scope "<scope>"] \
    [--no-commit] \
    --progress-file ".claude/refactor-deep-progress.json" \
    --project-dir "."

If --focus is supplied with anything other than testability or guidelines, the CLI rejects it.

Establish a green baseline

Skip on --resume only when the prior run completed at least one iteration — then the baseline already ran and its calibrated timeout is persisted. Check the progress file's single iteration.completed field (a targeted read — do not load the findings array into context): if it is 0, the prior run never entered the loop (it stopped at baseline-red, or was interrupted at or before the first iteration), and resume never re-checks the baseline — run the command below after resume (green required, or --allow-red per the user) before entering the loop. On a fresh run, after init succeeds, verify the suite is green before the loop:

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli baseline \
    --progress-file ".claude/refactor-deep-progress.json" \
    [--allow-red]

baseline runs the test command once and calibrates the per-iteration timeout from how long it takes (so a slow suite, re-run repeatedly during bisection, doesn't spuriously time out). It prints baseline-green (continue) or, on a failing suite, baseline-red with a non-zero exit. On baseline-red, stop and show the user the failing tests — a red starting tree makes bisection blame the iteration's fixes and revert good work. Tell the user to fix the failing tests, or to accept the red baseline by re-running with --allow-red-baseline; either way the run continues via --resume, which re-establishes the baseline per the skip rule above. The CLI's own failure message says to pass --allow-red — that is its internal flag, not a skill argument; the skill-level flag is --allow-red-baseline. Pass --allow-red only when the user supplied --allow-red-baseline (proceed without a green safety net; the timeout is left at its default).

Step 5: Run the Iteration Loop

Read $CLAUDE_PLUGIN_ROOT/references/orchestrator-loop-single.md and follow its 8-step per-iteration body, with these parameters:

• <base-skill> = refactor
• <progress-path> = .claude/refactor-deep-progress.json
• <max> = the iteration cap from Step 1

When dispatching the refactor subagent, include the focus keyword in the prompt body if one was set:

... Phase: refactor
    Focus: <testability|guidelines>
...

The base skill reads config.focus from the progress file (the CLI's init recorded it there) and applies the finding-cap weighting accordingly — but echoing the focus into the dispatch prompt makes the intent visible to anyone reading the run trace.

Step 6: Final Report

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli final-report \
    --progress-file ".claude/refactor-deep-progress.json" \
    --archive

This prints the cumulative report; archival semantics, including the diminishing-returns soft-exit exception, are in the loop reference's "After the loop" section.

Important

User approval recorded at Step 3 stands for the entire loop — fixes are applied without per-change confirmation. Recommend /optimus:commit next, followed by /optimus:pr once the branch is ready. Tell the user: Tip: stay in this conversation when running /optimus:commit and /optimus:pr so the implementation context is captured. Other downstream skills (/optimus:code-review, /optimus:unit-test) should still run in fresh conversations.

Tip

If the project has low test coverage and you suspect testability barriers are blocking better coverage, run with `

---

Content truncated.