Superpowers

https://github.com/obra/superpowers
Admin
Superpowers provides Claude Code with a comprehensive skills library, including testing, debugging,...
Tokens:447,857
Snippets:3,033
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Commit Installation Guide

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md

Commands to stage and commit the installation guide file.

```bash
git add .opencode/INSTALL.md
git commit -m "docs: add opencode installation guide"
```

--------------------------------

### Good Example: Explicit Dependency Installation

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Shows the recommended approach: explicitly instruct the agent to install the required package before using it. Includes a pip install command and a Python code snippet using the pypdf library.

```markdown
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
```

--------------------------------

### High-level guide with references (SKILL.md)

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Example SKILL.md file that provides a quick start with pdfplumber and links to separate files for advanced features. Agents load the referenced files only when needed.

```markdown
---
name: PDF Processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
```

--------------------------------

### Start server with instance id

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md

Example command to start the server with a per-start instance id passed as an inert command-line argument. The id is not an auth credential, only process-ownership evidence for local lifecycle scripts.

```text
node server.cjs --brainstorm-server-id=<id>
```

--------------------------------

### Bad Example: Assuming Package Installation

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Shows an incorrect instruction that assumes a library is already installed. This can lead to failures if the package is not present in the execution environment.

```markdown
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
```

--------------------------------

### Start server with non-loopback host

Source: https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md

Binds to 0.0.0.0 and sets --url-host to localhost for remote/containerized setups where the default URL is unreachable.

```bash
bash scripts/start-server.sh \
  --project-dir /path/to/project \
  --host 0.0.0.0 \
  --url-host localhost
```

--------------------------------

### Example Workflow: Full Inline Plan Execution

Source: https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md

A complete example of using the executing-plans skill to implement a plan inline. It shows the entire process from setup to completion, including task execution, handling of a typo discrepancy, and final review. This is a single, comprehensive example that illustrates the workflow.

```text
You: I'm using the executing-plans skill to implement this plan inline.

[Setup: worktree verified]
[Read plan once: docs/superpowers/plans/feature-plan.md; spec read]
[Resolve workspace: sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger]
[Create todos for all tasks]

Task 1: Hook installation script

[task-start plan 1 → brief read; BASE a1b2c3d]
[Step 1: write failing test — written]
[Step 2: run it — FAIL: install_hook not defined. Matches Expected.]
[Step 3: implement — written]
[Step 4: run it — PASS 1/1. Matches Expected.]
[Step 5: commit — d4e5f6a]
[Contract: tests ran, output read, no deviations]
[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]

Task 2: Recovery modes

[task-start plan 2 → brief read; BASE d4e5f6a]
[Step 2: run failing test — FAIL, but on an import error: Task 1 exported
 installHook, brief consumes install_hook]
[Ruling: brief's consumer name is a typo against Task 1's Produces block;
 use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
[Steps 2-5 as planned; commit b7c8d9e]
[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]

...

[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model]
Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor.
[Re-grade: Important stands; minors → ledger as deferred]
[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit]
[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]

Rulings I made:
- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename)

Deferred minors:
- README lacks a usage example
- recovery.js could split verify/repair into two files

[Delete this plan's workspace — the record now lives in git]

Using superpowers:finishing-a-development-branch.
```

--------------------------------

### Auto-detect and run setup commands

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-04-06-worktree-rototill.md

Runs the appropriate dependency installation or build command based on the presence of project files (package.json, Cargo.toml, requirements.txt, pyproject.toml, go.mod).

```bash
# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi
```

--------------------------------

### Start server with --open

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md

Command to start a user-approved companion session with auto-open behavior.

```bash
scripts/start-server.sh --project-dir /path/to/project --open
```

--------------------------------

### Example SDD Workflow

Source: https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md

A complete walkthrough of the Subagent-Driven Development loop, showing how to dispatch implementers and reviewers, handle fix rounds, and maintain the ledger. It includes the initial setup, task execution, review cycles, and final completion steps.

