superpowers-muse

A routing overlay for the stock Superpowers plugin for Claude Code. Superpowers keeps owning the process — brainstorming, plans, task briefs, worktrees, the fix loop, the ledger — while this skill decides who performs each role: a cheap external model writes the code, Codex reviews it, and a few rules stop the expensive models from being used badly.

How it relates to stock Superpowers

• Unchanged: every stock skill, script and artifact. Nothing in the plugin directory is modified; the workspace, briefs, review packages and progress.md ledger stay exactly where stock puts them.
• Replaced: the performers. Stock dispatches Claude subagents as implementer and reviewer; here the implementer is Muse Spark 1.3 Contributor through OpenCode (or a Claude Opus subagent when judgment matters more than cost), and the reviewers are Codex gpt-5.6-sol and gpt-6-astra.
• Added: a deck of workers with costs and strengths, ten invariants the coordinator may not trade away, defaults, thin CLI wrappers with anchored verdict contracts, and reviewer prompts derived from the stock ones.

Prerequisites

• Claude Code ≥ 2.1.x with superpowers@claude-plugins-official installed and enabled (claude plugin list).
• Codex CLI, signed in, with access to gpt-5.6-sol and gpt-6-astra.
• OpenCode ≥ 1.18.
• A Meta Model API key with muse-spark-1.3-contributor enabled and its data-use terms accepted.
• Git. On Windows, Git Bash (Claude Code's Bash tool runs it).

Install

1. Copy the skill:

   cp -r superpowers-muse "$HOME/.claude/skills/"

2. Append the contents of CLAUDE.global.md to $HOME/.claude/CLAUDE.md (create the file if it does not exist). That is what makes the routing apply in every session.
3. Set MODEL_API_KEY as a user environment variable (Windows: Edit environment variables for your account; POSIX: your shell profile). The scripts never take it as an argument and never print it.
4. Optional environment:
   • OPENCODE_EXE — full path to the OpenCode binary if it is not on PATH.
   • OPENCODE_MUSE_STATE — where this skill keeps OpenCode state (default %LOCALAPPDATA%\opencode-muse, or ${XDG_STATE_HOME:-$HOME/.local/state}/opencode-muse).
5. Start a new Claude Code session so the skill and CLAUDE.md are loaded.

Verify

SKILL="$HOME/.claude/skills/superpowers-muse"
codex login status                                             # Codex reachable
[ -n "$MODEL_API_KEY" ] && echo key-present                    # key visible
cmd //c "$SKILL/scripts/opencode-muse.cmd" models meta-muse    # Windows
bash "$SKILL/scripts/opencode-muse.sh" models meta-muse        # macOS/Linux

The last command should print meta-muse/muse-spark-1.3-contributor. The real test is the first run: make a scratch git repo, ask Claude Code to implement a one-file task through the skill, and watch it dispatch Muse, then Codex Sol.

How it works in a session

• Triggers: "implement the plan", "execute plan", "subagent-driven development", "request code review", "review the diff / this PR / the branch", "finish the branch", "Muse", "Codex review", and the Russian equivalents. It deliberately does not trigger on reviewing documents or contracts.
• Opt out: "stock superpowers", "plain mode", «без Muse» — stock Superpowers with Claude subagents for that session.
• Artifacts: everything lives in the stock SDD workspace, <repo-root>/.superpowers/sdd/<plan>/ — dispatches, reports, review packages, verdict files, the progress.md ledger. Audits use .superpowers/sdd/audit-<name>/. Stock deletes that workspace at the end, so the skill tells the coordinator to copy verdict files out first.
• Budget gate: before a batch bigger than ~3000 lines of diff or more than two Codex dispatches, the coordinator states scopes, model and effort per dispatch, rough wall-clock and the fact that it spends your weekly Codex quota — and waits for your answer.

The deck

Worker	Model	Typical use	Cost
Muse Spark 1.3 Contributor	via OpenCode, --effort minimal…xhigh	writes code from a well-specified brief	lowest
Claude Opus writer	Agent tool, model: "opus"	design judgment, unknown-cause debugging	high
Claude Sonnet explorer	Agent tool, model: "sonnet"	repo recon, mapping a codebase, call sites	low
Claude Haiku extractor	Agent tool, model: "haiku"	mechanical extraction from logs and test output	lowest
Codex Sol	gpt-5.6-sol, xhigh	task review, scoped re-review, per-module audit	mid
Codex Astra	gpt-6-astra, high/xhigh	architecture, important changes, final branch, synthesis	high
Fable second opinion	Agent tool, model: "fable"	mandatory second opinion on architecture	mid

The invariants

1. A task's code is reviewed by a different vendor than wrote it.
2. The architecture gate takes two opinions: Codex Astra and a fresh Fable subagent.
3. Astra owns auth, payments, migrations, concurrency, public API, irreversible state, deployment — and the final whole-branch review.
4. No silent substitution: an unavailable model, CLI or key is a blocker; departures from a default are ledgered with a reason.
5. One writer per worktree at a time; a writer never spawns reviewers or subagents.
6. Every dispatch names its model and effort explicitly.
7. Findings pass a YAGNI filter before they reach a writer.
8. The API key is never printed or persisted; no bypass flags.
9. Bulk never reaches a judgment model — paths and digests, never pasted code.
10. A batch is approved by you, never assumed; at most 2 Codex runs in flight.

Costs

• Muse is billed by the Meta Model API. Prompt caching is automatic and measured at 84-96% of input tokens in real runs (the low end is a run with two cold starts), so fix rounds resumed on the same session are much cheaper than the first dispatch; reasoning tokens bill as output. muse-implement.sh prints the cache share of every run.
• Codex runs on your ChatGPT subscription and draws on its weekly quota — that is why invariants 9 and 10 exist.
• Claude subagents (Opus, Sonnet, Haiku, Fable) run on your Claude subscription, in your own session.

Files

superpowers-muse/
  SKILL.md                     the overlay: paths, invariants, deck, defaults, workflow
  references/cli-handoff.md    exact commands, verdict contracts, exit codes, caching
  scripts/muse-implement.sh    one Muse run through OpenCode; evidence and key redaction
  scripts/codex-review.sh      one read-only Codex gate; anchored verdict contracts
  scripts/opencode-muse.cmd    Windows launcher (config + isolated state)
  scripts/opencode-muse.sh     macOS/Linux/Git Bash launcher
  assets/opencode-muse.json    OpenCode config: model, effort variants, permissions
  prompts/muse-implementer.md  implementer dispatch (stock report contract)
  prompts/task-review.md       Sol task review (spec + quality)
  prompts/re-review.md         Sol scoped re-review after a fix round
  prompts/module-review.md     Sol review of one module of existing code
  prompts/astra-architecture.md, fable-architecture.md   the two architecture gates
  prompts/astra-important-change.md, astra-final-branch.md, astra-diagnosis.md
  prompts/audit-synthesis.md   cross-cutting synthesis over module findings
CLAUDE.global.md               paste into ~/.claude/CLAUDE.md

Known limitations

• Windows-first: developed and tested on Windows 11 with Git Bash. The POSIX launcher is provided but has had less mileage; the interruption procedure in SKILL.md uses tasklist/taskkill.
• Muse cannot ask questions mid-run: a dispatch either carries what it needs or comes back NEEDS_CONTEXT.
• The Superpowers plugin path is resolved by glob, so a plugin update is absorbed automatically — but the prompts mirror the 6.3.0 verdict shapes. If a future plugin release changes them, re-sync the prompts and the --contract patterns in scripts/codex-review.sh.
• Model ids (muse-spark-1.3-contributor, gpt-5.6-sol, gpt-6-astra) are pinned on purpose; swapping them is an edit, not a flag.

Credits

Built on obra/superpowers (MIT), whose skills, prompts and verdict contracts this overlay adapts. MIT licensed — see LICENSE.