diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json index 7985be8..f170fbd 100644 --- a/pstack/.cursor-plugin/plugin.json +++ b/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.11.13", + "version": "0.11.14", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/pstack/skills/create-verification-skill/SKILL.md b/pstack/skills/create-verification-skill/SKILL.md index db06674..f869e26 100644 --- a/pstack/skills/create-verification-skill/SKILL.md +++ b/pstack/skills/create-verification-skill/SKILL.md @@ -33,7 +33,7 @@ Write `.cursor/skills/verify-/SKILL.md` with YAML frontmatter (`name: verif ## 3. Seed the feature map -Create `.cursor/skills/verify-/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). 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 map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others. +Create `.cursor/skills/verify-/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 `, 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 diff --git a/pstack/skills/create-verification-skill/references/feature-map-example/README.md b/pstack/skills/create-verification-skill/references/feature-map-example/README.md new file mode 100644 index 0000000..fb64570 --- /dev/null +++ b/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 -- `. +- 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 ` 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. diff --git a/pstack/skills/create-verification-skill/references/feature-map-example/create-note.md b/pstack/skills/create-verification-skill/references/feature-map-example/create-note.md new file mode 100644 index 0000000..2135756 --- /dev/null +++ b/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 --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. diff --git a/pstack/skills/create-verification-skill/references/feature-map-example/search.md b/pstack/skills/create-verification-skill/references/feature-map-example/search.md new file mode 100644 index 0000000..1f8e57d --- /dev/null +++ b/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.