```text
You: I'm using Subagent-Driven Development to execute this plan.

[Setup: worktree verified]
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Resolve workspace: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Create todos for all tasks]

Task 1: Hook installation script

[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: [Later]
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ✅ - all requirements met, nothing extra.
  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.

[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]

Task 2: Recovery modes

[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]

Implementer: [No questions]
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ❌:
  - Missing: Progress reporting (spec says "report every 100 items")
  Issues (Important): Magic number (100)

[Fix round 1: resume the implementer with both findings]
Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
  Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.

[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
  Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
  Verdict: all findings addressed.

[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]

...

[After all tasks]
[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
Final reviewer: All requirements met. Deferred minors triaged: none block merge.

[Delete this plan's workspace — the record now lives in git]

Done! Using superpowers:finishing-a-development-branch.
```

--------------------------------

### Example code review workflow

Source: https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md

Shows a complete example of requesting a code review after completing a task, including getting SHAs, dispatching the reviewer, and acting on feedback.

```text
[Just completed Task 2: Add verification function]

You: Let me request code review before proceeding.

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
HEAD_SHA=$(git rev-parse HEAD)

[Dispatch code reviewer subagent]
  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661

[Subagent returns]:
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed

You: [Fix progress indicators]
[Continue to Task 3]
```

--------------------------------

### Test server starts

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2026-01-17-visual-brainstorming.md

Starts the server with a timeout to verify it launches. Expected to see JSON with 'server-started' and port info.

```bash
cd lib/brainstorm-server && timeout 3 node index.js || true
```

--------------------------------

### Start server with --open and --foreground

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md

Command to start a user-approved companion session with auto-open and foreground mode.

```bash
scripts/start-server.sh --project-dir /path/to/project --open --foreground
```

--------------------------------

### Compress examples: verbose vs minimal

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md

Shows a verbose example (42 words) versus a minimal example (20 words) to illustrate token savings.

```markdown
# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```

--------------------------------

### Stage and install plugin with agy plugin install

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md

Stages the committed tree into a scratch directory and installs it as an agy plugin. Expected output: install [ok], skills processed, hooks skipped; 'agy plugin list' shows source 'antigravity'.

```bash
mkdir -p "$SCRATCH/accept/superpowers"
git archive HEAD | tar -x -C "$SCRATCH/accept/superpowers"
agy plugin install "$SCRATCH/accept/superpowers"
agy plugin list
```

--------------------------------

### Install Superpowers in OpenCode

Source: https://github.com/obra/superpowers/blob/main/README.md

Tell OpenCode to fetch and follow the installation instructions for Superpowers.

```text
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
```

--------------------------------

### Clone and install Superpowers as a Muse plugin

Source: https://github.com/obra/superpowers/blob/main/README.md

Clones the Superpowers repository and installs it as a Muse plugin, then approves the plugin. This is an alternative to installing from a local checkout. Restart any active Muse sessions after installing so the SessionStart hook takes effect; skills are active immediately, but hooks require approval on first install.

```bash
git clone https://github.com/obra/superpowers.git
muse plugins install ./superpowers
muse plugins approve superpowers
```

--------------------------------

### Example workflow: add workspace resolution step (old vs new)

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md

Two example workflow fragments showing the addition of a workspace resolution step after reading the plan file and before creating todos.

```text
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Create todos for all tasks]
```

```text
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Create todos for all tasks]
```

--------------------------------

### Install Superpowers directly in Kimi Code

Source: https://github.com/obra/superpowers/blob/main/README.md

Install Superpowers directly from this repository in Kimi Code.

```text
/plugins install https://github.com/obra/superpowers
```

--------------------------------

### Smoke check - install dependencies

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md

Installs dependencies for the evals project using uv sync. Expected output is 'Installed N packages' or similar, with no errors.

```bash
cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
uv sync
```

--------------------------------

### Utility scripts documentation example

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

A markdown example showing how to document utility scripts, including a bash command to run analyze_form.py and its JSON output format.

