From 49bf5ad6dc25a6a8eb536e29d9cbf5729b643804 Mon Sep 17 00:00:00 2001 From: Drew Ritter Date: Wed, 13 May 2026 17:53:35 -0700 Subject: [PATCH] Align Pi mapping with action vocabulary --- .pi/extensions/superpowers.ts | 8 ++--- skills/using-superpowers/SKILL.md | 2 +- .../using-superpowers/references/pi-tools.md | 30 +++++++++---------- 3 files changed, 19 insertions(+), 21 deletions(-) diff --git a/.pi/extensions/superpowers.ts b/.pi/extensions/superpowers.ts index 32c10771..a978e80e 100644 --- a/.pi/extensions/superpowers.ts +++ b/.pi/extensions/superpowers.ts @@ -88,13 +88,13 @@ function stripFrontmatter(content: string): string { 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 has native skills but does not expose Claude Code's \`Skill\` tool. When a Superpowers instruction says to invoke a skill, 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's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories. -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 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 \`Task\` 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.`; +Pi does not ship a standard 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. Treat older \`TodoWrite\` references as this task-tracking action.`; } function messageContainsBootstrap(message: unknown): boolean { diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index ddf50e19..c4c9d545 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -41,7 +41,7 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw ## Platform Adaptation -Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), and [gemini-tools.md](references/gemini-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. +Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), and [pi-tools.md](references/pi-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. # Using Skills diff --git a/skills/using-superpowers/references/pi-tools.md b/skills/using-superpowers/references/pi-tools.md index b0b5feda..04889cba 100644 --- a/skills/using-superpowers/references/pi-tools.md +++ b/skills/using-superpowers/references/pi-tools.md @@ -1,25 +1,23 @@ # Pi Tool Mapping -Pi supports Superpowers skills natively through skill discovery and `/skill:name` commands. It does not expose Claude Code's `Skill` tool. +Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below. -When a Superpowers skill mentions Claude Code tool names, use these Pi equivalents: - -| Superpowers / Claude Code name | Pi equivalent | +| Action skills request | 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` | +| Invoke a skill | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` | +| Read a file | `read` | +| Create a file | `write` | +| Edit a file | `edit` | +| Run a shell command | `bash` | +| Search file contents | `grep` when active; otherwise `bash` with `rg`/`grep` | +| Find files by name | `find` or `bash` with shell globs | +| List files and subdirectories | `ls` when active; otherwise `bash` with `ls` | +| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available | +| Task tracking ("create a todo", "mark complete") | 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. +Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose `skills/` through its `pi.skills` manifest entry. Pi does not expose Claude Code's `Skill` tool, but the agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding. ## Subagents @@ -27,4 +25,4 @@ Pi core does not ship a standard subagent tool. The `pi-subagents` package is a ## 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. +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. Older Superpowers docs may refer to `TodoWrite`; treat that as the task-tracking action above.