pi-superpowers

Structured workflow skills for pi, adapted from Superpowers by Jesse Vincent.

Brainstorming → Planning → TDD → Debugging → Code Review → Finishing — as composable skills your coding agent loads on demand.

Install

pi install git:github.com/coctostan/pi-superpowers

Or add to .pi/settings.json (project-level) or ~/.pi/agent/settings.json (global):

{
  "packages": ["git:github.com/coctostan/pi-superpowers"]
}

Optional: Subagent Tool

Several skills can dispatch work to subagents (marked with 🤖 below). pi-superpowers does not include a subagent tool. These skills still work as process guides without one — you just run tasks manually instead of dispatching them.

To enable automated dispatch, install a subagent extension:

• pi's example subagent extension — Ships with pi at examples/extensions/subagent/. See its README for installation via symlinks into ~/.pi/agent/extensions/subagent/.
• Any compatible subagent extension — Any extension that provides a subagent tool works.
• Manual alternative — Run pi -p "prompt" in another terminal, or use tmux panes for parallel tasks.

What's Inside

Skills

Skill	Description	Invoke
brainstorming	Socratic design refinement — questions, alternatives, incremental validation	/skill:brainstorming
writing-plans	Detailed implementation plans with bite-sized TDD tasks	/skill:writing-plans
executing-plans	Batch execution with checkpoints for architect review	/skill:executing-plans
🤖 subagent-driven-development	Fresh subagent per task with two-stage review	/skill:subagent-driven-development
test-driven-development	RED-GREEN-REFACTOR cycle (includes anti-patterns reference)	/skill:test-driven-development
systematic-debugging	4-phase root cause investigation	/skill:systematic-debugging
verification-before-completion	Evidence before claims, always	/skill:verification-before-completion
🤖 requesting-code-review	Pre-merge review with severity categories	/skill:requesting-code-review
receiving-code-review	Technical evaluation of review feedback	/skill:receiving-code-review
🤖 dispatching-parallel-agents	Concurrent subagent workflows	/skill:dispatching-parallel-agents
using-git-worktrees	Isolated development branches	/skill:using-git-worktrees
finishing-a-development-branch	Merge/PR decision workflow	/skill:finishing-a-development-branch
🤖 writing-skills	TDD applied to process documentation — create, test, and bulletproof skills	/skill:writing-skills

Plan Tracker

The plan_tracker tool replaces file-based task tracking. It stores state in the session and shows progress in the TUI:

Tasks: ✓✓→○○ (2/5)  Task 3: Recovery modes

Usage by the agent:

plan_tracker({ action: "init", tasks: ["Task 1: Setup", "Task 2: Core", ...] })
plan_tracker({ action: "update", index: 0, status: "complete" })
plan_tracker({ action: "status" })
plan_tracker({ action: "clear" })

The Workflow

1. Brainstorm — /skill:brainstorming refines your idea into a design document
2. Isolate — /skill:using-git-worktrees creates a clean workspace
3. Plan — /skill:writing-plans breaks work into bite-sized TDD tasks
4. Execute — /skill:executing-plans or /skill:subagent-driven-development works through the plan
5. Verify — /skill:verification-before-completion proves it works
6. Review — /skill:requesting-code-review catches issues
7. Finish — /skill:finishing-a-development-branch merges or creates a PR

Each skill cross-references related skills so the agent knows what to use next.

Development

Testing

Tests use vitest and live in tests/:

tests/
├── extension/
│   └── plan-tracker.test.ts   # Unit tests for plan-tracker core logic
└── skills/
    └── skill-validation.test.ts  # Validates all skills: frontmatter, cross-refs, file refs

Run the full suite:

npm test

Run in watch mode during development:

npm run test:watch

Skill validation tests check that every skill in skills/ has:

• A valid SKILL.md with YAML frontmatter (name, description)
• Name matching directory name, lowercase with hyphens, ≤ 64 chars
• All /skill:name cross-references pointing to existing skills
• All referenced .md, .sh, .ts files existing on disk
• Correct wiring in package.json (pi.skills, pi.extensions)

Extension tests cover the plan-tracker core: init, update, status, clear, formatting, widget data, and state reconstruction from conversation branches.

Attribution

Skill content adapted from Superpowers by Jesse Vincent, licensed under MIT.

License

MIT — see LICENSE for details.