```markdown
## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Output format:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Check for overlapping bounding boxes

```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```

**fill_form.py**: Apply field values to PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
```

--------------------------------

### Fresh Install Commands for Superpowers Plugin

Source: https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md

Run these commands in Claude Code to add the marketplace and install the Superpowers plugin. The plugin handles everything automatically after installation.

```bash
# In Claude Code
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```

--------------------------------

### Install Superpowers plugin for GitHub Copilot CLI

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers plugin for GitHub Copilot CLI.

```bash
copilot plugin install superpowers@superpowers-marketplace
```

--------------------------------

### Install Superpowers Skills (clone repository)

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md

Clones the superpowers skills repository into the OpenCode config directory. Requires OpenCode.ai, Node.js, and Git installed.

```bash
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
```

--------------------------------

### Install Superpowers plugin for Qwen Code

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers plugin for Qwen Code from this repository, picking 'superpowers' when prompted.

```bash
qwen extensions install obra/superpowers
```

--------------------------------

### Install Superpowers plugin for Devin CLI

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers plugin for Devin CLI from this repository.

```bash
devin plugins install obra/superpowers
```

--------------------------------

### Multi-Layer System Debugging Example (Bash)

Source: https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md

Example of diagnostic instrumentation for a multi-layer system (workflow, build script, signing script, actual signing). Reveals which layer fails by checking secrets, environment variables, keychain state, and signing.

```bash
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"

# Layer 2: Build script
echo "=== Env vars in build script: ==="
printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"

# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v

# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
```

--------------------------------

### Install Superpowers plugin from Superpowers marketplace

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers plugin for Claude Code from the Superpowers marketplace.

```bash
/plugin install superpowers@superpowers-marketplace
```

--------------------------------

### Example workflow: add workspace deletion after final review (old vs new)

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md

Two example workflow fragments showing the addition of a workspace deletion step after the final review is clean and before the 'Done!' message.

```text
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!
```

```text
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

[Delete this plan's workspace — the record now lives in git]

Done!
```

--------------------------------

### Start server with project directory and open browser

Source: https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md

Starts the visual companion server with a project directory and opens the browser. The response includes server-started JSON with port, URL, screen_dir, and state_dir. The URL contains a session key that must be preserved.

```bash
bash scripts/start-server.sh --project-dir /path/to/project --open

# Returns: {"type":"server-started","port":52341,
#           "url":"http://localhost:52341/?key=ab12…",
#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
```

--------------------------------

### Create setup helper sdd_quality_defect_plan.py

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md

Python setup helper that scaffolds a Node project with a two-task plan where Task 2 duplicates Task 1's formatting logic. The duplication is spec-compliant, so the spec compliance reviewer should pass it, but the quality reviewer should catch the DRY violation.

