@jiroamato/pstack 0.0.0-stage → 0.15.15

package/pstack/skills/benchmark-checklist/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/blast-radius/SKILL.md

@@ -0,0 +1,52 @@
+---
+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
+
+If the proof needs a running web, IDE, or Electron user flow, load [`control-ui`](../control-ui/SKILL.md); for CLI/TUI, load [`control-cli`](../control-cli/SKILL.md). Read [`pstack-harness`](../pstack-harness/SKILL.md) for invocation and include any project verification skill. Keep this risk investigation read-only with respect to the reviewed diff.
+
+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/pstack/skills/blast-radius/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/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/pstack/skills/bro/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/control-cli/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: control-cli
+description: Drive, inspect, and profile a local CLI or TUI with a repeatable terminal harness. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, keyboard behavior, or terminal demos.
+disable-model-invocation: true
+---
+
+# Control CLI
+
+Exercise the real command with repeatable input and capture evidence. Reuse the project's `verify-<app>` skill or checked-in test/demo harness first. Otherwise use terminal tools already available in the session. This skill supplies the workflow; it does not install a terminal driver.
+
+## Choose the driver
+
+- For a non-interactive command, run it through Claude Code's `Bash` or Codex's shell tool and capture stdout, stderr, exit status, and resulting files.
+- For prompts or a TUI, use a real PTY. On Codex, use `exec_command` with `tty: true` and `write_stdin` when those tools are available and support the host. Poll the returned session ID and send input to that same session.
+- On Claude Code, prefer a repo-native PTY helper, Expect, or `tmux` through `Bash`. A background shell with piped stdin is not proof of terminal behavior.
+- On Windows, use an available ConPTY driver such as a repo's `node-pty` or `pywinpty` harness, or the session's native PTY tool. Unix `pty`, Expect, and `tmux` recipes require a Unix host or WSL with the app running there too.
+- If no suitable driver exists, identify the missing capability and report what remains unverified. Do not substitute piped input for a TTY-sensitive flow or silently add a project dependency.
+
+## Harness loop
+
+1. Identify the command, terminal size, and smallest reproducible workspace. Discover package scripts, e2e tests, expect scripts, PTY helpers, and demo recorders.
+2. Launch an isolated session with the repo's required environment and disposable input/data. Record its session ID or PID, command, cwd, and terminal dimensions.
+3. Capture the screen before interacting. Keep terminal escape sequences when layout matters; use the existing terminal renderer for a visual capture if available.
+4. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, or resize. Use the driver's supported key encoding.
+5. Wait for a concrete prompt or screen pattern with a deadline before the next action. A successful input write does not prove the command handled it.
+6. Assert the user-visible result and side effects, including files, exit codes, or API responses. Save the transcript and any profile artifacts. Capture before/after runs for a bug fix.
+7. Close sessions and processes this run created, including failed attempts. Preserve evidence outside disposable state and confirm it survives cleanup.
+
+## tmux recipe
+
+On a Unix host with `tmux`, adapt this to the current command and prompt:
+
+```bash
+SESSION="cli-harness-$(date +%s)-$$"
+tmux new-session -d -s "$SESSION" -- <command-under-test>
+trap 'tmux kill-session -t "$SESSION" 2>/dev/null || true' EXIT
+tmux capture-pane -pt "$SESSION"
+# Wait for the app's ready prompt with a bounded poll before sending input.
+tmux send-keys -t "$SESSION" "help" Enter
+# Wait for the expected result, then capture and save the transcript.
+tmux capture-pane -pt "$SESSION"
+```
+
+Use a temporary directory from the host's temp API or environment, rather than assuming `/tmp`. Keep a one-off harness temporary unless the task calls for a reusable test. Do not hard-code paths from another repository.
+
+## Profiling and demos
+
+- Startup regression: compare baseline and treatment with the same machine, environment, command, and readiness condition.
+- Slow operation: collect a CPU profile around the operation and compare top self-time functions.
+- Memory leak: repeat the operation between heap snapshots; force GC if the runtime supports it and record whether you did.
+- Hang: capture the screen, active handles/resources, and a stack or CPU sample before interrupting.
+- Node or Bun inspector: use the runtime's supported inspector flag with a loopback address and an ephemeral port. Read the inspector URL from startup output and use available DevTools-compatible tooling.
+- Terminal demo: use an existing recorder or an asciinema-compatible tool when the user asks. A recording supplements the assertions above.
+
+Use deterministic waits rather than fixed sleeps. Keep credentials out of transcripts. Report the command, actions, observed result, evidence paths, and any unverified behavior.

