main 060ace4

An agentic skills framework & software development methodology that works.

Softpowers

Softpowers is a human-led software development workflow for coding agents. It uses LLMs for exploration, specifications, planning, research, review, and verification, while keeping implementation close to the developer by default.

Softpowers is a fork of Superpowers. The goal is to stay technically compatible with upstream where practical while taking a different product stance: agents should help humans think and ship better software, not silently become the default implementer.

How it works

It starts from the moment you fire up your coding agent. When a task is tiny or clearly scoped, it can just handle it directly. When the task looks bigger, riskier, or fuzzier, it can slow down and ask whether you want direct execution, light guidance, or the full Softpowers flow.

If you choose the full flow, the agent helps tease a spec out of the conversation, then shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent helps put together an implementation plan with clear phases, concrete verification steps, and enough context for a developer to execute without guessing. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), DRY, and maintaining the developer's mental model of the code.

Next up, the recommended path is Softassist: you stay the primary implementer while the agent guides one step at a time, fetches documentation, reviews diffs, runs verification, and takes on agreed mechanical chores when useful. Fully delegated implementation is still available, but it is an explicit choice rather than the default.

There's a bunch more to it, but that's the core of the system. The heavy workflows are available when you want them, instead of being forced onto every tiny request.

Why Softpowers?

LLMs are excellent collaborators for exploring ideas, surfacing trade-offs, drafting specifications, decomposing plans, finding documentation, reviewing changes, and running verification loops.

But implementation is not just typing. Writing, debugging, and refactoring code are how developers build and maintain their mental model of a system. If agents silently take over that work by default, the developer can lose the very cognitive skill needed to supervise those agents well.

Softpowers keeps the human in the implementation loop by default. The agent helps you think, plan, verify, and review. It can also take on boring or mechanical work when explicitly delegated. But the default workflow is human-led, not agent-led.

Use the ship's computer, not an autopilot you no longer understand.

About this fork

This fork carries bnema-specific experiments on top of obra/superpowers and is being repositioned as Softpowers. Use upstream/obra for the canonical Superpowers project and origin/bnema for these custom changes.

Notable differences in this fork:

  • OpenCode and Pi install/update docs point at github.com/bnema/softpowers.
  • Pi support is experimental, including .pi/agents/ setup for subagent-based workflows.
  • Heavy workflows are opt-in: small or clearly scoped tasks can stay in direct execution.
  • Plan execution recommends softassist, where the human stays the primary implementer and the agent provides guidance, research, review, verification, and explicitly delegated mechanical help.
  • Fully delegated implementation remains available for cases where the human deliberately wants the agent to implement phases or sub-tasks.
  • Both specs and implementation plans use Simple Markdown by default. The workflow creates Enriched HTML only when the user explicitly requests an HTML document, without asking for a format choice:
    • brainstorming produces spec documents.
    • writing-plans produces implementation playbooks with phases, tasks, and concrete verification steps.
    • softassist reads the approved spec and plan, then guides step-by-step.
    • Document storage resolves paths as follows:
      • When PROJECTS_DOCS_PATH is set, files go under $PROJECTS_DOCS_PATH/{repoName}/plans or $PROJECTS_DOCS_PATH/{repoName}/specs.
      • Otherwise, docs/softpowers/ in the repo is used.
      • Resolve the env variable explicitly with printenv PROJECTS_DOCS_PATH.
      • Derive {repoName} from the git top-level directory basename when possible.
      • Do not create a second repo-local copy when the resolved docs path lives outside the project repo.
  • Markdown-first doc authoring now has helper flows. Start from unique temp drafts such as SPEC_DRAFT="$(mktemp /tmp/softpowers-spec-XXXXXX.md)" and PLAN_DRAFT="$(mktemp /tmp/softpowers-plan-XXXXXX.md)" so concurrent agents do not collide. These helpers live in the Softpowers package, not in the target repo, so resolve SOFTPOWERS_ROOT to the installed package root. For Simple Markdown, copy the approved draft to the final .md path. For Enriched HTML, invoke helpers with absolute paths like node "$SOFTPOWERS_ROOT/scripts/create-spec-doc.mjs" ... and node "$SOFTPOWERS_ROOT/scripts/create-plan-doc.mjs" ... rather than node scripts/... from the project being designed. Before final output, those drafts go through the self-review and reviewer-subagent approval gates described in skills/brainstorming/ and skills/writing-plans/. Only after approval should the agent run node "$SOFTPOWERS_ROOT/scripts/create-spec-doc.mjs" --title "..." --slug ... --body "$SPEC_DRAFT" for enriched specs or node "$SOFTPOWERS_ROOT/scripts/create-plan-doc.mjs" --title "..." --slug ... --spec <spec-path> --body "$PLAN_DRAFT" for enriched plans, then re-check generated HTML with node "$SOFTPOWERS_ROOT/scripts/validate-spec-doc.mjs" <spec-path> and node "$SOFTPOWERS_ROOT/scripts/validate-plan-doc.mjs" <plan-path>. See examples/html-docs/canonical-spec.md and docs/softpowers/specs/2026-05-13-canonical-html-spec-workflow-design.html for the canonical enriched spec example.
  • The fast Claude Code skill test runner skips test-subagent-driven-development.sh in this fork because it requires a working Claude Code org/session in headless mode.

