pi-superpowers

中文版

A Pi platform port of the Superpowers workflow skill library, with Chinese trigger support

pi-superpowers ports 14 professional workflow skills from obra/superpowers to the Pi programming assistant platform, adding:

• 🇨🇳 Chinese trigger words: Every skill supports bilingual (Chinese/English) triggers — Chinese queries automatically match the corresponding skill
• 🔌 Bootstrap extension: Skill usage rules are automatically injected into context at the start of every session
• 🔧 Tool mapping: Automatically maps original Claude Code tools (Skill, TodoWrite, Task) to Pi equivalents
• 🤖 dispatch_agent tool: Simulates Claude Code's Task sub-agent with context isolation via pi --no-session --print subprocess
• ⚡ Prompt templates: 3 slash commands (/brainstorm, etc.)

---

Table of Contents

• Skill Overview
• Typical Workflows
• Prompt Template Commands
• Tool Mapping Reference
• dispatch_agent Tool
• Bootstrap Injection Mechanism
• Known Limitations
• Installation

---

Skill Overview

After installation, 14 skills are available. Skill descriptions include both Chinese and English keywords — Pi automatically loads the matching skill when a relevant request is received.

You can also force-load any skill with the /skill:<name> command.

Development Workflow Skills

Skill	Trigger Scenario	Chinese Keyword Examples
brainstorming	Requirements analysis and design before implementing a new feature/component	头脑风暴、做一个新功能、从哪里开始、需求分析
writing-plans	Breaking down requirements into fine-grained implementation steps	写计划、制定开发计划、拆分任务、做规划
subagent-driven-development	Executing multiple independent tasks according to an implementation plan	执行计划、开始实现、逐任务执行
executing-plans	Batch-executing an existing written plan	按计划实现、批次执行任务
test-driven-development	Before implementing any feature or fixing a bug	TDD、测试驱动开发、先写测试、测试优先
using-git-worktrees	When isolation from the current workspace is needed	git worktree、隔离开发、新分支开发
dispatching-parallel-agents	Facing 2+ independent tasks that can run in parallel	并行处理、多任务并发、同时修复多个问题
verification-before-completion	Just before declaring a task complete	验证完成、声明完成前、提交前验证

Quality Assurance Skills

Skill	Trigger Scenario	Chinese Keyword Examples
systematic-debugging	Encountering a bug, test failure, or unexpected behavior	调试、找 bug、修复问题、测试失败、根本原因分析
requesting-code-review	Code review before completing a task or merging	代码审查、code review、审查代码、提交前审查
receiving-code-review	Handling review feedback after receiving it	处理审查意见、回应评审、技术反驳
finishing-a-development-branch	Implementation complete, tests passing, ready to integrate	完成分支、提 PR、合并代码、结束开发

Meta Skills

Skill	Trigger Scenario	Chinese Keyword Examples
using-superpowers	At the start of every conversation (auto-injected by the Bootstrap extension)	Auto-triggered, no manual action needed
writing-skills	Creating or modifying skill files	写 skill、创建新技能、设计工作流技能

---

Typical Workflows

1. Full Feature Development Flow

You:  Help me build a user permissions management module
       └→ AI auto-loads brainstorming skill, begins requirements analysis
          ↓ Explores requirements, proposes multiple approaches, awaits confirmation
You:  OK, let's go with that approach
       └→ AI auto-loads writing-plans skill, breaks down implementation steps
          ↓ Generates a plan with 2–5 minute granularity per step
You:  Start implementing
       └→ AI auto-loads subagent-driven-development / executing-plans skill
          ↓ Implements task by task in TDD cycles (tests first, then implement, review, then continue)
You:  Everything is done
       └→ AI auto-loads verification-before-completion skill, runs verification commands
          ↓ After confirmation, loads finishing-a-development-branch to decide merge strategy

2. Bug Debugging Flow

You:  Tests are failing — TypeError: Cannot read property 'id' of undefined
       └→ AI auto-loads systematic-debugging skill
          ↓ Systematic root-cause analysis: confirm symptoms → isolate scope → find minimal repro → fix
          ↓ Must write a failing test that reproduces the bug before applying the fix (TDD)

3. Force-Loading with Slash Commands

When auto-triggering is unreliable, use /skill: commands to force-load a skill:

/skill:brainstorming               # Force requirements analysis
/skill:test-driven-development     # Force TDD mode
/skill:systematic-debugging        # Force systematic debugging
/skill:verification-before-completion  # Force completion verification

4. Chinese Conversation Examples

What you say	Skill auto-triggered
"帮我做一个登录功能"	brainstorming (pre-feature analysis)
"这个测试一直失败，帮我看看"	systematic-debugging
"用测试驱动开发这个接口"	test-driven-development
"代码写完了，帮我 review 一下"	requesting-code-review
"我要提交 PR 了"	verification-before-completion → finishing-a-development-branch
"有三个不相关的 bug 要修"	dispatching-parallel-agents

---

Prompt Template Commands

Prompt templates are triggered with a / prefix and enforce the full workflow of the corresponding skill:

Command	Description
/brainstorm	Start requirements analysis and design; AI is blocked from writing code before confirmation
/write-plan	Break a confirmed approach into fine-grained implementation steps
/execute-plan	Batch-execute an existing plan, reporting after each batch and waiting for feedback

Usage example:

/brainstorm I want to build a real-time chat room
/write-plan
/execute-plan

---

Tool Mapping Reference