package/pstack/skills/control-cli/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/control-ui/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: control-ui
+description: Drive and inspect a local web, IDE, or Electron UI with browser or CDP tooling. Use for UI verification, screenshots, accessibility snapshots, performance profiles, visual diffs, or reproducing UI bugs.
+disable-model-invocation: true
+---
+
+# Control UI
+
+Verify the running UI with evidence. Reuse the project's `verify-<app>` skill or checked-in Playwright, Cypress, browser, or Electron harness first. Otherwise use browser tools already available in the session. This skill supplies the workflow; it does not install a browser driver.
+
+## Setup
+
+1. Discover the app's documented dev command, local URL, required environment, and existing tests. Start an isolated instance and wait for a concrete readiness condition.
+2. On Claude Code, use available browser MCP tools or the repo's browser harness through `Bash`. On Codex, use the session's browser tools or an installed browser harness through the shell. Read the selected tool's instructions before driving it; availability differs by environment.
+3. For a web app, connect to its local URL. For Electron/Chromium, use the existing Electron harness or a loopback remote debugging port when supported.
+4. Select the correct page by URL and a stable app marker, not tab order alone. If none matches, list available page titles and URLs rather than guessing.
+5. Prefer accessibility roles, labels, and stable `data-*` selectors over coordinates. If no suitable tool exists, report the missing capability and what remains unverified. Do not silently add a project dependency.
+
+## Interaction loop
+
+1. Capture a snapshot or screenshot before acting.
+2. Choose a target from the latest page structure.
+3. Perform one structural action: click, type, keypress, drag, scroll, navigate, or resize.
+4. Wait for the expected state with a bounded assertion, then capture fresh evidence. Do not reuse stale element references after navigation or structural changes.
+5. Verify the visible result and the relevant side effect, such as a saved file, persisted record, or response. A screenshot alone does not prove a workflow succeeded.
+6. Save before/after artifacts for bug fixes or comparisons. Keep evidence outside disposable app state.
+7. Clean up dev servers, test profiles, and browser instances this run created, including failed attempts. Confirm the evidence still exists. Leave pre-existing user sessions running.
+
+Use coordinates only when semantic targeting is unavailable and a fresh screenshot identifies the target. For visual parity, compare against the reference at the same viewport, scale, theme, and font state.
+
+## Playwright recipe
+
+If the repo already has Playwright, adapt the URL, action, and assertion to the actual user flow. Run the probe where the existing package resolves. This example creates its own browser and evidence directory:
+
+```javascript
+import { chromium } from "playwright";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const evidence = await mkdtemp(join(tmpdir(), "ui-harness-"));
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+  await page.goto("http://127.0.0.1:<port>");
+  await page.screenshot({ path: join(evidence, "before.png"), fullPage: true });
+  await page.getByRole("button", { name: /submit/i }).click();
+  await page.getByRole("status").filter({ hasText: /saved/i }).waitFor();
+  await page.screenshot({ path: join(evidence, "after.png"), fullPage: true });
+  console.log(evidence);
+} finally {
+  await browser.close();
+}
+```
+
+Do not add Playwright solely for this probe when existing external browser tools can drive the app. Adapt selectors, ports, and paths from the current repo.
+
+## Electron and CDP
+
+Use the project's Electron automation when available. For a Chromium debug port, Playwright's `chromium.connectOverCDP("http://127.0.0.1:<debug-port>")` can expose pages through `browser.contexts().flatMap(context => context.pages())`. Select the page with a positive app-root marker; use a negative marker to exclude another surface if needed. Inventory titles and URLs when no page matches.
+
+Track ownership when attaching. Disconnect the automation connection using the driver's supported mechanism; close the app or browser only if this run launched it. Follow the environment's browser-control restrictions when deciding whether direct CDP is available.
+
+Use raw CDP only when higher-level APIs are insufficient:
+
+- Performance: CPU profiles, traces, paint flashing, FPS, and layout shift inspection.
+- Memory: heap snapshots and forced GC for leak investigations.
+- Network: request blocking, throttling, cache controls, and request/response logs.
+- Rendering: viewport, color scheme, reduced motion, and accessibility checks.
+- Debugging: console streaming, exceptions, and DOM snapshots.
+
+Keep test data disposable and credentials out of artifacts. Report the route, actions, observed result, evidence paths, and any unverified behavior.

