SuperPawers

Opinionated AI coding workflow skills and subagents for OpenCode. SuperPawers installs markdown-discovered agents plus a namespaced skill library for subagent-driven development with fail-fast and human-in-the-loop recovery. Fork of Superpowers. This removes some of Superpowers' "generalist"-focused implementations and narrows the context to a strict, human-in-the-loop, feature-by-feature implementation strategy. Worktrees have been replaced with branches, since branches are easier for agents to track and conceptualize. For planning, a new dedicated "planning" subagent has been added; you can configure it to a larger model to allow a small-to-medium model to orchestrate. I'm still experimenting with this approach, and the prompt modifications haven't been fully tested yet. This project exists purely to set up a skill tailored to my general workflow.

Quick Setup

npx @bubblebuffer/superpawers

If you are working from a local checkout of this repository, use the local CLI script instead of npx:

npm run cli:local -- --yes --path /path/to/project

Running npx @bubblebuffer/superpawers from inside this repository does not exercise the published npm package path and is not the supported local-development flow.

This will:

1. Detect a global OpenCode workspace in ~/.config/opencode/ or a project workspace in the current repository
2. Install markdown agents into ~/.config/opencode/agents/ or ./.opencode/agents/
3. Install skills into ~/.config/opencode/skills/superpawers/ or ./.opencode/skills/superpawers/
4. Read available model candidates from your OpenCode config and let you choose a model per agent when more than one is available

Project config is read from opencode.json or opencode.jsonc in the project root. Agent files are installed into .opencode/agents/ using OpenCode's markdown agent discovery.

Options

• --global - Use global workspace
• --local - Use local workspace (current directory)
• --path <path> - Use custom workspace path
• --yes - Skip prompts and use safe defaults (leave models unset)
• --uninstall - Remove installed files and legacy config entries

Release Verification

Before publishing a release, run:

npm test
npm run smoke:package
npm pack --dry-run

Model Selection

SuperPawers reads model candidates from the selected OpenCode config using these sources:

• provider.*.models
• top-level model
• top-level small_model
• any existing agent.*.model values

Install behavior:

• If more than one model is available, the installer prompts for a model per agent with a Leave unset option.
• If exactly one model is available, the installer asks whether to apply it.
• If no models are found, the installer warns and asks whether to install with no model: field.

Leaving model unset is valid: OpenCode will let subagents inherit the caller's model.

Example Configuration

---
description: Implements tasks following TDD with isolated context
mode: subagent
model: openai/gpt-5.1-codex
permission:
    edit: allow
    bash: allow
---

You are a SuperPawers implementer subagent.

Agent Names

| Agent | Purpose | |-------|---------| | superpawers-researcher | Codebase exploration and context gathering | | superpawers-implementer | Task implementation with TDD | | superpawers-reviewer | Spec compliance and code quality review | | superpawers-verifier | Independent test/lint/typecheck verification |

The Workflow

The canonical order for any new feature or change:

| # | Skill | Trigger | Input | Output | Next skill | |---|-------|---------|-------|--------|------------| | 1 | brainstorming | New feature, behavior change, or unclear request | User intent | Approved design (discussed, not yet committed) | using-git-branches | | 2 | using-git-branches | Design approved, about to produce tracked artifacts | Approved design | Isolated feature branch, clean baseline | writing-plans | | 3 | writing-plans | On a feature branch with an approved design | Design doc | Bite-sized implementation plan | subagent-driven-development | | 4 | subagent-driven-development | Plan approved, ready to execute | Plan file | Implemented, reviewed, verified work | finishing-a-development-branch | | 5 | finishing-a-development-branch | All tasks complete and verified | Feature branch with passing work | Merge, PR, kept branch, or discarded branch | — |

Supporting skills activate inside this flow:

| Skill | Role | |-------|------| | test-driven-development | Discipline enforced by implementer subagents during step 4 | | verification-before-completion | Gate applied before any completion claim, commit, or handoff | | systematic-debugging | Entry point when a bug, failure, or regression interrupts the flow | | root-cause-tracing | Trace bugs backward through call stack to find the original trigger | | defense-in-depth | Add validation at every layer after fixing a bug | | condition-based-waiting | Replace arbitrary timeouts with condition polling for flaky tests | | requesting-code-review | Ad-hoc or milestone review outside the automated two-stage review | | receiving-code-review | Handling incoming human or external review feedback | | dispatching-parallel-agents | Parallel research or investigation across independent domains | | using-superpawers | Router for picking the right entry skill for a new request | | writing-skills | Authoring standard for adding or editing skills |

License

MIT