@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.7

package/skills/blast-radius/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: blast-radius
+description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust."
+disable-model-invocation: true
+---
+
+# Blast radius
+
+Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet.
+
+Companion to `how` and `why`. `how` tells you what the code does. `why` tells you why it's shaped that way. Blast radius tells you what it breaks somewhere else.
+
+Listing the callers is not the job. The agent can grep those in a second. The job is the breakage grep won't show you.
+
+## Don't trust your own writeup
+
+A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it's true. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code.
+
+### How sure are you
+
+For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.
+
+1. You said so. Worthless on its own.
+2. You pointed at the line. A real `file:line`, or the library's own source.
+3. You showed the bad case can't happen. You walked the failure step by step and it doesn't reach.
+4. You ran it. A script or test that calls the real code and fails loud if you're wrong.
+5. You reproduced it in the running app.
+
+Step 4 is usually one small script that imports the same library the app ships and calls the exact function you're worried about.
+
+## Steps
+
+1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use `why` step 2 to pull the PR and commits.
+2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
+3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
+4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same rules as `why`. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
+5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
+6. For a big or wide change, run it as an `arena`. Ask more than one model the same question and merge the answers. Different models catch different real bugs.
+
+## What to hand back
+
+- **What it does.** What changed, including the part that isn't obvious.
+- **The one fact it's safe because of.** State it, say which step you got it to, and show the proof. If you couldn't prove it, write unproven.
+- **Risks.** Each names how it breaks, the `file:line`, how likely and how bad, and how to check. Paste the proof for the ones that matter.
+- **Cleared.** What you checked and why it's fine.
+- **Before you merge.** The cheapest test or repro that catches the real bug, including the script you wrote.
+
+Write it through `unslop`, cite real code, and strip anything private before it goes anywhere public.
+
+**Reply:** the writeup above, with the one safety fact either proven or marked unproven.

package/skills/bro/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bro
+description: Restate the last message in plain human language, with no jargon.
+disable-model-invocation: true
+---
+
+Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another.

package/skills/check-compiler-errors/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: check-compiler-errors
+description: Run compile and type-check commands and report failures
+---
+
+# Check compiler errors
+
+## Trigger
+
+Compile or type-check failures are blocking local validation or CI.
+
+## Workflow
+
+1. Run the repo's compile and type-check commands.
+2. Summarize errors by file and type.
+3. Fix the highest-confidence issues first.
+4. Re-run checks until clean or blocked.
+
+## Output
+
+- Current compile and type-check status
+- Error summary grouped by file and category
+- Fixes applied and remaining blockers

