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"]
}

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 |

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.

Subagent Dispatch

Skills that reference subagent dispatch (subagent-driven-development, requesting-code-review, dispatching-parallel-agents) work with any dispatch mechanism:

• With pi-superteam: The agent uses the team tool automatically
• Without pi-superteam: Run pi -p "prompt" in another terminal, or use tmux panes for parallel tasks

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.