package/pstack/skills/control-ui/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/correct/SKILL.md

@@ -0,0 +1,34 @@
+---
+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 would still pass if every function it calls returned nothing.
+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.
+
+Load [`deslop`](../deslop/SKILL.md) before each fix commit and rerun affected checks after cleanup. If a correction affects web, IDE, or Electron behavior, load [`control-ui`](../control-ui/SKILL.md) for before/after proof; for CLI/TUI, load [`control-cli`](../control-cli/SKILL.md). Read [`pstack-harness`](../pstack-harness/SKILL.md) for invocation and use any project verification skill for app-specific steps.
+
+## 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/pstack/skills/correct/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,47 @@
+---
+name: create-verification-skill
+description: "Generate a project-local verification skill that drives your app the way a user does, for any language, framework, or platform. Use for /create-verification-skill, \"make a verification skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
+disable-model-invocation: true
+---
+
+# Create a verification skill
+
+Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (`<project skills>/verify-<app>/`, where `<project skills>` is `.claude/skills` on Claude Code and `.agents/skills` on Codex, per the harness **project skills** row) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
+
+## 1. Interview the repo, not the user
+
+Answer these from the codebase and only ask the user what you cannot observe:
+
+- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
+- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
+- **Drive:** how can an agent interact with it programmatically? Load bundled [`control-ui`](../control-ui/SKILL.md) for web, IDE, and Electron or [`control-cli`](../control-cli/SKILL.md) for CLI/TUI. Adapt its workflow using existing Playwright/Cypress specs, expect scripts, PTY helpers, or a debug port before choosing another available driver. Use plain HTTP for services.
+- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
+- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.
+
+If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
+
+## 2. Generate the skill
+
+Write `<project skills>/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
+
+- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
+- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
+- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
+  For web, IDE, or Electron, the generated skill explicitly loads bundled `control-ui`; for CLI/TUI, `control-cli`, through the harness **skill** row. Then supply this app's exact recipe and feature map. This is an app-specific verification skill, not a separate generic `control` skill.
+- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
+- **Cleanup:** how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
+- **Helpers:** any script the skill ships is executable and its invocation is shown in the skill body. A helper the reader has to reverse-engineer is not a helper.
+
+## 3. Seed the feature map
+
+Create `<project skills>/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
+
+## 4. Prove the generated skill before handing it over
+
+If generation adds executable helpers, load [`deslop`](../deslop/SKILL.md) on that code before committing or the final proof run.
+
+Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
+
+## 5. Offer the maintenance loop
+
+Point the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.

package/pstack/skills/create-verification-skill/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/create-verification-skill/references/feature-map-example/README.md

@@ -0,0 +1,47 @@
+# Notes verification map
+
+This directory is the maintained source for verifying the user-facing behavior of Notes. Read the index before driving the app, then use the matching feature file as the recipe.
+
+## Baseline preconditions
+
+- Launch Notes at `http://127.0.0.1:4173` with a disposable data directory.
+- Set `NOTES_DATA_DIR=/tmp/notes-verify-$RUN_ID` so concurrent runs do not share state.
+- Seed notes titled `Quarterly plan` and `Grocery list`.
+- Put `control-notes` and the `notes` CLI on `PATH`.
+- Run `control-notes doctor` and require the expected URL, data directory, and build revision.
+- Never drive an instance that was not started by this verification run.
+
+## Driving conventions
+
+- Start every recipe from the baseline state unless its preconditions say otherwise.
+- Prefer ARIA roles and accessible names over CSS selectors or DOM position.
+- Treat every command as literal. Keep quoted names and flags unchanged.
+- Run browser actions through `control-notes browser`.
+- Run terminal actions through `control-notes cli -- <command>`.
+- Restore seeded data after a mutation. Do not remove proof artifacts during cleanup.
+
+## Proof and skip reporting
+
+- Capture the user action and the resulting state, not only the final screen.
+- UI proof includes an ARIA snapshot and a screenshot with the app identity visible.
+- CLI proof includes the command, stdout, stderr, and exit code.
+- Mutation proof includes a read-only second view of the stored value.
+- Record the feature ID and entry point used with every artifact.
+- Report an unreachable path with the attempted command and the unmet precondition.
+- Do not report a skipped entry point as verified through a different path.
+
+## Feature entry contract
+
+Each feature file starts with an H1 title and one paragraph describing the user-visible behavior. It then uses exactly four H2 sections in this order.
+
+1. `Sub-features` lists short IDs with one line for each behavior.
+2. `How to get to it (user POV)` lists every user entry point.
+3. `Driving it with <harness>` starts with `Preconditions:` and uses labeled bullets that pair each user action with an exact command and observable result.
+4. `Gotchas` lists traps that can waste or invalidate a verification run.
+
+Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof.
+
+## Features
+
+- [Create a note](./create-note.md) covers browser and CLI creation, cancellation, persistence, and cleanup.
+- [Search notes](./search.md) covers toolbar, keyboard, and CLI search with matching, empty, and clear states.