```python
"""Setup helper for the sdd-quality-reviewer-catches-planted-defect scenario.

Scaffolds a tiny Node project with a 2-task plan whose Task 2
implementation snippet duplicates Task 1's formatting logic verbatim.
The duplication is spec-compliant — the requirements only describe
behavior — so the spec compliance reviewer should pass it. The test
measures whether the per-task code quality reviewer catches the DRY
violation and forces a refactor in the review-fix loop.
"""

from __future__ import annotations

from pathlib import Path

from setup_helpers.base import _git

PACKAGE_JSON = """\
{
  "name": "report-quality",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
}
"""

PLAN_BODY = """\
# Report Formatter — Implementation Plan

Two report formatting functions. Implement exactly what each task
specifies.

## Task 1: User Report

**File:** `src/report.js`

**Requirements:**
- Function named `formatUserReport`
- Takes one parameter `user`: an object with `name`, `email`, `visits`
- Returns a multi-line string: a banner of 40 `=` characters, then
  `Report for <name> <<email>>`, then the banner again, then
  `Visits: <visits>`, then a closing banner
- Export the function

**Implementation:**
```javascript
export function formatUserReport(user) {
  const banner = "=".repeat(40);
  const lines = [];
  lines.push(banner);
  lines.push(`Report for ${user.name} <${user.email}>`);
  lines.push(banner);
  lines.push(`Visits: ${user.visits}`);
  lines.push(banner);
  return lines.join("\n");
}
```

**Tests:** Create `test/report.test.js` verifying:
- the result contains `Report for Ada <ada@example.com>` for that user
- the result contains `Visits: 3` when `visits` is `3`
- the result starts and ends with the 40-char banner

**Verification:** `npm test`

## Task 2: Admin Report

**File:** `src/report.js` (add to existing file)

**Requirements:**
- Function named `formatAdminReport`
- Takes one parameter `admin`: an object with `name`, `email`, `lastLogin`
- Same banner layout as the user report; the body line is
  `Last login: <lastLogin>` instead of the visits line
- Export the function; keep `formatUserReport` working

**Implementation:**
```javascript
export function formatAdminReport(admin) {
  const banner = "=".repeat(40);
  const lines = [];
  lines.push(banner);
  lines.push(`Report for ${admin.name} <${admin.email}>`);
  lines.push(banner);
  lines.push(`Last login: ${admin.lastLogin}`);
  lines.push(banner);
  return lines.join("\n");
}
```

**Tests:** Add to `test/report.test.js`:
- the result contains `Report for Grace <grace@example.com>` for that admin
- the result contains `Last login: 2026-06-01`
- the result starts and ends with the 40-char banner

**Verification:** `npm test`
"""


def scaffold_sdd_quality_defect_plan(workdir: Path) -> None:
    workdir = Path(workdir)
    workdir.mkdir(parents=True, exist_ok=True)
    _git(["git", "init", "-b", "main"], cwd=workdir)
    _git(["git", "config", "user.email", "drill@test.local"], cwd=workdir)
    _git(["git", "config", "user.name", "Drill Test"], cwd=workdir)

    (workdir / "package.json").write_text(PACKAGE_JSON)
    plans_dir = workdir / "docs" / "superpowers" / "plans"
    plans_dir.mkdir(parents=True, exist_ok=True)
    (plans_dir / "report-plan.md").write_text(PLAN_BODY)

    _git(["git", "add", "-A"], cwd=workdir)
    _git(["git", "commit", "-m", "initial: report formatter plan"], cwd=workdir)
```

--------------------------------

### Commit the porting guide changes

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md

Commits the changes to the porting guide as a separate commit. The commit message describes the update to Antigravity's rule bootstrap and removal of phantom installer references.

```bash
git add docs/porting-to-a-new-harness.md
git commit -m "docs(porting): describe Antigravity's rule bootstrap, drop phantom installer"
```

--------------------------------

### Install Superpowers as a Hermes plugin

Source: https://github.com/obra/superpowers/blob/main/README.md

Installs the Superpowers plugin for Hermes from the obra/superpowers repository and enables it. Restart any active Hermes sessions after installing; note that Hermes lacks a post-compaction hook, so a very long session that compacts over its first turn loses the bootstrap and may require starting a fresh session if skills stop triggering.

```bash
hermes plugins install obra/superpowers --enable
```

--------------------------------

### Run tests for setup-helpers

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md

Runs the test suite for setup-helpers, expecting PASS.

```bash
cd evals && bun test test/setup-helpers-sdd.test.ts test/setup-helpers-registry.test.ts
```

--------------------------------

### setup.sh for sdd-breaker-adjudicates-at-cap scenario

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md

Bash setup script that runs the helper `scaffold_sdd_midloop_parked` to prepare the scenario environment.

```bash
#!/usr/bin/env bash
set -euo pipefail
setup-helpers run scaffold_sdd_midloop_parked
```

--------------------------------

### Example error message from git init

Source: https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/root-cause-tracing.md

A sample error message showing a symptom that appears deep in the call stack, used as the starting point for tracing.

```text
Error: git init failed in ~/project/packages/core
```

--------------------------------

