Research 001 — Superpowers-backed development workflow

Status: complete Step 1.5 output. One entry per [NEEDS VERIFICATION] marker in spec.md, plus findings that turned up alongside. Evidence is cited, not recalled.

All entries verified 2026-07-23 against obra/superpowers at commit d884ae04edebef577e82ff7c4e143debd0bbec99 (= main HEAD = release v6.1.1).

V1 — Do superpowers' documented extension points hold?

Question. The integration rests on two behaviours: that CLAUDE.md outranks a skill, and that both brainstorming and writing-plans let a user preference override their default artifact location. Do the shipped skill files actually say this?

Verdict. Confirmed for the documented half. All three statements exist verbatim.

Evidence.

Claim	Source	Text
CLAUDE.md outranks skills	skills/using-superpowers/SKILL.md:62	"User instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to."
Spec location is overridable	skills/brainstorming/SKILL.md:107	"(User preferences for spec location override this default)"
Plan location is overridable	skills/writing-plans/SKILL.md:19	"(User preferences for plan location override this default)"

Default paths confirmed as the spec describes them: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md (brainstorming/SKILL.md:29,106) and docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md (writing-plans/SKILL.md:18). R3's redirect is therefore necessary, and documented as supported.

Caveat, carried forward. This confirms the skills say the override is honoured. It does not confirm an agent does honour it in a live session — that is behavioural, and static reading cannot reach it. The spec's own Assumptions already concede this class of claim is verified by human review rather than by test, and R5–R7 test artifacts rather than behaviour for the same reason. Nothing here changes that; the risk is documented, not eliminated.

V2 — Does the plugin ship all fourteen skills, under those names?

Verdict. Confirmed. Exactly fourteen SKILL.md files, names matching the spec's appendix one-to-one. No extras, none missing, no renames.

