Update to fstack

{
  "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.",
  "included_files": [
    {
      "relative_path": "references/feature-map-example/README.md",
      "size_in_bytes": 2648
    },
    {
      "relative_path": "references/feature-map-example/create-note.md",
      "size_in_bytes": 2965
    },
    {
      "relative_path": "references/feature-map-example/search.md",
      "size_in_bytes": 3523
    }
  ],
  "name": "create-verification-skill",
  "skill_md_contents": "---\r\nname: create-verification-skill\r\ndescription: \"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.\"\r\nmenu-description: generate a project-local verification skill and feature map\r\n---\r\n\r\n# Create a verification skill\r\n\r\nEvery 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 one project skill the whole team shares, at `.agents/skills/verify-<app>/`. 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.\r\n\r\n**Where it lives.** `.agents/skills/` is the harness-agnostic project skill directory (Cursor, Codex, Claude Code, Hermes, OpenClaw). Commit `verify-<app>/`. Do not write a second copy under `.claude/skills/` or `~/.codex/skills/`. Those paths are one person's harness, and the rest of the team never sees them. If `.agents/` is gitignored, add an exception for `.agents/skills/verify-*/` so the map stays in the repo. `fstack init` junctions live beside it; do not replace those junctions. The app-driving harness is platform-neutral; resolve Codex tool names via [`codex-tools.md`](../engineer-mode/references/codex-tools.md).\r\n\r\n## 1. Interview the repo, not the user\r\n\r\nAnswer these from the codebase and only ask the user what you cannot observe:\r\n\r\n- **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.\r\n- **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.\r\n- **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.\r\n- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.\r\n- **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.\r\n\r\nIf 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.\r\n\r\n## 2. Generate the skill\r\n\r\nWrite `.agents/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):\r\n\r\n- **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.\r\n- **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.\r\n- **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.\r\n- **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.\r\n- **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.\r\n- **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.\r\n\r\n## 3. Seed the feature map\r\n\r\nCreate `.agents/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.\r\n\r\n## 4. Prove the generated skill before handing it over\r\n\r\nRun 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.\r\n\r\n## 5. Offer the maintenance loop\r\n\r\nPoint the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.\r\n"
}