setup · diff

git:20260831.75526d7 to git:20260831.9d36849

61 added, 36 removed. Audit A to A.

---

name: setup

description: Use when superb's skills need their dependencies installed or checked — "set up superb", "install the dependencies", "why does pipeline say superpowers is missing", after a fresh plugin install, or on a new machine. Also use when a skill fails complaining that a superpowers sub-skill cannot be found.

argument-hint: "[check]"

---

# Setup

## Overview

Gets `superb`'s dependencies in place, and says plainly what it could not do.

`superb:craft` needs nothing. `superb:pipeline` and `superb:bug-fix` both

compose [superpowers](https://github.com/obra/superpowers) and do not run

without it.

- **Run `./check-deps.sh` from this skill's directory first, always.** It reports

- one fact per line and exits non-zero when a required dependency is missing, so

- you read its output rather than guessing at the state of the machine.

+ ## Step 1 — Run the check. Always, first.

+ Run `./check-deps.sh` from this skill's directory. It reports one fact per

+ line, and **its exit code is the instruction**:

+ | Exit | Meaning | What you do |

+ | ---- | ------- | ----------- |

+ | `0` | Everything required is satisfied | Report it. Stop. |

+ | `1` | Something is `MISSING` or `DISABLED` | Run the `ACTION` lines, then re-check. |

+ | `2` | **The state could not be determined** | **Do not install anything.** Report what it said. |

```

HARNESS claude | codex | unknown

- REQUIRED <name> OK | MISSING | DISABLED | UNKNOWN <detail>

- OPTIONAL <name> OK | MISSING <detail>

+ REQUIRED <name> OK | MISSING | DISABLED | ERROR | UNKNOWN <detail>

+ OPTIONAL <name> OK | MISSING <detail>

MARKET <name> OK | MISSING

- ACTION <the command that would fix the line above it>

+ ACTION <the command that fixes the line above it>

+ NOTE <something you need to know that is not actionable>

```

- If `check` was passed as the argument, report and stop. Otherwise continue.

+ If `check` was passed as the argument, report and stop regardless of the exit

+ code. With no argument, continue to Step 2.

- ## On Claude Code — install it

+ **Exit 2 is not a soft failure.** `ERROR` means the query failed, not that the

+ dependency is absent — a failed `claude plugin list` says nothing about what is

+ installed. Installing on an `ERROR` is how a present, working dependency gets

+ reinstalled over the top of itself. `UNKNOWN` means the same for a different

+ reason: nothing could look. In both cases report the `NOTE` lines and stop.

- Run the `ACTION` lines in the order they were printed. The order matters: a

- marketplace has to exist before a plugin can be installed from it.

+ ## Step 2 — Act, where you can

- ```

- claude plugin marketplace add anthropics/claude-plugins-official

- claude plugin install superpowers@claude-plugins-official

- ```

+ **Only on exit 1, and only on Claude Code.** Run the `ACTION` lines in the

+ order they were printed — a marketplace has to exist before a plugin installs

+ from it.

**`DISABLED` is not `MISSING`.** An installed-but-disabled plugin looks present

- to anything that only checks for the name, and its skills will not load.

- `claude plugin enable superpowers` is the fix, and reinstalling is not.

- **Then re-run `check-deps.sh` and report its output**, not your expectation of

- it. An install that printed no error has not been verified; the second run is

- the verification.

+ to anything matching on the name, and its skills never load. The action is

+ `claude plugin enable superpowers`; reinstalling is not the fix.

- ## On Codex — say what you cannot do

+ **Then re-run `check-deps.sh` and report its actual output.** An install that

+ printed no error has not been verified; the second run is the verification. If

+ the re-run does not reach exit `0`, say so and stop — **do not run the same

+ actions again.** A second identical attempt is how a loop starts, and the

+ script already told you it did not work.

- Codex installs plugins through an interactive picker, so nothing here can run

- it. Do not attempt a workaround, and do not write to `~/.codex/config.toml` —

- an install writing into a user's config is exactly what superpowers' own porting

- guide forbids.

+ ## Step 3 — What you cannot do, said plainly

- Report the state, then hand over the manual route:

+ **On Codex** (`HARNESS codex`), plugins install through an interactive picker.

+ Nothing here can run it, and nothing here can inspect it either — which is why

+ the state is `UNKNOWN` rather than `MISSING`. Report it, then hand over:

> Open `/plugins`, search for `superpowers`, and select Install Plugin.

+ **On `HARNESS unknown`**, neither CLI was found. Do not guess which harness this

+ is and do not run installer commands on spec. Report the output, name the two

+ supported routes, and let the user say which applies.

+ **Never write to `~/.codex/config.toml`**, or anywhere else under a user's

+ config. An install writing into user config is exactly what superpowers' own

+ porting guide forbids.

`superb:pipeline` and `superb:bug-fix` both degrade rather than break when a

subagent mechanism is absent, so this is a limitation to state, not an error to

resolve.

## Optional, and genuinely optional

| Dependency | Used by | Without it |

| ---------- | ------- | ---------- |

- | `python3` | `superb:craft`'s browser UI | Falls back to the `CRAFT.md` questionnaire; nothing is lost but the browser |

- | a git repository | `superb:pipeline`'s parallel waves | Waves need worktrees; a non-repo directory runs tasks one at a time |

+ | `python3` | `superb:craft`'s browser UI | Falls back to the `CRAFT.md` questionnaire; nothing lost but the browser |

- Report these as information. **Never install a language runtime or initialise a

- repository to satisfy them** — both are decisions with consequences well past

- this plugin, and neither blocks anything.

+ Report it. **Never install a language runtime to satisfy it** — that is a

+ decision with consequences well past this plugin, and it blocks nothing.

+ The script deliberately does not check whether the user's project is a git

+ repository: it runs from the plugin's install directory, so it would always be

+ describing the wrong directory. `superb:pipeline` establishes that itself, where

+ it can actually see the project.

## Red flags — STOP

- - About to report success without re-running `check-deps.sh` → the second run is

- the only evidence you have.

- - About to reinstall a plugin the script called `DISABLED` → enable it.

+ - About to install on exit `2` → the script could not tell whether it is already

+ there. You are about to reinstall something that may be working.

+ - About to reinstall something reported `DISABLED` → enable it.

+ - About to re-run the same `ACTION` lines after a failed re-check → that is a

+ loop. Report the output instead.

+ - About to report success without re-running the check → the second run is the

+ only evidence you have.

- About to edit `~/.codex/config.toml`, or any file under a user's config → not

yours to write.

- About to run `git init` or install a runtime → out of scope, and not asked for.

- - About to say "dependencies installed" on Codex → you could not check, let

- alone install. Say that instead.

+ - About to say "dependencies installed" on Codex or `unknown` → you could not

+ check, let alone install. Say that instead.