### Create minimal server that starts

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2026-01-17-visual-brainstorming.md

Sets up an Express server with WebSocket and chokidar. It creates the screen directory and default screen if missing, serves the screen with an injected helper script, watches for changes, and logs events to stdout.

```javascript
const express = require('express');
const http = require('http');
const WebSocket = require('ws');
const chokidar = require('chokidar');
const fs = require('fs');
const path = require('path');

const PORT = process.env.BRAINSTORM_PORT || 3333;
const SCREEN_FILE = process.env.BRAINSTORM_SCREEN || '/tmp/brainstorm/screen.html';
const SCREEN_DIR = path.dirname(SCREEN_FILE);

// Ensure screen directory exists
if (!fs.existsSync(SCREEN_DIR)) {
  fs.mkdirSync(SCREEN_DIR, { recursive: true });
}

// Create default screen if none exists
if (!fs.existsSync(SCREEN_FILE)) {
  fs.writeFileSync(SCREEN_FILE, `<!DOCTYPE html>
<html>
<head>
  <title>Brainstorm Companion</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
    h1 { color: #333; }
    p { color: #666; }
  </style>
</head>
<body>
  <h1>Brainstorm Companion</h1>
  <p>Waiting for Claude to push a screen...</p>
</body>
</html>`);
}

const app = express();
const server = http.createServer(app);
const wss = new WebSocket.Server({ server });

// Track connected browsers for reload notifications
const clients = new Set();

wss.on('connection', (ws) => {
  clients.add(ws);
  ws.on('close', () => clients.delete(ws));

  ws.on('message', (data) => {
    // User interaction event - write to stdout for Claude
    const event = JSON.parse(data.toString());
    console.log(JSON.stringify({ type: 'user-event', ...event }));
  });
});

// Serve current screen with helper.js injected
app.get('/', (req, res) => {
  let html = fs.readFileSync(SCREEN_FILE, 'utf-8');

  // Inject helper script before </body>
  const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
  const injection = `<script>\n${helperScript}\n</script>`;

  if (html.includes('</body>')) {
    html = html.replace('</body>', `${injection}\n</body>`);
  } else {
    html += injection;
  }

  res.type('html').send(html);
});

// Watch for screen file changes
chokidar.watch(SCREEN_FILE).on('change', () => {
  console.log(JSON.stringify({ type: 'screen-updated', file: SCREEN_FILE }));
  // Notify all browsers to reload
  clients.forEach(ws => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: 'reload' }));
    }
  });
});

server.listen(PORT, '127.0.0.1', () => {
  console.log(JSON.stringify({ type: 'server-started', port: PORT, url: `http://localhost:${PORT}` }));
});
```

--------------------------------

### E2E Test Subagent Prompt with Cleanup

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md

Example prompt for dispatching an E2E test subagent for an API server, including cleanup instructions to kill existing servers and verify port availability before starting, and to clean up after tests.

```markdown
Task: Run E2E test of API server

Prompt includes:
"Before starting the server:
- Kill any existing servers: pkill -f 'node.*server.js' 2>/dev/null || true
- Verify port 3001 is free: lsof -i :3001 && exit 1 || echo 'Port available'

After tests:
- Kill the server you started
- Verify: pgrep -f 'node.*server.js' || echo 'Cleanup verified'"
```

--------------------------------

### Setup script for sdd-quality-reviewer-catches-planted-defect scenario

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md

Bash script that runs the scaffold helper to create the scenario's plan. Must be made executable with chmod +x.

```bash
#!/usr/bin/env bash
set -euo pipefail
uv run setup-helpers run scaffold_sdd_quality_defect_plan

```

--------------------------------

### Replace installer-stripping bullet and add new bullet

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md

Replaces the sentences about the phantom installer example with a marker verification note, and adds a new bullet about shipping an always-on rule. The new bullet explains that Antigravity loads `rules/AGENTS.md` every session and that agy rewrites `@` paths to absolute paths without inlining.

```markdown
    **Verify with a marker** that the installer keeps the file and the
    harness loads it: a file the manifest doesn't declare can be stripped as
    unrecognized.