package/skills/control-cli/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: control-cli
+description: Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.
+---
+
+# Control CLI
+
+Use a repeatable local harness to exercise an interactive CLI instead of poking at it manually. First reuse the repo's own test/demo harness if it exists; otherwise assemble a temporary harness from standard local tools.
+
+## What It Is Used For
+
+- Reproducing CLI/TUI bugs with deterministic input.
+- Verifying keyboard flows, prompts, interrupts, resize behavior, and terminal layout.
+- Capturing before/after transcripts for bug fixes.
+- Profiling startup time, slow operations, hangs, or memory growth.
+- Recording a short terminal demo when output is easier to show than explain.
+
+## Harness Loop
+
+1. Identify the command under test and the smallest reproducible workspace.
+2. Discover existing local harnesses: package scripts, e2e tests, demo recorders, expect scripts, or PTY helpers.
+3. If no harness exists, launch the CLI in an isolated terminal session with deterministic env vars.
+4. Capture the current screen before interacting.
+5. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, resize.
+6. Wait for a concrete screen pattern or prompt before the next action.
+7. Save the transcript and any profile artifacts.
+8. Kill the session cleanly.
+
+## Harness Options
+
+- Repo-native harness: prefer checked-in scripts because they know the app's startup, env, and prompts.
+- `tmux`: managed sessions, `capture-pane`, `send-keys`, attach/detach.
+- PTY probe: use a short Python, Node, or Expect script when tmux is unavailable.
+- Runtime inspector: use Node or Bun inspector for CPU profiles, heap snapshots, and live evaluation.
+- Terminal recorder: use repo-local demo tools or asciinema-compatible tools when the user asks for a demo.
+
+## Minimal tmux Harness
+
+```bash
+SESSION="cli-harness-$(date +%s)"
+tmux new-session -d -s "$SESSION" -- <command-under-test>
+tmux capture-pane -pt "$SESSION"
+tmux send-keys -t "$SESSION" "help" Enter
+tmux capture-pane -pt "$SESSION"
+tmux kill-session -t "$SESSION"
+```
+
+For Node CLIs:
+
+```bash
+NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>
+```
+
+Read the terminal output to find the inspector URL, then use Chrome DevTools-compatible tooling if profiling is needed.
+
+## Minimal PTY Harness
+
+Use a PTY script when you need deterministic waits in a repo that does not have tmux or a demo harness. Keep it temporary unless the user asks to add a reusable test.
+
+```python
+import os
+import pty
+import select
+import subprocess
+import time
+
+master_fd, slave_fd = pty.openpty()
+proc = subprocess.Popen(
+    ["<command>", "<arg>"],
+    stdin=slave_fd,
+    stdout=slave_fd,
+    stderr=slave_fd,
+    close_fds=True,
+)
+os.close(slave_fd)
+
+deadline = time.time() + 30
+buffer = b""
+while time.time() < deadline:
+    ready, _, _ = select.select([master_fd], [], [], 0.25)
+    if not ready:
+        continue
+    chunk = os.read(master_fd, 4096)
+    buffer += chunk
+    if b"<ready text>" in buffer:
+        os.write(master_fd, b"help\n")
+        break
+
+print(buffer.decode(errors="replace"))
+proc.terminate()
+os.close(master_fd)
+```
+
+If the CLI needs richer terminal control, use `pty.fork()` or an existing PTY library.
+
+## Profiling Recipes
+
+- Startup regression: capture baseline and treatment startup timings under the same machine, env, and command.
+- Slow operation: start a CPU profile, perform the operation, stop the profile, and compare top self-time functions.
+- Memory leak: force GC if available, take a heap snapshot, perform the operation repeatedly, force GC again, and take another snapshot.
+- Hang: capture the screen, active handles/resources, and a stack/CPU sample before interrupting.
+
+## Guardrails
+
+- Prefer deterministic waits over sleeps. If you must sleep, explain why.
+- Do not send credentials or destructive commands into a controlled session.
+- Keep the harness in `/tmp` unless the repo already has a testing/demo harness.
+- Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
+- Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.

