oprogramadorreal/optimus-claude/deep

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

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 this skill's own location — the "Base directory for this skill:" line in your invocation context (Claude Code), the Plugin root: in the session-start note (Codex), or the path of this SKILL.md — strip the trailing /skills/... segment 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 as a plugin."

Wherever the steps below and the references they load write $CLAUDE_PLUGIN_ROOT in a command or path, substitute this plugin_root literally; <absolute-plugin-root> in dispatch prompts is the same value.

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).

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 ambiguous with the orchestrator's own checkpoint commits. Untracked harness state in .claude/ (a prior run's progress, .bak and .done.json files, and the loop's dot-prefixed scratch files) does not count.

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 mode ([target]) runs up to [N] iterative fix passes (cycles for coverage, each up to two subagent dispatches). Every pass spawns fresh subagents — credit and time consumption multiplies with the count. Fixes are applied automatically 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:deep [target] --resume.

Test command: [test command]

Focus: [focus or "balanced"] (refactor target only)

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

Use AskUserQuestion — header "Deep mode", question "Proceed with deep [target]?":

• Proceed — "Run the loop until clean (max [N] iterations/cycles)"
• 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 it with <progress-path> and <cap-flag> from the Targets table.

On fresh run

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli init \
    --skill <base-skill> \
    <cap-flag> [N] \
    --test-command "<test_command>" \
    [--focus testability | --focus guidelines] \
    [--scope "<scope>"] \
    [--no-commit] \
    --progress-file "<progress-path>" \
    --project-dir "."

Pass --focus only for the refactor target, and only with the value from Step 1.

Baseline

Run cli baseline before entering the loop. On --resume, run it after resume, skipping it only when the progress file's completed counter (iteration.completed, or cycle.completed for coverage) is above 0 and no _safety_error is recorded — targeted reads, never the findings array. resume never re-runs the baseline, and the CLI refuses snapshot and every step command until a green baseline clears _safety_error.

PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli baseline \
    --progress-file "<progress-path>" \
    [--allow-red]

baseline runs the test command once and calibrates the per-iteration timeout from its duration. Per target:

• review / refactor — green required. On baseline-red, stop and show the failing tests (a red starting tree makes bisection blame the iteration's fixes and revert good work); the user can fix them or re-run with --allow-red-baseline. Pass the CLI --allow-red only when the user supplied --allow-red-baseline — the CLI's own failure message names its internal flag, not the skill flag.
• coverage — always pass --allow-red: a coverage run legitimately starts with little or no passing coverage. If the CLI prints baseline-red-allowed and the project already has tests (or the baseline hit the test timeout), warn the user and confirm before entering the loop — under --yes, print the warning and proceed without confirming: a failing suite trips the unit-test phase's blocked stop gate at cycle 1, and a timing-out suite silently rolls every cycle's tests back.

Step 5: Run the Loop

Read the target's loop reference — $CLAUDE_PLUGIN_ROOT/references/orchestrator-loop-single.md (review, refactor) or $CLAUDE_PLUGIN_ROOT/references/orchestrator-loop-paired.md (coverage) — and follow its per-iteration body exactly, with:

• <base-skill> = the table's base skill
• <progress-path> = the table's progress file
• <max> = the cap from Step 1

Refactor target: when a focus is set, add Focus: <testability|guidelines> to the dispatch prompt after the Phase: line (the base skill reads config.focus from the progress file; the echo makes the intent visible in the run trace).

Between iterations, tell the user in one line what the CLI reported (the deep-step / unit-test-step / refactor-step result and the termination check), so a long run is visibly progressing. Findings themselves stay in the progress file and the final report — don't reproduce subagent output in conversation prose.

Step 6: Final Report

After the loop, follow the loop reference's "After the loop" section, then open your closing message with the outcome in two or three lines. Give the stop reason, the report's headline counts (fixed/reverted, or coverage before → after and tests created), and any --resume hint or rollback command the report printed, because the host may collapse the command's output. For a fresh second-opinion pass after a clean finish, re-run /optimus:deep <target> without --resume.

Close on the outcome — changes left uncommitted (--no-commit, or commits disabled mid-run) → /optimus:commit; checkpoint commits made → /optimus:pr once the branch is ready (squash first if wanted — the final report prints the command) — either way, stay in this conversation so the implementation context is captured.