23 23 /superpowers # toggle workflow discipline
26 -/superpowers run <
agent> [args]
26 +/superpowers run <
agent> [args] [
--share]
27 27 /superpowers open <
id>
28 28 /superpowers branch <
id>
29 29 /superpowers return <
summary>
46 46 #
visual brainstorming companion 47 47 /superpowers visual start
48 -/superpowers visual status
49 49 /superpowers visual stop
52 -Agents are normal Pi prompt templates:
52 +## Prompt frontmatter
56 -~/.pi/agent/prompts/*.md
59 -Use the same file either way:
63 -/superpowers run review ...
66 -Supported frontmatter:
54 +Agents are normal Pi prompt templates (`prompts/*.md`). Supported frontmatter:
57 +description: Run a focused code review
58 +argument-hint: "<file|directory|diff|scope>"
59 +tools: [read, bash, grep, find, ls]
70 60 extensions: ["*", "-superpowers"]
72 62 model: provider/model
63 +accent: syntaxKeyword
75 -Bundled workflow skills + prompt entrypoints:
68 +| `description` | Shown in autocomplete and status |
69 +| `argument-hint` | Autocomplete hint for arguments |
70 +| `tools` | Tool allowlist for the subagent |
71 +| `extensions` | Extension filter (`*` = all, `-name` = exclude) |
72 +| `thinking` | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
73 +| `model` | Override model: `provider/id` |
74 +| `accent` | Theme color for footer/widget/status rendering (see below) |
76 +###
`accent` — workflow color 78 +Controls the visual identity of a worker in the footer, widget, and status output.
79 +Value is a `ThemeColor` name from Pi's theme system. The color resolves to whatever
80 +the active theme defines for that semantic role, so it adapts to light/dark themes automatically.
82 +**Recommended accents per workflow:**
84 +| Workflow | Accent | Visual feel |
86 +| `brainstorming` | `accent` | purple — creative |
87 +| `writing-plans` | `dim` | quiet — preparation |
88 +| `executing-plans` | `success` | green — building |
89 +| `test-driven-development` | `syntaxString` | green tint — test-first |
90 +| `systematic-debugging` | `warning` | yellow — caution |
91 +| `requesting-code-review` | `syntaxKeyword` | amber — critical eye |
92 +| `receiving-code-review` | `syntaxFunction` | blue — integration |
93 +| `verification-before-completion` | `toolTitle` | cyan — verification |
94 +| `dispatching-parallel-agents` | `syntaxVariable` | distinct — multi-agent |
95 +| `using-git-worktrees` | `muted` | gray — infrastructure |
96 +| `writing-skills` | `syntaxFunction` | blue — meta-work |
98 +**Full `ThemeColor` palette** (51 names, all valid for `accent`):
101 +# Semantic roles — the useful ones for accent
102 +accent # primary brand color (purple in most themes)
103 +success # positive / done
104 +warning # caution / attention
105 +error # failure / blocker
106 +muted # secondary / quiet
107 +dim # lowest prominence
108 +text # default text color
110 +# Syntax highlighting — good for workflow identity
111 +syntaxKeyword # amber/orange — keywords, review, attention
112 +syntaxFunction # blue — functions, integration
113 +syntaxVariable # teal — variables, parallel
114 +syntaxString # green — strings, tests
115 +syntaxNumber # numeric literals
116 +syntaxType # type names
117 +syntaxOperator # operators
118 +syntaxPunctuation # brackets, commas
119 +syntaxComment # comments
121 +# Markdown rendering
122 +mdHeading # heading color
124 +mdCode # inline code
125 +mdCodeBlock # code block text
126 +mdCodeBlockBorder # code block border
127 +mdListBullet # bullet points
130 +toolTitle # tool name color (cyan-ish)
131 +toolOutput # tool result text
132 +toolDiffAdded # diff + lines
133 +toolDiffRemoved # diff - lines
134 +toolDiffContext # diff context lines
137 +thinkingText # assistant thinking text
138 +thinkingOff # off state
139 +thinkingMinimal # minimal
141 +thinkingMedium # medium
143 +thinkingXhigh # extra-high
146 +userMessageText # user message
147 +customMessageText # extension/custom message
148 +customMessageLabel # custom message label
151 +border # default border
152 +borderAccent # accent border
153 +borderMuted # muted border
156 +bashMode # bash mode indicator
157 +selectedBg # (ThemeBg, not ThemeColor — for backgrounds)
160 +Without an `accent` field, workers default to the extension's accent color (amber `syntaxKeyword` for review, etc.).
162 +##
Bundled workflows 78 165 /using-superpowers
94 -`skills/*/SKILL.md` holds the methodology. `prompts/*.md` are normal Pi slash prompt wrappers around those skills.
181 +`skills/*/SKILL.md` holds the methodology. `prompts/*.md` are normal Pi slash prompt wrappers with the full skill inlined — no runtime skill discovery needed.
96 183 Same prompts work as background workers:
100 187 /superpowers run requesting-code-review current diff
190 +## Worktree isolation
192 +By default, `/superpowers run` and workflow aliases create an isolated worktree/workspace for the subagent. This prevents filesystem collisions between concurrent tasks and keeps the parent working copy clean.
194 +| Repo type | Isolation mechanism | Path |
196 +| Git standard checkout | `git worktree add` | `.git/wt-<id>` |
197 +| Git bare (co/wt layout) | `git worktree add` | `<root>/<id>` |
198 +| Jujutsu (jj) | `jj workspace add` | `.jj/workspaces/<id>` |
199 +| No repo detected | in-place fallback | — |
201 +Use `--share` to run the subagent in the current working copy instead:
204 +/superpowers run implement fix-bug --share
207 +Isolation is skipped when:
208 +- `--share` is passed explicitly
209 +- No supported repo is detected
210 +- Worktree/workspace creation fails (falls back to in-place with a notice)
212 +On abort, isolated worktrees are cleaned up automatically. On successful completion, they are left for inspection — remove them manually or with `git worktree remove` / `jj workspace forget`.
216 +The footer and widget use compact, scannable formatting:
218 +**Footer** (status bar):
220 +on # strict mode active
221 +on 1↑ # 1 worker running
222 +on eye # visual brainstorming active
223 +1↑ # worker running, strict mode off
226 +**Widget** (above editor, when workers run):
229 +▶ sp-5 review 12s · 5 tools
230 +▶ sp-6 debug 1m3s · 8 tools
235 +▶ running ✓ done ⊘ aborted ✗ error ⤴ branched
238 +**Agent short names:**
240 +review fix design plan exec debug verify tdd parallel git skill finish sp sub
243 +`/superpowers status` lists all tasks. `/superpowers status <id>` shows full details.
103 247 Runtime state lives in the platform state dir, per project:
108 252 Windows: %LOCALAPPDATA%
\\pi
\\superpowers
\\<
project-hash>
\\ 258 +tasks.json # all tasks (running, done, aborted, error, branched)
259 +runs.jsonl # append-only audit log: one JSON line per completed task
260 +sessions/ # subagent session files
261 +visual/ # visual brainstorming state (ephemeral)
264 +Stale tasks (orphaned when the parent Pi session dies) are reaped on next session start.
111 266 Project/VCS state is only written by workflows that intentionally create docs/specs, e.g. `docs/superpowers/specs/...`.
113 -`status` is optimized for tmux supervision: summaries include id, state,
114 -elapsed time, agent name, tool count, and first result line. `status <id>` shows
115 -prompt, parent/child sessions, and latest result without opening an editor.
119 -From `/tmp/pi-superpowers-proto/DESIGN.md`:
122 271 run = background SDK agent
128 277 No Pi subprocesses. Uses Pi SDK sessions/resource loading directly.
279 +No Pi subprocesses. Uses Pi SDK sessions/resource loading directly.