```

```markdown
  - **Or ship an always-on rule, if the plugin format has rules.** Antigravity
    loads `rules/AGENTS.md` from an installed plugin every session; a one-line
    `@` pointer there bootstraps `using-superpowers`. Run a marker test to
    confirm what the harness does with `@` paths in rules — agy rewrites them
    to absolute paths without inlining them.
```

--------------------------------

### Good example: Provide a default

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Shows a recommended approach with a default library and an escape hatch for OCR, including a Python import snippet.

```markdown
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
```

--------------------------------

### Run npm install for brainstorm-server

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2026-01-17-visual-brainstorming.md

Installs the dependencies defined in package.json. Expected output: dependencies installed.

```bash
cd lib/brainstorm-server && npm install
```

--------------------------------

### startServer function and conditional main

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md

Creates the screen directory, starts the HTTP server with WebSocket upgrade handling, sets up a file watcher with debouncing, and logs startup info. The conditional main runs startServer when the script is executed directly.

```javascript
function startServer() {
  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });

  const server = http.createServer(handleRequest);
  server.on('upgrade', handleUpgrade);

  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
    if (!filename || !filename.endsWith('.html')) return;
    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
    debounceTimers.set(filename, setTimeout(() => {
      debounceTimers.delete(filename);
      const filePath = path.join(SCREEN_DIR, filename);
      if (eventType === 'rename' && fs.existsSync(filePath)) {
        const eventsFile = path.join(SCREEN_DIR, '.events');
        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
      } else if (eventType === 'change') {
        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
      }
      broadcast({ type: 'reload' });
    }, 100));
  });
  watcher.on('error', (err) => console.error('fs.watch error:', err.message));

  server.listen(PORT, HOST, () => {
    const info = JSON.stringify({
      type: 'server-started', port: Number(PORT), host: HOST,
      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
      screen_dir: SCREEN_DIR
    });
    console.log(info);
    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
  });
}

if (require.main === module) {
  startServer();
}
```

--------------------------------

### Good example: one-level-deep references

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Shows a recommended structure where SKILL.md directly links to all reference files, ensuring agents read complete files.

```markdown
# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```

--------------------------------

### Install superpowers plugin with npm on Windows

Source: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md

Workaround for Windows install issues with git-backed plugin specs. Installs the plugin using system npm and points OpenCode to the local package.

```powershell
npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
```

--------------------------------

### Register the helper in __init__.py

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md

Adds the import and registry entry for the new setup helper in the evals setup_helpers package.

```python
from setup_helpers.sdd_quality_defect_plan import scaffold_sdd_quality_defect_plan
```

```python
    "scaffold_sdd_quality_defect_plan": scaffold_sdd_quality_defect_plan,
```

--------------------------------

### Install Superpowers as Pi package

Source: https://github.com/obra/superpowers/blob/main/README.md

Install Superpowers as a Pi package from this repository.

```bash
pi install git:github.com/obra/superpowers
```

--------------------------------

### Start server for Gemini CLI

Source: https://github.com/obra/superpowers/blob/main/skills/brainstorming/visual-companion.md

Use --foreground and set is_background: true on the shell tool call so the process survives across turns.

```bash
bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
```

--------------------------------

### Install Superpowers extension for Gemini CLI

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers extension for Gemini CLI.

```bash
gemini extensions install https://github.com/obra/superpowers
```

--------------------------------

### Install Superpowers plugin for Factory Droid

Source: https://github.com/obra/superpowers/blob/main/README.md

Install the Superpowers plugin for Factory Droid.

```bash
droid plugin install superpowers@superpowers
```

--------------------------------

### Verbose Skill example: Extract PDF text (too verbose)

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

A verbose SKILL.md example that over-explains PDFs and libraries, using approximately 150 tokens. It is presented as a bad example to contrast with the concise version.

```markdown
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```

--------------------------------

### setup.sh for sdd-breaker-structural-blocks scenario

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md

Bash script that runs the scaffold_sdd_midloop_structural helper to set up the scenario environment.

```bash
#!/usr/bin/env bash
set -euo pipefail
setup-helpers run scaffold_sdd_midloop_structural

```

--------------------------------

### Stage everything (Task 3 Step 5)

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md

Stages the evals/ directory and shows the first 20 lines of git status. Expected output starts with 'A  evals/...' lines listing many added files, including scenarios/, drill/, backends/, setup_helpers/, etc.

```bash
git add evals/
git status --short | head -20
```

--------------------------------

### Install Superpowers in Cursor Agent chat

Source: https://github.com/obra/superpowers/blob/main/README.md

Install Superpowers in Cursor Agent chat from the marketplace.

```text
/add-plugin superpowers
```

--------------------------------

### Start the server manually for smoke test

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md

Runs the new server.js with environment variables for the screen directory and port. Expects a 'server-started' JSON output with port 9876.

```bash
cd skills/brainstorming/scripts
BRAINSTORM_DIR=/tmp/brainstorm-smoke BRAINSTORM_PORT=9876 node server.js
```

--------------------------------

### Install Superpowers plugin for Antigravity

Source: https://github.com/obra/superpowers/blob/main/README.md

Install Superpowers as a plugin for Antigravity. Reinstall with the same command to update.

```bash
agy plugin install https://github.com/obra/superpowers
```

--------------------------------

### Install Superpowers as a Muse plugin from local checkout

Source: https://github.com/obra/superpowers/blob/main/README.md

Installs Superpowers as a native Muse plugin from a local checkout and approves the plugin. The using-superpowers bootstrap is injected via the native SessionStart hook, so no per-session opt-in is needed. Restart any active Muse sessions after installing so the hook takes effect; skills are active immediately, but hooks require approval on first install.

```bash
muse plugins install ./
muse plugins approve superpowers
```

--------------------------------

### Run help flag

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md

Command to display usage information for the render script.

```bash
bash scripts/render-antigravity-logo.sh --help
```

--------------------------------

### Basic plugin file scaffold

Source: https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md

Initial plugin file with entry point and directory setup.

```javascript
#!/usr/bin/env node

/**
 * Superpowers plugin for OpenCode.ai
 *
 * Provides custom tools for loading and discovering skills,
 * with automatic bootstrap on session start.
 */

const skillsCore = require('../../lib/skills-core');
const path = require('path');
const fs = require('fs');
const os = require('os');

const homeDir = os.homedir();
const superpowersSkillsDir = path.join(homeDir, '.config/opencode/superpowers/skills');
const personalSkillsDir = path.join(homeDir, '.config/opencode/skills');

/**
 * OpenCode plugin entry point
 */
export const SuperpowersPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Custom tools and hooks will go here
  };
};
```

--------------------------------

### Move details to tool help: bad vs good

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md

Shows the contrast between documenting all flags in SKILL.md (bad) and referencing --help (good) to save tokens.

```bash
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
```

--------------------------------

### Run SDD fixture tests

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md

Execute the test file with bun. Expected failure because the new helpers are not yet exported.

```bash
cd evals && bun test test/setup-helpers-sdd.test.ts
```

--------------------------------

### Manual smoke test: start server

Source: https://github.com/obra/superpowers/blob/main/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md

Starts the brainstorm server manually for a smoke test. The server is started with a project directory, then you write a test fragment, open it in a browser, click an option, and verify the .events file is written and the indicator bar updates.

```bash
cd /Users/drewritter/prime-rad/superpowers && lib/brainstorm-server/start-server.sh --project-dir /tmp/brainstorm-smoke-test
```

--------------------------------

### SKILL.md overview with domain links and grep commands

Source: https://github.com/obra/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Example SKILL.md for a BigQuery skill that lists available datasets with links to reference files and shows grep commands for quick metric search.

```markdown
# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
```
Tokens:
Raw