/deep

description: Runs an iterative auto-fix loop on a chosen target — review, refactor, or coverage — dispatching the base skill into fresh subagent contexts per iteration, applying fixes automatically without per-change approval, running tests with bisection on failure, and checkpoint-committing until convergence or the cap. Requires /optimus:init and a test command in .claude/CLAUDE.md.
disable-model-invocation: true
argument-hint: "<review|refactor|coverage> [testability|guidelines] [path] [--resume] [--yes] [--max-iterations N | --max-cycles N] [--no-commit] [--focus testability|guidelines] [--allow-red-baseline]"

Deep Mode

Orchestrate a base skill in an iterative auto-fix loop. Each iteration runs in a fresh subagent context, so the loop is not bounded by single-conversation context decay. All state lives in the target's progress file; the `harness_common.cli` helper applies fixes, runs tests, bisects failures, and decides termination.

Targets

| Target | Base skill (`--skill`) | Progress file | Cap flag (default/hard) | Loop reference | Focus | |---|---|---|---|---|---| | `review` | `code-review` | `.claude/code-review-deep-progress.json` | `--max-iterations` 8/20 | `references/orchestrator-loop-single.md` | no | | `refactor` | `refactor` | `.claude/refactor-deep-progress.json` | `--max-iterations` 8/20 | `references/orchestrator-loop-single.md` | yes | | `coverage` | `unit-test` | `.claude/unit-test-deep-progress.json` | `--max-cycles` 5/10 | `references/orchestrator-loop-paired.md` | no — pinned to `testability` for its refactor phase; a user-supplied focus is rejected |

The progress-file paths are load-bearing CLI defaults — never rename them. The `coverage` target counts **cycles**, not iterations: each cycle dispatches a unit-test phase (write tests, measure coverage, flag untestable code) and, when untestable items are pending, a refactor phase with testability focus.

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."* This prevents a misbehaving subagent from spawning a recursive deep run.

Parse invocation arguments

1. Target — the first standalone token must be `review`, `refactor`, or `coverage`; otherwise stop and show the usage from the argument hint. All table lookups below use this target's row. 2. `--resume` and `--no-commit` flags (present/absent) 3. `--yes` flag — auto-confirm every confirmation prompt in this skill (the Step 3 prompt and Step 4's coverage red-baseline confirmation); required when invoked under `claude -p` or any other non-interactive session that cannot answer `AskUserQuestion`. 4. Cap — the target's cap flag from the table (`--max-iterations N` or `--max-cycles N`), default and hard cap per the table. 5. Focus — refactor target only; stop on any other value or any other target (the CLI rejects both). Accept **either** `--focus testability|guidelines` **or** a bare `testability`/`guidelines` token, applying the **Focus** detection rules in `$CLAUDE_PLUGIN_ROOT/skills/refactor/SKILL.md` — read that section when parsing this item; it is the single source for the rule (do not paraphrase it here). A token consumed as focus is removed from the scope text before item 7 — otherwise `deep refactor guidelines src` would lose the `src` path scope. 6. `--allow-red-baseline` — review/refactor only; coverage always tolerates a red baseline (see Step 4). 7. Everything else → scope text. An existing path scopes the run to that path; any other text is recorded as intent only — it does **not** filter. Default scope: `review` covers the branch diff; `refactor` covers the feature-branch diff when one exists, otherwise the full project, widening per iteration to files with active findings and newly modified files; `coverage` covers the full project.

Headless / CI example (skips the Step 3 confirmation): `claude -p "/optimus:deep review --yes src/auth"`.

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.

Prerequisites

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 (e.g. `npm test`, `pytest`) as `test_command` — the auto-fix loop has no safety net without one, so if none is documented, stop and recommend `/optimus:init`. Pass this captured command to `init` in Step 4 via `--test-command` (the CLI's own CLAUDE.md parser is stricter than a human read — passing the string you read avoids a spurious "No test command found" failure).

For `coverage`: if `/optimus:init` flagged the test framework as missing or "installed but no tests yet," warn the user but proceed — the unit-test phase will surface the gap.

Git state

On a fresh (non-`--resume`) run, refuse to proceed if the working tree has uncommitted changes unless `--no-commit` is passed — uncommitted state would be ambigu