An agentic skills framework & software development methodology that works.
feat: add pi superpowers package extension
Jesse Vincent71ac601627b4
diff --git a/README.md b/README.mdindex 80bb94e34..beb4220db 100644--- a/README.md+++ b/README.md@@ -11,7 +11,7 @@ If this sounds like someone you know, definitely send them our way.## Quickstart-Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode).+Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode), [Pi](#pi).## How it works@@ -158,6 +158,22 @@ already use it in another harness.- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)+### Pi++Install Superpowers as a Pi package from this repository:++```bash+pi install git:github.com/obra/superpowers+```++For local development, run Pi with this checkout loaded as a temporary package:++```bash+pi -e /path/to/superpowers+```++The Pi package loads the Superpowers skills and a small extension that injects the `using-superpowers` bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility `Skill` tool is required. Subagent and task-list tools remain optional Pi companion packages.+## The Basic Workflow1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.diff --git a/extensions/superpowers.ts b/extensions/superpowers.tsnew file mode 100644index 000000000..af44623d0--- /dev/null+++ b/extensions/superpowers.ts@@ -0,0 +1,121 @@+import { readFileSync } from "node:fs";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";++const EXTREMELY_IMPORTANT_MARKER = "<EXTREMELY_IMPORTANT>";+const BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for pi";++const extensionDir = dirname(fileURLToPath(import.meta.url));+const packageRoot = resolve(extensionDir, "..");+const skillsDir = resolve(packageRoot, "skills");+const bootstrapSkillPath = resolve(skillsDir, "using-superpowers", "SKILL.md");++let cachedBootstrap: string | null | undefined;++export default function superpowersPiExtension(pi: ExtensionAPI) {+ let injectBootstrap = true;++ pi.on("resources_discover", async () => ({+ skillPaths: [skillsDir],+ }));++ pi.on("session_start", async () => {+ injectBootstrap = true;+ });++ pi.on("session_compact", async () => {+ injectBootstrap = true;+ });++ pi.on("agent_end", async () => {+ injectBootstrap = false;+ });++ pi.on("context", async (event) => {+ if (!injectBootstrap) return;+ if (event.messages.some(messageContainsBootstrap)) return;++ const bootstrap = getBootstrapContent();+ if (!bootstrap) return;++ const bootstrapMessage = {+ role: "user" as const,+ content: [{ type: "text" as const, text: bootstrap }],+ timestamp: Date.now(),+ };++ const insertAt = firstNonCompactionSummaryIndex(event.messages);+ return {+ messages: [+ ...event.messages.slice(0, insertAt),+ bootstrapMessage,+ ...event.messages.slice(insertAt),+ ],+ };+ });+}++function getBootstrapContent(): string | null {+ if (cachedBootstrap !== undefined) return cachedBootstrap;++ try {+ const skillContent = readFileSync(bootstrapSkillPath, "utf8");+ const body = stripFrontmatter(skillContent);+ cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}+${BOOTSTRAP_MARKER}++You have superpowers.++The using-superpowers skill content is included below and is already loaded for this Pi session. Follow it now. Do not try to load using-superpowers again.++${body}++${piToolMapping()}+</EXTREMELY_IMPORTANT>`;+ return cachedBootstrap;+ } catch {+ cachedBootstrap = null;+ return null;+ }+}++function stripFrontmatter(content: string): string {+ const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);+ return (match ? match[1] : content).trim();+}++function piToolMapping(): string {+ return `## Pi tool mapping++Pi has native skills but does not expose Claude Code's \`Skill\` tool. When a Superpowers instruction says to use the \`Skill\` tool, use Pi's native skill system instead: load the relevant \`SKILL.md\` with \`read\` when the skill applies, or let a human invoke \`/skill:name\` explicitly.++Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Map Claude-style tool names \`Read\`, \`Write\`, \`Edit\`, and \`Bash\` to those Pi tools.++Pi does not ship a standard \`Task\` subagent tool. If a subagent tool such as \`subagent\` from \`pi-subagents\` is available, use it for Superpowers subagent workflows. If no subagent tool is available, do the work in this session or explain the missing capability instead of inventing tool calls.++Pi does not ship a standard \`TodoWrite\` task-list tool. If an installed todo/task tool is available, use it. Otherwise track work in plan files or a repo-local \`TODO.md\` when task tracking is needed.`;+}++function messageContainsBootstrap(message: unknown): boolean {+ const content = (message as { content?: unknown }).content;+ if (typeof content === "string") return content.includes(BOOTSTRAP_MARKER);+ if (!Array.isArray(content)) return false;+ return content.some((part) => {+ return (+ part &&+ typeof part === "object" &&+ (part as { type?: unknown }).type === "text" &&+ typeof (part as { text?: unknown }).text === "string" &&+ (part as { text: string }).text.includes(BOOTSTRAP_MARKER)+ );+ });+}++function firstNonCompactionSummaryIndex(messages: unknown[]): number {+ let index = 0;+ while ((messages[index] as { role?: unknown } | undefined)?.role === "compactionSummary") {+ index += 1;+ }+ return index;+}diff --git a/package.json b/package.jsonindex 2b8146635..00608b49c 100644--- a/package.json+++ b/package.json@@ -1,6 +1,23 @@{"name": "superpowers","version": "5.1.0",+ "description": "Superpowers skills and runtime bootstrap for coding agents","type": "module",- "main": ".opencode/plugins/superpowers.js"+ "main": ".opencode/plugins/superpowers.js",+ "keywords": [+ "pi-package",+ "skills",+ "tdd",+ "debugging",+ "collaboration",+ "workflow"+ ],+ "pi": {+ "extensions": [+ "./extensions/superpowers.ts"+ ],+ "skills": [+ "./skills"+ ]+ }}diff --git a/skills/using-superpowers/references/pi-tools.md b/skills/using-superpowers/references/pi-tools.mdnew file mode 100644index 000000000..b0b5fedaf--- /dev/null+++ b/skills/using-superpowers/references/pi-tools.md@@ -0,0 +1,30 @@+# Pi Tool Mapping++Pi supports Superpowers skills natively through skill discovery and `/skill:name` commands. It does not expose Claude Code's `Skill` tool.++When a Superpowers skill mentions Claude Code tool names, use these Pi equivalents:++| Superpowers / Claude Code name | Pi equivalent |+| --- | --- |+| `Skill` | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` |+| `Read` | `read` |+| `Write` | `write` |+| `Edit` | `edit` |+| `Bash` | `bash` |+| `Grep` | `grep` when active; otherwise `bash` with `rg`/`grep` |+| `Glob` | `find` or `bash` with shell globs |+| `LS` / `List` | `ls` when active; otherwise `bash` with `ls` |+| `Task` | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |+| `TodoWrite` | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |++## Skills++Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose `skills/` through its `pi.skills` manifest entry. The agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding.++## Subagents++Pi core does not ship a standard subagent tool. The `pi-subagents` package is a strong optional companion and provides a `subagent` tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate `Task` calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.++## Task lists++Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking.diff --git a/tests/pi/test-pi-extension.mjs b/tests/pi/test-pi-extension.mjsnew file mode 100644index 000000000..772f3ef90--- /dev/null+++ b/tests/pi/test-pi-extension.mjs@@ -0,0 +1,128 @@+import assert from 'node:assert/strict';+import { readFile } from 'node:fs/promises';+import { existsSync } from 'node:fs';+import { dirname, resolve } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';+import test from 'node:test';++const __dirname = dirname(fileURLToPath(import.meta.url));+const repoRoot = resolve(__dirname, '../..');+const packageJsonPath = resolve(repoRoot, 'package.json');+const extensionPath = resolve(repoRoot, 'extensions/superpowers.ts');+const piToolsPath = resolve(repoRoot, 'skills/using-superpowers/references/pi-tools.md');++async function readPackageJson() {+ return JSON.parse(await readFile(packageJsonPath, 'utf8'));+}++async function loadExtension() {+ const handlers = new Map();+ const pi = {+ on(event, handler) {+ if (!handlers.has(event)) handlers.set(event, []);+ handlers.get(event).push(handler);+ },+ };+ const mod = await import(pathToFileURL(extensionPath).href + `?cachebust=${Date.now()}-${Math.random()}`);+ mod.default(pi);+ return { handlers };+}++function firstHandler(handlers, event) {+ const eventHandlers = handlers.get(event) ?? [];+ assert.equal(eventHandlers.length, 1, `expected one ${event} handler`);+ return eventHandlers[0];+}++function textOf(message) {+ if (typeof message.content === 'string') return message.content;+ return message.content+ .filter((part) => part.type === 'text')+ .map((part) => part.text)+ .join('\n');+}++test('package.json declares a pi package with skills and extension resources', async () => {+ const pkg = await readPackageJson();++ assert.equal(pkg.name, 'superpowers');+ assert.ok(pkg.keywords.includes('pi-package'));+ assert.deepEqual(pkg.pi.skills, ['./skills']);+ assert.deepEqual(pkg.pi.extensions, ['./extensions/superpowers.ts']);+});++test('extension registers lifecycle hooks without pre-compaction injection', async () => {+ const { handlers } = await loadExtension();++ for (const event of ['resources_discover', 'session_start', 'session_compact', 'context', 'agent_end']) {+ assert.equal((handlers.get(event) ?? []).length, 1, `missing ${event} handler`);+ }+ assert.equal((handlers.get('session_before_compact') ?? []).length, 0);+});++test('resources_discover contributes the bundled skills directory', async () => {+ const { handlers } = await loadExtension();+ const discover = firstHandler(handlers, 'resources_discover');++ const result = await discover({ type: 'resources_discover', cwd: repoRoot, reason: 'startup' }, {});++ assert.deepEqual(result.skillPaths, [resolve(repoRoot, 'skills')]);+});++test('startup context injects the bootstrap as one user message until agent_end', async () => {+ const { handlers } = await loadExtension();+ const sessionStart = firstHandler(handlers, 'session_start');+ const context = firstHandler(handlers, 'context');+ const agentEnd = firstHandler(handlers, 'agent_end');++ await sessionStart({ type: 'session_start', reason: 'startup' }, {});++ const originalMessages = [+ { role: 'user', content: [{ type: 'text', text: 'Let us make a react todo list' }], timestamp: 1 },+ ];+ const result = await context({ type: 'context', messages: originalMessages }, {});++ assert.equal(result.messages.length, 2);+ assert.equal(result.messages[0].role, 'user');+ assert.match(textOf(result.messages[0]), /You have superpowers/);+ assert.match(textOf(result.messages[0]), /Pi tool mapping/);+ assert.equal(result.messages[1], originalMessages[0]);++ const repeatedProviderRequest = await context({ type: 'context', messages: originalMessages }, {});+ assert.equal(repeatedProviderRequest.messages.length, 2);+ assert.match(textOf(repeatedProviderRequest.messages[0]), /You have superpowers/);++ const alreadyInjected = await context({ type: 'context', messages: result.messages }, {});+ assert.equal(alreadyInjected, undefined, 'bootstrap should not duplicate when already present');++ await agentEnd({ type: 'agent_end', messages: [] }, {});+ const afterEnd = await context({ type: 'context', messages: originalMessages }, {});+ assert.equal(afterEnd, undefined, 'startup bootstrap should clear after agent_end');+});++test('session_compact injects bootstrap after compaction summaries, not before compaction', async () => {+ const { handlers } = await loadExtension();+ const sessionCompact = firstHandler(handlers, 'session_compact');+ const context = firstHandler(handlers, 'context');++ await sessionCompact({ type: 'session_compact', compactionEntry: {}, fromExtension: false }, {});++ const summary = { role: 'compactionSummary', summary: 'Prior work summary', tokensBefore: 123, timestamp: 1 };+ const user = { role: 'user', content: [{ type: 'text', text: 'Continue' }], timestamp: 2 };+ const result = await context({ type: 'context', messages: [summary, user] }, {});++ assert.equal(result.messages.length, 3);+ assert.equal(result.messages[0], summary);+ assert.equal(result.messages[1].role, 'user');+ assert.match(textOf(result.messages[1]), /You have superpowers/);+ assert.equal(result.messages[2], user);+});++test('pi tools reference documents pi-specific mappings', async () => {+ assert.equal(existsSync(piToolsPath), true, 'pi-tools.md should exist');+ const text = await readFile(piToolsPath, 'utf8');++ for (const expected of ['Skill', 'Task', 'TodoWrite', 'read', 'write', 'edit', 'bash']) {+ assert.match(text, new RegExp(expected));+ }+});