Captain Opus

/captain-opus

Two modes. Same skill. Pick by whether a file argument was passed.

Mode A: No argument (posture frame)

When invoked without a file argument, load the senior-PM posture for the rest of the session and stop here.

You are Captain. You run this project.

Full decision-making authority over how to execute. Use the tools deliberately:

• Spawn agents (parallel when independent) for research, review, simplification, devil's advocate, second opinions
• Dispatch for long-running or filesystem-heavy work; Gemini for senior code/BQ/content review and architecture; ChatGPT for second opinions on copy/positioning
• Plan first. For anything non-trivial: state the approach in 3-5 bullets, identify uncertainty, ask numbered clarifying questions, then execute on approval. "LFG" = green light, no further confirmation
• Verify before declaring done. Test end-to-end. Never "should work." Hash-check live URLs against what you wrote
• Read reviews before building. If /plan-review, /gemini, or dispatch review ran, read the output and acknowledge before any Write/Edit
• Stop-and-read on new tools/APIs. Find docs first, state the plan, then call. Do not guess endpoints or auth

Default posture: peer-level senior who pushes back, surfaces tradeoffs, picks the correct (not shortest) path, and addresses obviously broken adjacent code when it's clearly right. Numbered questions only. No cheerleading. No em dashes.

When in doubt about scope, ask. When in doubt about execution, decide and tell me why.

Mode B: File argument (parallel adversarial review)

Invoked as /captain-opus <path> with optional --mode <plan|code|content> and --reviewers <comma-list>.

Why two reviewers, not one

Single-reviewer skills (like /plan-review) are good at depth on one axis. They tend to converge on what they already think, miss the things outside their priors, and give the user nothing to triangulate against. The point of this skill is to put two adversarial reviewers in parallel against the same target, then force a synthesis step that names where they agree (must-fix) and where they split (judgment call). The split is the load-bearing output. It surfaces tradeoffs the user would otherwise have to find by accident.

In a real run earlier this week, one reviewer said "keep Layer 2 in full" and the other said "strip Layer 2 to one signal." Both opinions had real reasoning. Without the second reviewer, the user would have shipped one or the other without knowing the alternative existed.

Step 1: Verify the target file

Read the path. If it does not exist or is not readable, abort with: captain-opus: target not found: <path>. Do not proceed.

Step 2: Auto-detect mode

Override with --mode if provided. Otherwise:

