Workflow tooling

Facts about the machinery behind the workflow in CLAUDE.md, established by spec 001 and verified rather than assumed. Graduated from specs/001-workflow-tooling/research.md so the next spec does not re-derive them.

Verified 2026-07-23 against superpowers v6.1.1 (d884ae04) and Claude Code 2.1.218.

Setup costs two commands, not one

pnpm install
claude plugin install superpowers@claude-plugins-official

Enabling a plugin in a project's .claude/settings.json does not install it. From Claude Code v2.1.195, a plugin that only project settings enable, and that comes from an external source, does not load until each user installs it locally. Superpowers sources from github.com/obra/superpowers even inside the official marketplace, so it is exactly that case.

The committed .claude/settings.json therefore records which plugin the project uses; it does not provision it. This is why spec 001's SC1 ships known-unsatisfiable.

The plugin version floats

Official Anthropic marketplaces have auto-update enabled by default, so superpowers can move to a new release without anyone asking. Pinning was attempted and dropped:

• Marketplace sources (extraKnownMarketplaces) accept ref but not sha.
• Plugin sources inside a marketplace catalog accept both ref and sha.
• An exact-commit pin therefore needs an inline source: "settings" marketplace — which, written into project settings, did not register: claude plugin marketplace list showed only the official one.

The tripwire, in place of a pin: the skill-inventory test asserts the fourteen skill names spec 001 binds each workflow step to. An upstream rename fails the suite loudly rather than degrading quietly. That is detection, not prevention. If drift becomes a real problem, revisit pinning — the mechanism above is the map of what was already tried.

The SessionStart hook costs ~800 tokens per fire

Superpowers registers one hook, matcher: startup|clear|compact, async: false. It injects the full text of using-superpowers/SKILL.md (3,063 bytes) wrapped in an <EXTREMELY_IMPORTANT> block.

That is roughly 800 tokens on every startup, clear, and compact — a recurring charge on long sessions, not a one-off. Accepted, with the number attached.

Node runs TypeScript directly

scripts/*.ts run as node scripts/<name>.ts with no build step and no tsx, using unflagged type stripping. This is why engines.node is >=22.18 — the version where stripping became unflagged — and why tsconfig.json is noEmit: TypeScript typechecks, Node executes.

Worktrees carry a feature (spec 009)

Graduated from specs/009-worktree-at-scaffold/research.md. Verified against superpowers 6.1.1 on 2026-08-03.

• Isolation happens at step 0, not before implementation. /new-spec allocates the number, then EnterWorktree name=NNN-<slug> creates the branch and the worktree; the script never runs git checkout. The shared tree therefore never changes branch, which is what lets two features be open at once.
• Base ref is fresh = origin/main. A new worktree branches from origin/main, not local HEAD. So spec numbering is read from the same origin/main (merged specs) unioned with in-flight NNN-* branches — the two cannot disagree, and a parallel unmerged spec never reuses a number.
• Worktrees live under .claude/worktrees/, gitignored (.gitignore:24). This is the native location, not the .worktrees/ that superpowers:using-git-worktrees would pick as a git fallback.
• Cleanup is by hand, after the PR merges, from the main tree: git worktree remove .claude/worktrees/NNN-<slug>, git branch -D NNN-<slug>, git worktree prune. superpowers:finishing-a-development-branch does not do this: its cleanup only touches .worktrees//worktrees/, and only on the local-merge/discard paths — not the push-and-PR path a GitHub merge takes, which deliberately preserves the worktree. ExitWorktree cannot help either; it refuses worktrees from an earlier session.