@mccune1224/pi-pstack 0.1.0

package/skills/automate-me/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: automate-me
+description: "Use for \"automate me\", \"create/update/refresh my -mode skill\", \"turn/capture my preferences or working style into a skill\", or wanting agents to follow how the user works. Drafts or revises a personal -mode skill via create-skill + unslop, optionally pulling fresh evidence from recent transcripts."
+disable-model-invocation: true
+---
+
+# Automate me
+
+A guided flow for turning the user's working conventions into a skill agents will follow. The output is one `-mode` skill tailored to them (e.g. `jay-mode`, `priya-mode`).
+
+This skill orchestrates three others: an inline mining pass (see step 1), the `create-skill` skill (authoring, ships with this plugin), and the **unslop** skill (prose discipline). It sequences them; it doesn't replace them.
+
+## Flow
+
+### 0. Check for an existing skill
+
+Look recursively for `*-mode/SKILL.md` matching the user's handle in Pi's skill locations (`~/.pi/agent/skills/`, project `.pi/skills/`). Mode skills can live in a personal category directory (`~/.pi/agent/skills/<handle>/`), not only at the top level. If one exists, confirm intent with `ask_user_question` (unless they already said "update my skill" or similar):
+
+- Update the existing skill (default for repeat runs)
+- Start fresh (rare; ask why before doing it)
+
+Update mode changes the rest of the flow:
+- Step 1 mines only history since the skill was last edited (`git log -1 --format=%cI <path>`).
+- Step 2 asks what's changed or missing, not what to capture from zero.
+- Step 4 edits the existing file in place. Preserve sections the user hasn't contradicted; revise ones with new evidence; add new sections only for genuinely new rules.
+
+### 1. Mine their history
+
+Locate the active workspace's sessions before fanning out. Pi stores sessions under `~/.pi/agent/sessions/`, one subdirectory per working directory (cwd path with each `/` replaced by `-`). Use the active cwd's subdir only, ordered by modification time. Don't glob across other working-directory subdirs. That crosses workspaces and reads private sessions from unrelated projects.
+
+Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
+
+- Response preferences (length, tone, format, "dumb it down" corrections)
+- Delegation habits (subagents, models, specialized workflows, parallelism)
+- Verification posture (what "done" means; unit tests vs live repro; reviewers)
+- Code and prose discipline (style, principles cited, lint/format tools)
+- Process conventions (worktrees, commits, PRs, review/merge tooling)
+- Meta preferences (fixing skills mid-task, proposing new ones)
+
+Cross-check across slices before elevating a signal. Patterns seen in 2+ slices are high-confidence; lone signals are weak and usually get dropped.
+
+### 2. Ask the user directly
+
+Mining misses intent that hasn't come up yet. Use the `ask_user_question` tool (structured multi-choice) rather than asking the user to type from scratch. Lower cognitive load, higher hit rate.
+
+Shape: one or two questions with 4-6 options each, `allow_multiple: true` for category questions. Start broad ("Which areas matter most?"), then follow up on selected areas with specific options. After the structured rounds, one free-form chat question catches anything the options missed.
+
+Don't dump 20 questions. Two structured rounds plus one open question is usually enough.
+
+### 3. Cluster findings
+
+Group the combined signals into sections. Common ones (use only what applies):
+
+- **Response style**: length, tone, format.
+- **Autonomy**: how much to do without asking; MCP tool use.
+- **Understand first**: which skills to reach for when scoping or investigating a change.
+- **Subagents**: default, parallelism, model-to-task, specialized workflows.
+- **Prose / code discipline**: principles, lint tools, style guides.
+- **Review and verify**: repro posture, verification skills, live-testing tools.
+- **Process**: git worktrees, commits, PRs, review/merge tooling.
+- **Skills**: skill-authoring habits, fix-the-skill-first, proposing new skills.
+
+The **poteto-mode** skill shows the shape. Read it for granularity. Don't copy its content; the user's rules are not the same as poteto-mode's.
+
+### 4. Draft the skill
+
+Use the `create-skill` skill (ships with this plugin) to author the skill. Placement:
+
+- Path: preserve an existing mode skill's category. For a new mode, use `~/.pi/agent/skills/<handle>/<handle>-mode/SKILL.md` when there is an established personal category for that handle; otherwise default to `.pi/skills/<handle>-mode/SKILL.md` in the project (or `~/.pi/agent/skills/<handle>-mode/` if the user prefers a personal skill).
+- Handle: the user's first name or chosen identifier.
+- Frontmatter `description`: trigger on their name + `/<handle>-mode` + "work in their style", not on generic keywords like "write code" or "review PR".
+- Frontmatter formatting: follow `create-skill`'s YAML rules. Keep `description` as one YAML scalar; quote it or use `description: >-` with indented continuation lines when punctuation or wrapping requires it.
+- Frontmatter `disable-model-invocation: true` by default. Mode skills are heavy and opinionated; they should only apply when the user explicitly invokes them (by name or slash command), not auto-trigger on description matching. Opt out only if the user explicitly wants their mode to apply on every turn.
+
+### 5. Iterate on prose
+
+Apply the **unslop** skill and `create-skill`'s writing guidelines to every line. Both apply to any agent-read prose, not just skills.
+
+Show the draft to the user and take feedback. Expect multiple iterations. Cut ruthlessly; a mode skill is not a manual.
+
+### 6. Land it
+
+Work in a worktree off main. Commit and open a PR so the user can review it. Don't push to main directly.
+
+## Guardrails
+
+- **Don't overfit to one conversation.** A preference stated once and contradicted another time is noise. Require multiple instances before codifying it.
+- **Don't be clever.** Restating other skills' contents, inventing metaphors, or writing "poetic" prose for an agent reader is cost without benefit. Keep it operational.
+- **Reference, don't inline.** Other skills the user relies on should appear as path references, not pasted excerpts. Same for any principle docs they maintain elsewhere.
+- **Keep sections minimal.** Only add a section if the user has a specific, non-default rule there. "Communicate clearly" is not a section. "Short paragraphs. Tables when comparing options. Bullets only when items are genuinely parallel." is.
+- **Name conventions generic.** Use "the user" or "the human" in imperatives, not the author's first name. Others may read or adopt the skill.
+- **Don't force symmetry.** If a user has no process rules worth writing down, skip the Process section entirely. Sparse is fine; bloated is not.
+
+## Evaluation
+
+A `-mode` skill is subjective output. A `create-skill`-style test/iterate benchmark loop isn't useful here. Vibe-check with the user: does it read like them? Did it miss anything? Then ship.
+
+Run a description-optimization loop only if the skill's trigger accuracy turns out to be a problem in practice.
+
+## When not to use
+
+- User wants a task-specific skill (not working conventions): `create-skill` alone, no mining required.
+- User wants to capture one narrow workflow (e.g. "how I write commit messages"): that's a regular skill, not a mode skill.
+
+## Reference files
+
+- The **poteto-mode** skill: example of the output shape.
+- The **unslop** skill: prose discipline for every line.
+- The `create-skill` skill (ships with this plugin): skill authoring process and writing guidelines.

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, and that is the trap you are walking into. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code. Words are where you start, not what you ship.
+
+### 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.
+
+Any safety fact you can't get to step 4, say so out loud. Don't write it up as settled. 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 scary 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 of the scary cases die 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. If you can't prove it cheaply, mark it unproven. Don't round up.
+6. For a big or wide change, run it as an `arena`. Ask several models 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.** Only the real ones. 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/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 the bundled verification skills (create-verification-skill, maintain-verification-skill).
+
+## 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/create-skill/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: create-skill
+description: Author or edit a SKILL.md for an agent skill. Use before writing or modifying any SKILL.md file.
+---
+
+# Create skill
+
+Write agent skills the agent can actually follow. This page covers the SKILL.md contract, structure, and prose rules. Follow it before authoring or editing any SKILL.md.
+
+## Frontmatter
+
+SKILL.md starts with YAML frontmatter. Two fields are required.
+
+| Field | Rule |
+|---|---|
+| `name` | Lowercase letters, numbers, hyphens. 1-64 characters. Prefer a name that matches the parent directory. |
+| `description` | What the skill does and when to use it. Be specific. Under 1024 characters. This is the only part the agent sees up front, so make it load-bearing. |
+
+Pi honors two optional fields. `disable-model-invocation: true` hides the skill from the system prompt; only `/skill:name` invokes it. `mode: true` makes the skill a sticky mode that stays on across turns.
+
+## Structure
+
+A skill is a directory with a SKILL.md file. Everything else is freeform.
+
+```
+my-skill/
+├── SKILL.md
+├── scripts/
+│   └── run.sh
+└── references/
+    └── details.md
+```
+
+Reference files with relative paths from the skill directory. Load detailed material on demand instead of inlining it. The agent sees only the description until it reads the file.
+
+## Progressive disclosure
+
+The description is always in context. The rest of the SKILL.md loads on demand. Keep the first page load-bearing. Put step-by-step workflows in the SKILL.md body and depth in the references.
+
+## Prose rules
+
+- Write concise Simplified Technical English. Short declarative sentences.
+- Imperative mood. Tell the agent what to do.
+- Example first, explanation second. A runnable snippet beats a paragraph.
+- No AI tells or filler. No "delve", "leverage", "comprehensive".
+- No narrating comments in script examples. The assertion or command output is the doc.
+- One name per concept. One spelling per concept across the skill.
+
+## Example
+
+~~~markdown
+---
+name: pdf-merge
+description: Merge multiple PDFs in order. Use when the user asks to combine PDF files.
+---
+
+# PDF merge
+
+Merge PDFs with the system `pdfunite` tool.
+
+    pdfunite a.pdf b.pdf out.pdf
+
+Verify the output page count matches the sum of the inputs.
+~~~
+
+## References
+
+- Agent Skills specification: https://agentskills.io/specification
+- Pi skills documentation: docs/skills.md in the pi-coding-agent package

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

@@ -0,0 +1,44 @@
+---
+name: create-verification-skill
+description: "Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /create-verification-skill, \"make a control 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 (`.pi/skills/verify-<app>/`) 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? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, 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 `.pi/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.
+- **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 `.pi/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
+
+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/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/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/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.