app-verification

App Verification

Builds, inside a product's own repository, the harness every agent uses to run that product and prove a claim about it: a verify CLI, a doctor command, an isolated instance per worktree, a feature map written from the user's point of view, seed data and test accounts, and a reproduce-first bug handoff. The harness lives in the target repo, not in this skill; this skill scaffolds and then maintains it, so every agent that opens that repo runs the app the same way instead of writing a throwaway script each session.

• IS: scaffolding a project-local verification harness (Create mode) and running or extending one that already exists (Maintain mode): the verify CLI's contract, the feature-map format, the proof record, per-worktree isolation and seed data, the cheapest-method ladder up to computer use, and the bug-handoff format.
• IS NOT: ad hoc browser probes against a fixed catalogue of UI rules (ui-verification; this skill's verify can call those probes as one check among several), repo-wide module boundaries and enforcement tooling (codebase-architecture; this skill's CI wiring follows its enforcement order), pruning an existing test suite (test-audit), or a plan for one feature (planning).

Invocation

Create mode edits the target repo and Maintain mode drives a real running instance of it; both run only when named, not from a loose "check the app" prompt a lighter skill might serve better. On a host that supports it, add disable-model-invocation: true to the installed copy's frontmatter. It is a host extension, not a portable field, so it is not shipped in this source (agent-skills-creator's references/format-specification.md explains why). Hosts with an equivalent explicit-invocation setting should apply it the same way.

Contents

• Modes
• The harness contract
• Create mode
• Maintain mode
• References
• Gotchas
• Related skills
• Credit

Modes

Pick by what exists, and say which you picked.

Copy this to track progress:

App verification progress:
- [ ] Mode chosen and stated (Create / Maintain)
- [ ] doctor run first, read-only, before any drive
- [ ] Isolation confirmed: own port, own database, own browser profile; refused (not fell back to) the main instance
- [ ] Every path in scope checked or named as a skip with a reason
- [ ] Native/desktop paths, if any, verified with computer use as the last-resort method, not the first
- [ ] Outcome stated: clean / changed / blocked, or a reproduce-first handoff

The harness contract

Both modes build toward the same three commands, kept inside a skill folder in the target repo (for example .claude/skills/verify-<app>/ or that host's equivalent project-skill location) so the commands live at one path every session finds the same way.

doctor and verify are separate commands: one is read-only triage, the other drives and reports. Merging them hides the read-only fast check behind the slow one every time.

Create mode

references/create-mode.md. Interview the repo (surface, run, drive, observe, isolate), scaffold doctor, seed, verify and the feature map per the contract above, wire isolation before writing the first feature file, seed the top three to five features, then prove the generated harness end to end before calling it done. A harness nobody has run is a draft, not a deliverable.

Maintain mode

references/maintain-mode.md. Run doctor first, every session, before the first drive and after any failed one. Pick one outcome and say which: clean (nothing needed changing), changed (one PR or commit of proven corrections to the harness itself, never to product code), or blocked (name exactly what blocked it). A maintenance run that finds a real product bug reports it; it does not quietly patch around it inside the harness.

Two things this mode owns that a lighter probe skill does not: scoped proof (every listed path checked or skipped with a reason, recorded in the proof file; references/maintain-mode.md) and the reproduce-first bug handoff, whose first line is exactly Reproduced, Reproduced but already fixed on main or Could not reproduce (references/bug-handoff.md).

References

Load only when the condition applies.

Gotchas

• A dev-only sign-in shortcut or a fixed test-account secret is a production backdoor the moment it ships enabled; gate it and verify the guard per references/worktree-isolation.md before adding one.
• verify --fast (cli checks only) is a development convenience, never a merge gate on its own; a run that skipped every browser and computer-use check is not the same proof as a full one, and the proof record says which mode ran.
• Two feature maps drift the moment a second one exists. Keep one canonical map per app; if a lighter probe skill also tracks routes or components, point at this map rather than growing a parallel one.

Related skills

• ui-verification: scoped browser probes against a fixed UI rule catalogue, one finding at a time. This skill's verify can call those probes for the paths they cover; it does not replace them for a rule-by-rule audit.
• codebase-architecture: repo-wide module boundaries, CI guardrails, and the enforcement order this skill's own CI wiring follows.
• test-audit: suite-wide pruning of a durable test suite, a different asset from the feature map here. Gating a new test in a diff is tidy.
• planning: a plan for one feature; a new feature's plan is where its eventual feature file starts.

Maintenance only: evals/evals.json holds the behavioural scenarios and routing prompts for anyone changing this skill. It never loads during a verification run.

Credit

Builds on Lauren Tan's pstack create-verification-skill and maintain-verification-skill (MIT): the interview-then-generate method, the outcome-based maintenance loop, and the reproduce-first handoff are hers. This skill generalizes that method past one company's conventions and adds a machine-checkable proof contract. Credit them; this is not a copy of either file.