Pi tool names differ from Claude Code's originals. The Bootstrap extension injects the following mapping into the system prompt, and the AI will automatically use Pi-equivalent tools:

Original Claude Code Tool	Pi Equivalent
Skill tool	Use read to load skills/<name>/SKILL.md, or use the /skill:<name> command
TodoWrite	Use write/edit to manage TODO.md at the project root (Markdown checkbox format)
Task (sub-agent dispatch)	Option A (fallback) Sequential mode: implement tasks one by one in the current conversation with role-switching for review; Option B (recommended) dispatch_agent tool: true context isolation via pi --no-session --print subprocess (see below)
Read	read (same name, use directly)
Write	write (same name, use directly)
Edit	edit (same name, use directly)
Bash	bash (same name, use directly)

Sub-agent Execution Modes

The original superpowers subagent-driven-development skill relies on the Task tool to dispatch independent sub-agents. pi-superpowers provides two alternatives:

Option A: Sequential Fallback Mode (no extra tooling required)

Execute tasks sequentially in the current conversation, simulating multiple perspectives through role-switching:

1. Implementer role:       Implement task → write tests → self-review → commit
2. Spec Reviewer role:     Independently verify with read tool, do not trust implementer's report
3. Code Quality Reviewer:  Review code quality (only after Spec review passes)
4. Fix issues → re-review → proceed to next task after passing

Task status is tracked in a TODO.md file:

- [x] Task 1: Implement user model
- [ ] Task 2: Implement auth middleware
- [ ] Task 3: Implement login endpoint

---

dispatch_agent Tool

Option B: dispatch_agent Tool (recommended, requires pi in PATH)

dispatch_agent is a custom tool registered by pi-superpowers (extensions/subagent.ts). It achieves true context isolation by launching a pi --no-session --print subprocess, matching the behavior of Claude Code's Task tool.

LLM call example:

dispatch_agent({
  task: "Implement user auth middleware: 1) validate JWT 2) handle expiration 3) write unit tests",
  role: "implementer"
})

Supported roles (role parameter):

Role	Description
implementer	Implements the task, writes tests, self-reviews
spec-reviewer	Independently verifies the implementation against the spec (critical perspective)
code-quality-reviewer	Reviews code quality; runs only after Spec review passes
(omitted)	General-purpose sub-agent with no role restriction

Underlying implementation:

# When role = "implementer", equivalent to:
pi --no-session --print \
   --append-system-prompt "You are a implementer." \
   "Implement user auth middleware: ..."

Prerequisite: The pi binary must be accessible in $PATH. If not found, the tool returns a clear error message rather than crashing.

---

Bootstrap Injection Mechanism

Problem: The original superpowers uses Claude Code's SessionStart hook to auto-inject using-superpowers content at the beginning of every session. Pi does not have this hook.

Solution: pi-superpowers provides two Pi extensions:

Extension File	Purpose
extensions/bootstrap.ts	Injects using-superpowers rules into the system prompt before the first message of each session
extensions/subagent.ts	Registers the dispatch_agent tool as a replacement for Claude Code's Task sub-agent

bootstrap.ts injection flow:

User sends first message
      ↓
before_agent_start fires
      ↓
Is this the first user turn of this session?
  YES → Read using-superpowers/SKILL.md
      → Assemble <EXTREMELY_IMPORTANT> injection block
      → Append to systemPrompt
      → Mark session as injected (prevents re-injection on subsequent turns)
  NO  → Skip injection
      ↓
AI follows using-superpowers rules in this response

Injected content includes:

• Full using-superpowers skill text (skill usage rules, priority, red flags checklist)
• Pi platform tool mapping table (alternatives for Skill/TodoWrite/Task)

---

Known Limitations

Limitation	Impact	Mitigation
No built-in sub-agents (Task tool unavailable)	subagent-driven-development cannot truly run in parallel	Resolved via dispatch_agent tool: extensions/subagent.ts achieves context isolation through pi --no-session --print subprocess; fallback: sequential execution mode
No TodoWrite tool	Task progress cannot be shown in native UI	Track with TODO.md file — functionally equivalent
before_agent_start fires on every turn	Need to detect whether injection has already occurred	Bootstrap extension uses session ID + turn count for double detection
Flowcharts in using-superpowers require Graphviz	Dot syntax code blocks cannot render in Pi TUI	Diagrams still serve as text-based logic references; no functional impact

---

Installation

Option 1: npm Install (Recommended)

# Global install (available to all projects)
pi install npm:@weiping/pi-superpowers

# Project-level install (current project only, can be committed and shared with the team)
pi install -l npm:@weiping/pi-superpowers

Restart Pi after installation for changes to take effect.

---

Option 2: Git Install

# Install latest version from GitHub
pi install https://github.com/weiping/pi-superpowers

# Pin to a specific version (pi update won't auto-upgrade)
pi install https://github.com/weiping/pi-superpowers@v1.0.0

---

Option 3: Prompt-based Auto Install

Paste the following prompt in a Pi session and Pi will complete the installation automatically:

Run: pi install npm:@weiping/pi-superpowers, then tell me the install is complete and I need to restart Pi.

---

Option 4: Local Path Install

# Global install
pi install /path/to/pi-superpowers

# Project-level install
pi install -l /path/to/pi-superpowers

See INSTALL.md for details.

---

OpenClaw Installation

If you use OpenClaw:

openclaw plugins install @weiping/openclaw-superpowers

---

License

MIT.
Original superpowers project by Jesse Vincent, also licensed under MIT.