story-gate
Make your AI prove its work before it ships.
story-gate makes your AI coding tool plan before it builds, check its course while it builds, and show you the feature working when it's done. Then it waits for your OK. No coding needed (a little GitHub is).
Free and open source (MIT) · pilot release (pre-1.0) · Works in Claude Code, Codex, Cursor, VS Code, Gemini CLI, Hermes, Windsurf and cloud agents (what each tool gets).
Key features
| Feature | What it means for you |
|---|---|
| Four checks on every story | Plan first (READY), stay on course (CHECKPOINTS), prove it works (DONE), you approve (ACCEPTANCE) |
| An independent judge | A separate AI scores the evidence. Your coding AI never grades its own work |
| Proof, not promises | Your AI runs the feature for every goal. The pull request check runs those runs again on GitHub; one that can only run on your computer (it needs a device, say) is marked "reported" and flagged for you |
| A one-page validation report | Each goal next to the run that shows it working, with screenshots and steps to try it yourself |
| Nothing merges without you | A failing story blocks the pull request, and only you (or people you name) can approve |
| A live dashboard | A pinned GitHub issue: what's in progress, what's blocked, and what needs you |
| Works with your plans | Reads Spec Kit, OpenSpec, Matt Pocock's skills, GitHub issues, and Linear or Jira tickets (Jira Server and Data Center are still experimental) |
| Settings without editing files | story-gate settings explains every setting and changes it safely (new) |
| Short CI setup | Three short workflow files that call story-gate's own, pinned to a signed release (new) |
| Built to be trusted | Your AI uses its own GitHub login, branches can't switch the checks off, and every release is signed |
New in v0.11.0
- Solo builders can approve their AI's setup PR. GitHub never counts an approval from whoever opened a pull request. Now your AI's own GitHub App opens it and makes the last commit, so your approval counts. Your login commits only the workflow files, which the App is never allowed to change (guide).
- Upgrade every repository in one go:
story-gate upgrade-repoopens one upgrade pull request per repository (--org NAMEfor all of them,--dry-runto preview,--reportfor a version table). Your own workflow steps, settings, budgets, stories and files are kept. - CI checks the copied code is a signed release. A pull request that changes story-gate's code in a repository must carry a signed, same-or-newer release with nothing extra Python could load (no
.pyc,.so, package folders, or links of any name). Hand-edited story-gate code fails. - Tighter AI access: every token story-gate creates for an agent is capped at what a builder needs (no workflows, secrets or settings), even when the App was given more. Anyone who holds the App's private key can still mint a broader token, so give the App itself only the access you want to allow.
- Safer setup: setup and upgrades stop when the default branch has a link where story-gate writes, in any letter case, and send Windows line endings as LF.
- Files in a story folder count as code. Only the gate's own records there are left out of the diff and the work fingerprint now. The
exempt_globsin your settings still apply: by default Markdown files are exempt, so a Markdown-only change in a story folder may not trigger the gates, even if app code loads that file. Before, a script placed in a story folder could be run by ordinary code and never be judged (decision). - Clearer CI isolation messages. When CI can't set up its throwaway account, the message now says which administrative command timed out and why.
- Pick the runner for the secret-free CI jobs. The reusable
gate.ymlhas an optionalrunnerinput for thetestsandmeasurejobs, which hold no GitHub secrets. Those jobs run the pull request's code. A self-hosted runner that keeps files or credentials between jobs can expose them to that code, so use a hosted runner unless the self-hosted runner is isolated. The default isubuntu-latest. With the defaultci_isolation: "strict", the runner must be Linux withuseradd,userdel,pkill,pgrep,chownandsetpriv, and run as root or have password-freesudo; Windows and macOS runners can't run the pull request's tests under strict isolation. Thestory-gatejob, the audit and the dashboard always run onubuntu-latest.story-gate installdoes not write this line yet, so add it by hand and add it again after a re-install. - The signed-copy check catches links of any name. A link called
jsonthat points to a folder with an__init__.pywould have loaded instead of Python's ownjsonmodule, and its name had no.pyto give it away. Now any link the signed release does not list fails the check, a folder the check can't list fails it too, and a pull request that adds only such a link is checked.
New in v0.10.1
- Setup no longer writes your computer's Python path into the committed
AGENTS.md,CLAUDE.mdandGEMINI.md. The cloud fallback is nowpython3 .story-gate/gate.py(pythonon Windows). If you set up a repository with v0.10.0, runstory-gate installin it again to refresh those files. - DONE steps name every argument that
record-testsandlearnneed. - The dashboard only edits its own issue: the issue its workflow opened, even when many other labelled issues come first. It never edits a pull request.
New in v0.10.0
- Story dependencies, risks and blockers: a story says what it waits for (
depends_onplus a## Dependenciessection withwhen: before-start | before-mergeandwhy:), what could go wrong (## Risks) and what's blocking it (## Blockers). READY checks that every dependency exists, that there is no loop, and that a before-start dependency is finished on the latest main. DONE makes sure every dependency is finished before the story can merge. An open blocker fails READY, and that can't be waived. The link is written once, on the waiting story; "blocks" is worked out from the other side, so finished stories are never edited (dependencies). - See it on the dashboard: a new Waiting stage, a "Depends on / Blocks" column, a warning for dependency loops and a suggested build order.
gate.py deps <ID>prints both directions. - Known pitfalls (off by default): READY shows each story the mistakes other projects kept making, from a learner's feed, and asks the story to acknowledge the critical ones (pitfalls).
- Judge: with
TYPESAFE_API_KEYset, story-gate asks TypeSafe's Jev judge directly first and uses OpenRouter only if that fails (turn it off withjudge.jev_fallback: false).
Upgrading: one behaviour change. A story that lists
depends_onbut has no## Dependenciessection now treats each dependency as before-start. If you re-score it while that dependency isn't merged yet, READY fails (before, it only checked for a handoff). The fix is one edit: add a## Dependenciessection and mark parallel workwhen: before-merge. Stories without dependencies behave exactly as before.
Sound familiar?
- Your AI says "done", but the button does nothing.
- You fix one thing, and two other things break.
- It built something you never asked for.
- You can't tell if the code is any good, so you're afraid to merge.
Use it when real people will use what you build, when your AI keeps breaking things that worked, or when more than one person (or AI) works in the same project. Skip it for a weekend prototype: the checks add a few minutes per story.
How it works
| When | What story-gate checks | What you see |
|---|---|---|
| Before any code | The plan is clear and every goal has a test (READY) | A short plain-English summary |
| While it builds | It's still on course, with no scope creep (CHECKPOINTS) | % done on the dashboard |
| When it says done | The tests pass, and the AI ran the feature for real for every goal (DONE). The pull request check runs them again; a run that can't work there is marked "reported" and flagged | A one-page validation report |
| Before it merges | You approve it on GitHub | Nothing merges without you, where GitHub enforces branch rules |
Each fact on the validation page is marked checked (the pull request check ran it) or reported (the AI says so). Ask your AI: story-gate report <story id> --open.
See it block a real pull request
In our public demo repository, an AI opened this pull request for one small feature: 10% off orders of 10 or more items. Its own unit tests pass, and its write-up says "Done".
story-gate ran every goal again on GitHub. An order of exactly 10 items paid full price (40.00, not 36.00). The check is red and the merge is blocked. Open the story-gate check on that pull request to see the evidence.
Then the AI fixed it in this pull request: qty > 10 became qty >= 10, and it added the missing test for exactly 10 items. Every goal passes, the judge agrees, and the check turns green once a person approves.
| Red: #5 | Green: #6 | |
|---|---|---|
| The AI says | "Done" | "Done" |
| Its own unit tests | Pass | Pass |
| story-gate runs "exactly 10 items" | 40.00, expected 36.00 | 36.00 |
| Merge | Blocked | Allowed after a person approves |
Try it in two minutes
Nothing to set up, and your own projects aren't touched.
Mac or Linux (Terminal):
curl -LsSf https://raw.githubusercontent.com/SathiaAI/story-gate/v0.11.0/install.sh -o /tmp/story-gate-install.sh && sh /tmp/story-gate-install.sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/SathiaAI/story-gate/v0.11.0/install.ps1 | iex"
Then run story-gate try. It makes a throwaway project with one small story and a real bug, runs each goal, shows one pass and one fail, and opens the validation page. No GitHub, no judge key, no network.
What the installer does: it installs uv (a Python tool manager) if you don't have it, then story-gate at this exact release, and puts story-gate on your PATH. Nothing else. Read install.sh or install.ps1 first if you like. Already have uv? Run uv tool install --python 3.12 git+https://github.com/SathiaAI/story-gate@v0.11.0 instead.
Set it up in 5 steps
Step 1. Open your project in your AI tool and paste:
Set up story-gate in my project (the folder I have open). Install it from https://github.com/SathiaAI/story-gate, but don't change that repository.
Already use skills? npx skills add SathiaAI/story-gate adds the story-gate skill to Claude Code, Codex, Cursor and 20+ other AI tools. Then paste the same sentence.
Steps 2 to 5 happen on a page that opens in your browser. It tells you exactly what to click and ticks each step off.
| You need | Details |
|---|---|
| A GitHub account and your project on GitHub | Your AI installs everything else |
| A judge key (step 4) | Make one at openrouter.ai/keys and add some credit. Each check is one small call. Setup does not hand the key to your AI. It goes into a GitHub secret, and a copy stays on your computer that anything running as you can read, so give it a spending limit. No key yet? Click Skip for now (see the FAQ) |
| Who approves | You, plus anyone you add in step 5. Working alone is fine: the AI opens pull requests under its own login, so your approval counts |
| Teammates | Each person pastes the same sentence once on their own computer |
From day one, a pull request that fails story-gate can't be merged (where GitHub enforces branch rules: public repositories and paid plans), as long as your project has tests your AI can name for setup. Without tests, story-gate starts by only warning.
Short workflows (optional): ask your AI to run story-gate install --ci reusable. Your repository then keeps three short workflow files instead of three long ones, and upgrades are a one-line change. How it works.
Your first story
- Ask your AI for one small feature, for example: "Add a contact form with name, email and message."
- Your AI writes the story: a plain summary, the goals and the tests. story-gate checks it (READY).
- Your AI builds it. story-gate checks it stays on course.
- Your AI runs the feature for every goal and writes the validation report (DONE).
- It opens a pull request. Open the validation page, try the demo steps, then approve on GitHub.
Habits that pay off: keep stories small (one feature a person can see), read the report before you approve, and when a check fails, ask your AI to fix the cause, not to skip the check. Lost track? Ask your AI to run story-gate next.
The dashboard
The dashboard answers one question: is the work on course, and does anything need me? You don't need to open a terminal or read code to use it.
Find it. Open your repository on GitHub → Issues → Story-gate dashboard, pinned at the top. Setup creates it, and story-gate doctor prints its link. Only people who can see the repository can see it.
It stays current by itself. It refreshes every 30 minutes, after every story-gate check on a pull request, and after every merge to your main branch. To refresh it now: Actions → story-gate-dashboard → Run workflow.
Read it top to bottom:
- The top numbers. Stories ready, in progress, blocked and done, and the share of acceptance criteria that tests proved.
- Who is working on what. Each AI agent, its story, its stage, % done (an estimate), drift, the pull request check and its last report.
- Queued to start. Stories that passed READY and are waiting for an agent.
- Features. Each feature's stories, how many are done and how many acceptance criteria are proven.
- All stories. Every story and where it is: Draft → Queued → In progress → In review → Done, or Blocked.
What needs you:
| You see | It means | Do this |
|---|---|---|
| Blocked | The agent went off course, or a check needs a human decision | Open the story's pull request and read the last checkpoint. Decide, or ask your AI what it needs from you |
Drift other than none, or AT_RISK | The work is moving away from the plan | Ask your AI to run story-gate next and explain the drift in plain words |
| ⚠ stale | No new record from that agent for 3 days | Check whether the work stopped. Restart it or drop the story |
| (out of date) next to READY | The story or its tests changed after READY passed | Ask your AI to re-check READY before it carries on |
| (checked without a judge) | The story was checked in objective mode | Fine if that's your choice. Only tests, structure and traceability were checked |
| Ownership conflicts | Two agents claimed the same story | Pick one and stop the other |
| source changed next to a story's CI result | A ticket copied in with spec-pull differs from the live issue | Ask your AI to pull it again and re-check READY |
| Refresh failed note at the top | The last update didn't run | The numbers shown are from the last good refresh. Open the linked run, or run the workflow again |
The full report. Click download the HTML dashboard in the issue for charts, the pipeline and every quality number with how it's calculated. Or ask your AI to run story-gate dashboard --open to build it from your computer, including branches you haven't pushed yet.
More detail: the dashboard guide.
Works with Spec Kit, OpenSpec, BMAD, Matt Pocock's skills, Linear and Jira
Keep the tool you plan with. These tools write a good plan, but none of them blocks a pull request when the code doesn't do what the plan says. story-gate is that gate.
| You plan with | Link it in the story | story-gate reads |
|---|---|---|
| Spec Kit | spec: specs/001-checkout/spec.md (add #US1 for one user story) | Each "Given … When … Then" scenario |
| OpenSpec | spec: openspec/changes/add-discount | Each #### Scenario: |
| Matt Pocock's skills | The ticket file, e.g. spec: .scratch/refunds/issues/03-refund.md | Each - [ ] criterion and "As a …, I want …" user story |
| GitHub Issues | story-gate spec-pull <story> #42 | The issue's criteria and user stories |
| Linear or Jira (Cloud, Server, Data Center; Server and Data Center experimental) | story-gate spec-pull <story> ENG-12, once the tracker is set up (Linear, Jira) | The ticket's criteria and user stories |
| BMAD | Not read yet (its file layout is changing). Copy its acceptance criteria into story.md | Your acceptance criteria |
For every one of them: each requirement must be covered by an acceptance criterion with passing tests, a recorded run and your approval. A dropped or hidden requirement blocks the check. A ticked box is not proof; only a passing test is. Copied issues and tickets are compared with the live version on every pull request (how; specs in another repository).
How it compares
| Checks the plan first | Proves each goal works | Re-checks on every pull request | Needs your approval | |
|---|---|---|---|---|
| Nothing (just the AI) | No | No | No | No |
| Your tests in CI | No | Only what the tests cover | Yes | No |
| A PR review bot (e.g. CodeRabbit) | No | No | Yes (reads the code) | No |
| A spec tool (Spec Kit, OpenSpec, BMAD) | Yes | No (the AI checks its own work) | No | No |
| story-gate | Yes | Yes | Yes | Yes |
story-gate works alongside your tests and your review bot: it runs your tests itself and waits for the review bot's threads to be resolved.
Good to know
- Your AI never uses your GitHub login. It works through its own login, so it can't approve or merge its own work.
- Branches can't switch story-gate off. The rules come from your main branch, and the checks run from a verified copy. See security.
- Change settings safely.
story-gate settingslists every setting in plain English; a change that loosens the rules needs a code owner's approval (how). - Plain English. Your AI writes replies, pull request descriptions, summaries and handoffs in short, plain sentences. story-gate scores this and gives advice (plain writing).
- Pilot: pre-1.0, so commands and settings may still change. Every release since v0.7.0 is signed, and story-gate checks the signature before it installs itself (how).
FAQ
Do I need to code? No. You need a GitHub account, and you click Approve and Merge on GitHub. Your AI does the rest.
What does it cost? story-gate is free. The judge runs on OpenRouter, which charges per call. Each check is one small call, and your OpenRouter activity page shows the exact cost. By default story-gate also runs a second, "shadow" pass of narrow questions (about one request per changed file, criterion and group of files, at most 60) to compare with the first. It never decides the result: judge.decompose: on is disabled in this release until the narrow-check hardening (issue #106) is done, and the only values are off and shadow.
Will it slow my AI down? A little. Each story takes extra time for the plan, the checks and the report. You get that back in less rework.
What if the judge is wrong? Tell story-gate (story-gate label). A person can also record a decision or a waiver, but it counts only after a code owner approves.
Is my code sent anywhere? Yes, to the judge you chose (OpenRouter by default). For each check it gets that story's evidence: the story and its context, the test plan, the scenarios (what each one runs and expects), validation.md, the handoff, the learnings, and the code changes. If you set up a webhook, control-hub or a command to receive events, it gets story-gate's events: verdicts, progress and learnings. Your AI coding tool already sends far more to its own model.
Can I try it without a judge key? Yes. Click Skip for now at the key step. story-gate then runs in objective mode: it still checks the plan, runs your tests and the story's scenarios in CI, and needs your approval, but nothing checks that the code really does what the story asks. Your tests must write a JUnit XML report (one setting; your AI sets it up) so story-gate sees each test's own result. Every result says checked without a judge. To turn the judge on later, do both: add the OPENROUTER_API_KEY repository secret, then set "judge_mode": "full" in .story-gate/config.json in a pull request (see Fallbacks in the guide). A key alone doesn't turn it on.
I'm on a free GitHub plan with a private repository. GitHub doesn't enforce "must be approved" there. story-gate still checks every pull request and marks it ADVISORY.
Words used here
| Word | Meaning |
|---|---|
| Story | One piece of work, small enough to build and check in one go |
| Acceptance criteria (goals) | The things that must be true when the story is done |
| Scenario | Your AI running the feature the way a person would, to show a goal working |
| READY, CHECKPOINTS, DONE | The three checks story-gate runs: before, during and after the build |
| Judge | An independent AI that scores the evidence. It is never your coding AI |
| Pull request (PR) | GitHub's page where a change waits for your approval before it joins your project |
| CI | The checks GitHub runs on every pull request |
| Drift | The work, the story and your product documents (PRD, TRD) no longer agree |
| Code owner | A person allowed to approve changes. You, and anyone you add |
Learn more
- The full guide: every setting, manual setup, lockdown and fallbacks.
- How each AI tool runs story-gate · Pinned project hooks
For AI agents: how to run the setup
When the person asks you to set up story-gate:
- Make sure
uvis installed (uv --version). If it isn't, install it with the official installer:- macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
- macOS / Linux:
- Install story-gate:
uv tool install --python 3.12 git+https://github.com/SathiaAI/story-gate@v0.11.0, thenuv tool update-shellifstory-gateisn't found. - Find how the project's tests run on a clean Linux machine, including installing what they need (for example
npm ci && npm test). In the project folder, runstory-gate init --test-command "<that command>"in the background (leave the flag out if there are no tests yet). It prints a local page address and opens it in the browser. Keep it running until it printsstory-gate: story-gate is protecting .... - Tell the person: "A setup page opened in your browser. Follow it; I'll wait." Do not click, sign in, create apps or type the judge key for them. Those steps are theirs.
- When it finishes, run
story-gate doctorand report its summary in plain words. Tell the person where their dashboard is (the linkdoctorprints).
If the setup page reports an error, read it to the person and follow its instructions. Run story-gate init again to continue; it skips what is already done on GitHub.
Tests: python -m unittest tests/test_gate.py tests/test_packaging.py. CI runs tests/test_gate.py on Linux, Windows and macOS. MIT licensed. story-gate by Viaknox.