Create a project verification guide

Use this when

An agent needs a reliable way to verify behavior through the same interface a person uses, and the repository does not already have a clear, maintained guide for doing so.

This applies to web and desktop apps, command-line tools, APIs, services, mobile apps, and libraries. Choose the primary user-facing surface for the guide; mention additional surfaces when they need different launch or interaction steps.

Steps

1. Inspect the repository before asking questions

Read its agent instructions, README, quickstart, package scripts, build files, existing tests, and relevant source. Record facts you can establish from the checkout. Ask the user only about details the repository cannot reveal, such as unavailable credentials or a required external environment.

Determine:

• Surface: What does a user operate: a browser, desktop window, terminal, API, mobile app, or library? Which surface should the guide cover first?
• Launch: What documented command starts or builds it? Record required environment variables, ports, credentials, seed data, migrations, and the exact signal that means the app is ready for real use.
• Interaction: Which existing harness can an agent use? Look for browser or end-to-end tests, CLI scripts, PTY helpers, debug interfaces, or HTTP endpoints. Prefer an existing supported path before adding a generic browser, terminal, or HTTP driver.
• Evidence: What can prove the user journey worked: screenshots, terminal output, response bodies, logs, exit codes, created files, database changes, or another observable side effect?
• Isolation: Can verification use its own process, port, data directory, account, browser profile, or terminal session? If it cannot be isolated safely from a shared user session, document the limit and do not drive that shared instance concurrently.

Build and start the project once before authoring the guide. If the existing checkout is broken, fix the underlying issue first or record the exact failure and stop. Add temporary scaffolding only when an irrelevant missing file blocks startup; mark it as verification-only and remove it during cleanup.

2. Write a project-local guide

Put the guide in a discoverable location in the repository, such as docs/verification/<app>.md. If the project has an established convention for agent instructions, link to the guide from there. Write for an agent arriving mid-task with no prior context. Use real commands, routes, selectors, prompts, and paths found in this repository; leave no example placeholders.

Include these sections:

1. Launch: Exact setup and launch/build commands, required configuration and data, how to recognize a usable ready state, and how to stop what the guide started. For a short-lived command or library, describe the build/install step and how to run each check in an isolated process or terminal session.
2. Doctor: A read-only check that confirms the instance is worth driving: correct process and version, expected port belongs to this run, required authentication works, and initialization is complete. Run it first when the app behaves unexpectedly.
3. Drive: The actual interaction recipe. Use stable handles such as accessible names, labels, data attributes, command prompts, or route paths rather than screen coordinates or fragile tab order.
4. Evidence: What to capture, how to name it, and where to save it. Record both the action and resulting state. Follow the user’s real path through the app, and check meaningful side effects as well as what is visible. Use mocks only at existing boundaries that isolate external systems.
5. Cleanup: Stop only processes and services started by this verification run; never kill processes by name. Remove temporary instances and scratch data while preserving the evidence artifacts.
6. Helpers: Document every helper script, its executable command, inputs, and outputs. Avoid helpers whose behavior an agent must reverse engineer.

For dry-run or test modes, observe what the mode actually skips, including network access, browser launches, file writes, or git changes. Do not infer safety from a flag’s name.

3. Map the user-facing features

Create a feature index and one short file per important user-facing feature. Start with roughly three to five features found in routes, commands, menus, or documentation. Each feature entry should explain:

• What the user can do with the feature.
• How a user reaches it.
• How to exercise it with the selected harness.
• What visible result and side effect prove success.
• Preconditions and known gotchas.

Use the feature map as the coverage plan. A successful run through one convenient entry point does not cover other paths listed in the map. If the seeded account or test data lacks a required precondition, report that gap; do not weaken the user journey to make it pass.

4. Run the guide and keep its evidence

Follow the new guide from start to finish once: launch, doctor, drive one mapped feature, capture evidence, and clean up. After cleanup, confirm the named evidence still exists and can be inspected. Fix failures and repeat cleanup after each attempt so a failed iteration does not leave processes, ports, or scratch data behind.

If you verified against a stand-in rather than the intended target, list the setup the stand-in supplied and what remains unverified on the real target. A guide that has not been run end to end is a draft; label it honestly and state what blocked verification.

5. Maintain the guide as the app changes

When routes, commands, workflows, launch requirements, or data preconditions change, update the corresponding feature entry and rerun the affected journey. Keep evidence locations and cleanup instructions accurate. Hand off known gaps so the next agent can distinguish verified behavior from assumptions.

Done when

• The repository’s real launch and interaction paths are recorded without placeholders.
• The guide can detect an unusable or incorrectly owned instance before driving it.
• The feature map names meaningful user journeys and their observable success conditions.
• A first feature journey was exercised and its evidence survives cleanup, or the guide is clearly marked draft with the blocker described.
• Shared sessions, destructive cleanup, and any unverified stand-in behavior are addressed.