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 Markdownby default. The workflow createsEnriched HTMLonly when the user explicitly requests an HTML document, without asking for a format choice:brainstormingproduces spec documents.writing-plansproduces implementation playbooks with phases, tasks, and concrete verification steps.softassistreads the approved spec and plan, then guides step-by-step.- Document storage resolves paths as follows:
- When
PROJECTS_DOCS_PATHis set, files go under$PROJECTS_DOCS_PATH/{repoName}/plansor$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.
- When
- Markdown-first doc authoring now has helper flows. Start from unique temp drafts such as
SPEC_DRAFT="$(mktemp /tmp/softpowers-spec-XXXXXX.md)"andPLAN_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 resolveSOFTPOWERS_ROOTto the installed package root. ForSimple Markdown, copy the approved draft to the final.mdpath. ForEnriched HTML, invoke helpers with absolute paths likenode "$SOFTPOWERS_ROOT/scripts/create-spec-doc.mjs" ...andnode "$SOFTPOWERS_ROOT/scripts/create-plan-doc.mjs" ...rather thannode scripts/...from the project being designed. Before final output, those drafts go through the self-review and reviewer-subagent approval gates described inskills/brainstorming/andskills/writing-plans/. Only after approval should the agent runnode "$SOFTPOWERS_ROOT/scripts/create-spec-doc.mjs" --title "..." --slug ... --body "$SPEC_DRAFT"for enriched specs ornode "$SOFTPOWERS_ROOT/scripts/create-plan-doc.mjs" --title "..." --slug ... --spec <spec-path> --body "$PLAN_DRAFT"for enriched plans, then re-check generated HTML withnode "$SOFTPOWERS_ROOT/scripts/validate-spec-doc.mjs" <spec-path>andnode "$SOFTPOWERS_ROOT/scripts/validate-plan-doc.mjs" <plan-path>. Seeexamples/html-docs/canonical-spec.mdanddocs/softpowers/specs/2026-05-13-canonical-html-spec-workflow-design.htmlfor the canonical enriched spec example. - The fast Claude Code skill test runner skips
test-subagent-driven-development.shin 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
-
workflow selection - For gray-area tasks, the agent offers a choice: direct execution, light guidance, or the full Softpowers flow.
-
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.
-
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.
-
writing-plans / co-planning - Activates with approved design. Saves a Simple Markdown implementation playbook by default; use Enriched HTML only when explicitly requested.
-
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.
-
delegated implementation - Optional and explicit. If the human wants the agent to implement, the workflow can use
subagent-driven-developmentorexecuting-planswith green verification after each step and one final implementation review. This is available, but not the default Softpowers path. -
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.
-
requesting-code-review - Activates once after implementation and final verification. Reviews the complete change by severity before completion or merge.
-
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:
- Fork the repository
- Create a branch for your skill
- Follow the
writing-skillsskill for creating and testing new skills - 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.
- Issues: https://github.com/bnema/softpowers/issues
- Upstream project: https://github.com/obra/superpowers