Verify Setup

/verify-setup

Run once per repo. Later /verify runs read .verify/setup.json and ask nothing.

Hard rule: never ask for or store passwords, API keys, or connection strings. The one exception is captured browser session state (.verify/auth.json, written by the auth step below): it holds reusable cookies for the app under test, is gitignored, and deleting the file revokes it. Treat it like a logged-in browser profile, not a secret store. No production connection strings, no cloud keys. The most this file may reference is one of the repo's own local .env files, chosen by the user. If a user pastes a secret, refuse to write it and tell them to keep it in their environment.

1. Ignore rules

grep -qxF ".verify/" .gitignore 2>/dev/null || echo ".verify/" >> .gitignore

.verify/setup.json is the one file meant to be shared. After writing it, offer: "Commit .verify/setup.json so your team skips this interview? (y/n)" — on yes, git add -f .verify/setup.json and commit it.

Write the recipe, not the resolved values

The contract must work in every checkout and worktree of the repo, or the interview repeats forever. Two rules:

• Ports and hosts go through environment variables. When the repo documents per-worktree port variables (an AGENTS.md export block, a .env.example), write http://localhost:${INGESTION_PORT:-8082} — the repo's own variable name with the repo's default — never the number the current worktree happens to use. URL fields (base_url, health_url) support exactly ${VAR} and ${VAR:-default} — no nesting, no command substitution — expanded identically by the scripts and the engine at run time. Probes and boot are shell programs and expand everything the shell does, for free.

• Nothing run-scoped. A probe that names a specific run's container (verify-20260901-042757-worker-1) is dead the moment that run ends. Key probes to the compose service via the current run's project instead:

  docker ps --filter "label=com.docker.compose.project=$(jq -r .project .verify/run-env.json)" \
    --filter "label=com.docker.compose.service=worker" --format '{{.State}}' | grep -q running

Before offering the commit, re-read the drafted contract and reject your own draft if any field contains a resolved port number that has a documented variable, or any name containing a run id.

2. Sniff the repo

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
bash "$VERIFY_SCRIPTS/sniff.sh" > /tmp/verify-sniff.json
cat /tmp/verify-sniff.json

3. Confirm, one question per unknown

Use AskUserQuestion. Every option must come from the sniff output; the user corrects rather than authors. A single unambiguous candidate is taken silently and shown in the final summary.

• Boot: options = each .boot[] candidate (label with its cmd), plus "it's already running (breaks isolation — not recommended)" which selects "mode": "external". The chosen candidate's mode and compose_file are copied into the contract — never mix a process boot with a compose teardown. For "process" mode, health_url is required — do not write the contract until the user supplies the URL to poll. For "compose" mode, write teardown: "docker compose -f <file> down -v" — a throwaway stack that keeps its volumes is not throwaway.
• Seed: options = .seed[], plus "no seeding" and "I have a data file to load" (if chosen, ask for the path and put it in seed_data_files; it is a plain file the user produced themselves — how they made it is outside verify).
• Env file: options = .env_files[], plus "none". The chosen file is sourced by the environment manager before boot, seeds, and probes.
• Base URL: default http://localhost:3000, or the value in the env file if it names one.
• How do API requests authenticate? A) a header whose value lives in an env var — name the header (for example, X-API-Key) and the env var name; or B) no auth. The value itself is never written anywhere: the contract stores only the header name and the env var name.
• Probes: for each of worker, sink, storage, ask "is there a one-line command that proves your <part> is alive? (leave blank to skip)". Explain: a part with no probe still runs its criteria, but a failure on it will be reported as possibly environmental rather than blamed on the change. (api, browser, and db have built-in probes; don't ask about them.)

If .has_stack is false: plain-command mode. Write the contract with "mode": "none" and empty boot/teardown/health, and say: "No runnable stack found; /verify will run criteria as plain commands."

4. Write the contract

Write .verify/setup.json. The shape (this example is load-bearing — a test parses it):

{
  "mode": "compose",
  "compose_file": "compose.yaml",
  "boot": "docker compose -f compose.yaml up -d --wait",
  "teardown": "docker compose -f compose.yaml down -v",
  "seed": ["scripts/seed-e2e.sql"],
  "seed_data_files": [],
  "health_url": "",
  "base_url": "http://localhost:${APP_PORT:-3000}",
  "auth": {"header": "", "value_env": ""},
  "env_file": ".env.example",
  "observe": {"db_url_env": "DATABASE_URL"},
  "probes": {"worker": "", "sink": "", "storage": ""}
}

Valid modes: "compose", "process" (health_url required), "external", "none".

Show the written file and the summary of silently-taken single candidates.

5. Capture authentication, if needed

Keep authentication as Playwright storage state. It contains no password entry flow or credential capture by Verify; the user logs in directly in the browser.

Check whether the selected base URL is running:

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
BASE_URL=$(jq -r '.base_url' .verify/setup.json | bash "$VERIFY_SCRIPTS/expand.sh" --load-env .verify/setup.json)
curl -sf "$BASE_URL" > /dev/null 2>&1 || echo "⚠ Dev server not running at $BASE_URL. Start it before logging in."

If the app requires login, open Playwright codegen and let the user authenticate:

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
BASE_URL=$(jq -r '.base_url' .verify/setup.json | bash "$VERIFY_SCRIPTS/expand.sh" --load-env .verify/setup.json)
mkdir -p .verify
echo "A browser will open. Log in, then close the browser window."
npx playwright codegen --save-storage=.verify/auth.json "$BASE_URL"
chmod 600 .verify/auth.json

Verify the capture:

if [ -f .verify/auth.json ] && [ -s .verify/auth.json ]; then
  COOKIE_COUNT=$(jq '.cookies | length' .verify/auth.json 2>/dev/null || echo 0)
  echo "✓ Auth state captured: $COOKIE_COUNT cookies"
else
  echo "✗ auth.json is empty. Log in when the browser opens, then close it."
  exit 1
fi

6. Share with your worktrees

A git worktree gets the committed contract for free but not the gitignored files. Push them to the per-repo shared store so every worktree inherits them:

VERIFY_SCRIPTS="${VERIFY_SCRIPTS:-$CLAUDE_PLUGIN_ROOT/scripts}"
bash "$VERIFY_SCRIPTS/shared-store.sh" push

This copies .verify/auth.json and the chosen env file to ~/.verify/<repo-slug>/ (permissions 700/600). Tell the user: deleting that folder stops NEW worktrees inheriting the login; copies already pulled into worktrees remain until their .verify/ is deleted. Run push again whenever auth is recaptured or the env file changes.