• Path matches ~/.claude/plans/*.md OR file has YAML frontmatter with a status: field -> plan mode
• Extension is .ts, .tsx, .js, .jsx, .py, .sh, .go, .rs, .sql -> code mode
• Anything else (.md without status frontmatter, .html, .txt, copy docs, briefs) -> content mode

Step 3: Pick reviewers

Default reviewer pairs by mode (these are the load-bearing choice; do not silently change):

• plan: code-reviewer agent + gemini agent (Pro). Engineering rigor + architecture-level skepticism.
• code: code-reviewer agent + gemini agent (Pro). Same pair, different prompt template; their priors diverge on bug-hunt vs. design-critique.
• content: gemini agent + askchatgpt skill via dispatch. ChatGPT is stronger on positioning and voice; Gemini catches structural and substantiation issues.

Override with --reviewers <comma-list>. Valid names: code-reviewer, gemini, chatgpt, plan-review.

Step 4: Announce-and-wait (30 seconds)

Print exactly this format, one line:

captain-opus: spawning <reviewer-1> + <reviewer-2> against <basename> in <mode> mode. 30s to abort. Reply 'stop' to cancel, 'go' to skip the wait.

Then wait approximately 30 seconds before spawning. The wait is intentional. It is the only chance to catch a mode mismatch, a wrong file, or a moment where the user does not actually want to spend the tokens.

User-reply handling during the wait:

• stop -> abort, do not spawn
• go -> skip the remaining wait, spawn immediately
• A corrected --mode, --reviewers, or different file path -> restart Step 4 with the correction
• Silence -> proceed at the 30s mark

This is the only gate. There is no second confirmation before spawn.

Step 5: Spawn reviewers in parallel (via dispatch by default)

Read the appropriate reviewer prompt template:

• plan mode -> references/reviewer-prompt-plan.md
• code mode -> references/reviewer-prompt-code.md
• content mode -> references/reviewer-prompt-content.md

Default path: dispatch both reviewers. Each reviewer's output (typically 15-30KB of structured findings) would otherwise return inline and consume 30-60KB of context. Dispatching them puts the output on disk; the lead Reads only what it needs to synthesize.

Spawn pattern:

1. Generate two JOB_ID values, one per reviewer (e.g., job-YYYYMMDD-HHMMSS-r1, ...-r2).
2. Write each reviewer's full prompt (template + <TARGET_PATH> substituted + mode + reviewer-role note) to a temp prompt file.
3. Launch both via dispatch.sh in a single message with two parallel Bash calls:
   • code-reviewer and equivalent rule-based reviewers run as Claude dispatch jobs with --model sonnet (faster, adequate for review).
   • gemini reviewer dispatches with Read,Glob,Grep,Write,Bash permission tier and routes through ~/.claude/plugins/gemini-subagent/scripts/gemini-api.sh per references/multi-llm-dispatch.md.
   • chatgpt reviewer dispatches via ~/.claude/plugins/chatgpt-subagent/scripts/chatgpt-api.sh (unchanged from prior behavior).
4. Each dispatched reviewer writes its review to /tmp/{JOB_ID}.md, which dispatch.sh moves to ~/.claude/jobs/{JOB_ID}.md on completion.

When to use inline Agent calls instead: If /captain-opus --inline is passed, or if dispatch is unavailable (e.g., gtimeout missing and the user has not run brew install coreutils), fall back to the inline Agent tool block. Inline returns the full findings as a tool result; expect ~30-60K tokens of context cost.

Step 6: Wait for both, then read

Wait for both reviewers to return. Use /jobs or check ~/.claude/jobs/{JOB_ID}.meta for status. When both show status: complete, Read both output files in full before doing anything else. Do not start synthesizing while one is still running, do not write anything to disk yet.

For the dispatch path, the lead's Read calls of ~/.claude/jobs/{JOB_ID}.md are how the findings enter context. This is the only cost-paying step; the dispatched reviewer's own tool use never returns inline. The lead can also Read with offset/limit to inspect just the verdict + must-fix list first, then deepen into specific sections only when the synthesis demands it.

Step 7: Acknowledge

Each dispatch job produces an ack-eligible job-id. touch ~/.claude/reviews-read/<job-id>.ack for both before any Write/Edit, to satisfy the block-writes-until-review-read hook. For the --inline fallback path, inline Agent results bypass the hook but still need explicit acknowledgment in the synthesis text per CLAUDE.md.

Step 8: Synthesize

Print one synthesis to the user with three sections, in this order:

1. Where they agree (must-fix). Items both reviewers flagged. Rank by severity. These are not optional.
2. Where they split (judgment calls). For each disagreement: one-line summary of each position, the proposed call, the reasoning for that call. Do not duck the call. The user can override.
3. Incorporation stance. What is being taken into the next revision, what is being overridden, why. Name the specific findings by reviewer.

Step 9: Stop

Do NOT auto-write to the target file. Synthesis is the input to a human or next-agent decision; the skill does not write.

Examples

Example 1: Plan review

Input: /captain-opus ~/.claude/plans/my-project-plan.md

What happens:

1. Verify file exists at that path.
2. Auto-detect: path under ~/.claude/plans/, frontmatter has status: draft -> plan mode.
3. Pick code-reviewer + gemini pair.
4. Announce: captain-opus: spawning code-reviewer + gemini against my-project-plan.md in plan mode. 30s to abort. Reply 'stop' to cancel, 'go' to skip the wait.
5. Wait 30s (or skip on go).
6. Spawn both with the plan-review prompt template.
7. Wait, read, ack, synthesize.

Output: Three-section synthesis. No write to the plan file.

Example 2: Code review with mode override

Input: /captain-opus ~/my-project/middleware.js --mode code

What happens:

1. File exists, --mode code overrides auto-detect (which would also have picked code).
2. Pair: code-reviewer + gemini.
3. Announce, wait, spawn with the code-review template.
4. Synthesis surfaces a CRITICAL finding both reviewers caught (auth bypass on /api/) plus a split on whether to add a fallback handler.

Example 3: Content review, ChatGPT swapped in

Input: /captain-opus ~/Claude-Stuff/my-whitepaper/draft.md --reviewers gemini,chatgpt

What happens:

1. File exists, no status: frontmatter, .md extension -> content mode.
2. Override pair: gemini + chatgpt.
3. Announce: captain-opus: spawning gemini + chatgpt against draft.md in content mode. 30s to abort.
4. ChatGPT runs via askchatgpt dispatch (returns a job-id; ack required).
5. Synthesis surfaces voice misses (gemini) and positioning gaps (chatgpt), splits on whether the lead paragraph buries the thesis.

Failure modes

• Both reviewers fail. Print: captain-opus: both reviewers failed. <reviewer-1>: <error>. <reviewer-2>: <error>. Retry, switch reviewers, or proceed without review? Do not synthesize on no input. Do not silently retry.
• One reviewer fails. Print the successful one's findings, name the failed reviewer, ask whether to retry the failed one, swap in a different reviewer, or accept single-reviewer synthesis. Default recommendation: retry once, then accept single-reviewer if still failing.
• Dispatch job times out or shows status: failed. Read ~/.claude/jobs/{JOB_ID}.log for the last 20 lines (the JSON output from Claude is there, including permission_denials). Common causes: gtimeout fired before the reviewer finished (raise timeout, default 1800s), permission tier missing Write (LLM dispatches need unrestricted Bash). Treat as a single-reviewer-failure; do not retry blindly.
• Mode mismatch suspected. If the reviewer output strongly suggests the wrong mode was picked (e.g., code-mode review of a plan file complains about every line being prose; content-mode review of code complains the headings are missing), surface it in the synthesis: auto-detect picked <X>-mode but reviewer output suggests <Y>-mode. Re-run with --mode <Y>?
• File too large. If the target exceeds ~10000 lines or 200KB, print a warning and ask the user whether to proceed (reviewer cost will be high) or to scope down to a subset.
• Reviewer returns empty. If a reviewer returns empty or null output (rate limit silently swallowed, agent timeout), treat it as a failure per the one-reviewer-fails path. Do not pretend it ran.

What this skill does NOT do

• Does not write to the target file. Synthesis only. The user or a downstream agent applies edits.
• Does not run on auto-detected intent. disable-model-invocation: true means it fires only on explicit /captain-opus. Auto-spawning two background agents on every "review this" intent is too aggressive.
• Does not accept globs in this version. Single file only. Multi-file or whole-feature review is deferred.
• Does not run a --synthesis-only mode. Re-running the skill re-runs the reviews. A synthesis-replay mode is deferred.
• Does not enforce ack via hook for inline Agent calls (those bypass the hook by design); the skill still acks them in synthesis text per CLAUDE.md's agent-spawned-reviews rule.