opslane/verify / skills/verify-setup
verify-setup
UnverifiedOne-time setup for /verify and /break. Sniffs the repo, confirms boot/seed/health with you, writes .verify/setup.json, captures auth if the app needs login, and builds .verify/profile.json, a model of how the app runs.
/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), writehttp://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 itscmd), plus "it's already running (breaks isolation — not recommended)" which selects"mode": "external". The chosen candidate'smodeandcompose_fileare copied into the contract — never mix a process boot with a compose teardown. For"process"mode,health_urlis required — do not write the contract until the user supplies the URL to poll. For"compose"mode, writeteardown: "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 inseed_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 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, anddbhave 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.
7. Build the app profile
/break attacks a change on a local copy of the app. To pick attacks that match how the
app really runs, it reads a profile of the app: what runs in the background, which
tables have statuses and what moves them, which outside services it calls, which
settings change behaviour when empty, and what sits in front of it in production.
Always build it; it is part of setup, not a question for the user. Build it from the
code alone: read the repo, do not boot anything, use no network. It takes a few minutes.
If it fails, say so in the summary and finish setup anyway: /break works without it.
Fill exactly this shape and write it to .verify/profile.json (this example is
load-bearing: a test checks it against the engine's validator):
{
"version": 1,
"services": [
{"name": "api", "kind": "api", "run": "compose service api", "source": "compose.yaml:3"}
],
"actors": [
{"name": "job-reaper", "kind": "reaper", "service": "worker", "interval_s": 60,
"interval_env": "REAPER_INTERVAL_MS", "touches": ["jobs"], "source": "worker/src/index.ts:191"}
],
"entities": [
{"table": "jobs", "status_field": "status", "statuses": ["pending", "claimed", "completed", "dead_letter"],
"transitions": [
{"from": "claimed", "to": "pending", "by": "job-reaper", "source": "worker/src/db.ts:1323"},
{"from": "any", "to": "pending", "by": "request:POST /api/jobs", "source": "api/handler/jobs.go:40"}
],
"source": "migrations/001_jobs.sql:5"}
],
"external": [
{"name": "anthropic", "kind": "llm", "env": ["ANTHROPIC_API_KEY"], "stubbable": "yes",
"stub_how": "ANTHROPIC_BASE_URL", "source": "worker/src/llm.ts:12"}
],
"config": [
{"name": "OPENAI_API_KEY", "default": null, "effect": "empty: no embeddings, duplicates are never merged",
"source": ".env.example:20"}
],
"edge": {"hops": ["cloudflare", "load_balancer"], "source": "answered by the user"}
}
- services: every process, from compose files, Procfiles, package scripts or
manifests.
kindis one ofapi,worker,web,db,queue,storage,other. - actors: every loop, timer, scheduler, poller, reaper, sweeper, cron job, queue
consumer, boot-time task and startup migration runner.
kindis one ofscheduler,poller,reaper,sweeper,consumer,boot_task,migration.toucheslists the tables or queues it writes;/breakuses it to find the actors that matter for a change. - entities: only tables with a status or state field. List the transitions you can
find;
byis an actor name,request:<METHOD /path>, orunknown. - external: every outside API or SDK.
stubbablesays whether a local stand-in can replace it andstub_hownames the setting that points it elsewhere (or null). - config: only settings where an empty or default value changes behaviour, with the effect in one line. Never record a secret value.
- edge: the chain in front of production, outermost first, each hop one of
cloudflare,cdn,vercel,load_balancer,nginx_or_ingress,none,unknown. Detect it from deploy files and docs when you can.
Rules:
- Every item cites
sourceaspath:linein this repo. No source, no item. - What the code does not show is
"unknown", never a guess. Unknowns are fine:/breaktests both ways when that is cheap. - Do not record which writes lack a guard, who else reads shared data, or how many
replicas run. They are easy to get wrong from reading, so
/breakworks them out fresh for each change. - Ask the user only when an unknown field would block a likely, valuable attack and their answer changes how it is tested. Use AskUserQuestion with the field's allowed values as the options, never an open question. In practice this is usually one question: confirm the edge chain. Decisions about how to test (whether to point a test tenant at a stub, for example) are yours to make, not questions for the user.
- Record an answer as
"source": "answered by the user".
Check it with the engine and fix every error it reports:
VERIFY_PIPELINE="${VERIFY_PIPELINE:-$CLAUDE_PLUGIN_ROOT/pipeline}"
(cd "$VERIFY_PIPELINE" && npx --no-install tsx src/cli.ts profile-check --repo "$(pwd -P)")
Show the user a short summary: counts per section, the edge chain, and the few config
settings with the biggest effect. Then offer: "Commit .verify/profile.json so your team
and future runs share it? (y/n)". On yes, git add -f .verify/profile.json and commit it.
Finish with: ✓ Setup complete. Run /verify before your next PR.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |