Status: Proposed (follow-up to the 2026-06-09 SDD review-dispatch work; separate PR per the one-problem-per-PR rule) Driver: Measured evidence (2026-06-10) that some negative instructions in skill prose backfire, while others work — and that the difference is predictable. Micro-tests on 2026-06-10 (opus, 5 reps per phrasing, programmatic scoring; harness described below) measured how guidance phrasing changes what a controller composes: |---|---|---| The doctrine (use this to
--- name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code --- Write the test first. Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
Goal: Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries. Architecture: Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped sessionStorage, and navigates to a bare / screen URL.
Goal: Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad. skills/requesting-code-review/ is deliberately untouched.
Date: 2026-02-19 Status: Approved Scope: lib/brainstorm-server/, skills/brainstorming/visual-companion.md, tests/brainstorm-server/ During visual brainstorming, Claude runs wait-for-feedback.sh as a background task and blocks on TaskOutput(block=true, timeout=600s). This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running.
Goal: Finish PR #1720's final hardening fixup with test-first changes, clean rebase state, and reviewer-ready evidence. Spec: docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md Architecture: Keep the companion zero-dependency and local-first.
Browser-based visual brainstorming companion for showing mockups, diagrams, and options. The test: would the user understand this better by seeing it than reading it?
Make superpowers skills work in the Codex App's sandboxed worktree environment without breaking existing Claude Code or Codex CLI behavior. Ticket: PRI-823 The Codex App runs agents inside git worktrees it manages — detached HEAD, located under $CODEXHOME/worktrees/, with a Seatbelt sandbox that blocks git checkout -b, git push, and network access.
Date: 2026-06-11 Status: Draft for Drew review Finish the PR #1720 visual companion hardening pass so the branch is ready for Jesse review with clean security behavior, deterministic tests, and a PR diff that contains only the companion work. This is a fixup on top of the existing auth hardening design.
Status: Proposed experiment ladder (not implementation). Each rung ships only with its gate evidence; abort any rung whose gates fail.
with maintainer sign-off after the RED baseline did not reproduce blind stale-ledger adoption. 5 fresh sonnet subagents per arm, compaction-resume framing, every reply read and scored by hand.
Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them. Give your agent Superpowers: Claude Code, Antigravity, Codex App, Codex CLI, Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode, Pi.
Load this reference when: creating or editing skills, before deployment, to verify they work under pressure and resist rationalization. Testing skills is just TDD applied to process documentation.
Goal: Add full superpowers support for OpenCode.ai with a native JavaScript plugin that shares core functionality with the existing Codex implementation. Architecture: Extract common skill discovery/parsing logic into lib/skills-core.js, refactor Codex to use it, then build OpenCode plugin using their native plugin API with custom tools and session hooks.
Goal: Make superpowers defer to native harness worktree systems when available, fall back to manual git worktrees when not, and fix three known finishing bugs. Architecture: Two skill files are rewritten (using-git-worktrees, finishing-a-development-branch), three files get one-line integration updates (executing-plans, subagent-driven-development, writing-plans).
Make subagent-driven-development's per-task reviews cheaper and faster without weakening them, by scoping per-task review prompts to the task and stopping redundant work — while final branch review stays broad. Per-task code quality reviewers in SDD routinely do branch-review-scale work on single-task diffs.
--- name: subagent-driven-development description: Use when executing implementation plans with independent tasks in the current session --- Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end. Why subagents: You delegate tasks to specialized agents with isolated context.
Date: 2026-04-06 Status: Draft Ticket: PRI-974 Subsumes: PRI-823 (Codex App compatibility) Superpowers is opinionated about worktree management — specific paths (.worktrees/ ), specific commands (git worktree add), specific cleanup (git worktree remove). Meanwhile, Claude Code, Codex App, Gemini CLI, and Cursor all provide native worktree support with their own paths, lifecycle management, and cleanup.
We are implementing these ourselves; the referenced community PRs are evidence and reference material, not code we intend to merge. A single place that captures every open issue and PR touching the visual brainstorming companion (the local server in skills/brainstorming/scripts/), distilled to the underlying problem and the change we'd make.
--- name: writing-skills description: Use when creating new skills, editing existing skills, or verifying skills work before deployment --- Writing skills IS Test-Driven Development applied to process documentation. Personal skills live in your runtime's skills directory (~/.claude/skills/ on Claude Code) — see codex-tools.md or gemini-tools.md for the path on those runtimes.
Status: Proposed (follow-up to the 2026-06-09 SDD review-dispatch work; separate PR per the one-problem-per-PR rule) Driver: Measured evidence (2026-06-10) that some negative instructions in skill prose backfire, while others work — and that the difference is predictable. Micro-tests on 2026-06-10 (opus, 5 reps per phrasing, programmatic scoring; harness described below) measured how guidance phrasing changes what a controller composes: |---|---|---| The doctrine (use this to
--- name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code --- Write the test first. Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
Goal: Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries. Architecture: Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped sessionStorage, and navigates to a bare / screen URL.
Goal: Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad. skills/requesting-code-review/ is deliberately untouched.
Date: 2026-02-19 Status: Approved Scope: lib/brainstorm-server/, skills/brainstorming/visual-companion.md, tests/brainstorm-server/ During visual brainstorming, Claude runs wait-for-feedback.sh as a background task and blocks on TaskOutput(block=true, timeout=600s). This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running.
Goal: Finish PR #1720's final hardening fixup with test-first changes, clean rebase state, and reviewer-ready evidence. Spec: docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md Architecture: Keep the companion zero-dependency and local-first.
Browser-based visual brainstorming companion for showing mockups, diagrams, and options. The test: would the user understand this better by seeing it than reading it?
Make superpowers skills work in the Codex App's sandboxed worktree environment without breaking existing Claude Code or Codex CLI behavior. Ticket: PRI-823 The Codex App runs agents inside git worktrees it manages — detached HEAD, located under $CODEXHOME/worktrees/, with a Seatbelt sandbox that blocks git checkout -b, git push, and network access.
Date: 2026-06-11 Status: Draft for Drew review Finish the PR #1720 visual companion hardening pass so the branch is ready for Jesse review with clean security behavior, deterministic tests, and a PR diff that contains only the companion work. This is a fixup on top of the existing auth hardening design.
Status: Proposed experiment ladder (not implementation). Each rung ships only with its gate evidence; abort any rung whose gates fail.
with maintainer sign-off after the RED baseline did not reproduce blind stale-ledger adoption. 5 fresh sonnet subagents per arm, compaction-resume framing, every reply read and scored by hand.
Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them. Give your agent Superpowers: Claude Code, Antigravity, Codex App, Codex CLI, Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode, Pi.
Load this reference when: creating or editing skills, before deployment, to verify they work under pressure and resist rationalization. Testing skills is just TDD applied to process documentation.
Goal: Add full superpowers support for OpenCode.ai with a native JavaScript plugin that shares core functionality with the existing Codex implementation. Architecture: Extract common skill discovery/parsing logic into lib/skills-core.js, refactor Codex to use it, then build OpenCode plugin using their native plugin API with custom tools and session hooks.
Goal: Make superpowers defer to native harness worktree systems when available, fall back to manual git worktrees when not, and fix three known finishing bugs. Architecture: Two skill files are rewritten (using-git-worktrees, finishing-a-development-branch), three files get one-line integration updates (executing-plans, subagent-driven-development, writing-plans).
Make subagent-driven-development's per-task reviews cheaper and faster without weakening them, by scoping per-task review prompts to the task and stopping redundant work — while final branch review stays broad. Per-task code quality reviewers in SDD routinely do branch-review-scale work on single-task diffs.
--- name: subagent-driven-development description: Use when executing implementation plans with independent tasks in the current session --- Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end. Why subagents: You delegate tasks to specialized agents with isolated context.
Date: 2026-04-06 Status: Draft Ticket: PRI-974 Subsumes: PRI-823 (Codex App compatibility) Superpowers is opinionated about worktree management — specific paths (.worktrees/ ), specific commands (git worktree add), specific cleanup (git worktree remove). Meanwhile, Claude Code, Codex App, Gemini CLI, and Cursor all provide native worktree support with their own paths, lifecycle management, and cleanup.
We are implementing these ourselves; the referenced community PRs are evidence and reference material, not code we intend to merge. A single place that captures every open issue and PR touching the visual brainstorming companion (the local server in skills/brainstorming/scripts/), distilled to the underlying problem and the change we'd make.
--- name: writing-skills description: Use when creating new skills, editing existing skills, or verifying skills work before deployment --- Writing skills IS Test-Driven Development applied to process documentation. Personal skills live in your runtime's skills directory (~/.claude/skills/ on Claude Code) — see codex-tools.md or gemini-tools.md for the path on those runtimes.