package/pstack/skills/create-verification-skill/references/feature-map-example/create-note.md

@@ -0,0 +1,39 @@
+# Create a note
+
+Create note lets a user save a titled note from the browser or CLI, cancel an unfinished draft, and confirm the saved note from a second user-facing view.
+
+## Sub-features
+
+- `create-open` opens a blank editor from each browser entry point.
+- `create-save` persists a title and body.
+- `create-cancel` discards an unfinished browser draft.
+- `create-cli` creates the same note shape from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `New note` button in the browser toolbar.
+- Press `n` in the browser while focus is outside an editable field.
+- Run `notes create --title <title> --body <body>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- No note is titled `Release checklist`.
+- `control-notes doctor` reports the expected URL and disposable data directory.
+
+- **Open editor.** Choose `New note`. Run `control-notes browser click --role button --name "New note"`. A form named `Note editor` appears with focus in the `Title` textbox.
+- **Enter content.** Type the title and body. Run `control-notes browser fill --role textbox --name "Title" --value "Release checklist"` and `control-notes browser fill --role textbox --name "Body" --value "Tag and publish"`. The `Save note` button becomes enabled.
+- **Save note.** Choose `Save note`. Run `control-notes browser click --role button --name "Save note"`. A status named `Note saved` appears and the heading reads `Release checklist`.
+- **Confirm persistence.** Return to the note list and reopen the note. Run `control-notes browser click --role link --name "All notes"` and `control-notes browser click --role link --name "Release checklist"`. The editor shows both saved values.
+- **Cancel draft.** Open a new note, enter `Discard me`, and choose `Cancel`. Run `control-notes browser click --role button --name "New note"`, `control-notes browser fill --role textbox --name "Title" --value "Discard me"`, and `control-notes browser click --role button --name "Cancel"`. The note list returns and has no `Discard me` link.
+- **CLI entry.** Create a second note. Run `control-notes cli -- notes create --title "CLI note" --body "Created from terminal" --format json`. Exit code `0` and stdout contain the new note ID and title.
+- **Proof.** Reopen both saved notes from `All notes`. Run `control-notes browser snapshot --aria --path artifacts/create-note/list.aria.txt` and `control-notes browser screenshot --path artifacts/create-note/list.png`. The artifacts show `Release checklist` and `CLI note`.
+
+## Gotchas
+
+- Pressing `n` while a textbox has focus types the character instead of opening a new editor.
+- Titles are trimmed on save. Assert the rendered title, not the draft input value.
+- A save status alone is insufficient proof. Reopen the note from the list.
+- Remove `Release checklist` and `CLI note` during fixture cleanup, but retain their proof artifacts.

package/pstack/skills/create-verification-skill/references/feature-map-example/search.md

@@ -0,0 +1,45 @@
+# Search notes
+
+Search lets a user find notes by title or body text, inspect a matching note, and distinguish no matches from an unavailable search.
+
+## Sub-features
+
+- `search-open` opens search from each supported browser entry point.
+- `search-match` returns title and body matches without changing note data.
+- `search-open-result` opens a result in the note editor.
+- `search-empty` shows a complete empty state for a query with no matches.
+- `search-clear` removes the query and restores the recent-notes view.
+- `search-cli` returns the same matching notes from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `Search` button in the browser toolbar.
+- Press `/` in the browser while focus is outside an editable field.
+- Run `notes search <query>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- The disposable data directory contains `Quarterly plan` with body text `Draft budget`.
+- `control-notes doctor` reports the expected URL and data directory.
+
+- **Toolbar entry.** Choose the `Search` button. Run `control-notes browser click --role button --name "Search"`. A dialog named `Search notes` appears with focus in its searchbox.
+- **Keyboard entry.** Close the dialog, focus the page, and press `/`. Run `control-notes browser press --key "/"`. The same dialog appears and the page does not insert a slash.
+- **Title match.** Type `quarterly`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "quarterly"`. The `Search results` list contains `Quarterly plan` and does not contain `Grocery list`.
+- **Body match.** Replace the query with `budget`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "budget"`. The result `Quarterly plan` remains visible with a body-match excerpt.
+- **Open result.** Choose `Quarterly plan`. Run `control-notes browser click --role link --name "Quarterly plan"`. The dialog closes and the editor heading reads `Quarterly plan`.
+- **Empty state.** Reopen search and enter `volcano`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "volcano"`. A status named `No matching notes` appears after search completes.
+- **Clear query.** Choose `Clear search`. Run `control-notes browser click --role button --name "Clear search"`. The searchbox is empty and the `Recent notes` region replaces the result list.
+- **CLI match.** Search from the terminal. Run `control-notes cli -- notes search "quarterly" --format json`. Exit code `0` and stdout contain one object whose title is `Quarterly plan`.
+- **CLI miss.** Search for an absent value. Run `control-notes cli -- notes search "volcano" --format json`. Exit code `0` and stdout are `[]`.
+- **Proof.** Capture the populated result state. Run `control-notes browser snapshot --aria --path artifacts/search/results.aria.txt` and `control-notes browser screenshot --path artifacts/search/results.png`. Both artifacts identify Notes, the query, and `Quarterly plan`.
+
+## Gotchas
+
+- Pressing `/` while the editor or searchbox has focus inserts text instead of opening search.
+- Results update after a short debounce. Wait for the results list or empty status, not a fixed sleep.
+- Archived notes are excluded unless the user enables `Include archived`.
+- The CLI defaults to human-readable output. Use `--format json` for stable assertions.
+- Opening a result changes browser state. Reopen search before proving another query.

package/pstack/skills/deslop/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: deslop
+description: Remove AI-generated code slop from a branch or working diff before committing. Use for /deslop, code cleanup, unnecessary comments, redundant guards, type escape hatches, or patterns that do not fit the surrounding code.
+disable-model-invocation: true
+---
+
+# Remove AI code slop
+
+Check the diff and remove AI-generated slop introduced by the current work. This is code cleanup; use `unslop` for prose and `no-comments` for the independent comment review.
+
+## Choose the diff
+
+Use the base the user or PR names. Otherwise resolve the repository's default branch from its documentation or `refs/remotes/origin/HEAD`; do not assume it is called `main`. Compare from the merge base (`git diff <base>...HEAD`) and inspect staged and unstaged changes (`git diff --cached`, `git diff`). Read new untracked files that belong to the task too. If the base is unavailable locally, inspect the working diff and report the limited scope.
+
+Read the surrounding code before editing. Clean the current task's changes; leave unrelated user edits alone.
+
+## Focus areas
+
+- Extra comments that are unnecessary or inconsistent with local style.
+- Defensive checks or try/catch blocks that are abnormal for trusted code paths.
+- Casts to `any` used only to bypass type issues.
+- Deeply nested code that should be simplified with early returns.
+- Dead compatibility paths, needless abstractions, and placeholder names.
+- Other patterns inconsistent with the file and surrounding codebase.
+
+## Finish
+
+Keep behavior unchanged and prefer minimal edits over broad rewrites. Preserve validation at external boundaries and comments that explain a real constraint. If cleanup exposes a bug, handle it within the user's task or report it separately.
+
+Inspect the resulting diff and run the checks appropriate to the code you changed. In a pstack commit workflow, follow with `no-comments` per the harness **deslop** row. Keep the final summary to 1-3 sentences, including any checks that could not run.

package/pstack/skills/deslop/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/figure-it-out/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: figure-it-out
+description: "Design an auditable playbook when no narrower one fits: a large migration, an ambitious multi-part change, or work a human reviews after stepping away. Scales rigor to the task, runs a hypothesis loop, and logs decisions via show-me-your-work. Use for /figure-it-out, 'figure it out', a large migration, or when no narrower playbook applies."
+disable-model-invocation: true
+---
+
+# Figure it out
+
+When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away.
+
+## Start
+
+Open a todolist whose first item is to read the Principles section of the **poteto-mode** skill. Then add the phases below as todos.
+
+## Phase A: Frame
+
+Ground first, then commit. Don't start the run until you can state:
+
+- The definition of done as a falsifiable predicate (the **prove-it-works** principle skill).
+- Scope, quantified: rough units and effort, plus the blockers grounding surfaced.
+- The rigor level, biased high. One-way doors and high blast radius get more. Reversible low-stakes steps get less. Rigor is gates and artifacts, not "try harder".
+
+Present the framing and tradeoffs before committing to a long run. Reversible work proceeds (the **never-block-on-the-human** principle skill), but a multi-hour run earns one checkpoint.
+
+## Phase B: Design the workflow
+
+Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first. Scaffold and verification come before features (the **foundational-thinking** principle skill).
+
+- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
+- For web, IDE, or Electron units, load [`control-ui`](../control-ui/SKILL.md); for CLI/TUI units, [`control-cli`](../control-cli/SKILL.md). Read [`pstack-harness`](../pstack-harness/SKILL.md) and apply its **verification harness** row with any project verification skill. Put the driver path and calls in each delegated unit's brief.
+- For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
+- Decide what fans out. Parallelize only across seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan.
+- Write the designed phase list down. That list is what the human reviews.
+
+Then execute the design. Add its steps to the todolist as concrete items, after the Phase C entry and before Phase D. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
+
+## Phase C: Run the loop
+
+Each unit is an experiment. State the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't.
+Load [`deslop`](../deslop/SKILL.md) before committing or handing back each kept code unit, then rerun the checks its cleanup affects. Include this in code-writing workers' briefs.
+Apply the **sequence-verifiable-units** principle skill, verifying each unit before starting the next instead of batching checks at the end.
+
+- Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system.
+- Pair delegated work with a judge. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
+- A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Inconclusive is not a pass. Don't hide a negative.
+
+## Phase D: Keep the audit trail
+
+Log the run via the **show-me-your-work** skill. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work.
+
+## Phase E: Verify and hand back
+
+Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script (the **encode-lessons-in-structure** principle skill).
+
+**Reply:** the playbook you designed, the rigor level and why, the decision-trail path, what's verified against the predicate, and what's still open.

package/pstack/skills/figure-it-out/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/how/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: how
+description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation."
+disable-model-invocation: true
+---
+
+# How
+
+Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
+
+Read the **pstack-harness** skill first. Each spawn below names a role line in the pstack models file (`~/.pstack/models.md`, harness **models file** row) and a default (harness **tiers** row). Set `model` to that line's value, or to the default if the file or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the spawn rejects a model, use the default and say so. If it rejects the default, use the closest valid model of the same family from its error message.
+
+## Step 1. Assess Complexity
+
+If the scope is ambiguous, state your interpretation and explore. The user can redirect.
+
+- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.
+- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): spawn parallel explorers first, then hand off to the explainer. Go to Step 2a.
+
+When in doubt, take the simple path.
+
+## Step 2a. Explore (complex questions only)
+
+Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message:
+
+- `subagent_type`: `general-purpose` (harness **default agent** row)
+- `model`: the `how explorer` line, default the code tier
+- `readonly`: `true` (harness **read-only** row)
+
+Each explorer gets the prompt in `references/explorer-prompt.md` with its angle filled in. Then go to Step 3.
+
+## Step 2b. Direct Explain (simple questions)
+
+Spawn one subagent that explores and explains in one pass:
+
+- `subagent_type`: `general-purpose` (harness **default agent** row)
+- `model`: the `how explainer` line, default the judgment tier
+- `readonly`: `true` (harness **read-only** row)
+
+Build its prompt from `references/explainer-prompt.md` without the explorer-findings section. Go to Step 4.
+
+## Step 3. Synthesize (complex questions only)
+
+Once all explorers have returned, spawn one subagent to synthesize their findings into one explanation:
+
+- `subagent_type`: `general-purpose` (harness **default agent** row)
+- `model`: the `how explainer` line, default the judgment tier
+- `readonly`: `true` (harness **read-only** row)
+
+Build its prompt from `references/explainer-prompt.md` with every explorer's findings filled in.
+
+## Step 4. Present
+
+Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
+
+## Output Format
+
+The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.

package/pstack/skills/how/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false