Open-source · Go · MCP-native

Ground your AI agents in real-world human problems and production battle-scars.

Claude Code, Cursor and Antigravity write the happy path. OpenStories hands them what production already taught everyone else: user stories with Gherkin criteria, the edge cases that broke real systems, and the GitHub issues, Reddit threads and post-mortems that prove it.

0evidence-backed stories

0industries

0domains

Stress-test a spec

The happy-path bias

Your agent has never been paged at 3 AM.

Ask a coding agent for a magic-link login and it will write one that works in the demo. It has no way of knowing that Microsoft Defender pre-fetches every link in an inbound email, burning the one-time token before a human ever clicks. Someone on GitHub knows. Someone on Reddit ranted about it. OpenStories puts that knowledge in the agent's context before it writes a line.

openstories eval report: Reality Coverage Score 54/100 with production blind spots listed — `openstories eval` on a one-line spec. Every blind spot cites a story, every story cites its evidence.

Reality stress-tester

Type a feature. See what production would have said.

The same engine as openstories eval: your spec is matched against the library, every known edge case it does not mention counts against it. Pick a sample or write your own.

Incident showcase

Stories that started as someone's outage.

Five of the curated stories, each with its acceptance criteria and the public evidence behind it. Click the quotes; they go to the source.

1-click MCP setup

Two commands. Your agent reads the library before it writes.

openstories install claude and openstories install cursor writing MCP server entries — `openstories install claude` writes the MCP entry into `~/.claude.json` and Claude Desktop. `openstories install cursor` does the same for `~/.cursor/mcp.json`.

Install the binary. go install github.com/gabrielrondon/openstories/cmd/openstories@latest. Zero dependencies, the library is embedded.
Register the MCP server. openstories install claude or openstories install cursor. Restart the client.
Ask before you build. "What does production say about magic links?" The agent calls search_stories and gets the criteria, the edge cases and the citations.
Lint the spec. openstories eval --file spec.md in CI, or the evaluate_spec tool from inside the agent.

Also: openstories serve runs the web dashboard and a REST API (/api/stories, /api/eval) on your machine. openstories harvest --repo mines a public repo's issues into new stories.

openstories get OS-DEV-001 showing Gherkin acceptance criteria, edge cases and evidence links — `openstories get OS-DEV-001`. Idempotency keys on mutation endpoints, with the $45k duplicate-charge incident that made someone write it down.

openstories list showing stories across industries with demand scores — `openstories list` and `openstories search`. Every story has an id, an industry, a domain and a demand score.

openstories serve dashboard: catalog of stories filtered by industry and domain — `openstories serve`. The same library in a local dashboard, filterable by industry, domain and demand score.

Story detail in the dashboard: acceptance criteria, edge cases and evidence — Story detail: the user story, Gherkin scenarios, edge cases and the evidence, one click from the list.

Get it

Stories are Markdown files with YAML front matter under stories/<industry>/<domain>/. A story needs a real citation to be merged. Contributing guide.