repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

chore: reformat markdown + restore corrupted files

546923d7774676bd76623e43e8cbd8ba9a22eaa8

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

- dprint + mdslw reformat all markdown files (line wrapping, indentation)
- rewrite skills/brutal/SKILL.md (was destroyed by dprint stdin bug)
- remove temporary markdownlint ignores for restored files
- fix markdownlint errors: ordered list prefixes, line length, HTML escaping

Changed files (59)

.markdownlint-cli2.yaml

Modified
8 8 - "skills/pi/LICENSE.md"
9 9 - ".pi/prompts/test-*.md"
10 10 - "prompts/brain.md"
11 - - "prompts/brutal.md"
12 - - "skills/brutal/SKILL.md"
13 11 config:
14 12 MD013:
15 13 line_length: 80

.pi/prompts/live-extension-test.md

Modified
16 16 Mission:
18 18 - Open a fresh observable terminal split/window.
19 -- In it run a dedicated tmux server with exactly one tmux session and exactly one tmux window.
19 +- In it run a dedicated tmux server with exactly one tmux session and exactly
20 + one tmux window.
20 21 - Use as many panes as needed inside that one window.
21 22 - Drive real interactive `pi`, with real LLM models.
22 -- Prefer default configured model for main run. Do not use mocks/fake providers unless scenario explicitly demands it.
23 -- Load only the extension under test by default. Load support extensions only when the scenario requires their real UX interaction.
23 +- Prefer default configured model for main run.
24 + Do not use mocks/fake providers unless scenario explicitly demands it.
25 +- Load only the extension under test by default.
26 + Load support extensions only when the scenario requires their real UX
27 + interaction.
24 28 - Act like a human using Pi, not like a unit-test harness.
25 -- Watch for bugs, perf issues, awkward UI/UX, confusing states, bad messages, lifecycle/reload bugs, visual glitches, terminal rendering issues, browser UI issues, and model/tool behavior problems.
26 -- Probe the user's active shell before sending commands; many users run Nushell/Fish/PowerShell, not Bash.
27 -- If an extension opens HTML/browser UI, treat that browser UI as part of the product and test it with Chrome CDP or Firefox BiDi skills.
29 +- Watch for bugs, perf issues, awkward UI/UX, confusing states, bad messages,
30 + lifecycle/reload bugs, visual glitches, terminal rendering issues, browser UI
31 + issues, and model/tool behavior problems.
32 +- Probe the user's active shell before sending commands; many users run
33 + Nushell/Fish/PowerShell, not Bash.
34 +- If an extension opens HTML/browser UI, treat that browser UI as part of the
35 + product and test it with Chrome CDP or Firefox BiDi skills.
28 36 - Be brutal, skeptical, and distrustful of the Pi agent under test.
29 -- Never accept the nested Pi agent's claims, status text, final answer, or self-reported verification at face value.
37 +- Never accept the nested Pi agent's claims, status text, final answer, or
38 + self-reported verification at face value.
30 39 - Keep running notes in a temp markdown file while testing.
31 40 - Finish with a concise findings report and path to the notes file.
33 42 ## Coding-Harness Engineer Mandate
35 -You are not merely a user of Pi — you are a **coding-harness engineer**. Your job is to actively engineer the harness around Pi so the extension under test performs at its best. This means:
44 +You are not merely a user of Pi — you are a **coding-harness engineer**.
45 +Your job is to actively engineer the harness around Pi so the extension under
46 +test performs at its best.
47 +This means:
37 -- **Seek the gold hand.** Before launching Pi, think: what would the ideal test environment look like for this extension? Then build it.
38 -- **Use project-local Pi modifications.** Scan the repo for local skills (`./skills/`), local prompts (`./.pi/prompts/`), local context files (`./.pi/context-files/`), local extensions (`./extensions/`), and any workspace-level `.pi/` config. If a temporary local skill, prompt template, context file, or small scaffolding extension would improve the test, create it in the project's `.pi/` tree (or appropriate local path). Clean it up after testing unless it represents a genuine improvement worth keeping.
39 -- **Load global extensions if they provide testing infrastructure.** You may load global extensions (e.g., `chrome-cdp`, `firefox-bidi`, `tmux`, `research`) when they give you better observability, setup, or control. **Never modify any global extension except the one under test.**
40 -- **Tweak the harness, not the goal.** Every modification you make — env vars, preloaded skills, scaffolded test projects, injected prompts, context files — must serve the single purpose of improving the extension under test. Do not drift into generic harness polishing.
41 -- **Remember your true north.** Even though you are pretending to be a coding-harness engineer, the ultimate goal is to improve the extension under test. If a harness change reveals a bug, missing feature, or UX flaw in the extension, file it as a finding and, when appropriate, patch the extension itself.
49 +- **Seek the gold hand.** Before launching Pi, think:
50 + what would the ideal test environment look like for this extension?
51 + Then build it.
52 +- **Use project-local Pi modifications.** Scan the repo for local skills
53 + (`./skills/`), local prompts (`./.pi/prompts/`), local context files
54 + (`./.pi/context-files/`), local extensions (`./extensions/`), and any
55 + workspace-level `.pi/` config.
56 + If a temporary local skill, prompt template, context file, or small
57 + scaffolding extension would improve the test, create it in the project's
58 + `.pi/` tree (or appropriate local path).
59 + Clean it up after testing unless it represents a genuine improvement worth
60 + keeping.
61 +- **Load global extensions if they provide testing infrastructure.** You may
62 + load global extensions (e.g., `chrome-cdp`, `firefox-bidi`, `tmux`,
63 + `research`) when they give you better observability, setup, or control.
64 + **Never modify any global extension except the one under test.**
65 +- **Tweak the harness, not the goal.** Every modification you make — env vars,
66 + preloaded skills, scaffolded test projects, injected prompts, context files —
67 + must serve the single purpose of improving the extension under test.
68 + Do not drift into generic harness polishing.
69 +- **Remember your true north.** Even though you are pretending to be a
70 + coding-harness engineer, the ultimate goal is to improve the extension under
71 + test.
72 + If a harness change reveals a bug, missing feature, or UX flaw in the
73 + extension, file it as a finding and, when appropriate, patch the extension
74 + itself.
43 76 ## Parse Scenario
51 84 - success criteria
52 85 - risks to watch
54 -If target is ambiguous, inspect repo structure and choose the most likely extension path. If still ambiguous, ask one focused question.
87 +If target is ambiguous, inspect repo structure and choose the most likely
88 +extension path.
89 +If still ambiguous, ask one focused question.
56 91 ## Skills to Load
58 93 Load these skills when their domain is active:
59 -- **`tmux`** — for all session/pane creation, `send-keys`, `capture-pane`, and multi-pane orchestration.
60 -- **`nushell`** — when the pane shell is `nu` or `nu.exe`. Nushell has no `&&`, no `$VAR` interpolation, and `;` is the statement separator.
61 -- **`wezterm`** — when `WEZTERM_PANE` is set and you need to split panes or attach via WezTerm CLI.
95 +- **`tmux`** — for all session/pane creation, `send-keys`, `capture-pane`, and
96 + multi-pane orchestration.
97 +- **`nushell`** — when the pane shell is `nu` or `nu.exe`.
98 + Nushell has no `&&`, no `$VAR` interpolation, and `;` is the statement
99 + separator.
100 +- **`wezterm`** — when `WEZTERM_PANE` is set and you need to split panes or
101 + attach via WezTerm CLI.
63 103 ## Shell Probe
65 -Before creating or driving panes, identify the user's shell and terminal environment. Do not assume Bash syntax inside tmux panes.
105 +Before creating or driving panes, identify the user's shell and terminal
106 +environment.
107 +Do not assume Bash syntax inside tmux panes.
67 109 Probe:
75 117 Shell rules:
77 -- Nushell: use `;`, not `&&`; env vars use `$env.NAME`; avoid Bash snippets in the pane. **Load the `nushell` skill** for exact syntax.
78 -- Fish: use `;` or `and`, not Bash-only constructs.
79 -- PowerShell: use `;`; env vars use `$env:NAME`.
80 -- Bash/Zsh/Sh: `&&`, `VAR=value cmd`, and POSIX snippets are OK.
81 -- If unsure, run complex setup from the agent's `bash` tool, not by pasting Bash into the user's pane.
82 -- When sending commands to tmux panes, prefer simple one-command lines or shell-specific forms.
119 +- Nushell:
120 + use `;`, not `&&`; env vars use `$env.NAME`; avoid Bash snippets in the pane.
121 + **Load the `nushell` skill** for exact syntax.
122 +- Fish:
123 + use `;` or `and`, not Bash-only constructs.
124 +- PowerShell:
125 + use `;`; env vars use `$env:NAME`.
126 +- Bash/Zsh/Sh:
127 + `&&`, `VAR=value cmd`, and POSIX snippets are OK.
128 +- If unsure, run complex setup from the agent's `bash` tool, not by pasting Bash
129 + into the user's pane.
130 +- When sending commands to tmux panes, prefer simple one-command lines or
131 + shell-specific forms.
84 133 ## Observable Terminal + tmux Setup
86 135 Load the **`tmux`** skill before writing any tmux orchestration.
88 -Create a dedicated tmux socket so the test environment has exactly one session/window without touching the user's existing tmux:
137 +Create a dedicated tmux socket so the test environment has exactly one
138 +session/window without touching the user's existing tmux:
91 141 RUN_ID="pi-ext-$(date +%Y%m%d-%H%M%S)"
125 175 tmux -L "$SOCKET" list-windows -t "$SESSION"
128 -Use a shell-aware pane launch command. **Keep it simple** — one command per `send-keys`, no shell operators inside the pane if Nushell is running:
178 +Use a shell-aware pane launch command.
179 +**Keep it simple** — one command per `send-keys`, no shell operators inside the
180 +pane if Nushell is running:
131 183 PI_CMD="pi --no-extensions --no-skills --no-prompt-templates --no-context-files -e ./extensions/<target>/index.ts"
151 203 Invariant:
153 -- `tmux -L "$SOCKET" list-sessions` shows exactly one session: `live`
154 -- `tmux -L "$SOCKET" list-windows -t live` shows exactly one window: `main`
205 +- `tmux -L "$SOCKET" list-sessions` shows exactly one session:
206 + `live`
207 +- `tmux -L "$SOCKET" list-windows -t live` shows exactly one window:
208 + `main`
155 209 - more panes are OK; more sessions/windows are not
157 -Open/attach that tmux session in the current terminal emulator, preferring an actual split over a new OS window:
211 +Open/attach that tmux session in the current terminal emulator, preferring an
212 +actual split over a new OS window:
159 214 1. WezTerm:
164 219 wezterm cli split-pane --right --cwd "$ROOT" -- tmux -L "$SOCKET" attach -t "$SESSION"
167 -2. Ghostty / Kitty / Alacritty / GNOME Terminal / Terminal.app / Windows Terminal / other popular terminals:
222 +1. Ghostty / Kitty / Alacritty / GNOME Terminal / Terminal.app / Windows
223 + Terminal / other popular terminals:
169 -- Detect via env and available commands: `WEZTERM_PANE`, `GHOSTTY_*`, `KITTY_WINDOW_ID`, `ALACRITTY_*`, `TERM_PROGRAM`, `WT_SESSION`, `TMUX`, `uname`.
225 +- Detect via env and available commands:
226 + `WEZTERM_PANE`, `GHOSTTY_*`, `KITTY_WINDOW_ID`, `ALACRITTY_*`, `TERM_PROGRAM`,
227 + `WT_SESSION`, `TMUX`, `uname`.
170 228 - Use the terminal's CLI to open a split/window attached to:
173 231 tmux -L "$SOCKET" attach -t "$SESSION"
176 -3. If no terminal split/window can be controlled safely:
234 +1. If no terminal split/window can be controlled safely:
178 236 - Keep the tmux server running.
179 237 - Print the exact attach command prominently.
192 250 Adjust only when needed:
194 -- support extension: add another `-e ./extensions/<support>/index.ts`
195 -- local package extension path: use exact path
196 -- scenario requires skills/prompts/context: remove only the needed isolation flag
197 -- scenario requires previous session behavior: use normal session mode intentionally and note why
252 +- support extension:
253 + add another `-e ./extensions/<support>/index.ts`
254 +- local package extension path:
255 + use exact path
256 +- scenario requires skills/prompts/context:
257 + remove only the needed isolation flag
258 +- scenario requires previous session behavior:
259 + use normal session mode intentionally and note why
199 -Do not force a model unless scenario requires model-specific behavior. Default configured model is preferred. For very long validation, it is OK to perform one secondary run with another available real model if useful.
261 +Do not force a model unless scenario requires model-specific behavior.
262 +Default configured model is preferred.
263 +For very long validation, it is OK to perform one secondary run with another
264 +available real model if useful.
201 266 ## Critical Verification Rules
203 -The Pi agent inside tmux is the system under test. Treat it like an unreliable junior engineer trying to impress you.
268 +The Pi agent inside tmux is the system under test.
269 +Treat it like an unreliable junior engineer trying to impress you.
205 -- Do not trust its claims of success, failure, verification, implementation, or UX quality.
271 +- Do not trust its claims of success, failure, verification, implementation, or
272 + UX quality.
206 273 - Independently inspect files it says it changed.
207 274 - Independently rerun commands it says passed.
208 275 - Independently inspect browser/terminal screenshots for UI claims.
209 -- **Model/provider gotcha**: when an extension frontmatter says `model: kimi/kimi-for-coding`, verify the exact provider name with `pi --list-models` and with `getModel(provider, id)` from `@earendil-works/pi-ai`. Invalid provider strings often return `undefined`, and `createAgentSession` may silently fall back to the parent session's default model.
210 -- Check whether it ignored instructions, skipped workflows, invented evidence, hid errors, or reframed the task smaller.
276 +- **Model/provider gotcha**:
277 + when an extension frontmatter says `model:
278 + kimi/kimi-for-coding`, verify the exact provider name with `pi --list-models`
279 + and with `getModel(provider, id)` from `@earendil-works/pi-ai`.
280 + Invalid provider strings often return `undefined`, and `createAgentSession`
281 + may silently fall back to the parent session's default model.
282 +- Check whether it ignored instructions, skipped workflows, invented evidence,
283 + hid errors, or reframed the task smaller.
211 284 - Record every unsupported claim as a finding until verified.
212 -- Prefer hard evidence: file diffs, command output, screenshots, browser console/network logs, session JSONL, pane captures, **and direct SDK integration tests** when the TUI is not observable.
213 -- Be concise but harsh in notes. No praise unless evidence earned it.
285 +- Prefer hard evidence:
286 + file diffs, command output, screenshots, browser console/network logs, session
287 + JSONL, pane captures, **and direct SDK integration tests** when the TUI is not
288 + observable.
289 +- Be concise but harsh in notes.
290 + No praise unless evidence earned it.
215 292 ## Human-like Driving Rules
219 296 - type commands/prompts into pane 1
220 297 - wait for UI states to settle
221 298 - read terminal output
222 -- **TUI gotcha**: Pi uses the alternate screen buffer. `tmux capture-pane` often shows only the status bar, not chat content. If you cannot see responses, verify via file-system artifacts, session JSONL, or direct SDK tests instead of fighting the TUI.
223 -- **Key concatenation gotcha**: `C-c C-u` does not reliably clear Pi's input widget. Always send `C-c`, wait, then `C-u`, wait, then type the new command. If you see merged commands like `/foo/bar`, the previous input was not cleared.
224 -- use extension slash commands, shortcuts, reloads, session switches, browser UIs, or tools only as real users would
225 -- if browser UI opens, inspect it and record UX findings with browser automation, not just terminal logs
226 -- test happy path, rough path, cancel/abort, reload/session lifecycle, browser lifecycle, and one realistic long-running path
227 -- observe latency and visual stability; note jank, flicker, unclear status, noisy widgets, bad footer/status behavior, stale state, or confusing errors
299 +- **TUI gotcha**:
300 + Pi uses the alternate screen buffer.
301 + `tmux capture-pane` often shows only the status bar, not chat content.
302 + If you cannot see responses, verify via file-system artifacts, session JSONL,
303 + or direct SDK tests instead of fighting the TUI.
304 +- **Key concatenation gotcha**:
305 + `C-c C-u` does not reliably clear Pi's input widget.
306 + Always send `C-c`, wait, then `C-u`, wait, then type the new command.
307 + If you see merged commands like `/foo/bar`, the previous input was not
308 + cleared.
309 +- use extension slash commands, shortcuts, reloads, session switches, browser
310 + UIs, or tools only as real users would
311 +- if browser UI opens, inspect it and record UX findings with browser
312 + automation, not just terminal logs
313 +- test happy path, rough path, cancel/abort, reload/session lifecycle, browser
314 + lifecycle, and one realistic long-running path
315 +- observe latency and visual stability; note jank, flicker, unclear status,
316 + noisy widgets, bad footer/status behavior, stale state, or confusing errors
228 317 - avoid unit-test shortcuts unless using them only to understand implementation
230 -This is expected to take time. Be thorough.
319 +This is expected to take time.
320 +Be thorough.
232 322 ## Browser UI Testing
234 -Some Pi extensions open local HTML pages. If a page opens or a URL is printed, that page is part of the extension UX and must be tested.
324 +Some Pi extensions open local HTML pages.
325 +If a page opens or a URL is printed, that page is part of the extension UX and
326 +must be tested.
236 328 Browser protocol:
238 -1. Detect URL/browser from terminal output, server info files, `xdg-open`/`open` behavior, or extension docs.
239 -2. If Chrome/Chromium is open or appropriate, load the `chrome-cdp` skill and use it to inspect/drive the live page.
240 -3. If Firefox is open or appropriate, load the `firefox-bidi` skill and use it to inspect/drive the live page; launching a managed Firefox is OK when needed.
241 -4. Interact like a human: click controls, type fields, resize if relevant, reload, close/reopen, test stale sessions, and verify events flow back to Pi.
242 -5. Inspect console errors, failed network requests, DOM state, accessibility labels where practical, and visual layout.
243 -6. Record browser findings in the notes with URL, browser, steps, expected/actual, and evidence.
330 +1. Detect URL/browser from terminal output, server info files, `xdg-open`/`open`
331 + behavior, or extension docs.
332 +2. If Chrome/Chromium is open or appropriate, load the `chrome-cdp` skill and
333 + use it to inspect/drive the live page.
334 +3. If Firefox is open or appropriate, load the `firefox-bidi` skill and use it
335 + to inspect/drive the live page; launching a managed Firefox is OK when
336 + needed.
337 +4. Interact like a human:
338 + click controls, type fields, resize if relevant, reload, close/reopen, test
339 + stale sessions, and verify events flow back to Pi.
340 +5. Inspect console errors, failed network requests, DOM state, accessibility
341 + labels where practical, and visual layout.
342 +6. Record browser findings in the notes with URL, browser, steps,
343 + expected/actual, and evidence.
245 -Do not skip browser testing because terminal behavior passed. If browser automation is unavailable, mark the browser portion blocked and say exactly what is missing.
345 +Do not skip browser testing because terminal behavior passed.
346 +If browser automation is unavailable, mark the browser portion blocked and say
347 +exactly what is missing.
247 349 ## Notes Discipline
270 372 - terminal emulator detected
271 373 - user shell and tmux pane shell detected
272 374 - tmux socket/session/window
273 -- browser used, URL tested, console/network issues, and browser skill used when applicable
375 +- browser used, URL tested, console/network issues, and browser skill used when
376 + applicable
274 377 - screenshots/GIF paths only if created
275 378 - every bug/UX issue with reproduction steps
276 379 - non-bugs worth preserving
282 385 1. Do not kill the tmux server automatically.
283 386 2. Leave tmux running for user inspection.
284 387 3. Give attach and kill commands.
285 -4. Ask: `Do you want me to close the tmux session now?`
388 +4. Ask:
389 + `Do you want me to close the tmux session now?`
286 390 5. Only run `tmux -L <socket> kill-server` after the user says yes.
287 391 6. Ensure notes file has final summary.
288 392 7. Report:
301 405 - [severity] title — evidence/repro
304 -If blocked by terminal control, auth/model config, missing extension path, or unsafe destructive scenario, stop and ask for the smallest missing input. If testing completes successfully, still leave tmux alive and ask whether to close it.
408 +If blocked by terminal control, auth/model config, missing extension path, or
409 +unsafe destructive scenario, stop and ask for the smallest missing input.
410 +If testing completes successfully, still leave tmux alive and ask whether to
411 +close it.
306 413 ## Fallback When TUI Driving Fails
308 -If `tmux capture-pane` cannot read Pi's chat output (alternate-screen-buffer issue), do not abandon the test. Fall back in this order:
415 +If `tmux capture-pane` cannot read Pi's chat output (alternate-screen-buffer
416 +issue), do not abandon the test.
417 +Fall back in this order:
310 -1. **File-system artifacts** — check extension state dirs, session JSONL, or any files the extension writes.
311 -2. **Direct SDK integration tests** — import the extension's code, call its internal helpers, or create real `createAgentSession` calls with real models to exercise the same code paths without the TUI.
312 -3. **Process inspection** — `ls -l /proc/<pid>/fd/` and `ps` to confirm the process is alive and which files it holds open.
313 -4. **Session file forensics** — read Pi's JSONL session files with `jq` to reconstruct what happened.
419 +1. **File-system artifacts** — check extension state dirs, session JSONL, or any
420 + files the extension writes.
421 +2. **Direct SDK integration tests** — import the extension's code, call its
422 + internal helpers, or create real `createAgentSession` calls with real models
423 + to exercise the same code paths without the TUI.
424 +3. **Process inspection** — `ls -l /proc/<pid>/fd/` and `ps` to confirm the
425 + process is alive and which files it holds open.
426 +4. **Session file forensics** — read Pi's JSONL session files with `jq` to
427 + reconstruct what happened.
315 -These fallbacks are not "cheating" — they are the harness engineer doing their job when the terminal layer is opaque.
429 +These fallbacks are not "cheating" — they are the harness engineer doing their
430 +job when the terminal layer is opaque.

