run

Files (2)

• SKILL.md
• drive.sh · scripts/

SKILL.md (first lines)

# Run

Prove behavior on the real artifact, the way a user reaches it. A passing build or unit test is an input, not the proof. The deliverable is evidence you captured and read: output with its exit code, a screen capture, a response body, a screenshot you opened.

A project `verify` skill (`.agents/skills/verify/`) outranks this one; it knows the repo's harness. Use this skill when there is none, and consider generating one with **create-verification-skill** when the repo will be driven again.

`scripts/drive.sh` in this skill's directory does the mechanics: tmux sessions for interactive programs, background process groups for servers, and waits that poll with a deadline and print what they last saw. Run it with no arguments for its usage.

## 1. Pick the surface and the launch

Use the repo's documented dev command (package scripts, Makefile, README). Isolate the instance: a fresh port, a temp data directory, a throwaway profile. Never drive the user's own running instance or their real data. Build once before the first drive.

## 2. Drive it

**One-shot CLI.** Run the exact command a user would with `bash`, and keep its output and exit code. Exercise the changed path and the failure path.

**Interactive CLI or TUI.** Host it in tmux, act, and wait for the screen instead of sleeping:

```bash
drive.sh tui-start app -- <command...>
drive.sh tui-wait app '<prompt or screen text>'
drive.sh tui-type app '<text>'; drive.sh tui-keys app Enter
drive.sh tui-wait app '<expected result>'
drive.sh tui-screen app          # the evidence
drive.sh tui-stop app
```

Key names follow tmux: `Enter`, `Escape`, `Tab`, `BSpace`, `Up`, `C-c`. A timeout prints the last screen; read it before retrying.

**Server or API.** Start it detached, wait for readiness, drive it with real requests:

```bash
drive.sh bg-start api /tmp/api.log -- <command...>
drive.sh wait-url http://127.0.0.1:<port>/health     # or: drive.sh wait-log /tmp/api.log '<ready line>'
curl -sS -i http://127.0.0.1:<port>/<route>          # the evidence
drive.sh bg-stop api
```

Many runtimes buffer stdout into a file; run them unbuffered (`python3 -u`, `stdbuf -oL`) when waiting on a log line.

**Browser or Electron app.** Take the first driver that exists:

1. The repo's own end-to-end harness (Playwright, Cypress, WebDriver specs). Run the relevant spec or write a scratch one next to them.
2. A browser MCP server through the `mcp` tool: `mcp({ search: "screenshot" })` or `mcp({ search: "navigate" })` finds it, then `mcp({ tool, args })` drives it.
3. A scratch project with Playwright installed locally, after the user approves downloading the dependency and browser. Run the script with `node` so its `playwright` import resolves from that project's `node_modules`; use that project's Playwright CLI to install Chromium if needed. For Electron, launch through Playwright's `_electron` API or start the app with `--remote-debugging-port` and connect over CDP.

Select elements by stable handles: roles and accessible names, labels, `data-*` attributes, visible text. Save screenshots to a temp path and open each with `read`, which displays images, before drawing a conclusion from it.

## 3. Report the evidence

For every behavior claimed, give the command or action, then what was observed: the output excerpt and exit code, the screen text, the response status and body, or the screenshot path you viewed. A bug fix shows the failing observation before the change and the passing one after, on the same surface. When the surface cannot be driven here (hardware, a paid service, missing credentials), say exactly what blocked it and hand the user one concrete manual check.

## 4. Clean up

Stop every tmux session and background process you started (`tui-stop`, `bg-stop`), and remove scratch data and scripts outside the repo's own test tree. Leave nothing listening.

From proguha/pstack-pi, MIT.

More from proguha/pstack-pi