These changes are fork-specific unless and until they are merged upstream.

Installation

Note: Installation differs by platform. Softpowers currently prioritizes local fork compatibility rather than a separate marketplace mirror. Where a marketplace only offers upstream Superpowers, use the local/manual install path for this fork.

Codex CLI / Codex App

For this fork, install Softpowers as a local Codex plugin through a local marketplace rather than using an upstream marketplace listing:

Fetch and follow instructions from https://raw.githubusercontent.com/bnema/softpowers/refs/heads/main/.codex/INSTALL.md

Detailed docs: docs/README.codex.md

OpenCode

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/bnema/softpowers/refs/heads/main/.opencode/INSTALL.md

Detailed docs: docs/README.opencode.md

Gemini CLI

gemini extensions install https://github.com/bnema/softpowers

To update:

gemini extensions update softpowers

Pi (experimental)

pi install https://github.com/bnema/softpowers

Pi discovers skills from the skills/ directory automatically. No plugins or bootstrap required for skills. For subagent-based workflows, install the bundled Pi agent profile from .pi/agents/ (see docs).

Detailed docs: docs/README.pi.md

Verify Installation

Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant Softpowers skill.

The Basic Workflow

  1. workflow selection - For gray-area tasks, the agent offers a choice: direct execution, light guidance, or the full Softpowers flow.

  2. brainstorming / co-design - Activates when you choose the full design-first flow. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves a Simple Markdown spec by default; use Enriched HTML only when explicitly requested.

  3. using-git-worktrees - Activates after design approval when implementation needs an isolated workspace. Creates or verifies an isolated workspace, runs project setup, verifies clean test baseline.

  4. writing-plans / co-planning - Activates with approved design. Saves a Simple Markdown implementation playbook by default; use Enriched HTML only when explicitly requested.

  5. softassist - Recommended after planning. The human remains the primary implementer. The agent reads the approved plan, proposes an ownership split, guides one step at a time, fetches docs, runs verification, and handles agreed mechanical chores when explicitly delegated. One final implementation review runs after the work is verified.

  6. delegated implementation - Optional and explicit. If the human wants the agent to implement, the workflow can use subagent-driven-development or executing-plans with green verification after each step and one final implementation review. This is available, but not the default Softpowers path.

  7. test-driven-development - Activates during structured implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.

  8. requesting-code-review - Activates once after implementation and final verification. Reviews the complete change by severity before completion or merge.

  9. finishing-a-development-branch - Activates when phases complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

The agent should consider relevant skills before any task. Lightweight skills can trigger automatically; heavyweight workflows should be offered or explicitly chosen, not forced onto every request.

What's Inside

Skills Library

Testing

  • test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

  • systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
  • verification-before-completion - Ensure it's actually fixed

Collaboration

  • brainstorming - Socratic co-design and design refinement; saves Markdown specs by default and reusable HTML specs on request
  • writing-plans - Detailed co-planning for human-led or delegated implementation; produces Markdown plans by default or HTML playbooks with phase/task/step navigation on request
  • softassist - Human-led implementation with agent guidance, verification, research, and one final implementation review
  • executing-plans - Delegated inline phase execution with verification checkpoints
  • dispatching-parallel-agents - Concurrent subagent workflows
  • requesting-code-review - One final implementation review
  • receiving-code-review - Responding to feedback
  • using-git-worktrees - Parallel development branches
  • finishing-a-development-branch - Merge/PR decision workflow
  • subagent-driven-development - Optional delegated implementation with green verification after each step and one final implementation review

Meta

  • writing-skills - Create new skills following best practices (includes testing methodology)
  • using-softpowers - Introduction to the skills system

Philosophy

  • Human-led implementation by default - The developer stays close to the code and keeps ownership of the system's mental model
  • LLMs as thinking tools - Use agents for exploration, specs, plans, research, review, and verification before using them as implementers
  • Negotiated delegation - Let agents handle boring or mechanical work when explicitly agreed, not by silent takeover
  • Test-Driven Development - Write tests first, always
  • Systematic over ad-hoc - Process over guessing
  • Complexity reduction - Simplicity as primary goal
  • Evidence over claims - Verify before declaring success

Softpowers intentionally diverges from upstream Superpowers in its default implementation stance while preserving the same discipline around tests, reviews, and verification.

Contributing

Skills live directly in this repository. To contribute:

  1. Fork the repository
  2. Create a branch for your skill
  3. Follow the writing-skills skill for creating and testing new skills
  4. Submit a PR

See skills/writing-skills/SKILL.md for the complete guide.

Updating

Skills update automatically when you update the plugin:

/plugin update softpowers

License

MIT License - see LICENSE file for details

Community

Softpowers is maintained as a human-led fork of upstream Superpowers.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 33

↑↓ moveenter openesc close