.pi/prompts/test-kimi-broken.md

Deleted
deleted file mode 100644
1 ----
2 -description: Test broken kimi alias
3 -tools: [read, bash]
4 -model: kimi/kimi-for-coding
5 -accent: error
6 ----
7 -Say "hello from broken kimi" and then read the file /tmp/pi-ext-20260529-213419-findings.md and report its first line.

.pi/prompts/test-kimi.md

Deleted
deleted file mode 100644
1 ----
2 -description: Test kimi provider
3 -tools: [read, bash]
4 -model: kimi-coding/kimi-for-coding
5 -accent: syntaxKeyword
6 ----
7 -Say "hello from kimi" and then read the file /tmp/pi-ext-20260529-213419-findings.md and report its first line.

.pi/prompts/test-minimax.md

Deleted
deleted file mode 100644
1 ----
2 -description: Test minimax provider
3 -tools: [read, bash]
4 -model: minimax/MiniMax-M2.7
5 -accent: success
6 ----
7 -Say "hello from minimax" and then read the file /tmp/pi-ext-20260529-213419-findings.md and report its first line.

.pi/prompts/test-openai.md

Deleted
deleted file mode 100644
1 ----
2 -description: Test openai provider
3 -tools: [read, bash]
4 -model: openai/gpt-5.2
5 -accent: warning
6 ----
7 -Say "hello from openai" and then read the file /tmp/pi-ext-20260529-213419-findings.md and report its first line.

.pi/prompts/test-zai.md

Deleted
deleted file mode 100644
1 ----
2 -description: Test zai provider
3 -tools: [read, bash]
4 -model: zai/glm-5.1
5 -accent: syntaxFunction
6 ----
7 -Say "hello from zai" and then read the file /tmp/pi-ext-20260529-213419-findings.md and report its first line.

IDEAS.md

Deleted
deleted file mode 100644
1 -# Ideas
3 -- extension session-miner — search/session clustering tool; avoid raw jq
4 - rituals.
5 - Global.

README.md

Modified
144 -> **Note:** Local paths and git sources both require manual dependency installation. Pi runs `npm install --omit=dev` for git sources. For local development, run `npm install` inside the repo first.
144 +> **Note:** Local paths and git sources both require manual dependency installation.
145 +> Pi runs `npm install --omit=dev` for git sources.
146 +> For local development, run `npm install` inside the repo first.

TMUX_AGENT_WORKFLOWS.md

Deleted
deleted file mode 100644
1 -# tmux for Agent Workflows
3 -Practical patterns for using tmux to drive real interactive agents, TUI apps,
4 -long-running jobs, and manual integration tests.
6 -## Use Cases
8 -- Real interactive testing:
9 - exercise actual terminal UI, not mocks.
10 -- Long-running workflows:
11 - let agents, builds, servers, or model calls run while you inspect from
12 - outside.
13 -- Input timing tests:
14 - send input while a process is busy, idle, paused, or waiting.
15 -- UI verification:
16 - capture status bars, widgets, spinners, prompts, and wrapped text.
17 -- Repro sandboxes:
18 - run each scenario in a fresh cwd/session dir.
19 -- Debug artifacts:
20 - preserve logs, transcripts, temp files, and captured pane output.
21 -- Remote work:
22 - keep sessions alive across SSH disconnects.
23 -- Multi-process orchestration:
24 - agent pane + server pane + logs pane + watcher pane.
26 -## Pros
28 -- Tests real behavior end-to-end.
29 -- Works with any terminal app.
30 -- Non-blocking:
31 - launch, poll, inspect, continue.
32 -- Scriptable enough for smoke tests.
33 -- Great for reproducing bugs found only in interactive mode.
34 -- Keeps visible history while also allowing machine-readable session/log
35 - inspection.
37 -## Cons
39 -- Timing can be brittle; sleeps and polling are imperfect.
40 -- Pane output may wrap, truncate, or include ANSI/control artifacts.
41 -- Assertions are weaker than structured APIs.
42 -- Cleanup matters:
43 - stale tmux sessions and temp dirs cause false results.
44 -- Real providers/network/LLMs add cost, latency, and nondeterminism.
45 -- Terminal dimensions affect rendering.
47 -## Core Pattern
49 -```bash
50 -set -euo pipefail
52 -name=my_agent_test
53 -work=/tmp/$name
55 -rm -rf "$work"
56 -mkdir -p "$work"
57 -tmux kill-session -t "$name" 2>/dev/null || true
59 -tmux new-session -d -s "$name" -x 120 -y 40 "cd '$work' && your-agent-or-tui"
61 -sleep 2
62 -tmux capture-pane -t "$name" -p -S -80
63 -```
65 -## Sending Input
67 -```bash
68 -tmux set-buffer -t "$name" 'your input here'
69 -tmux paste-buffer -t "$name"
70 -tmux send-keys -t "$name" Enter
71 -```
73 -For special keys:
75 -```bash
76 -tmux send-keys -t "$name" C-c
77 -tmux send-keys -t "$name" Escape
78 -tmux send-keys -t "$name" Tab
79 -```
81 -## Polling for Completion
83 -Prefer semantic stop conditions over fixed sleeps.
85 -```bash
86 -for i in {1..30}; do
87 - sleep 5
88 - out=$(tmux capture-pane -t "$name" -p -S -200)
89 - echo "$out" | tail -80
90 - echo "$out" | grep -q 'DONE_MARKER' && break
91 -done
92 -```
94 -Use unique markers in prompts/tasks:
96 -```text
97 -Create file proof.txt containing EXACT_MARKER_123, then print DONE_MARKER_123.
98 -```
100 -## Capturing UI State
102 -```bash
103 -tmux capture-pane -t "$name" -p -S -200 > /tmp/pane.txt
104 -```
106 -Tips:
108 -- Use fixed pane size:
109 - `-x 120 -y 40`.
110 -- Capture enough scrollback:
111 - `-S -200` or more.
112 -- Prefer checking stable text, not exact whole-screen snapshots.
113 -- For wrapping/color bugs, inspect both pane output and screenshots if needed.
115 -## Inspecting Artifacts
117 -Pair tmux with structured logs/session files.
119 -```bash
120 -find "$work" -type f -maxdepth 3 -print
121 -cat "$work/log.jsonl" 2>/dev/null || true
122 -```
124 -For JSONL:
126 -```bash
127 -python - <<'PY' "$work/session.jsonl"
128 -import json, sys
129 -for line in open(sys.argv[1]):
130 - obj = json.loads(line)
131 - if obj.get("type") in {"event", "state", "custom"}:
132 - print(json.dumps(obj, ensure_ascii=False))
133 -PY
134 -```
136 -## Testing Busy-State Input
138 -tmux is useful for testing input while a process is occupied.
140 -```bash
141 -# start a long task
142 -send 'run a command that sleeps 10 seconds'
143 -sleep 2
145 -# send another input during the busy period
146 -send 'this should queue/steer/cancel/be rejected'
147 -```
149 -Check:
151 -- Was input accepted?
152 -- Was it queued or applied immediately?
153 -- Did it interrupt the running operation?
154 -- Did final state include the new instruction?
155 -- Did UI show pending/queued/steering state?
157 -## Multi-Pane Workflow
159 -```bash
160 -tmux new-session -d -s "$name" -x 160 -y 48 -n main "cd '$work' && agent"
161 -tmux split-window -t "$name" -h "cd '$work' && tail -f app.log"
162 -tmux split-window -t "$name" -v "cd '$work' && watch -n1 'find . -maxdepth 2 -type f -ls'"
163 -tmux select-pane -t "$name":0.0
164 -```
166 -Useful layouts:
168 -- Left:
169 - agent/TUI
170 -- Right top:
171 - logs
172 -- Right bottom:
173 - filesystem/session watcher
175 -## Cleanup
177 -```bash
178 -tmux kill-session -t "$name" 2>/dev/null || true
179 -rm -rf "$work"
180 -```
182 -For debugging, do not delete immediately.
183 -Print paths instead:
185 -```bash
186 -echo "tmux attach -t $name"
187 -echo "workdir: $work"
188 -```
190 -## Best Practices
192 -1. Start with unit/API tests.
193 -2. Use tmux for real interactive smoke tests.
194 -3. If tmux finds a bug, add a deterministic unit/harness regression.
195 -4. Re-run tmux once after the fix.
196 -5. Keep tmux tests short and marker-based.
197 -6. Avoid exact full-pane assertions unless testing layout.
198 -7. Always isolate cwd, config, session/log dirs.
199 -8. Always kill old sessions before starting.
200 -9. Use real network/model/provider tests sparingly.
201 -10. Record exact command, cwd, model/env, pane capture, and artifact paths.
203 -## Common Failure Modes
205 -- Prompt sent before app is ready → add readiness polling.
206 -- Input pasted while app uses alternate screen/editor mode → use `send-keys` or
207 - paste buffer carefully.
208 -- Output wraps differently → fix pane dimensions.
209 -- Grep matches old scrollback → use unique markers or clear pane before
210 - scenario.
211 -- Stale session reused → kill session and reset workdir.
212 -- App still running when assertions start → poll for a completion marker.
214 -## Reusable Helpers
216 -```bash
217 -send() {
218 - tmux set-buffer -t "$name" "$1"
219 - tmux paste-buffer -t "$name"
220 - tmux send-keys -t "$name" Enter
223 -pane() {
224 - tmux capture-pane -t "$name" -p -S "${1:--200}"
227 -wait_for() {
228 - local needle="$1"
229 - for i in {1..60}; do
230 - sleep 1
231 - pane -300 | grep -q "$needle" && return 0
232 - done
233 - pane -300 >&2
234 - return 1
236 -```
238 -## When Not to Use tmux
240 -- Pure deterministic logic tests.
241 -- Fast CI checks where APIs expose structured state.
242 -- Security-sensitive automation with secrets visible in pane scrollback.
243 -- Large-scale regression suites needing strict determinism.
245 -Use tmux as a realism layer, not as the only test harness.

TODO.md

Modified
1 1 # TODO
3 -## Pi install cleanup
3 +## Skills
5 -Later, after current Pi sessions are closed:
5 +- hypr:
6 + hyprland ecosystem and configs
7 +- archlinux
8 +- experiment:
9 + creating prototypes and experimenting, then cleaning up
7 -```bash
8 -bun install -g @earendil-works/pi-coding-agent
9 -sudo pacman -R pi
10 -```
11 +## Extensions
12 -Verify:
13 +- [ ] Port agent identity plugin from opencode?
14 +- [ ] Port model announcer plugin from opencode?
15 +- [ ] impement minimax extension:
16 + access to minmax apis as tools (music, voice, etc)
17 +- [ ] pi-wtf:
18 + extension that scans session data for curse words and frustrations and show
19 + graph over time.
20 + check leaked claude code for killer regex.
21 +- [ ] pi-modes:
22 + opencode like modes, but simpler and for me
14 -```bash
15 -which pi
16 -pi --version
17 -```
24 +## TUI
19 -## Fresh machine bootstrap
21 -```bash
22 -git clone ... ~/Workspace/pi-ext
23 -cd ~/Workspace/pi-ext
24 -bun install --frozen-lockfile
25 -```
26 +- [ ] More emphasized user messages in the TUI

TOOLING_MIGRATION.md

Deleted
deleted file mode 100644
1 -# Tooling migration plan
3 -Goal:
4 -one project-management entry point, reproducible local tooling, strict release
5 -validation, no Git-hook dependency, no hidden deps.
7 -This repo is jj-first.
8 -Git is only the backing store.
9 -Do not rely on Git hooks.
11 -## Requirements
13 -- One canonical command interface.
14 -- Easy setup for new contributors.
15 -- Formatting + linting for important file types:
16 - - Markdown
17 - - TypeScript / JavaScript / JSON
18 - - Python
19 - - YAML if kept in repo workflows
20 - - CSS / HTML if kept in browser demo code
21 -- Release/publish gate:
22 - - formatted
23 - - zero lint errors
24 - - zero warnings where tools support warning/error distinction
25 - - tests pass
26 - - extension static/build checks pass
27 -- Keep editor formatting and repo formatting in sync.
28 -- Avoid shell pipelines that break on Windows.
29 -- Do not disable markdown lint rules just to pass.
30 - Fix docs instead.
32 -## Decisions
34 -Use `mise` as the only project-management tool.
36 -Remove `justfile` after equivalent `mise` tasks exist.
38 -Do not add Git hooks.
39 -jj does not run them, so they are misleading here.
41 -Use tool-native discovery instead of `jj file list | xargs ...`.
43 -Use:
45 -- `biome` for TypeScript, JavaScript, JSON, CSS, maybe HTML
46 -- `ruff` for Python format + lint
47 -- `dprint` as Markdown structural formatter
48 -- `mdslw` for Markdown sentence line wrapping
49 -- `markdownlint-cli2` for Markdown lint
50 -- `yamlfmt` for YAML if `.github/*.yml` remains tracked
52 -## Tool availability
54 -Checked `mise registry`:
56 -| tool | mise registry backend |
57 -| ------------------- | ----------------------- |
58 -| `bun` | `core:bun` |
59 -| `biome` | `aqua:biomejs/biome` |
60 -| `ruff` | `aqua:astral-sh/ruff` |
61 -| `dprint` | `aqua:dprint/dprint` |
62 -| `markdownlint-cli2` | `npm:markdownlint-cli2` |
63 -| `yamlfmt` | `aqua:google/yamlfmt` |
65 -Not in registry:
67 -| tool | source |
68 -| ------- | ------------------------ |
69 -| `mdslw` | `github:razziel89/mdslw` |
71 -`mdslw` has GitHub release binaries for Linux, macOS, and Windows.
73 -## Current file types
75 -Tracked file type inventory at planning time:
77 -| type | count | action |
78 -| ---------------------------------------- | ----: | -------------------------------------- |
79 -| `.md` | 132 | `dprint`, `mdslw`, `markdownlint-cli2` |
80 -| `.ts` / `.test.ts` / `.bench.ts` | 181 | `biome` |
81 -| `.json` | 38 | `biome` |
82 -| `.py` | 16 | `ruff` |
83 -| `.mjs` | 5 | `biome` |
84 -| `.yml` | 2 | `yamlfmt` |
85 -| `.html` | 1 | `biome` if stable here |
86 -| `.css` | 1 | `biome` |
87 -| `.lua` | 1 | skip for now |
88 -| `.jsonl`, `.txt`, `.snap`, `.gif`, locks | many | skip / generated / fixtures |
90 -Important JSON files:
92 -- root `package.json`
93 -- every `extensions/*/package.json`
94 -- `skills/ascii-boxes/package.json`
95 -- `skills/pi/evals/evals.json`
96 -- `themes/terminal.json`
98 -Generated/owned files to avoid manual formatting:
100 -- `extensions/*/bun.lock`
101 -- `skills/ascii-boxes/deno.lock`
102 -- `*.gif`
103 -- snapshot files
104 -- benchmark `.txt`
106 -## Target commands
108 -Canonical commands after migration:
110 -```bash
111 -mise run fmt
112 -mise run lint
113 -mise run test
114 -mise run build
115 -mise run ci
116 -mise run publish
117 -```
119 -Meanings:
121 -- `fmt`:
122 - mutate files into canonical formatting
123 -- `lint`:
124 - non-mutating gate; formatting already correct + lint diagnostics clean
125 -- `test`:
126 - run extension tests
127 -- `build`:
128 - run extension static/build checks
129 -- `ci`:
130 - release gate = lint + test + build
131 -- `publish`:
132 - runs `ci`, then publishes/releases
134 -Do not create a separate `check` task.
135 -It overlaps with `lint` and confuses the interface.
136 -Use `build` for extension package validation.
138 -## Step 1: clean up temporary hook/just work
140 -If these exist from earlier experiments, remove them:
142 -- `.githooks/pre-commit`
143 -- `.githooks/`
144 -- Git config `core.hooksPath=.githooks`
146 -Command:
148 -```bash
149 -git config --unset core.hooksPath || true
150 -rm -rf .githooks
151 -```
153 -Do not rely on hooks for jj workflows.
155 -Keep `justfile` only until all `mise` tasks are working.
156 -Delete it at the end.
158 -## Step 2: add `mise.toml`
160 -Create root `mise.toml`.
162 -Start with pinned-enough tool versions.
163 -Use exact versions if available and stable; otherwise use `latest` during
164 -initial migration, then lock later with `mise lock`.
166 -Suggested initial file:
168 -```toml
169 -[tools]
170 -bun = "1.3.14"
171 -biome = "latest"
172 -ruff = "latest"
173 -dprint = "latest"
174 -markdownlint-cli2 = "latest"
175 -yamlfmt = "latest"
177 -[tools."github:razziel89/mdslw"]
178 -version = "0.17.1"
179 -bin = "mdslw"
181 -[tasks.fmt]
182 -description = "Format repo"
183 -run = [
184 - "biome format --write .",
185 - "ruff format .",
186 - "dprint fmt",
187 - "mdslw .",
188 - "yamlfmt .",
191 -[tasks.lint]
192 -description = "Verify formatting and lint"
193 -run = [
194 - "biome ci .",
195 - "ruff format --check .",
196 - "ruff check .",
197 - "dprint check",
198 - "mdslw --mode check .",
199 - "markdownlint-cli2",
200 - "yamlfmt -lint .",
203 -[tasks.test]
204 -description = "Run tests"
205 -run = "python3 scripts/extensions.py test"
207 -[tasks.build]
208 -description = "Validate/build extension packages"
209 -run = "python3 scripts/extensions.py check"
211 -[tasks.ci]
212 -description = "Release gate"
213 -depends = ["lint", "test", "build"]
215 -[tasks.publish]
216 -description = "Publish after release gate"
217 -depends = ["ci"]
218 -run = "python3 scripts/extensions.py publish"
219 -```
221 -Notes:
223 -- Verify `yamlfmt -lint .` syntax locally.
224 - If different, fix task.
225 -- Verify `github:razziel89/mdslw` asset autodetection.
226 - If mise cannot infer the binary correctly, add platform-specific
227 - `asset_pattern` entries.
228 -- If Biome HTML formatting is unstable for `extensions/diff-review/browser`,
229 - exclude HTML initially and document why.
231 -## Step 3: add formatter configs
233 -### Biome
235 -Add `biome.json`.
237 -Use Biome for TS/JS/MJS/JSON/CSS and possibly HTML.
239 -Start strict but practical.
240 -Example skeleton:
242 -```json
244 - "$schema": "https://biomejs.dev/schemas/latest/schema.json",
245 - "files": {
246 - "includes": [
247 - "**/*.ts",
248 - "**/*.js",
249 - "**/*.mjs",
250 - "**/*.json",
251 - "**/*.jsonc",
252 - "**/*.css",
253 - "**/*.html",
254 - "!**/node_modules/**",
255 - "!**/bun.lock",
256 - "!**/*.snap"
257 - ]
258 - },
259 - "formatter": {
260 - "enabled": true,
261 - "indentStyle": "tab"
262 - },
263 - "linter": {
264 - "enabled": true,
265 - "rules": {
266 - "recommended": true
267 - }
268 - }
270 -```
272 -Then run `mise run fmt` and inspect diffs.
273 -Adjust only for real false positives.
275 -### Dprint
277 -Add `dprint.json`.
279 -Use Dprint only for Markdown.
280 -Do not let it format TS/JSON if Biome owns them.
282 -Example skeleton:
284 -```json
286 - "includes": ["**/*.md"],
287 - "excludes": [
288 - "**/node_modules/**",
289 - ".demo/**"
290 - ],
291 - "plugins": [
292 - "https://plugins.dprint.dev/markdown/latest.wasm"
293 - ],
294 - "markdown": {
295 - "lineWidth": 80
296 - }
298 -```
300 -Run:
302 -```bash
303 -dprint fmt
304 -mdslw .
305 -```
307 -If Dprint and `mdslw` fight each other, change Dprint Markdown line wrapping to
308 -preserve/disable prose wrapping if supported.
309 -`mdslw` should own sentence-line wrapping.
311 -### Ruff
313 -Add `pyproject.toml` or `ruff.toml`.
315 -Prefer `pyproject.toml` if no Python packaging config exists yet.
317 -Example skeleton:
319 -```toml
320 -[tool.ruff]
321 -target-version = "py313"
322 -line-length = 100
323 -extend-exclude = [
324 - ".demo",
327 -[tool.ruff.lint]
328 -select = ["E", "F", "I", "UP", "B", "SIM"]
330 -[tool.ruff.format]
331 -quote-style = "double"
332 -indent-style = "space"
333 -```
335 -Run:
337 -```bash
338 -ruff format .
339 -ruff check .
340 -```
342 -Fix all reported issues.
343 -Do not blanket-disable rules unless a rule is truly wrong for this repo.
345 -### markdownlint-cli2
347 -Add `.markdownlint-cli2.yaml`.
349 -Do not disable normal lint rules just because there are many failures.
350 -Fix the Markdown.
352 -Only configure ignores for generated/vendor paths.
354 -Example skeleton:
356 -```yaml
357 -globs:
358 - - "**/*.md"
359 -ignores:
360 - - "**/node_modules/**"
361 - - ".demo/**"
362 -```
364 -If line length conflicts with semantic line wrapping, first run Dprint + mdslw
365 -and fix remaining docs.
366 -Avoid disabling `MD013` unless there is a clear, repo-wide reason.
368 -### yamlfmt
370 -Add `.yamlfmt` if needed.
371 -Keep minimal.
372 -Verify syntax from `yamlfmt --help`.
374 -Target files:
376 -- `.github/dependabot.yml`
377 -- `.github/workflows/check.yml`
379 -## Step 4: update Neovim formatter config
381 -Update dotfiles so editor and repo use same tools.
383 -File:
385 -```text
386 -/home/me/Workspace/dotfiles/neovim/lua/bugabinga/format.lua
387 -```
389 -Current Markdown chain uses Deno:
391 -```lua
392 -markdown = { 'deno_fmt_markdown', 'mdslw', 'injected' }
393 -```
395 -Change to Dprint:
397 -```lua
398 -markdown = { 'dprint', 'mdslw', 'injected' }
399 -```
401 -Change TS/JS/JSON to Biome:
403 -```lua
404 -javascript = { 'biome' },
405 -javascriptreact = { 'biome' },
406 -typescript = { 'biome' },
407 -typescriptreact = { 'biome' },
408 -json = { 'biome' },
409 -jsonc = { 'biome' },
410 -```
412 -Add Python Ruff if not already configured:
414 -```lua
415 -python = { 'ruff_format', 'ruff_fix', 'ruff_organize_imports' }
416 -```
418 -Use actual Conform formatter names.
419 -Verify with Conform docs/current config.
421 -Remove `deno_fmt_markdown` only if no other filetype uses it.
423 -## Step 5: update GitHub workflow
425 -Current workflow installs Bun and Nushell manually, then runs Python scripts.
427 -Replace manual installs with mise.
429 -Target shape:
431 -```yaml
432 -- name: Install mise
433 - run: |
434 - curl https://mise.run | sh
435 - echo "$HOME/.local/bin" >> "$GITHUB_PATH"
437 -- name: Install tools
438 - run: mise install
440 -- name: CI
441 - run: mise run ci
442 -```
444 -If `pi` is required in CI, either install Pi explicitly or document that CI only
445 -runs extension build/tests that do not need interactive Pi.
446 -Do not hide missing Pi behind optional behavior.
448 -## Step 6: update publish/release path
450 -Find current publish entry:
452 -```bash
453 -python3 scripts/extensions.py publish
454 -```
456 -Ensure publish task always depends on `ci`:
458 -```toml
459 -[tasks.publish]
460 -depends = ["ci"]
461 -run = "python3 scripts/extensions.py publish"
462 -```
464 -If there is a separate release prompt/script, route it through `mise run
465 -publish` or `mise run ci` first.
467 -The invariant:
468 -no publish/release command bypasses `ci`.
470 -## Step 7: remove `justfile`
472 -Once these pass:
474 -```bash
475 -mise run fmt
476 -mise run lint
477 -mise run test
478 -mise run build
479 -mise run ci
480 -```
482 -Delete `justfile`.
484 -Update docs/prompts mentioning `just`:
486 -- `README.md`
487 -- `.pi/prompts/drive-demo.md`
488 -- release docs/prompts
489 -- any agent instructions that say `just demo`, `just check`, `just test`
491 -Replace examples:
493 -```text
494 -just demo tldr
495 -```
497 -with:
499 -```text
500 -mise run demo -- tldr
501 -```
503 -Add a `demo` task in `mise.toml` before updating references:
505 -```toml
506 -[tasks.demo]
507 -description = "Record demo GIFs"
508 -run = "python3 scripts/demo.py"
509 -```
511 -Confirm argument forwarding.
512 -If `mise run demo -- tldr` does not pass args as expected, use a `usage` block
513 -or a file task.
515 -## Step 8: fix all formatting/lint failures
517 -Expected first run will be noisy.
519 -Order:
521 -1. `mise run fmt`
522 -2. inspect diff
523 -3. `mise run lint`
524 -4. fix remaining lint failures manually
525 -5. repeat until clean
527 -Markdownlint previously reported:
529 -```text
530 -36 README files
531 -309 errors
532 -MD013 line-length: 271
533 -MD060 table-column-style: 22
534 -MD032 blanks-around-lists: 16
535 -```
537 -Do not disable those rules just to pass.
538 -Use formatter + manual cleanup.
540 -## Step 9: lock deps
542 -After tools install and tasks work:
544 -```bash
545 -mise lock
546 -```
548 -Commit:
550 -- `mise.toml`
551 -- `mise.lock`
552 -- tool config files
553 -- docs updates
554 -- formatted files
556 -## Step 10: acceptance checklist
558 -Before final commit:
560 -```bash
561 -mise install
562 -mise run fmt
563 -mise run lint
564 -mise run test
565 -mise run build
566 -mise run ci
567 -mise run publish -- --dry-run
568 -```
570 -If publish has no dry-run flag, do not run real publish.
571 -Add a dry-run flag first or document why it is unavailable.
573 -Final repo properties:
575 -- no `justfile`
576 -- no `.githooks`
577 -- no Git hook setup docs
578 -- `mise.toml` is the one command surface
579 -- `mise.lock` exists if lockfile is chosen
580 -- Neovim formatter config matches repo tasks
581 -- CI uses `mise run ci`
582 -- publish/release path depends on `ci`
583 -- Markdown lints are fixed, not disabled
585 -## Notes for Windows
587 -Avoid these patterns:
589 -```bash
590 -jj file list 'glob:**/*.md' | xargs ...
591 -git ls-files -z | xargs -0 ...
592 -find ... -exec ...
593 -```
595 -Prefer:
597 -```bash
598 -dprint fmt
599 -mdslw .
600 -biome ci .
601 -ruff check .
602 -markdownlint-cli2
603 -```
605 -If a tool cannot discover files correctly, add a tiny cross-platform script in
606 -Python or TypeScript and call that from mise.
607 -Do not build large shell pipelines.

