Skip to content

sathiaai/story-gate

v0.11.0MIT

Make your AI prove its work before it ships: it plans before it builds, checks its course while it builds, shows every goal working, and waits for a person to approve on GitHub. Works in Claude Code, Codex, Cursor, VS Code, Gemini CLI and Hermes.

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

FeatureWhat it means for you
Four checks on every storyPlan first (READY), stay on course (CHECKPOINTS), prove it works (DONE), you approve (ACCEPTANCE)
An independent judgeA separate AI scores the evidence. Your coding AI never grades its own work
Proof, not promisesYour 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 reportEach goal next to the run that shows it working, with screenshots and steps to try it yourself
Nothing merges without youA failing story blocks the pull request, and only you (or people you name) can approve
A live dashboardA pinned GitHub issue: what's in progress, what's blocked, and what needs you
Works with your plansReads 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 filesstory-gate settings explains every setting and changes it safely (new)
Short CI setupThree short workflow files that call story-gate's own, pinned to a signed release (new)
Built to be trustedYour 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-repo opens one upgrade pull request per repository (--org NAME for all of them, --dry-run to preview, --report for 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_globs in 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.yml has an optional runner input for the tests and measure jobs, 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 is ubuntu-latest. With the default ci_isolation: "strict", the runner must be Linux with useradd, userdel, pkill, pgrep, chown and setpriv, and run as root or have password-free sudo; Windows and macOS runners can't run the pull request's tests under strict isolation. The story-gate job, the audit and the dashboard always run on ubuntu-latest. story-gate install does 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 json that points to a folder with an __init__.py would have loaded instead of Python's own json module, and its name had no .py to 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.md and GEMINI.md. The cloud fallback is now python3 .story-gate/gate.py (python on Windows). If you set up a repository with v0.10.0, run story-gate install in it again to refresh those files.
  • DONE steps name every argument that record-tests and learn need.
  • 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_on plus a ## Dependencies section with when: before-start | before-merge and why:), 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_KEY set, story-gate asks TypeSafe's Jev judge directly first and uses OpenRouter only if that fails (turn it off with judge.jev_fallback: false).

Upgrading: one behaviour change. A story that lists depends_on but has no ## Dependencies section 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 ## Dependencies section and mark parallel work when: 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

WhenWhat story-gate checksWhat you see
Before any codeThe plan is clear and every goal has a test (READY)A short plain-English summary
While it buildsIt's still on course, with no scope creep (CHECKPOINTS)% done on the dashboard
When it says doneThe 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 flaggedA one-page validation report
Before it mergesYou approve it on GitHubNothing 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: #5Green: #6
The AI says"Done""Done"
Its own unit testsPassPass
story-gate runs "exactly 10 items"40.00, expected 36.0036.00
MergeBlockedAllowed 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 needDetails
A GitHub account and your project on GitHubYour 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 approvesYou, plus anyone you add in step 5. Working alone is fine: the AI opens pull requests under its own login, so your approval counts
TeammatesEach 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

  1. Ask your AI for one small feature, for example: "Add a contact form with name, email and message."
  2. Your AI writes the story: a plain summary, the goals and the tests. story-gate checks it (READY).
  3. Your AI builds it. story-gate checks it stays on course.
  4. Your AI runs the feature for every goal and writes the validation report (DONE).
  5. 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:

  1. The top numbers. Stories ready, in progress, blocked and done, and the share of acceptance criteria that tests proved.
  2. Who is working on what. Each AI agent, its story, its stage, % done (an estimate), drift, the pull request check and its last report.
  3. Queued to start. Stories that passed READY and are waiting for an agent.
  4. Features. Each feature's stories, how many are done and how many acceptance criteria are proven.
  5. All stories. Every story and where it is: Draft → Queued → In progress → In review → Done, or Blocked.

What needs you:

You seeIt meansDo this
BlockedThe agent went off course, or a check needs a human decisionOpen 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_RISKThe work is moving away from the planAsk your AI to run story-gate next and explain the drift in plain words
⚠ staleNo new record from that agent for 3 daysCheck whether the work stopped. Restart it or drop the story
(out of date) next to READYThe story or its tests changed after READY passedAsk your AI to re-check READY before it carries on
(checked without a judge)The story was checked in objective modeFine if that's your choice. Only tests, structure and traceability were checked
Ownership conflictsTwo agents claimed the same storyPick one and stop the other
source changed next to a story's CI resultA ticket copied in with spec-pull differs from the live issueAsk your AI to pull it again and re-check READY
Refresh failed note at the topThe last update didn't runThe 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 withLink it in the storystory-gate reads
Spec Kitspec: specs/001-checkout/spec.md (add #US1 for one user story)Each "Given … When … Then" scenario
OpenSpecspec: openspec/changes/add-discountEach #### Scenario:
Matt Pocock's skillsThe ticket file, e.g. spec: .scratch/refunds/issues/03-refund.mdEach - [ ] criterion and "As a …, I want …" user story
GitHub Issuesstory-gate spec-pull <story> #42The 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
BMADNot read yet (its file layout is changing). Copy its acceptance criteria into story.mdYour 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 firstProves each goal worksRe-checks on every pull requestNeeds your approval
Nothing (just the AI)NoNoNoNo
Your tests in CINoOnly what the tests coverYesNo
A PR review bot (e.g. CodeRabbit)NoNoYes (reads the code)No
A spec tool (Spec Kit, OpenSpec, BMAD)YesNo (the AI checks its own work)NoNo
story-gateYesYesYesYes

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 settings lists 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

WordMeaning
StoryOne 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
ScenarioYour AI running the feature the way a person would, to show a goal working
READY, CHECKPOINTS, DONEThe three checks story-gate runs: before, during and after the build
JudgeAn 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
CIThe checks GitHub runs on every pull request
DriftThe work, the story and your product documents (PRD, TRD) no longer agree
Code ownerA person allowed to approve changes. You, and anyone you add

Learn more

For AI agents: how to run the setup

When the person asks you to set up story-gate:

  1. Make sure uv is 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"
  2. Install story-gate: uv tool install --python 3.12 git+https://github.com/SathiaAI/story-gate@v0.11.0, then uv tool update-shell if story-gate isn't found.
  3. 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, run story-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 prints story-gate: story-gate is protecting ....
  4. 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.
  5. When it finishes, run story-gate doctor and report its summary in plain words. Tell the person where their dashboard is (the link doctor prints).

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.