Forespec – catches what your AI coder didn't know to ask Forespec, an early-build tool from developer SteveWeed79, runs inside AI coding agents such as Claude Code to surface non-obvious requirements — atomic stock holds, tenant isolation, payment webhook authenticity — before code is written, then grades what was built. The tool ships five archetypes, a reasoning verifier, a plan/interrogator, a PR gate, and a greenfield on-ramp, and can be tried with no install or API key via the command "npx forespec demo"; standalone grading requires an API key, while the Claude Code plugin path runs on an existing Claude Code subscription. Forespec keeps you pointed in the right direction — at the start of a feature, along the way as it grows, and over time by remembering your past results to catch code degradation before it compounds. It's the domain foresight a senior engineer brings, codified, and kept live through your whole build. You ship fast with AI coding tools. They build what you ask — not the non-obvious thing your kind of app actually requires: an ecommerce checkout needs an atomic stock hold ; a SaaS needs tenant isolation ; a payment webhook needs authenticity . Miss one and you find out in month three, doing surgery on a live flow. Forespec surfaces those requirements before you build , hands your AI coder a gotcha-aware spec, then grades what got built and tracks how each part moves run-over-run — so the foresight arrives on time, and stays live. Forespec is not a security scanner. Security is one row of what it checks; the rest is correctness, data-modeling, reliability, and design — the whole backbone your archetype requires. It runs inside the coding agent you already use Claude Code first , so the foresight lands while the code is being written rather than in a review three days later. Status: early build. Five archetypes, the reasoning verifier, the plan/interrogator, the PR gate, and the greenfield on-ramp are here and runnable. New to this kind of project? SETUP.md https://github.com/SteveWeed79/forespec/blob/main/SETUP.md gets you going on Windows, step by step. No install, no API key, nothing to configure — this replays the verifier on a bundled vulnerable-checkout example so you can see exactly what a real grade looks like: npx forespec demo It flags the non-obvious criticals a Stripe call with no idempotency key → double charges; a stock race ; an order marked paid on the unverified client return , passes the one that's actually fine card data never touches your server , and surfaces a required piece you haven't built yet — the discernment a grader you'd trust with "is this shippable?" has to earn. Then point it at your own repo: The shortest path to a real grade on your own code. No API key, no metered cost — it runs on the Claude Code subscription you already have: /plugin marketplace add SteveWeed79/forespec /plugin install forespec@forespec /forespec:plan add checkout before you build — what does this actually require? /forespec:verify after you build — what's shippable, what's not It also loads on its own the moment you start writing payment, auth, tenancy, upload, LLM, or Supabase/Firebase code, so the requirement arrives at write time — an idempotency key passed on the payment intent is an argument; retrofitted into a live payment path it's surgery. Full details, including how to drive it from any other agent: docs/claude-code-plugin.md https://github.com/SteveWeed79/forespec/blob/main/docs/claude-code-plugin.md . This is also the better grader , not a cheap fallback. The API path packs keyword-ranked files into a character budget and grades the blob, so it can only cite a file path. An agent has grep and read: it follows the call chain into the middleware that supposedly verifies the signature, and cites file:line — a finding you can fix instead of one you have to go re-investigate. For scripting, or when there's no agent in the loop: New/empty repo — DECLARE what you're building; Forespec points you and writes a build plan: forespec start "an online store with checkout" Existing repo — detect the archetype from your code's metadata instead: forespec init Before a feature — interrogate what it actually requires foresight before you build : forespec plan "add checkout flow" After you build — grade the backbone, and see how each checkpoint moved vs last time: forespec verify standalone grading needs an API key — see below forespec verify --html …drop a visual report you can open in a browser forespec gate --help wire the PR/CI gate that comments on every pull request start and plan are the foresight-before-build half: they surface the non-obvious, archetype-required properties — the "decide first" questions and acceptance criteria — and hand them to your AI coder as an ordered, dangerous-pieces-first spec. verify and gate are the keeps-it-honest half: they grade those same checkpoints on the real code, flag what's unsafe, surface the required backbone you haven't built yet , and — reading the calibration store — show how each checkpoint moved since your last run , so a regression doesn't slip through. Over time forespec proficiency reads how much judgment you've shown per domain self-facing only and plan adapts how much it explains — full where you're learning, terse where you're fluent. start / init read only metadata dependencies, paths, schema-model names or your one-line description — never your code — to pick the archetype. Grading needs a reasoning verifier , and there are two ways to get one: - The plugin above — your coding agent grades the repo and hands the verdicts back through the same roll-up, gaps report and calibration store. No key, no cost, and it can cite file:line . Run it as /forespec:verify . Measured on the same corpus as the API path: 0 false-greens across 152 critical-bad trials → 95% upper bound ≤2.0% , with 100% outcome agreement across two independent runs. Caveats — that measures the grading contract on snippets, not the repo-navigation advantage, and your session's model is the grader — are in VALIDATION-NOTES.md https://github.com/SteveWeed79/forespec/blob/main/VALIDATION-NOTES.md . - An API key — set ANTHROPIC API KEY + ANTHROPIC MODEL and verify calls the model directly. It carries the measured bar: 0 false-greens on 52 critical bad cases, rule-of-three 95% upper bound ≤ 2.9% see VALIDATION-NOTES.md https://github.com/SteveWeed79/forespec/blob/main/VALIDATION-NOTES.md . That bar covers the ecommerce/universal corpus; the newer saas / ai-app / baas archetypes are first-pass validated full rule-of-three pending . With neither, verify refuses. It won't fake a grade — a page of keyword-matched "risky" verdicts looks like a verdict no matter how it's labelled, and the point of this tool is a number you can act on. The mock keyword baseline still exists as the dumb bar a real verifier has to beat, but you have to ask for it by name --adapter mock , and it can never certify a merge. Full walkthrough: repo-verify/README.md https://github.com/SteveWeed79/forespec/blob/main/repo-verify/README.md . CI runs on your subscription too. claude setup-token produces an OAuth token that authenticates with a Pro/Max/Team/Enterprise plan, so the PR gate bills against the plan you already have rather than a metered key — docs/ci-gate-agent.md https://github.com/SteveWeed79/forespec/blob/main/docs/ci-gate-agent.md . The merge decision stays deterministic: the agent produces verdicts, forespec gate reads them and decides. What works with no verifier at all , right now, no setup: forespec demo a real graded run on a bundled example , forespec plan "