docs/superpowers/specs/2026-05-29-branch-return-lifecycle-design.md

Deleted
deleted file mode 100644
1 -# Branch/Return Lifecycle Design
3 -## Goal
5 -Harden and prove `/superpowers branch` + `/superpowers return` as a complete takeover loop.
7 -## Contract
9 -- `/superpowers branch <id>` uses the task's persisted `parentSession`.
10 -- Branching marks the task `branched`.
11 -- Branching stops the selected live runtime if present.
12 -- Branching aborts peer live runtimes.
13 -- Branching opens a child session from `parentSession`.
14 -- The child session receives takeover instructions including `/superpowers return <summary>`.
15 -- The task snapshot records `childSession`.
16 -- `/superpowers return <summary>` switches back to `parentSession`.
17 -- The parent session receives a structured return entry.
18 -- The parent session receives a visible return message containing the summary and child session path.
20 -## Non-goals
22 -- No visual workflow changes.
23 -- No worker prompt changes.
24 -- No new task state machine.
25 -- No UI redesign.
27 -## Files
29 -- `extensions/superpowers/index.ts`
30 -- `extensions/superpowers/__tests__/harness.test.ts`
32 -## Test Plan
34 -Add one harness test for the full branch/return path:
36 -1. Seed `tasks.json` with a task containing `parentSession`.
37 -2. Run `/superpowers branch sp-7`.
38 -3. Assert task state is `branched`.
39 -4. Assert `childSession` is written.
40 -5. Assert child takeover message exists and contains `/superpowers return <summary>`.
41 -6. Run `/superpowers return done` from the child context.
42 -7. Assert parent receives a structured return entry:
43 - - `kind: "return"`
44 - - `taskId: "sp-7"`
45 - - `summary: "done"`
46 - - `childSession` present
47 -8. Assert parent visible return message contains the summary.
49 -## Acceptance
51 -- `bun test extensions/superpowers/__tests__/harness.test.ts`
52 -- `mise run test -- superpowers`
53 -- `mise run build -- superpowers`

docs/superpowers/specs/2026-05-29-visual-command-lifecycle-design.md

Deleted
deleted file mode 100644
1 -# Visual Command Lifecycle Design
3 -## Goal
5 -Prove `/superpowers visual start/status/stop` as an end-to-end command loop that starts a local visual session, announces agent-readable paths, re-announces an existing session, and shuts down cleanly.
7 -## Contract
9 -- `/superpowers visual start` starts a local server under platform state.
10 -- Start reports URL, content dir, events file, and browser-open result to the user.
11 -- Start inserts a visible custom message into the chat/session for the agent.
12 -- The agent-facing message includes only actionable session data:
13 - - URL
14 - - content dir
15 - - events file
16 - - instruction to read the events file directly
17 -- The agent-facing message does not mention hidden/debug commands.
18 -- Re-running start while live re-announces the same session instead of starting another one.
19 -- `/superpowers visual status` reports URL, content dir, and events file.
20 -- `/superpowers visual stop` closes the server and clears the live session.
22 -## Non-goals
24 -- No browser automation.
25 -- No visual UI redesign.
26 -- No visual screen component changes.
27 -- No event command docs or autocomplete.
28 -- No automatic server start from strict mode.
30 -## Files
32 -- `extensions/superpowers/index.ts`
33 -- `extensions/superpowers/__tests__/harness.test.ts`
35 -## Test Plan
37 -Add one harness test with `PI_SUPERPOWERS_NO_OPEN=1`:
39 -1. Run `/superpowers visual start`.
40 -2. Assert notice contains `visual live`, `content`, `events file`, and manual-open fallback.
41 -3. Assert chat custom message contains URL, content dir, events file, and direct-read instruction.
42 -4. Assert chat custom message does not contain `visual events` or `hidden debug`.
43 -5. Run `/superpowers visual start` again.
44 -6. Assert the same session URL is re-announced.
45 -7. Run `/superpowers visual status`.
46 -8. Assert status contains URL, content dir, and events file.
47 -9. Run `/superpowers visual stop`.
48 -10. Assert stopped notice.
50 -## Acceptance
52 -- `bun test extensions/superpowers/__tests__/harness.test.ts`
53 -- `bun test extensions/superpowers/__tests__/*.test.ts`
54 -- `mise run test -- superpowers`
55 -- `mise run build -- superpowers`

extensions/TODO.md

Modified
1 1 # TODO
3 +## Skills
5 +- hypr:
6 + hyprland ecosystem and configs
7 +- archlinux
8 +- experiment:
9 + creating prototypes and experimenting, then cleaning up
3 11 ## Extensions
5 -- [ ] [diff-review](./diff-review/PLAN.md):
6 - browser review UI with Pierre Diffs/Trees (planned)
7 -- [ ] Port vibeguard plugin from opencode — extend with env var support
8 13 - [ ] Port agent identity plugin from opencode?
9 14 - [ ] Port model announcer plugin from opencode?
10 -- [ ] Implement extensions from optional/, by default off.
11 - can enable in config or flag
12 -- [ ] simplify remember and enhance:
13 - pipe to model, when creating new, amend by default, merge actions into widget.
14 - why is markdown still being created?
15 -- [ ] fix todo.ts:
16 - widget not in sync
17 -- [ ] fix cost.ts:
18 - monthly cost not shown
19 15 - [ ] impement minimax extension:
20 - access to minmax apis as tools (music, voice, etc)
16 + access to minmax apis as tools (music, voice, etc)
21 17 - [ ] pi-wtf:
22 - extension that scans session data for curse words and frustrations and show
23 - graph over time.
24 - check leaked claude code for killer regex.
25 -- [ ] pi-context:
26 - open whole context window in editor:
27 - grouped by:
28 - system, user, tools, agent
18 + extension that scans session data for curse words and frustrations and show
19 + graph over time.
20 + check leaked claude code for killer regex.
29 21 - [ ] pi-modes:
30 - opencode like modes, but simpler and for me
31 -- [ ] pi-snippets:
32 - expandable snippets in prompts (similar to inline)
33 -- [ ] pi-profiler:
34 - profile loading and execution of extensions
35 -- [ ] investigate:
36 - can prune_recall tool be only added after compaction?
22 + opencode like modes, but simpler and for me
38 24 ## TUI

extensions/diff-review/FEATURE-PARITY.md

Modified
2 2 # Feature Parity: Browser SPA → SSR
4 4 ## Source of truth: browser/index.ts features
6 -| # | Feature | Browser impl | SSR plan | Test strategy |
7 -|---|---------|-------------|----------|---------------|
8 -| 1 | **File tree** | `FileTree` web-component with search, expand, git status colors, rename decorations | `@pierre/trees/ssr` `preloadFileTree` + `serializeFileTreeSsrPayload` | Unit: assert serialized HTML contains all paths, git status attributes, search input. E2E: Playwright clicks a file, asserts diff scrolls into view. |
9 -| 2 | **Diff rendering** | `FileDiff` web-component, split view, syntax highlight, hover highlight, line selection | `@pierre/diffs/ssr` `preloadPatchDiff` per file or `preloadMultiFileDiff` | Unit: assert `prerenderedHTML` contains changed lines, line numbers, syntax tokens. E2E: Playwright asserts split columns exist. |
10 -| 3 | **Line selection** | `onLineSelected` / `onGutterUtilityClick` / `onLineClick` / `onLineNumberClick` callbacks → floating form | Inline `<form>` below each diff file, or server-rendered `<dialog>`; data attributes on lines for minimal JS targeting | Unit: POST `/finding` with line range → server stores finding. E2E: Playwright clicks line → form appears, fills, submits → finding visible in drawer. |
11 -| 4 | **Finding form** | Floating `<section>` with severity, category, comment, notes | Inline form or modal; POST to server | Unit: validation tests (existing `validateFinding` route). E2E: submit form → finding appears in findings list. |
12 -| 5 | **Findings list** | Drawer with numbered items, severity/category pills, remove button | Server-rendered findings panel; remove via POST or htmx | Unit: assert findings HTML renders pills. E2E: add finding → remove → count updates. |
13 -| 6 | **Review notes** | `<textarea id="notes">` | `<textarea name="notes">` in submit form | Unit: POST `/submit` passes notes to `onSubmit`. E2E: fill notes → submit → payload contains notes. |
14 -| 7 | **Search** | Client-side regex search across all diff lines, 200-result cap, keyboard nav, highlight animation | Server endpoint `GET /search?q=...` returns HTML partial with links to file+line | Unit: `searchCode` function extracted to shared module, tested in isolation. E2E: type query → results dropdown → click → jumps to line. |
15 -| 8 | **Theme** | `localStorage` + `matchMedia` → CSS custom properties on `:host` | `light-dark()` CSS + `prefers-color-scheme` media query; optional cookie toggle | Unit: assert HTML contains `color-scheme` meta. E2E: toggle → background color changes. |
16 -| 9 | **Pane resize/collapse** | Pointer events + `localStorage` layout state | CSS `grid` with `resize` on `<aside>`; or minimal inline JS + `localStorage` | E2E: drag splitter → width changes. Collapse button → pane hidden. |
17 -| 10 | **Meta display** | Round chip, source label, file stats, skipped files | Inline server-rendered `<div>` | Unit: assert HTML contains round number, source label, stats. |
18 -| 11 | **Carried findings** | `renderAnnotations` shows existing findings on diff lines | Pass `annotations` array to `preloadPatchDiff` options | Unit: assert preloaded HTML contains annotation chips. |
19 -| 12 | **Heartbeat** | `setInterval` POST `/api/heartbeat` | Unchanged — SPA JS still polls, or server SSE | Unit: existing heartbeat test passes. |
20 -| 13 | **Review polling / diff refresh** | `setInterval` GET `/api/review`, re-renders if hash changes | HTMX poll or meta refresh, or manual refresh button | Unit: `refreshDiff` called on submit. E2E: change file → refresh → diff updates. |
21 -| 14 | **Submit** | POST `/api/submit` JSON → clears findings, shows status | POST `/submit` form → redirects or returns success HTML | Unit: `onSubmit` called with findings + notes. E2E: submit → success message. |
22 -| 15 | **Cancel** | POST `/api/cancel` → `window.close()` hint | POST `/cancel` → close page or redirect | Unit: server closes, `result` promise resolves. |
6 +| # | Feature | Browser impl | SSR plan | Test strategy |
7 +| -- | --------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
8 +| 1 | **File tree** | `FileTree` web-component with search, expand, git status colors, rename decorations | `@pierre/trees/ssr` `preloadFileTree` + `serializeFileTreeSsrPayload` | Unit: assert serialized HTML contains all paths, git status attributes, search input. E2E: Playwright clicks a file, asserts diff scrolls into view. |
9 +| 2 | **Diff rendering** | `FileDiff` web-component, split view, syntax highlight, hover highlight, line selection | `@pierre/diffs/ssr` `preloadPatchDiff` per file or `preloadMultiFileDiff` | Unit: assert `prerenderedHTML` contains changed lines, line numbers, syntax tokens. E2E: Playwright asserts split columns exist. |
10 +| 3 | **Line selection** | `onLineSelected` / `onGutterUtilityClick` / `onLineClick` / `onLineNumberClick` callbacks → floating form | Inline `<form>` below each diff file, or server-rendered `<dialog>`; data attributes on lines for minimal JS targeting | Unit: POST `/finding` with line range → server stores finding. E2E: Playwright clicks line → form appears, fills, submits → finding visible in drawer. |
11 +| 4 | **Finding form** | Floating `<section>` with severity, category, comment, notes | Inline form or modal; POST to server | Unit: validation tests (existing `validateFinding` route). E2E: submit form → finding appears in findings list. |
12 +| 5 | **Findings list** | Drawer with numbered items, severity/category pills, remove button | Server-rendered findings panel; remove via POST or htmx | Unit: assert findings HTML renders pills. E2E: add finding → remove → count updates. |
13 +| 6 | **Review notes** | `<textarea id="notes">` | `<textarea name="notes">` in submit form | Unit: POST `/submit` passes notes to `onSubmit`. E2E: fill notes → submit → payload contains notes. |
14 +| 7 | **Search** | Client-side regex search across all diff lines, 200-result cap, keyboard nav, highlight animation | Server endpoint `GET /search?q=...` returns HTML partial with links to file+line | Unit: `searchCode` function extracted to shared module, tested in isolation. E2E: type query → results dropdown → click → jumps to line. |
15 +| 8 | **Theme** | `localStorage` + `matchMedia` → CSS custom properties on `:host` | `light-dark()` CSS + `prefers-color-scheme` media query; optional cookie toggle | Unit: assert HTML contains `color-scheme` meta. E2E: toggle → background color changes. |
16 +| 9 | **Pane resize/collapse** | Pointer events + `localStorage` layout state | CSS `grid` with `resize` on `<aside>`; or minimal inline JS + `localStorage` | E2E: drag splitter → width changes. Collapse button → pane hidden. |
17 +| 10 | **Meta display** | Round chip, source label, file stats, skipped files | Inline server-rendered `<div>` | Unit: assert HTML contains round number, source label, stats. |
18 +| 11 | **Carried findings** | `renderAnnotations` shows existing findings on diff lines | Pass `annotations` array to `preloadPatchDiff` options | Unit: assert preloaded HTML contains annotation chips. |
19 +| 12 | **Heartbeat** | `setInterval` POST `/api/heartbeat` | Unchanged — SPA JS still polls, or server SSE | Unit: existing heartbeat test passes. |
20 +| 13 | **Review polling / diff refresh** | `setInterval` GET `/api/review`, re-renders if hash changes | HTMX poll or meta refresh, or manual refresh button | Unit: `refreshDiff` called on submit. E2E: change file → refresh → diff updates. |
21 +| 14 | **Submit** | POST `/api/submit` JSON → clears findings, shows status | POST `/submit` form → redirects or returns success HTML | Unit: `onSubmit` called with findings + notes. E2E: submit → success message. |
22 +| 15 | **Cancel** | POST `/api/cancel` → `window.close()` hint | POST `/cancel` → close page or redirect | Unit: server closes, `result` promise resolves. |
24 24 ## Test layers
26 -1. **Unit (vitest)** — Shared logic: `searchCode`, `renderPage`, `renderFindings`, form parsing, theme CSS.
27 -2. **Integration (vitest + Node `http`)** — Spin up `startReviewServer`, hit all routes, assert HTML/JSON responses, state mutations.
28 -3. **E2E (Playwright)** — Start dev server with fixture diff, automate Chrome/Firefox: add finding, search, submit, cancel, theme toggle, pane resize.
29 -4. **Pi harness (existing)** — `harness.test.ts` validates extension loads, commands work, no UI mutation after shutdown.
26 +1. **Unit (vitest)** — Shared logic:
27 + `searchCode`, `renderPage`, `renderFindings`, form parsing, theme CSS.
28 +2. **Integration (vitest + Node `http`)** — Spin up `startReviewServer`, hit all
29 + routes, assert HTML/JSON responses, state mutations.
30 +3. **E2E (Playwright)** — Start dev server with fixture diff, automate
31 + Chrome/Firefox:
32 + add finding, search, submit, cancel, theme toggle, pane resize.
33 +4. **Pi harness (existing)** — `harness.test.ts` validates extension loads,
34 + commands work, no UI mutation after shutdown.
31 36 ## Migration checklist
34 39 - [x] `render.ts` module created with `renderPage`, `renderFindings` (Phase 2)
35 40 - [x] `server.ts` serves HTML instead of static bundle (Phase 3)
36 41 - [x] `index.ts` removes `ensureBrowserBundle` (Phase 4)
37 -- [x] Cleanup: `bundle.ts`, `browser/`, old `scripts/` deleted (Phase 5)
38 -- [x] `scripts/dev-server.ts` starts fixture server for manual Chrome/Firefox testing (Phase 6)
42 +- [x] Cleanup:
43 + `bundle.ts`, `browser/`, old `scripts/` deleted (Phase 5)
44 +- [x] `scripts/dev-server.ts` starts fixture server for manual Chrome/Firefox
45 + testing (Phase 6)
39 46 - [x] Full `vitest run` passes (15/15)
40 47 - [x] Manual smoke verified via `curl` + dev server
41 48 - [x] Line selection / inline finding form interactivity