package/skills/control-ui/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: control-ui
+description: Build or adapt a local browser/CDP harness to drive and inspect a web, IDE, or Electron UI. Use for local UI verification, screenshots, accessibility snapshots, perf profiles, visual diffs, or reproducing UI bugs.
+---
+
+# Control UI
+
+Use local browser automation to verify UI behavior with evidence. First reuse the repo's own Playwright, browser, or Electron harness if it exists; otherwise assemble a temporary local harness around the app's dev server or Chromium debug port.
+
+## What It Is Used For
+
+- Reproducing UI bugs that depend on real browser focus, keyboard input, scrolling, resizing, or rendering.
+- Verifying visual or accessibility changes with screenshots and snapshots.
+- Checking local web, IDE, or Electron behavior before shipping.
+- Capturing console logs, network logs, CPU profiles, traces, or heap snapshots.
+- Creating before/after evidence for `verify-this`.
+
+## Setup Pattern
+
+1. Start the app locally using the repo's documented dev command.
+2. Discover existing local harnesses: Playwright tests, Cypress specs, Storybook, browser scripts, Electron launch scripts, or snapshot tools.
+3. For a web app, connect to the local URL with the existing browser tooling.
+4. For Electron/Chromium, enable a remote debugging port when supported.
+5. Select the correct page by stable app markers, not by tab order alone.
+6. Prefer accessibility roles, labels, and stable `data-*` selectors over coordinates.
+
+## Generic Web Harness
+
+Use the repo's installed browser tooling when possible. If the repo already has Playwright, a minimal one-off probe looks like:
+
+```javascript
+import { chromium } from "playwright";
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+await page.goto("http://127.0.0.1:<port>");
+await page.getByRole("button", { name: /submit/i }).click();
+await page.screenshot({ path: "/tmp/ui-harness-after.png", fullPage: true });
+await browser.close();
+```
+
+Do not add Playwright as a project dependency just for this probe unless the user asks. Prefer existing dev dependencies or external browser tools already available in the environment.
+
+## Generic CDP Harness
+
+For Electron or a Chromium app launched with `--remote-debugging-port=<port>`, connect over CDP:
+
+```javascript
+import { chromium } from "playwright";
+
+const browser = await chromium.connectOverCDP("http://127.0.0.1:<debug-port>");
+const pages = browser.contexts().flatMap((context) => context.pages());
+let page;
+for (const candidate of pages) {
+  if (await candidate.locator("<app-root-selector>").count()) {
+    page = candidate;
+    break;
+  }
+}
+
+if (!page) {
+  console.log(await Promise.all(pages.map(async (p) => ({
+    title: await p.title(),
+    url: p.url(),
+  }))));
+  throw new Error("No matching app page found");
+}
+
+await page.screenshot({ path: "/tmp/ui-harness-cdp.png", fullPage: true });
+await browser.close();
+```
+
+Replace `<app-root-selector>` with a stable marker from the current repo, such as a root app node, landmark, or product-specific `data-*` attribute.
+
+## Interaction Loop
+
+1. Capture a page snapshot or screenshot before acting.
+2. Choose a target from the latest page structure.
+3. Perform exactly one structural action: click, type, keypress, drag, scroll, navigate, or resize.
+4. Capture a fresh snapshot/screenshot.
+5. Verify the expected state change.
+6. Save artifacts for before/after comparisons when the user asked for proof.
+
+## CDP Capabilities
+
+Use raw CDP only when higher-level browser APIs are insufficient:
+
+- Performance: CPU profiles, traces, paint flashing, FPS meter, layout shift inspection.
+- Memory: heap snapshots and forced GC for leak investigations.
+- Network: request blocking, throttling, cache disablement, request/response logs.
+- Rendering: viewport changes, color scheme emulation, reduced motion, accessibility checks.
+- Debugging: console streaming, exception capture, DOM snapshots.
+
+## Page Selection
+
+When multiple app windows/tabs share a debug port:
+
+- Prefer a positive marker for the surface under test, such as an app root selector.
+- Use a negative marker to avoid the wrong surface when necessary.
+- If no page matches, list available page titles and URLs instead of guessing.
+
+## Guardrails
+
+- Do not rely on stale element references after navigation or structural changes.
+- Avoid coordinate clicks unless a fresh screenshot was captured immediately before the click.
+- Keep test data local and disposable.
+- Do not store screenshots or heap snapshots from privacy-sensitive workspaces unless the user explicitly agrees.
+- Do not hard-code selectors, ports, or script paths from another repository. Discover the current repo's local app markers.
+- Clean up dev servers, debug sessions, and temp profiles when done.

package/skills/correct/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: correct
+description: "Find the mistakes agents keep repeating in this repo and make each one impossible. Try architecture first, then types, then a lint whose error names the fix, then a test, and write docs last. Prove each check fails on a real past mistake. Repeat this each time the operator corrects you. Use for /correct."
+disable-model-invocation: true
+---
+
+# Correct
+
+The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them.
+
+Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo.
+
+## Find the mistake classes
+
+First, read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Group the mistakes into classes. A class counts once it has happened twice.
+
+## Fix each class at the highest level that works
+
+1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy.
+2. **Enforce it with types so the bad state can't be written.** If bad code still compiles, add a lint or CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more.
+3. **Test the behavior.** Fix or delete any test that still passes when the behavior it checks breaks, or that fails when only the internals change.
+4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them.
+
+## Fix and prove
+
+Then fix the most frequent classes now, one commit each. Prove each new check fails on a real past mistake. Run the same command locally and in CI. Exceptions go on the offending line with a reason, an expiry date, and a human's approval.
+
+## Keep the rule table
+
+Last, keep a table in the agent instruction file that pairs each rule with what enforces it. When the operator corrects you, fix the mistake and add the rule. If the rule was already there and nothing enforces it, that's a repeat, so fix it at the highest level in the same change. Drop a rule once its mistake can't happen.
+
+**Reply:** each class with its evidence, the level you picked, and why a higher level didn't work.