Evidence. Repository tree at d884ae04, skills/*/SKILL.md:

brainstorming              executing-plans                 receiving-code-review
dispatching-parallel-agents finishing-a-development-branch  requesting-code-review
subagent-driven-development systematic-debugging            test-driven-development
using-git-worktrees         using-superpowers               verification-before-completion
writing-plans               writing-skills

The appendix table needs no correction.

V3 — Does the plugin ship a SessionStart hook, and what does it cost?

Verdict. Confirmed, including the matcher. Cost now measured rather than assumed.

Evidence. hooks/hooks.json registers a single hook:

{ "hooks": { "SessionStart": [ { "matcher": "startup|clear|compact",
  "hooks": [ { "type": "command",
    "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
    "async": false } ] } ] } }

The matcher is exactly startup|clear|compact, as the spec assumed. async: false, so it runs synchronously on each of those events.

hooks/session-start injects the full text of using-superpowers/SKILL.md wrapped in an <EXTREMELY_IMPORTANT> block. That file is 3,063 bytes / 481 words / 62 lines, so the injection costs roughly 800 tokens per startup, clear, and compact — not once per session, but every compact too. On a long session with several compactions this is a recurring charge, which is a sharper statement than the spec's "its token cost is accepted". It remains small enough to accept; it is now accepted with a number attached.

F4 — Superpowers ships in Anthropic's official marketplace (unprompted finding)

Finding. Not a spec claim — turned up while checking installation. superpowers is a listed plugin in anthropics/claude-plugins-official, at ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json:

{ "name": "superpowers", "category": "development",
  "source": { "source": "url", "url": "https://github.com/obra/superpowers.git",
              "sha": "d884ae04edebef577e82ff7c4e143debd0bbec99" } }

Why it matters. R1 wants the plugin declared in project-scoped, version-controlled settings. That is simpler than assumed — the official marketplace is already registered on this machine (known_marketplaces.json, last updated 2026-07-22), so no third-party marketplace needs adding.

It also touches an Out of scope line. The spec declines to pin a version and says "we track the marketplace's current release" — but the official marketplace pins a sha, so tracking it is pinning, just not by us. Today that sha equals main HEAD equals v6.1.1, so the distinction is currently invisible; it will stop being invisible the first time upstream moves and the marketplace does not. A plan-level decision, flagged, not made here.

F5 — The plugin is not currently installed (unprompted finding)

Finding. ~/.claude/plugins holds only known_marketplaces.json and the claude-plugins-official marketplace checkout. No superpowers install, and none of the fourteen skills are available in this session.

Everything above was verified by reading the upstream repository, which is why V1's behavioural half could not be closed. Spec 001 was written the same way — .claude/settings.local.json carries an allow-rule for curl … api.github.com/repos/obra/superpowers/… from an earlier session.

Consequence. Installing the plugin is implementation work under R1, correctly on the far side of the plan gate. No blocker: nothing in the spec assumed it was already installed.

V6 — Does enabling the plugin in project settings require a per-machine step? (raised at plan time)

Question. SC1 requires that a fresh clone plus one dependency install yields a working session "with no per-machine configuration step". Does declaring enabledPlugins in a version-controlled .claude/settings.json achieve that?

Verdict. Refuted. It does not. A second, per-machine command is required.

Evidence.

1. Documentation, discover-plugins.md line 446: "As of Claude Code v2.1.195, this install step applies on every path that loads plugins. A plugin that only the project's .claude/settings.json enables, and that comes from an external source such as a GitHub repository or npm package, doesn't load until the team member installs it."
2. Superpowers is exactly that case. Its official-marketplace entry sources from an external URL — {"source": "url", "url": "https://github.com/obra/superpowers.git"} (F4). Being in the official marketplace does not exempt it; officialMarketplaceAutoInstalled in ~/.claude.json refers to the marketplace being registered, not to its plugins being installed.
3. Installed CLI is 2.1.218, past the 2.1.195 threshold, so the rule is live here.
4. Direct spike. A throwaway project outside the repo, containing only .claude/settings.json with {"enabledPlugins": {"superpowers@claude-plugins-official": true}}. Run in that directory, claude plugin list reports No plugins installed. Use 'claude plugin install' to install a plugin. The setting alone loads nothing. Spike discarded.

The missing step, confirmed against claude plugin install --help:

claude plugin install superpowers@claude-plugins-official [--scope user|project|local]

Consequence. SC1 is unachievable as worded. A fresh clone needs two commands — pnpm install and claude plugin install … — not one. Nothing about the design is wrong; the success criterion counted wrong, and it counted wrong because it was written before anyone checked.

Silver lining. --scope project writes the enabledPlugins entry into .claude/settings.json itself, so R1's file can be generated by the install command rather than hand-authored — which keeps the "no hand-editing of config files" property that SC1 was probably reaching for.

Disposition (human, 2026-07-23). Amending SC1 was offered and declined; SC1 stands as written and the spec stays approved. It therefore ships as a known-unsatisfiable criterion, covered by an it.fails() test so the gap is recorded in the suite rather than only here. See plan.md, Open questions #1.

V7 — Does declaring obra/superpowers as its own marketplace pin the version? (closed — abandoned)

Verdict. Refuted in practice, then made moot by decision. Pinning is dropped; the plugin is consumed from the official marketplace. Closed 2026-07-23 during T2.

What was tried. Documentation research found a real distinction worth keeping on record:

Source kind	Where it is set	Pinning fields
Marketplace source	extraKnownMarketplaces	ref only — no sha
Plugin source	source of an entry inside a marketplace catalog	ref and sha

So an exact-commit pin required an inline source: "settings" marketplace, declaring the plugin with {repo: "obra/superpowers", ref: "v6.1.1", sha: "d884ae04…"}. Tag v6.1.1 resolves to exactly d884ae04edebef577e82ff7c4e143debd0bbec99, matching the official catalog. Upstream's own .claude-plugin/marketplace.json is named superpowers-dev, not superpowers, so the plugin id would have been superpowers@superpowers-dev — the plan's assumed superpowers@superpowers was wrong.

Why it failed. Written into project .claude/settings.json, the inline marketplace was invisible to the CLI. claude plugin marketplace list showed only claude-plugins-official, and claude plugin marketplace update superpowers-pinned reported Marketplace 'superpowers-pinned' not found. Whether project-scoped extraKnownMarketplaces needs an interactive trust step to register was not pursued — see below.

Decision (human, 2026-07-23). Stop. Drop the custom marketplace and install from the official one. The earlier "let's pin" decision is reversed.

Consequences, recorded so they are not rediscovered:

• The plugin version floats. The official marketplace auto-updates by default, so a superpowers release can arrive without us asking. The fourteen-name inventory test is the tripwire that turns silent drift into a failing suite.
• This restores consistency with the spec. Out of scope says "Pinning a superpowers version. We track the marketplace's current release and revisit if it breaks" — which is now exactly what happens. The contradiction flagged in plan.md Risks is gone rather than absorbed.

Installed state, verified. superpowers@claude-plugins-official, version 6.1.1, scope user, status enabled. Fourteen SKILL.md files present at ~/.claude/plugins/cache/claude-plugins-official/superpowers/6.1.1/skills, matching V2.

V7 — original question, for context

Question. The human chose to pin. The official marketplace auto-updates by default (discover-plugins.md: "Official Anthropic marketplaces have auto-update enabled by default"), so consuming superpowers through it does not pin, regardless of the sha in its catalog entry. The plan therefore declares the upstream repo as its own marketplace, relying on third-party marketplaces defaulting to autoUpdate: false. Two things need confirming before the settings file is written:

1. That obra/superpowers's .claude-plugin/marketplace.json registers cleanly as a marketplace, and what plugin id it yields (superpowers@superpowers is the assumption).
2. That the resulting install does not auto-update — i.e. autoUpdate really defaults to false for this source, and no per-machine toggle is needed.

Verdict. Open. To be resolved by the task that writes .claude/settings.json, not by assumption. If it fails, the fallback is autoUpdate: false on an extraKnownMarketplaces entry for the official marketplace, whose support outside managed settings is itself unverified.

Known. The repo does ship .claude-plugin/marketplace.json (seen in the tree at d884ae04), which is what makes option 1 plausible in the first place.

Graduation — done

Moved to docs/architecture/workflow-tooling.md at step 6: the two-command setup (V6), the floating version and the pinning routes already tried (V7, F4), the ~800-token SessionStart cost (V3), and Node's unflagged type stripping. Everything else here is spec-001-specific and stays.

Graduation — original notes

Nothing here has outlived the feature yet. On completion of step 6, the v6.1.1 pin and the ~800-token SessionStart cost are the two candidates for docs/architecture/.