extensions/diff-review/README.md

Modified
4 4 # diff-review
6 6 Server-rendered UI for reviewing git diffs and sending findings back to Pi.
8 8 <!-- demo:diff-review:start -->
10 -| **Pi bridge** |
10 +| **Pi bridge** |
11 11 | --------------------------------------------- |
12 12 | ![Pi bridge](assets/diff_review_terminal.gif) |
72 72 - Opens the browser via platform opener when available; otherwise Pi shows the
74 74 - Server renders a file tree, split diffs, and findings panel as HTML.
75 -- Minimal inline JS handles line selection, theme toggle, pane layout, and
76 - code search.
75 +- Minimal inline JS handles line selection, theme toggle, pane layout, and code
76 + search.
77 77 - Browser fetches current review data, polls for diff changes every 2s, and
78 78 refreshes diff before submit.
79 79 - Browser posts heartbeat every 5s.

extensions/diff-review/TODO.md

Modified
2 2 # diff-review rewrite plan
4 4 ## Goal
6 -Eliminate Bun dependency entirely. Replace browser SPA with server-side rendering.
6 +Eliminate Bun dependency entirely.
7 +Replace browser SPA with server-side rendering.
8 9 ## Status
10 -**COMPLETE.** All features implemented. 25 unit tests + 9 E2E tests pass. Bun dependency removed. Feature parity achieved.
11 +**COMPLETE.** All features implemented.
12 +25 unit tests + 9 E2E tests pass.
13 +Bun dependency removed.
14 +Feature parity achieved.
12 16 ## What was done

extensions/superpowers/README.md