package/skills/create-formal-verification-skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: create-formal-verification-skill
+description: "Generate a project-local skill that formally verifies the code where a bug costs the most and tests reach the least, in any language, with whichever verification tool fits. Use for /create-formal-verification-skill, \"model-check this race\", \"prove this invariant\", or when concurrency, retries, state machines, parsers, or unsafe code need more than tests."
+disable-model-invocation: true
+---
+
+# Create a formal verification skill
+
+A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language.
+
+## Choose the target from the code
+
+Answer from the codebase, and ask the user only what you cannot observe. If the user named an area or a bug, start there.
+
+A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify.
+
+## Let the question choose the tool
+
+Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. Whether events can happen in a bad order usually suits a model checker over a small model of the design, and TLA+ is the default for that in any language. Whether the code itself behaves for every input, as with memory safety, overflow, or a data-structure invariant, usually suits a verifier that runs on the code. If no verifier runs on this language, say so, and test the real code with generated inputs, not a hand model of the function. A property that must hold at every size, where a bound is not enough, can need a proof. Prefer a tool that the repo's developers can install and run, and tell the user why you chose it.
+
+## What makes it good
+
+- **True to the code.** Every part of the model or proof points to code that a reviewer can open. What the verification treats as one indivisible step is one indivisible step in the code. Names come from this repo.
+- **Able to fail.** A check that you have never seen fail proves nothing. Show each property failing on a broken variant of the code it guards, such as a removed check or a reordered step.
+- **Findings stay findings.** When the current code breaks the property, report it with the counterexample in the code's terms. Do not weaken the property or the model until it passes, and do not change product code unless the user asks.
+- **Honest about scope.** Say what is verified, under which bounds and assumptions, and what is left out. A pass covers the model or the bound, not the whole system.
+- **Readable without the tool.** State the property and the harm in one plain sentence each. Tell a counterexample as a short sequence of steps in the code's words.
+- **Cheap to rerun.** One command, a reproducible tool version, and a run short enough that the next agent will use it on every relevant change.
+- **Kept in step with the code.** Record which files and functions each check covers, and the commit at which you last confirmed that the verification describes them. When the covered code changes after that commit, the next agent can see that the verification needs another look.
+
+## Generate the verify skill
+
+Write a project-local skill with frontmatter that names the area and says when to use it. Without frontmatter, the skill never registers. From the skill alone, the next agent must be able to tell whether a change touches the verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Put the coverage record and the sync commit in the skill, and tell the next agent to move the sync commit forward only after it confirms that the verification describes the code at the new commit. Use this repo's real commands, paths, and nouns, and leave no placeholders.
+
+If the check is a TLA+ model, tell the next agent to read every result with the pstack [`/statechart`](../statechart/SKILL.md) skill. It shows each invariant violation the checker finds as its shortest path in plain words. When the check passes, `/statechart` draws a chart of how the system moves between states. Refer to `/statechart` by name. Its commands, options, and file paths change between releases and machines, so copy none of them into the generated skill or its scripts.
+
+## Prove it before you hand off
+
+Follow the generated skill once, as the next agent would, on a scratch change that breaks the property in the real code. It must catch the break. Then drop the scratch change and confirm that the check is back where it started: passing, or failing only on the findings you will report. A verify skill that was never run is a draft. If the skill misses the break or a step does not run, fix the skill or the verification, not the scratch change.
+
+## Hand off
+
+Tell the user what you verified, which tool you used and why, the bounds, what the check found in plain words, how to run it, and what it does not cover. Suggest a second target only if you found a close one. Point the user at `/maintain-formal-verification-skill` for bringing the verification back in line after changes that did not recheck it.