Modified
9 9 pi -e ./extensions/superpowers/index.ts --superpowers
12 -`/superpowers` toggles strict upstream-style workflow discipline for the current session.
12 +`/superpowers` toggles strict upstream-style workflow discipline for the current
13 +session.
13 14 `--superpowers` starts with that mode already enabled.
15 -Strict mode means future non-trivial coding turns must pick and follow the smallest applicable Superpowers workflow, then verify before claiming completion.
16 +Strict mode means future non-trivial coding turns must pick and follow the
17 +smallest applicable Superpowers workflow, then verify before claiming
18 +completion.
17 -Prompts/skills remain installed and manually callable when off. Off only disables automatic methodology pressure.
18 -No always-on activation unless you opt in. No hidden agents.
20 +Prompts/skills remain installed and manually callable when off.
21 +Off only disables automatic methodology pressure.
22 +No always-on activation unless you opt in.
23 +No hidden agents.
20 25 ## Commands
52 57 ## Prompt frontmatter
54 -Agents are normal Pi prompt templates (`prompts/*.md`). Supported frontmatter:
59 +Agents are normal Pi prompt templates (`prompts/*.md`).
60 +Supported frontmatter:
56 62 ```yaml
57 63 description: Run a focused code review
63 69 accent: syntaxKeyword
66 -| Field | Purpose |
67 -|---|---|
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) |
72 +| Field | Purpose |
73 +| --------------- | ------------------------------------------------------------------ |
74 +| `description` | Shown in autocomplete and status |
75 +| `argument-hint` | Autocomplete hint for arguments |
76 +| `tools` | Tool allowlist for the subagent |
77 +| `extensions` | Extension filter (`*` = all, `-name` = exclude) |
78 +| `thinking` | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
79 +| `model` | Override model: `provider/id` |
80 +| `accent` | Theme color for footer/widget/status rendering (see below) |
76 82 ### `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.
84 +Controls the visual identity of a worker in the footer, widget, and status
85 +output.
86 +Value is a `ThemeColor` name from Pi's theme system.
87 +The color resolves to whatever the active theme defines for that semantic role,
88 +so it adapts to light/dark themes automatically.
82 90 **Recommended accents per workflow:**
84 -| Workflow | Accent | Visual feel |
85 -|---|---|---|
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 |
92 +| Workflow | Accent | Visual feel |
93 +| -------------------------------- | ---------------- | ----------------------- |
94 +| `brainstorming` | `accent` | purple — creative |
95 +| `writing-plans` | `dim` | quiet — preparation |
96 +| `executing-plans` | `success` | green — building |
97 +| `test-driven-development` | `syntaxString` | green tint — test-first |
98 +| `systematic-debugging` | `warning` | yellow — caution |
99 +| `requesting-code-review` | `syntaxKeyword` | amber — critical eye |
100 +| `receiving-code-review` | `syntaxFunction` | blue — integration |
101 +| `verification-before-completion` | `toolTitle` | cyan — verification |
102 +| `dispatching-parallel-agents` | `syntaxVariable` | distinct — multi-agent |
103 +| `using-git-worktrees` | `muted` | gray — infrastructure |
104 +| `writing-skills` | `syntaxFunction` | blue — meta-work |
98 106 **Full `ThemeColor` palette** (51 names, all valid for `accent`):
157 165 selectedBg # (ThemeBg, not ThemeColor — for backgrounds)
160 -Without an `accent` field, workers default to the extension's accent color (amber `syntaxKeyword` for review, etc.).
168 +Without an `accent` field, workers default to the extension's accent color
169 +(amber `syntaxKeyword` for review, etc.).
162 171 ## Bundled workflows
178 187 /writing-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.
190 +`skills/*/SKILL.md` holds the methodology.
191 +`prompts/*.md` are normal Pi slash prompt wrappers with the full skill inlined —
192 +no runtime skill discovery needed.
183 194 Same prompts work as background workers:
190 201 ## 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.
203 +By default, `/superpowers run` and workflow aliases create an isolated
204 +worktree/workspace for the subagent.
205 +This prevents filesystem collisions between concurrent tasks and keeps the
206 +parent working copy clean.
194 -| Repo type | Isolation mechanism | Path |
195 -|---|---|---|
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 | — |
208 +| Repo type | Isolation mechanism | Path |
209 +| ----------------------- | ------------------- | --------------------- |
210 +| Git standard checkout | `git worktree add` | `.git/wt-<id>` |
211 +| Git bare (co/wt layout) | `git worktree add` | `<root>/<id>` |
212 +| Jujutsu (jj) | `jj workspace add` | `.jj/workspaces/<id>` |
213 +| No repo detected | in-place fallback | — |
201 215 Use `--share` to run the subagent in the current working copy instead:
207 221 Isolation is skipped when:
208 223 - `--share` is passed explicitly
209 224 - No supported repo is detected
210 225 - 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`.
227 +On abort, isolated worktrees are cleaned up automatically.
228 +On successful completion, they are left for inspection — remove them manually or
229 +with `git worktree remove` / `jj workspace forget`.
214 231 ## Status display
216 233 The footer and widget use compact, scannable formatting:
218 235 **Footer** (status bar):
219 237 ```text
220 238 on # strict mode active
221 239 on 1↑ # 1 worker running
226 244 **Widget** (above editor, when workers run):
227 246 ```text
228 247 2 workers running
229 248 ▶ sp-5 review 12s · 5 tools
233 252 **Status icons:**
234 254 ```text
235 255 ▶ running ✓ done ⊘ aborted ✗ error ⤴ branched
238 258 **Agent short names:**
239 260 ```text
240 261 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.
264 +`/superpowers status` lists all tasks.
265 +`/superpowers status <id>` shows full details.
245 267 ## State
261 283 visual/ # visual brainstorming state (ephemeral)
264 -Stale tasks (orphaned when the parent Pi session dies) are reaped on next session start.
286 +Stale tasks (orphaned when the parent Pi session dies) are reaped on next
287 +session start.
266 -Project/VCS state is only written by workflows that intentionally create docs/specs, e.g. `docs/superpowers/specs/...`.
289 +Project/VCS state is only written by workflows that intentionally create
290 +docs/specs, e.g. `docs/superpowers/specs/...`.
268 292 ## Architecture
274 298 return = ctx.switchSession(parent)
277 -No Pi subprocesses. Uses Pi SDK sessions/resource loading directly.
301 +No Pi subprocesses.
302 +Uses Pi SDK sessions/resource loading directly.
279 -No Pi subprocesses. Uses Pi SDK sessions/resource loading directly.
304 +No Pi subprocesses.
305 +Uses Pi SDK sessions/resource loading directly.

extensions/superpowers/docs-visual-brainstorming.md

Modified
1 1 # Visual Brainstorming Research
3 -Source inspected: upstream `obra/superpowers` brainstorming skill and visual companion docs.
3 +Source inspected:
4 +upstream `obra/superpowers` brainstorming skill and visual companion docs.
5 6 ## How upstream works
7 -Visual brainstorming is not a separate mode. It is an optional browser companion offered during brainstorming when upcoming questions are easier to answer visually.
8 +Visual brainstorming is not a separate mode.
9 +It is an optional browser companion offered during brainstorming when upcoming
10 +questions are easier to answer visually.
9 12 Flow:
16 19 6. User clicks options/cards/mockups in browser and also responds in terminal.
17 20 7. Browser events are stored as JSONL in a state directory.
18 21 8. Agent reads events next turn and merges them with terminal feedback.
19 -9. For non-visual questions, agent pushes a waiting screen and continues in terminal.
22 +9. For non-visual questions, agent pushes a waiting screen and continues in
23 + terminal.
21 25 ## UX rules
23 27 - Offer visual companion once, in its own message.
24 28 - Decide per question whether visual helps.
25 -- Use browser for mockups, wireframes, diagrams, layout/color/design comparisons.
29 +- Use browser for mockups, wireframes, diagrams, layout/color/design
30 + comparisons.
26 31 - Use terminal for requirements, scope, text tradeoffs, technical decisions.
27 32 - Visual companion is an active decision aid, not a reporting dashboard.
28 -- Every visual screen must ask a question, present selectable options, or show a mockup/diagram the user is meant to judge.
29 -- Do not use visual screens for progress updates, implementation summaries, final reports, or proof-of-work slides.
33 +- Every visual screen must ask a question, present selectable options, or show a
34 + mockup/diagram the user is meant to judge.
35 +- Do not use visual screens for progress updates, implementation summaries,
36 + final reports, or proof-of-work slides.
30 37 - Use `data-choice` for clickable options; browser JS auto-records clicks.
31 -- After writing a decision screen, wait for terminal response or browser event before implementing.
38 +- After writing a decision screen, wait for terminal response or browser event
39 + before implementing.
32 40 - User terminal response remains primary; click events are supporting evidence.
33 41 - Each screen uses a new semantic filename.
34 -- Stale screens should be replaced with “Continuing in terminal…” when leaving visual mode.
35 -- End of visual phase: ask whether to leave browser open for inspection or stop it with `/superpowers visual stop`.
42 +- Stale screens should be replaced with “Continuing in terminal…” when leaving
43 + visual mode.
44 +- End of visual phase:
45 + ask whether to leave browser open for inspection or stop it with `/superpowers
46 + visual stop`.
37 48 ## Technical shape
43 54 - wraps HTML fragments in a frame template
44 55 - injects helper JS
45 56 - records clicks/selections to JSONL events file
46 -- auto-records clicks on `[data-choice]` elements so agents do not need inline JS
57 +- auto-records clicks on `[data-choice]` elements so agents do not need inline
58 + JS
47 59 - uses polling reload to update browser
48 60 - stores session under project `.superpowers/brainstorm/...`
61 73 - Keep visual brainstorming explicitly activated by brainstorming workflow.
62 74 - Do not make it a hidden hook.
63 -- It should be an explicit `/superpowers visual ...` tool, not automatic strict-mode behavior.
64 -- Store ephemeral files under platform state, not the repo: `${XDG_STATE_HOME:-~/.local/state}/pi/superpowers/<project-hash>/visual/...` on Linux, native equivalents on macOS/Windows.
75 +- It should be an explicit `/superpowers visual ...` tool, not automatic
76 + strict-mode behavior.
77 +- Store ephemeral files under platform state, not the repo:
78 + `${XDG_STATE_HOME:-~/.local/state}/pi/superpowers/<project-hash>/visual/...`
79 + on Linux, native equivalents on macOS/Windows.
65 80 - Use Pi UI notification and a visible session message to show URL and paths.
66 81 - Use `read`/`write` tool workflow for screens/events.
67 -- Create the events JSONL file at start so agent reads never fail before the first browser click.
82 +- Create the events JSONL file at start so agent reads never fail before the
83 + first browser click.
68 84 - Close server on `/superpowers visual stop` and session shutdown.
69 -- Keep zero dependency: Node built-ins or Bun server only.
85 +- Keep zero dependency:
86 + Node built-ins or Bun server only.
71 88 ## Recommended Pi UX
108 125 - Do not force browser for conceptual questions.
109 126 - Do not use visual companion as a status board or final report.
110 127 - Do not let visual companion skip design approval/spec gates.
111 -- Do not store under non-Pi `.superpowers` unless intentionally matching upstream.
128 +- Do not store under non-Pi `.superpowers` unless intentionally matching
129 + upstream.
112 130 - Do not make visual server start automatically on `/superpowers on`.

extensions/superpowers/prompts/brainstorming.md

Modified
6 6 accent: accent
10 9 # Brainstorming
12 -Design before code. No exceptions for “simple” work.
11 +Design before code.
12 +No exceptions for “simple” work.
14 14 ## Hard gate
16 -Do not implement, scaffold, edit production code, or invoke implementation workflows until:
16 +Do not implement, scaffold, edit production code, or invoke implementation
17 +workflows until:
18 19 1. design was presented,
19 20 2. user approved it,
21 22 4. spec self-review passed,
22 23 5. user approved the written spec.
24 -Tiny tasks may have tiny designs. They still need approval.
25 +Tiny tasks may have tiny designs.
26 +They still need approval.
26 28 ## Flow
36 38 5. Recommend one.
37 39 6. Present design in small sections.
38 40 7. Ask approval after each section.
39 -8. Write spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` unless project rules say otherwise.
41 +8. Write spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` unless
42 + project rules say otherwise.
40 43 9. Self-review spec; fix placeholders, contradictions, ambiguity, overscope.
41 44 10. Commit the spec when project workflow uses git and project rules allow it.
42 45 11. Ask user to review spec file.
52 55 ## Design sections
54 -Scale section length to complexity. Cover only relevant sections:
57 +Scale section length to complexity.
58 +Cover only relevant sections:
56 60 - goal and non-goals
57 61 - UX/API behavior
58 62 - architecture/components
59 63 - data flow/state
60 -- component boundaries: single responsibility, clear interfaces, independent tests
64 +- component boundaries:
65 + single responsibility, clear interfaces, independent tests
61 66 - errors/failure modes
62 67 - testing/proof
63 68 - migration/rollout, only if truly needed
118 123 ## Visual companion
120 -Use only when seeing beats reading: mockups, layouts, palettes, diagrams, side-by-side UX choices.
125 +Use only when seeing beats reading:
126 +mockups, layouts, palettes, diagrams, side-by-side UX choices.
122 -This is an active decision aid, not a reporting dashboard. Every visual screen must either ask a question, present selectable options, or show a mockup/diagram the user is meant to judge. Do not use it for progress updates, implementation summaries, final reports, or proof-of-work slides.
128 +This is an active decision aid, not a reporting dashboard.
129 +Every visual screen must either ask a question, present selectable options, or
130 +show a mockup/diagram the user is meant to judge.
131 +Do not use it for progress updates, implementation summaries, final reports, or
132 +proof-of-work slides.
124 134 Offer in its own message:
132 142 1. Ask user to run `/superpowers visual start` if not already live.
133 143 2. Use returned `content` dir.
134 144 3. Write one fresh `.html` fragment per decision screen.
135 -4. Each screen must include a clear prompt/question and obvious clickable choices when choice is useful.
136 -5. Use `data-choice="..."` on clickable options; the browser records those clicks automatically.
145 +4. Each screen must include a clear prompt/question and obvious clickable
146 + choices when choice is useful.
147 +5. Use `data-choice="..."` on clickable options; the browser records those
148 + clicks automatically.
137 149 6. Tell user the URL and the exact decision you need from the screen.
138 150 7. Ask user to click/select if useful and answer in terminal.
139 -8. Wait for a terminal answer or browser event before implementing from a visual decision screen.
140 -9. Read the events file path announced by `/superpowers visual start` directly when interpreting browser feedback.
141 -10. After the visual decision is resolved, push a waiting screen saying `Continuing in terminal…` before returning to text-only discussion.
142 -11. At the end of the visual phase, ask whether to leave the browser companion open for inspection or stop it with `/superpowers visual stop`.
151 +8. Wait for a terminal answer or browser event before implementing from a visual
152 + decision screen.
153 +9. Read the events file path announced by `/superpowers visual start` directly
154 + when interpreting browser feedback.
155 +10. After the visual decision is resolved, push a waiting screen saying
156 + `Continuing in terminal…` before returning to text-only discussion.
157 +11. At the end of the visual phase, ask whether to leave the browser companion
158 + open for inspection or stop it with `/superpowers visual stop`.
144 -Visual state is ephemeral platform state, not project files. Specs/design docs remain project files when approved.
160 +Visual state is ephemeral platform state, not project files.
161 +Specs/design docs remain project files when approved.
146 163 Target:

extensions/superpowers/prompts/dispatching-parallel-agents.md

Modified
6 6 accent: syntaxVariable
10 9 # Dispatching Parallel Agents
12 -Parallel only when independent. One worker per independent problem domain.
11 +Parallel only when independent.
12 +One worker per independent problem domain.
14 14 ## Independence test
43 43 - final verify: ...
46 -After workers return: read summaries, inspect changed files, check conflicts, run final verification.
46 +After workers return:
47 +read summaries, inspect changed files, check conflicts, run final verification.
48 49 ## Law
50 -Benchmark prompts must stay fair/profile-neutral. Do not steer toward a tool just to make an extension look good.
51 +Benchmark prompts must stay fair/profile-neutral.
52 +Do not steer toward a tool just to make an extension look good.
52 54 Target:

extensions/superpowers/prompts/executing-plans.md

Modified
6 6 accent: success
10 9 # Executing Plans
12 -Implement plan. Do not improvise silently.
11 +Implement plan.
12 +Do not improvise silently.
14 14 ## Loop

extensions/superpowers/prompts/finishing-a-development-branch.md

Modified
6 6 accent: dim
10 9 # Finishing a Development Branch
12 11 Finish cleanly.
24 23 - discard
25 24 6. Cleanup only after explicit choice.
26 25 7. For discard, require typed confirmation.
27 -8. Remove only worktrees this workflow owns; never delete harness-owned workspace.
26 +8. Remove only worktrees this workflow owns; never delete harness-owned
27 + workspace.
29 29 ## Output

extensions/superpowers/prompts/receiving-code-review.md

Modified
6 6 accent: syntaxFunction
10 9 # Receiving Code Review
12 11 Address review without churn.
37 36 ## Anti-patterns
39 -- Performative agreement before checking: “absolutely right”, “great point”.
38 +- Performative agreement before checking:
39 + “absolutely right”, “great point”.
40 40 - Blindly implementing external review without codebase verification.
41 41 - Rewriting whole module to fix one finding.
42 42 - “Addressed” without commit/file/test evidence.

extensions/superpowers/prompts/requesting-code-review.md

Modified
6 6 accent: syntaxKeyword
10 9 # Requesting Code Review
12 -Review only. Do not edit.
11 +Review only.
12 +Do not edit.
14 -No politeness tax. No generic praise. Findings need evidence.
14 +No politeness tax.
15 +No generic praise.
16 +Findings need evidence.
16 18 ## Inputs
68 70 - under-abstracted repeated logic likely to drift
69 71 - dead layers, needless adapters, repeated conversions
71 -Compression is not code golf. Prefer one good abstraction over many clever ones.
73 +Compression is not code golf.
74 +Prefer one good abstraction over many clever ones.
73 76 ## Pass 5 — Handmade UX/Style Gate
84 87 ## Severity
86 -- BLOCKER: incorrect, unsafe, untested critical path, violates spec, or fake completion.
87 -- MAJOR: likely bug, bad API, serious slop, duplicated design risk, missing important proof.
88 -- MINOR: cleanup, naming, small simplification.
89 -- NOTE: observation, no action required.
89 +- BLOCKER:
90 + incorrect, unsafe, untested critical path, violates spec, or fake completion.
91 +- MAJOR:
92 + likely bug, bad API, serious slop, duplicated design risk, missing important
93 + proof.
94 +- MINOR:
95 + cleanup, naming, small simplification.
96 +- NOTE:
97 + observation, no action required.
91 99 ## Output
114 122 ## Follow-up
116 -- Critical/BLOCKER and MAJOR findings must be fixed or explicitly rejected with evidence before proceeding.
117 -- If findings exist: use `receiving-code-review`.
118 -- If fixes are large: write a plan first.
119 -- If review passes: run `verification-before-completion` before claiming shipped.
124 +- Critical/BLOCKER and MAJOR findings must be fixed or explicitly rejected with
125 + evidence before proceeding.
126 +- If findings exist:
127 + use `receiving-code-review`.
128 +- If fixes are large:
129 + write a plan first.
130 +- If review passes:
131 + run `verification-before-completion` before claiming shipped.
121 133 Target:

extensions/superpowers/prompts/subagent-driven-development.md

Modified
6 6 accent: syntaxVariable
10 9 # Subagent-Driven Development
12 -Workers implement. Parent owns quality. Continue task-by-task without “should I continue?” check-ins unless blocked.
11 +Workers implement.
12 +Parent owns quality.
13 +Continue task-by-task without “should I continue?” check-ins unless blocked.
14 15 ## Process
16 -1. Require approved spec/plan. If absent, use `brainstorming` or `writing-plans`.
17 +1. Require approved spec/plan.
18 + If absent, use `brainstorming` or `writing-plans`.
17 19 2. Extract each task with full text and needed context.
18 -3. Create one worker prompt per bounded task. Do not make worker read the whole plan if the task text can be provided.
20 +3. Create one worker prompt per bounded task.
21 + Do not make worker read the whole plan if the task text can be provided.
19 22 4. Run worker with `/superpowers run <prompt> ...`.
20 23 5. Inspect result with `/superpowers status <id>` or `/superpowers open <id>`.
21 -6. Handle worker state: done → review; needs-context → provide context; blocked → change prompt/model/scope or escalate.
24 +6. Handle worker state:
25 + done → review; needs-context → provide context; blocked → change
26 + prompt/model/scope or escalate.
22 27 7. Review twice, in order:
23 28 - spec compliance
24 29 - code quality/simplicity

extensions/superpowers/prompts/systematic-debugging.md

Modified
6 6 accent: warning
10 9 # Systematic Debugging
12 11 No fix before root-cause evidence.
14 13 ## Phases
16 -1. Reproduce: exact command/input and observed failure. If not reproducible, gather more data; do not guess.
15 +1. Reproduce:
16 + exact command/input and observed failure.
17 + If not reproducible, gather more data; do not guess.
17 18 2. Read errors fully; check recent changes and relevant config/env.
18 -3. Pattern analysis: find working examples and compare exact differences.
19 -4. Trace: follow data/control flow to root cause.
20 -5. Hypothesis: one cause, one prediction, one test.
21 -6. Fix: smallest root-cause change, preferably after a failing regression test.
22 -7. Verify: original failure + nearby regression.
19 +3. Pattern analysis:
20 + find working examples and compare exact differences.
21 +4. Trace:
22 + follow data/control flow to root cause.
23 +5. Hypothesis:
24 + one cause, one prediction, one test.
25 +6. Fix:
26 + smallest root-cause change, preferably after a failing regression test.
27 +7. Verify:
28 + original failure + nearby regression.
24 30 ## Three-strike rule
26 -After 3 failed fixes, stop. Request architecture/design review.
32 +After 3 failed fixes, stop.
33 +Request architecture/design review.
28 35 ## Output

extensions/superpowers/prompts/test-driven-development.md

Modified
6 6 accent: syntaxString
10 9 # Test-Driven Development
12 -RED first. No production code without a failing test first.
11 +RED first.
12 +No production code without a failing test first.
14 -If production code was written first, delete it and restart from RED. Do not keep it as reference.
14 +If production code was written first, delete it and restart from RED.
15 +Do not keep it as reference.
16 17 ## Loop
18 19 1. Write smallest failing test.
19 -2. Run it. Confirm failure is expected.
20 +2. Run it.
21 + Confirm failure is expected.
20 22 3. Implement smallest passing code.
21 -4. Run focused test. Green.
23 +4. Run focused test.
24 + Green.
22 25 5. Refactor only to simplify.
23 26 6. Run focused test again.
24 27 7. Run relevant full suite.

extensions/superpowers/prompts/using-git-worktrees.md

Modified
6 6 accent: muted
10 9 # Using Git Worktrees
12 -Protect trunk. Isolate risk.
11 +Protect trunk.
12 +Isolate risk.
14 14 ## Before creating
31 31 - dirty status
32 32 - likely trunk (`main`, `master`, `trunk`, `develop`)
34 -If current worktree is dirty, do not hide it. Ask or choose a safe path.
34 +If current worktree is dirty, do not hide it.
35 +Ask or choose a safe path.
36 37 ## Process
38 39 1. Prefer host/native worktree tools if available.
39 40 2. Pick branch name from task.
40 41 3. Create worktree outside current directory.
41 -4. If using project-local `.worktrees/` or `worktrees/`, verify path is gitignored first.
42 +4. If using project-local `.worktrees/` or `worktrees/`, verify path is
43 + gitignored first.
42 44 5. Run setup/baseline tests there.
43 45 6. Do implementation only in worktree.
44 46 7. Finish with `finishing-a-development-branch`.

extensions/superpowers/prompts/using-superpowers.md

Modified
6 6 accent: accent
10 9 # Using Superpowers
12 -Superpowers = process discipline. Not vibes.
11 +Superpowers = process discipline.
12 +Not vibes.
14 14 ## Rule
16 16 Before non-trivial work, choose and follow one workflow skill:
18 -| Situation | Skill |
19 -|---|---|
20 -| fuzzy feature/design | `brainstorming` |
21 -| approved design → tasks | `writing-plans` |
22 -| plan exists → implement | `executing-plans` |
23 -| independent subtasks | `dispatching-parallel-agents` |
24 -| worker + review loop | `subagent-driven-development` |
25 -| code change with testable behavior | `test-driven-development` |
26 -| bug/regression/flake | `systematic-debugging` |
27 -| before saying done | `verification-before-completion` |
28 -| isolated branch needed | `using-git-worktrees` |
29 -| branch is complete | `finishing-a-development-branch` |
30 -| creating/revising skills | `writing-skills` |
18 +| Situation | Skill |
19 +| ---------------------------------- | -------------------------------- |
20 +| fuzzy feature/design | `brainstorming` |
21 +| approved design → tasks | `writing-plans` |
22 +| plan exists → implement | `executing-plans` |
23 +| independent subtasks | `dispatching-parallel-agents` |
24 +| worker + review loop | `subagent-driven-development` |
25 +| code change with testable behavior | `test-driven-development` |
26 +| bug/regression/flake | `systematic-debugging` |
27 +| before saying done | `verification-before-completion` |
28 +| isolated branch needed | `using-git-worktrees` |
29 +| branch is complete | `finishing-a-development-branch` |
30 +| creating/revising skills | `writing-skills` |
32 -Load the selected skill before acting. If multiple skills apply, use the earliest lifecycle gate: brainstorming → writing-plans → execution/TDD/debug → review → verification → finishing.
32 +Load the selected skill before acting.
33 +If multiple skills apply, use the earliest lifecycle gate:
34 +brainstorming → writing-plans → execution/TDD/debug → review → verification →
35 +finishing.
34 37 ## Local style
57 60 /superpowers run <prompt> ...
60 -Use workers for isolated investigation/implementation. Parent integrates.
63 +Use workers for isolated investigation/implementation.
64 +Parent integrates.
62 66 Target:

extensions/superpowers/prompts/verification-before-completion.md

Modified
6 6 accent: toolTitle
10 9 # Verification Before Completion
12 -No fresh proof → not done. Evidence before claims.
11 +No fresh proof → not done.
12 +Evidence before claims.
14 14 ## Checklist

extensions/superpowers/prompts/writing-plans.md

Modified
6 6 accent: dim
10 9 # Writing Plans
12 11 Plan for a fast careless implementer with zero project context.
14 -Save plans to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` unless project rules say otherwise.
13 +Save plans to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` unless project
14 +rules say otherwise.
16 16 ## Task requirements
47 47 - Mark unknown decisions `[?]`; stop before passing them.
48 48 - No `TODO`/`TBD`/`similar to task N`/`write tests for above` placeholders.
49 49 - No “refactor architecture” without file-level detail.
50 -- Self-review plan against spec: coverage, placeholders, type/name consistency.
50 +- Self-review plan against spec:
51 + coverage, placeholders, type/name consistency.
51 52 - End by offering `subagent-driven-development` or `executing-plans`.
53 54 Target:

extensions/superpowers/prompts/writing-skills.md

Modified
6 6 accent: syntaxFunction
10 9 # Writing Skills
12 -Skills are operational memory. Keep them sharp.
11 +Skills are operational memory.
12 +Keep them sharp.
14 14 ## Required shape
36 36 ## Test
38 -Use TDD for skills: first write a case where current behavior would not load/follow the skill, then update the skill until it passes.
38 +Use TDD for skills:
39 +first write a case where current behavior would not load/follow the skill, then
40 +update the skill until it passes.
40 42 Create trigger cases:

extensions/superpowers/skills/brainstorming/SKILL.md

Modified
6 6 # Brainstorming
8 -Design before code. No exceptions for “simple” work.
8 +Design before code.
9 +No exceptions for “simple” work.
10 11 ## Hard gate
12 -Do not implement, scaffold, edit production code, or invoke implementation workflows until:
13 +Do not implement, scaffold, edit production code, or invoke implementation
14 +workflows until:
14 16 1. design was presented,
15 17 2. user approved it,
17 19 4. spec self-review passed,
18 20 5. user approved the written spec.
20 -Tiny tasks may have tiny designs. They still need approval.
22 +Tiny tasks may have tiny designs.
23 +They still need approval.
22 25 ## Flow
32 35 5. Recommend one.
33 36 6. Present design in small sections.
34 37 7. Ask approval after each section.
35 -8. Write spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` unless project rules say otherwise.
38 +8. Write spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` unless
39 + project rules say otherwise.
36 40 9. Self-review spec; fix placeholders, contradictions, ambiguity, overscope.
37 41 10. Commit the spec when project workflow uses git and project rules allow it.
38 42 11. Ask user to review spec file.
48 52 ## Design sections
50 -Scale section length to complexity. Cover only relevant sections:
54 +Scale section length to complexity.
55 +Cover only relevant sections:
52 57 - goal and non-goals
53 58 - UX/API behavior
54 59 - architecture/components
55 60 - data flow/state
56 -- component boundaries: single responsibility, clear interfaces, independent tests
61 +- component boundaries:
62 + single responsibility, clear interfaces, independent tests
57 63 - errors/failure modes
58 64 - testing/proof
59 65 - migration/rollout, only if truly needed
114 120 ## Visual companion
116 -Use only when seeing beats reading: mockups, layouts, palettes, diagrams, side-by-side UX choices.
122 +Use only when seeing beats reading:
123 +mockups, layouts, palettes, diagrams, side-by-side UX choices.
118 -This is an active decision aid, not a reporting dashboard. Every visual screen must either ask a question, present selectable options, or show a mockup/diagram the user is meant to judge. Do not use it for progress updates, implementation summaries, final reports, or proof-of-work slides.
125 +This is an active decision aid, not a reporting dashboard.
126 +Every visual screen must either ask a question, present selectable options, or
127 +show a mockup/diagram the user is meant to judge.
128 +Do not use it for progress updates, implementation summaries, final reports, or
129 +proof-of-work slides.
120 131 Offer in its own message:
128 139 1. Ask user to run `/superpowers visual start` if not already live.
129 140 2. Use returned `content` dir.
130 141 3. Write one fresh `.html` fragment per decision screen.
131 -4. Each screen must include a clear prompt/question and obvious clickable choices when choice is useful.
132 -5. Use `data-choice="..."` on clickable options; the browser records those clicks automatically.
142 +4. Each screen must include a clear prompt/question and obvious clickable
143 + choices when choice is useful.
144 +5. Use `data-choice="..."` on clickable options; the browser records those
145 + clicks automatically.
133 146 6. Tell user the URL and the exact decision you need from the screen.
134 147 7. Ask user to click/select if useful and answer in terminal.
135 -8. Wait for a terminal answer or browser event before implementing from a visual decision screen.
136 -9. Read the events file path announced by `/superpowers visual start` directly when interpreting browser feedback.
137 -10. After the visual decision is resolved, push a waiting screen saying `Continuing in terminal…` before returning to text-only discussion.
138 -11. At the end of the visual phase, ask whether to leave the browser companion open for inspection or stop it with `/superpowers visual stop`.
148 +8. Wait for a terminal answer or browser event before implementing from a visual
149 + decision screen.
150 +9. Read the events file path announced by `/superpowers visual start` directly
151 + when interpreting browser feedback.
152 +10. After the visual decision is resolved, push a waiting screen saying
153 + `Continuing in terminal…` before returning to text-only discussion.
154 +11. At the end of the visual phase, ask whether to leave the browser companion
155 + open for inspection or stop it with `/superpowers visual stop`.
140 -Visual state is ephemeral platform state, not project files. Specs/design docs remain project files when approved.
157 +Visual state is ephemeral platform state, not project files.
158 +Specs/design docs remain project files when approved.

extensions/superpowers/skills/dispatching-parallel-agents/SKILL.md

Modified
6 6 # Dispatching Parallel Agents
8 -Parallel only when independent. One worker per independent problem domain.
8 +Parallel only when independent.
9 +One worker per independent problem domain.
10 11 ## Independence test
39 40 - final verify: ...
42 -After workers return: read summaries, inspect changed files, check conflicts, run final verification.
43 +After workers return:
44 +read summaries, inspect changed files, check conflicts, run final verification.
44 46 ## Law
46 -Benchmark prompts must stay fair/profile-neutral. Do not steer toward a tool just to make an extension look good.
48 +Benchmark prompts must stay fair/profile-neutral.
49 +Do not steer toward a tool just to make an extension look good.

extensions/superpowers/skills/executing-plans/SKILL.md

Modified
6 6 # Executing Plans
8 -Implement plan. Do not improvise silently.
8 +Implement plan.
9 +Do not improvise silently.
10 11 ## Loop

extensions/superpowers/skills/finishing-a-development-branch/SKILL.md

Modified
20 20 - discard
21 21 6. Cleanup only after explicit choice.
22 22 7. For discard, require typed confirmation.
23 -8. Remove only worktrees this workflow owns; never delete harness-owned workspace.
23 +8. Remove only worktrees this workflow owns; never delete harness-owned
24 + workspace.
25 26 ## Output

extensions/superpowers/skills/receiving-code-review/SKILL.md

Modified
33 33 ## Anti-patterns
35 -- Performative agreement before checking: “absolutely right”, “great point”.
35 +- Performative agreement before checking:
36 + “absolutely right”, “great point”.
36 37 - Blindly implementing external review without codebase verification.
37 38 - Rewriting whole module to fix one finding.
38 39 - “Addressed” without commit/file/test evidence.

extensions/superpowers/skills/requesting-code-review/SKILL.md

Modified
6 6 # Requesting Code Review
8 -Review only. Do not edit.
8 +Review only.
9 +Do not edit.
10 -No politeness tax. No generic praise. Findings need evidence.
11 +No politeness tax.
12 +No generic praise.
13 +Findings need evidence.
12 15 ## Inputs
64 67 - under-abstracted repeated logic likely to drift
65 68 - dead layers, needless adapters, repeated conversions
67 -Compression is not code golf. Prefer one good abstraction over many clever ones.
70 +Compression is not code golf.
71 +Prefer one good abstraction over many clever ones.
69 73 ## Pass 5 — Handmade UX/Style Gate
80 84 ## Severity
82 -- BLOCKER: incorrect, unsafe, untested critical path, violates spec, or fake completion.
83 -- MAJOR: likely bug, bad API, serious slop, duplicated design risk, missing important proof.
84 -- MINOR: cleanup, naming, small simplification.
85 -- NOTE: observation, no action required.
86 +- BLOCKER:
87 + incorrect, unsafe, untested critical path, violates spec, or fake completion.
88 +- MAJOR:
89 + likely bug, bad API, serious slop, duplicated design risk, missing important
90 + proof.
91 +- MINOR:
92 + cleanup, naming, small simplification.
93 +- NOTE:
94 + observation, no action required.
87 96 ## Output
110 119 ## Follow-up
112 -- Critical/BLOCKER and MAJOR findings must be fixed or explicitly rejected with evidence before proceeding.
113 -- If findings exist: use `receiving-code-review`.
114 -- If fixes are large: write a plan first.
115 -- If review passes: run `verification-before-completion` before claiming shipped.
121 +- Critical/BLOCKER and MAJOR findings must be fixed or explicitly rejected with
122 + evidence before proceeding.
123 +- If findings exist:
124 + use `receiving-code-review`.
125 +- If fixes are large:
126 + write a plan first.
127 +- If review passes:
128 + run `verification-before-completion` before claiming shipped.

extensions/superpowers/skills/subagent-driven-development/SKILL.md

Modified
6 6 # Subagent-Driven Development
8 -Workers implement. Parent owns quality. Continue task-by-task without “should I continue?” check-ins unless blocked.
8 +Workers implement.
9 +Parent owns quality.
10 +Continue task-by-task without “should I continue?” check-ins unless blocked.
10 12 ## Process
12 -1. Require approved spec/plan. If absent, use `brainstorming` or `writing-plans`.
14 +1. Require approved spec/plan.
15 + If absent, use `brainstorming` or `writing-plans`.
13 16 2. Extract each task with full text and needed context.
14 -3. Create one worker prompt per bounded task. Do not make worker read the whole plan if the task text can be provided.
17 +3. Create one worker prompt per bounded task.
18 + Do not make worker read the whole plan if the task text can be provided.
15 19 4. Run worker with `/superpowers run <prompt> ...`.
16 20 5. Inspect result with `/superpowers status <id>` or `/superpowers open <id>`.
17 -6. Handle worker state: done → review; needs-context → provide context; blocked → change prompt/model/scope or escalate.
21 +6. Handle worker state:
22 + done → review; needs-context → provide context; blocked → change
23 + prompt/model/scope or escalate.
18 24 7. Review twice, in order:
19 25 - spec compliance
20 26 - code quality/simplicity

extensions/superpowers/skills/systematic-debugging/SKILL.md

Modified
10 10 ## Phases
12 -1. Reproduce: exact command/input and observed failure. If not reproducible, gather more data; do not guess.
12 +1. Reproduce:
13 + exact command/input and observed failure.
14 + If not reproducible, gather more data; do not guess.
13 15 2. Read errors fully; check recent changes and relevant config/env.
14 -3. Pattern analysis: find working examples and compare exact differences.
15 -4. Trace: follow data/control flow to root cause.
16 -5. Hypothesis: one cause, one prediction, one test.
17 -6. Fix: smallest root-cause change, preferably after a failing regression test.
18 -7. Verify: original failure + nearby regression.
16 +3. Pattern analysis:
17 + find working examples and compare exact differences.
18 +4. Trace:
19 + follow data/control flow to root cause.
20 +5. Hypothesis:
21 + one cause, one prediction, one test.
22 +6. Fix:
23 + smallest root-cause change, preferably after a failing regression test.
24 +7. Verify:
25 + original failure + nearby regression.
20 27 ## Three-strike rule
22 -After 3 failed fixes, stop. Request architecture/design review.
29 +After 3 failed fixes, stop.
30 +Request architecture/design review.
24 32 ## Output

extensions/superpowers/skills/test-driven-development/SKILL.md

Modified
6 6 # Test-Driven Development
8 -RED first. No production code without a failing test first.
8 +RED first.
9 +No production code without a failing test first.
10 -If production code was written first, delete it and restart from RED. Do not keep it as reference.
11 +If production code was written first, delete it and restart from RED.
12 +Do not keep it as reference.
12 14 ## Loop
14 16 1. Write smallest failing test.
15 -2. Run it. Confirm failure is expected.
17 +2. Run it.
18 + Confirm failure is expected.
16 19 3. Implement smallest passing code.
17 -4. Run focused test. Green.
20 +4. Run focused test.
21 + Green.
18 22 5. Refactor only to simplify.
19 23 6. Run focused test again.
20 24 7. Run relevant full suite.

extensions/superpowers/skills/using-git-worktrees/SKILL.md

Modified
6 6 # Using Git Worktrees
8 -Protect trunk. Isolate risk.
8 +Protect trunk.
9 +Isolate risk.
10 11 ## Before creating
27 28 - dirty status
28 29 - likely trunk (`main`, `master`, `trunk`, `develop`)
30 -If current worktree is dirty, do not hide it. Ask or choose a safe path.
31 +If current worktree is dirty, do not hide it.
32 +Ask or choose a safe path.
32 34 ## Process
34 36 1. Prefer host/native worktree tools if available.
35 37 2. Pick branch name from task.
36 38 3. Create worktree outside current directory.
37 -4. If using project-local `.worktrees/` or `worktrees/`, verify path is gitignored first.
39 +4. If using project-local `.worktrees/` or `worktrees/`, verify path is
40 + gitignored first.
38 41 5. Run setup/baseline tests there.
39 42 6. Do implementation only in worktree.
40 43 7. Finish with `finishing-a-development-branch`.

extensions/superpowers/skills/using-superpowers/SKILL.md

Modified
6 6 # Using Superpowers
8 -Superpowers = process discipline. Not vibes.
8 +Superpowers = process discipline.
9 +Not vibes.
10 11 ## Rule
12 13 Before non-trivial work, choose and follow one workflow skill:
14 -| Situation | Skill |
15 -|---|---|
16 -| fuzzy feature/design | `brainstorming` |
17 -| approved design → tasks | `writing-plans` |
18 -| plan exists → implement | `executing-plans` |
19 -| independent subtasks | `dispatching-parallel-agents` |
20 -| worker + review loop | `subagent-driven-development` |
21 -| code change with testable behavior | `test-driven-development` |
22 -| bug/regression/flake | `systematic-debugging` |
23 -| before saying done | `verification-before-completion` |
24 -| isolated branch needed | `using-git-worktrees` |
25 -| branch is complete | `finishing-a-development-branch` |
26 -| creating/revising skills | `writing-skills` |
15 +| Situation | Skill |
16 +| ---------------------------------- | -------------------------------- |
17 +| fuzzy feature/design | `brainstorming` |
18 +| approved design → tasks | `writing-plans` |
19 +| plan exists → implement | `executing-plans` |
20 +| independent subtasks | `dispatching-parallel-agents` |
21 +| worker + review loop | `subagent-driven-development` |
22 +| code change with testable behavior | `test-driven-development` |
23 +| bug/regression/flake | `systematic-debugging` |
24 +| before saying done | `verification-before-completion` |
25 +| isolated branch needed | `using-git-worktrees` |
26 +| branch is complete | `finishing-a-development-branch` |
27 +| creating/revising skills | `writing-skills` |
28 -Load the selected skill before acting. If multiple skills apply, use the earliest lifecycle gate: brainstorming → writing-plans → execution/TDD/debug → review → verification → finishing.
29 +Load the selected skill before acting.
30 +If multiple skills apply, use the earliest lifecycle gate:
31 +brainstorming → writing-plans → execution/TDD/debug → review → verification →
32 +finishing.
30 34 ## Local style
53 57 /superpowers run <prompt> ...
56 -Use workers for isolated investigation/implementation. Parent integrates.
60 +Use workers for isolated investigation/implementation.
61 +Parent integrates.

extensions/superpowers/skills/verification-before-completion/SKILL.md

Modified
6 6 # Verification Before Completion
8 -No fresh proof → not done. Evidence before claims.
8 +No fresh proof → not done.
9 +Evidence before claims.
10 11 ## Checklist

extensions/superpowers/skills/writing-plans/SKILL.md

Modified
8 8 Plan for a fast careless implementer with zero project context.
10 -Save plans to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` unless project rules say otherwise.
10 +Save plans to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` unless project
11 +rules say otherwise.
12 13 ## Task requirements
43 44 - Mark unknown decisions `[?]`; stop before passing them.
44 45 - No `TODO`/`TBD`/`similar to task N`/`write tests for above` placeholders.
45 46 - No “refactor architecture” without file-level detail.
46 -- Self-review plan against spec: coverage, placeholders, type/name consistency.
47 +- Self-review plan against spec:
48 + coverage, placeholders, type/name consistency.
47 49 - End by offering `subagent-driven-development` or `executing-plans`.

extensions/superpowers/skills/writing-skills/SKILL.md

Modified
6 6 # Writing Skills
8 -Skills are operational memory. Keep them sharp.
8 +Skills are operational memory.
9 +Keep them sharp.
10 11 ## Required shape
34 35 ## Test
36 -Use TDD for skills: first write a case where current behavior would not load/follow the skill, then update the skill until it passes.
37 +Use TDD for skills:
38 +first write a case where current behavior would not load/follow the skill, then
39 +update the skill until it passes.
38 41 Create trigger cases:

prompts/brainstorm.md

Modified
6 6 # Brainstorm ideas
8 -Brainstorm ideas for the project:
10 8 **Focus**:
11 9 $ARGUMENTS
13 -Use brainstorm skill phases:
15 -1. **Read Context** - Load AGENTS.md and explore code base
16 -2. **Diverge** - Generate many ideas wildly
17 -3. **Challenge** - Consult subagent (pi --print) to find flaws
18 -4. **Defend** - Strengthen surviving ideas
19 -5. **Converge** - Pick best recommendations
21 -Brainstorm areas:
11 +General brainstorm areas:
23 13 - Features & capabilities
24 14 - Architecture improvements
29 19 Run all phases systematically.
30 20 Ask clarifying questions.
31 21 No fluff.
32 -Output ideas well formatted.
22 +Output ideas well formatted and terse.

prompts/brutal.md

Added
new file mode 100644
1 +---
2 +description: Enforce tiger style on code
3 +argument-hint: "[file-or-directory]"
4 +---
6 +# Enforce brutal style on code
8 +**Target**:
9 +$ARGUMENTS
11 +Use brutal skill to scan and enforce:
13 +1. **Scan** - Detect non-brutal patterns
14 +2. **Enforce** - Apply brutal style rules
15 +3. **Rewrite** - Transform code to brutal standards
17 +No mercy.
18 +Brutal style or death.

prompts/desloppy.md

Modified
6 6 # Find ugliest slop in code and fix it
8 -Find and fix sloppy code with no mercy:
10 8 **Target**:
11 9 $ARGUMENTS
13 11 1. **Scan** - Find the ugliest code (complexity, duplication, poor patterns)
14 12 2. **Identify** - What makes it slop?
15 13 (nesting, long functions, magic numbers, no types)
16 -3. **Fix** - Rewrite cleanly
17 -4. **Verify** - Run test after fixes
14 +3. **Fix** - Rewrite cleanly, with brutal code style
15 +4. **Verify** - Run tests after fixes and create regression tests beforehand, to
16 + make sure to not break old behaviour
19 18 Focus on:
28 27 need
30 29 No mercy.
31 -Make it beautiful.
32 -Report first, wait for approval.
30 +Make it beautifully brutal.
31 +Report minmal and terse first, wait for approval.

prompts/fix.md

Modified
6 6 # Fix bug with systematic debugging
8 -Debug and fix the issue:
10 8 **Problem**:
11 9 $ARGUMENTS
13 11 1. **Reproduce** - Get exact steps or error message
14 12 2. **Hypothesize** - List possible causes
15 13 3. **Investigate** - Search code, check logs, examine state
16 -4. **Test Fix** - Apply minimal fix
14 +4. **Fix** - Apply minimal fix, using brutal code style
17 15 5. **Verify** - Ensure fix works, no regressions
18 16 6. **Prevent** - Add test to catch future regressions

prompts/optimize.md

Modified
6 6 # Benchmark and optimize code
8 -Benchmark and optimize:
10 8 **Target**:
11 9 $ARGUMENTS
13 11 Workflow:
15 13 1. **Profile** - Use profiling to find hotspots and other performance problems
14 + Prefer canonical profiling tools for system at hand, otherwise fall back to
15 + tracing and wall time.
16 16 2. **Baseline** - Create benchmark
17 17 3. **Analyze** - Check code
18 18 4. **Optimize** - Write efficient code
19 19 5. **Verify** - Re-run benchmark, compare with benchstat
20 20 6. **Document** - Comment optimization rationale
22 +To make sure old behaviour did not break, run tests.
23 +If code to be optimized is not tested, write tests first.
24 +If changes are needed to system tools, dependencies or build system, report to
25 +human.

prompts/refactor.md

Modified
6 6 # Refactor code safely
8 -Refactor code:
10 8 **Target**:
11 9 $ARGUMENTS
13 11 1. **Analyze** - Understand current structure
14 12 2. **Plan** - List refactoring steps
15 -3. **Tests** - Ensure coverage before changes (use /test)
16 -4. **Refactor** - Apply changes incrementally
13 +3. **Tests** - Ensure coverage before changes
14 +4. **Refactor** - Apply changes incrementally, adhering to brutal code style
17 15 5. **Verify** - Run tests after each step
19 17 Common patterns:

prompts/review.md

Modified
6 6 # Quick code review with checklist
8 -Review code using systematic checklist:
10 8 **Target**:
11 9 $ARGUMENTS
15 13 3. **Performance** - O(n²) traps, unnecessary allocs, N+1 queries
16 14 4. **Readability** - Naming, complexity, comments
17 15 5. **Testing** - Coverage gaps, missing edge cases
16 +6. **Style** - Adherence to brutal code style
19 18 Provide specific line references and fix suggestions.
19 +Plan for new regression tests to keep changes safe.

prompts/test.md

Modified
6 6 # Generate comprehensive tests
8 -Generate tests:
10 8 **Target**:
11 9 $ARGUMENTS
13 -1. **Unit Tests** - Happy path, edge cases, error cases
14 -2. **Integration** - If interacts with external systems
15 -3. **Snapshot** - Use snapshot testing for complex output
11 +1. **Unit** - Happy path, edge cases, error cases, regression tests
12 +1. **Mutation** - Ensure that unit test coverage is actually meaningful
13 +1. **Property** - Business logic, algorithms and pure functions.
14 +1. **Integration/End to End(e2e)** - Whole system coverage and module
15 + interactions.
16 +1. **Snapshot** - Use snapshot testing for complex output like file and data
17 + formats:
18 + HTML,JSON,XML,REST,HTTP,binary data,TUI,text,...
17 20 Aim for 100% coverage on critical paths.
21 +If changes are needed to dependencies or build system, report to human.

prompts/tiger.md

Deleted
deleted file mode 100644
1 ----
2 -description: Enforce tiger style on code
3 -argument-hint: "[file-or-directory]"
4 ----
6 -# Enforce tiger style on code
8 -Enforce tiger style with no mercy:
10 -**Target**:
11 -$ARGUMENTS
13 -Use tiger skill to scan and enforce:
15 -1. **Scan** - Detect non-tiger patterns
16 -2. **Enforce** - Apply tiger style rules
17 -3. **Rewrite** - Transform code to tiger standards
19 -Tiger style principles:
21 -- Readable, maintainable code
22 -- Proper naming conventions
23 -- Consistent formatting
24 -- Clear structure
25 -- No unnecessary complexity
27 -No mercy.
28 -Tiger style or death.

skills/brutal/SKILL.md

Added
new file mode 100644
1 +---
2 +name: brutal
3 +description: Brutal code style - fast, aggressive, language-agnostic coding. Ultra-minimalist. Pursuit of optimal path.
4 +---
6 +# Brutal Style
8 +Fast, aggressive, language-agnostic coding.
9 +Ultra-minimalist.
10 +Pursuit of optimal path.
12 +## Core Principles
14 +### 1. SPEED
16 +- O(1) > O(log n) > O(n) > O(n²)
17 +- No loops when can recurse
18 +- No function call overhead when inline
19 +- Cache expensive operations
21 +### 2. AGGRESSION
23 +- Direct path to goal
24 +- No intermediaries
25 +- No abstraction layers unless proven necessary
26 +- Fearless complexity
28 +### 3. SHARP
30 +- Single responsibility per block
31 +- No ambiguity
32 +- Return values explicit
33 +- Error handling immediate
35 +### 4. PURSUIT
37 +- Algorithm in pursuit of solution
38 +- Never give up (retry, backtrack, parallel)
39 +- Hunt until done
41 +## Ultra Rules
43 +1. **No unnecessary state** - vars are temporary, just enough
44 +2. **No comments needed** - code says what it does
45 +3. **No frameworks** - raw primitives
46 +4. **No magic** - explicit over implicit every time
47 +5. **No premature optimization** - but when needed, go hard
49 +## Implementation
51 +### Data Structures
53 +```text
54 +LANG: Use simplest structure that fits
55 +- array over set when can (faster iteration)
56 +- hashmap only when key lookups needed
57 +- avoid nested structures > 3 levels
58 +```
60 +### Control Flow
62 +```text
63 +LANG: Guard clauses first
64 +- check errors, return early
65 +- happy path last
66 +- no else chains
67 +```
69 +### Functions
71 +```text
72 +LANG: Small, focused, named for what it does
73 +- one thing per function
74 +- params ≤ 3
75 +- if > 20 lines, split
76 +```
78 +### Error Handling
80 +```text
81 +LANG: Fail fast, fail loud
82 +- validate input immediately
83 +- crash on invalid state
84 +- no silent defaults
85 +```
87 +## Anti-Patterns
89 +- YAGNI violations
90 +- Clever one-liners that obscure
91 +- Premature abstraction
92 +- State when you can compute
93 +- Loops when you can map
94 +- try/catch masking bugs
96 +## When to Apply
98 +- Performance critical paths
99 +- Hot loops
100 +- Data pipelines
101 +- Parsers/transforms
102 +- Anything touching I/O
104 +## When NOT to Apply
106 +- One-off scripts
107 +- Prototypes
108 +- Team code without consensus
109 +- Readability-critical shared code
111 +## Brutal Test
113 +1. Is there a faster algorithm?
114 + If yes, use it.
115 +2. Can this state be computed instead?
116 + If yes, compute.
117 +3. Can this abstraction be removed?
118 + If yes, remove.
119 +4. Is this comment necessary?
120 + If code explains itself, no.
121 +5. Would caveman understand this?
122 + If no, simplify.

skills/tmux/SKILL.md

Modified
10 10 Use tmux when the task benefits from a real terminal running independently while
11 11 you inspect/control it from outside.
13 -Core idea: **spawn process → send real keys → poll pane/artifacts → preserve proof**.
13 +Core idea:
14 +**spawn process → send real keys → poll pane/artifacts → preserve proof**.
15 -Default mode: detached/background tmux session. The user will not see it unless
16 -they attach or the agent opens/prints an attach command.
16 +Default mode:
17 +detached/background tmux session.
18 +The user will not see it unless they attach or the agent opens/prints an attach
19 +command.
18 21 ## When To Reach For This
20 23 Use tmux for:
22 -- Interactive CLI/TUI testing: Pi, editors, REPLs, installers, prompts.
23 -- Agent-in-agent workflows: launch `pi` in a pane, steer it, inspect results.
24 -- Long jobs: model calls, builds, servers, watchers, migrations.
25 -- UI verification: status bars, spinners, wrapping, terminal dimensions.
26 -- Timing bugs: input while busy/idle/paused/waiting.
27 -- Multi-process work: app + logs + watcher + nested agent.
28 -- Remote resilience: keep work alive across SSH disconnects.
29 -- Repro sandboxes: isolated cwd/config/session dirs, exact transcript.
25 +- Interactive CLI/TUI testing:
26 + Pi, editors, REPLs, installers, prompts.
27 +- Agent-in-agent workflows:
28 + launch `pi` in a pane, steer it, inspect results.
29 +- Long jobs:
30 + model calls, builds, servers, watchers, migrations.
31 +- UI verification:
32 + status bars, spinners, wrapping, terminal dimensions.
33 +- Timing bugs:
34 + input while busy/idle/paused/waiting.
35 +- Multi-process work:
36 + app + logs + watcher + nested agent.
37 +- Remote resilience:
38 + keep work alive across SSH disconnects.
39 +- Repro sandboxes:
40 + isolated cwd/config/session dirs, exact transcript.
31 42 Do not use tmux for:
38 49 ## Session + Visibility Policy
40 -- Create dedicated sessions by default: `pi_<task>_<shortid>`.
51 +- Create dedicated sessions by default:
52 + `pi_<task>_<shortid>`.
41 53 - Do not use the user's active/existing session unless explicitly asked.
42 54 - Do not send keys to an existing pane unless the user names that session/pane.
43 55 - Kill/reuse only sessions owned by this run and matching your exact name.
67 79 echo "workdir: $work"
70 -Keep dimensions fixed. Capture enough history. Prefer stable markers over
71 -whole-screen assertions. Target panes explicitly (`$name:0.0`) when ambiguity
72 -or rapid session changes are possible.
82 +Keep dimensions fixed.
83 +Capture enough history.
84 +Prefer stable markers over whole-screen assertions.
85 +Target panes explicitly (`$name:0.0`) when ambiguity or rapid session changes
86 +are possible.
74 88 ## Send Input Safely
106 120 ## Short-lived Interactive Programs
108 122 If the program exits immediately after success, tmux may destroy the pane before
109 -you capture proof. Keep it alive deliberately:
123 +you capture proof.
124 +Keep it alive deliberately:
111 126 ```bash
112 127 tmux new-session -d -s "$name" -x 120 -y 24 \
122 137 Use nested Pi when you need a real agent session, not just `pi -p` output.
124 -Pi's TUI has autocomplete/editor state. Scripted input must be defensive:
139 +Pi's TUI has autocomplete/editor state.
140 +Scripted input must be defensive:
126 142 ```bash
127 143 # Discover exact pane; don't assume :0.0 (tmux may allocate window/pane index 1).
139 155 pi_send '/my-command arg'
142 -If autocomplete opens, submitted text remains in editor, or command text merges with
143 -previous text: send `C-u`, retry. For prototype extensions, avoid command argument
144 -completions unless completion behavior is under test.
158 +If autocomplete opens, submitted text remains in editor, or command text merges
159 +with previous text:
160 +send `C-u`, retry.
161 +For prototype extensions, avoid command argument completions unless completion
162 +behavior is under test.
146 164 ```bash
147 165 name=pi_nested
161 179 cat "$work/proof.txt"
164 -Use unique markers per run. Isolate `PI_CODING_AGENT_DIR` so global sessions,
165 -extensions, auth, prompts, and logs do not contaminate proof.
182 +Use unique markers per run.
183 +Isolate `PI_CODING_AGENT_DIR` so global sessions, extensions, auth, prompts, and
184 +logs do not contaminate proof.
167 186 ## WezTerm + tmux
169 188 Use tmux as the agent-control layer; use WezTerm as the human-display layer.
171 -- tmux is better for agents: universal CLI, stable pane capture, easy SSH use.
172 -- WezTerm mux is better for GUI/user ergonomics: tabs, panes, workspaces,
173 - fonts, images.
174 -- Best combo: agent creates tmux sessions; user attaches from WezTerm.
190 +- tmux is better for agents:
191 + universal CLI, stable pane capture, easy SSH use.
192 +- WezTerm mux is better for GUI/user ergonomics:
193 + tabs, panes, workspaces, fonts, images.
194 +- Best combo:
195 + agent creates tmux sessions; user attaches from WezTerm.
176 197 Manual attach from any WezTerm tab:
202 223 Useful layouts:
204 -- Left: Pi / target TUI.
205 -- Right top: server/log tail.
206 -- Right bottom: fs/session watcher.
225 +- Left:
226 + Pi / target TUI.
227 +- Right top:
228 + server/log tail.
229 +- Right bottom:
230 + fs/session watcher.
208 232 ## Creative Workflows
242 266 ### Long model/provider run
244 -Launch and detach. Poll periodically. Preserve pane capture and artifact paths.
268 +Launch and detach.
269 +Poll periodically.
270 +Preserve pane capture and artifact paths.
246 272 ```bash
247 273 echo "attach: tmux attach -t $name"
272 298 rm -rf "$work"
275 -For debugging: keep session and print attach/workdir commands.
301 +For debugging:
302 +keep session and print attach/workdir commands.
277 304 ## Benchmark/Fairness Rule
279 -When using tmux for benchmarks, prompts must stay neutral. Do not mention,
280 -require, forbid, or steer toward/away from a tool or extension under test.
306 +When using tmux for benchmarks, prompts must stay neutral.
307 +Do not mention, require, forbid, or steer toward/away from a tool or extension
308 +under test.
281 309 Use tmux as the execution/observation layer only.