# Agent guidance: executable-stories
TypeScript-first BDD story testing monorepo. Tests and documentation from the same code. Context for AI agents working in this repo.
## Vision
Framework native first.
This project is not Cucumber. We do not implement Gherkin, step matching, or a world object. We build small APIs that feel normal inside the host framework.
Rule of thumb:
If a change makes it feel less like Vitest, Jest, or Playwright, do not do it.
Examples:
- Prefer using the framework test primitives and reporting hooks.
- Do not add a separate runtime, interpreter, or feature file layer.
- Do not invent global shared state to simulate a world.
Goal:
Tests are the source of truth. Docs are derived from test registration and results.
## Project structure
```
packages/
executable-stories-vitest/ # Vitest adapter (story API + StoryReporter)
executable-stories-jest/ # Jest adapter
executable-stories-playwright/ # Playwright adapter
executable-stories-cypress/ # Cypress adapter
executable-stories-e2e/ # e2e (TesterArmy) reporter + step markers
executable-stories-bun/ # bun:test adapter (test/describe wrappers + preload)
executable-stories-formatters/ # Core: report generation (HTML, Markdown, JUnit, Cucumber JSON/HTML/Messages)
executable-stories-trackers/ # Tracker-agnostic: group a run by ticket, word a status, publish through a TrackerClient
executable-stories-linear/ # Linear TrackerClient + `executable-stories-linear publish` CLI (one updating attachment per issue)
executable-stories-ruby/ # Ruby adapter (Minitest story API + JSON output)
executable-stories-go/ # Go adapter (testing.T story API + JSON output)
executable-stories-rust/ # Rust adapter (Story struct + JSON output)
executable-stories-pytest/ # Python pytest adapter
executable-stories-junit5/ # JUnit 5 (Kotlin) adapter
executable-stories-xunit/ # xUnit (C#) adapter
executable-stories-showcase/ # Open any app state from a URL (scenarios, dev panel, Playwright helpers, store adapters)
executable-stories-showcase-cli/ # Showcase CLI: shoot, affected, coverage, publish, record, validate, doctor, MCP; ships its own skills
executable-stories-showcase-react/ # useScenarioState for React/Preact
executable-stories-remotion/ # Remotion compositions from a run's storyboard and showcase recordings
eslint-config/ # Shared ESLint config
eslint-plugin-*-executable-stories/ # Per-framework ESLint plugins
apps/
vitest-example/ # Vitest example app
jest-example/ # Jest example app
playwright-example/ # Playwright example app
cypress-example/ # Cypress example app
docs-site/ # Astro Starlight documentation site
showcase/ # Showcase unit tests, Playwright suite, and example apps (examples/* are workspace packages)
remotion-example/ # Remotion videos rendered from its own story run and a showcase recording
```
- **Packages** (publishable): `executable-stories-formatters` is the CLI; can be built as a Bun single binary via `bun run compile`; CI/release artifacts include prebuilt binaries for linux, darwin, windows.
- **Example apps** (consumers): used to validate the packages. Monorepo: pnpm workspaces, Turbo for build/lint/test/type-check.
## Tech stack
- **Runtime**: Node >= 22, pnpm 10, TypeScript ~6.0.3 (publishable packages). Example apps stay on `^5.9.3` where their framework/test toolchain still caps at TS 5 (e.g. `ts-jest`, Astro 6's `tsconfck`).
- **Monorepo**: pnpm workspaces + Turborepo
- **Build**: tsup (all packages)
- **Test**: Vitest (packages + vitest-example), Jest (jest-example), Playwright (playwright-example), Cypress (cypress-example)
- **Lint**: ESLint 9 flat config, Prettier
- **Docs**: Astro Starlight with Tailwind CSS
## Key commands
Run full quality gate before claiming work complete:
```bash
pnpm quality # Full pipeline: build -> lint -> type-check -> test (excludes cypress)
pnpm build # turbo run build
pnpm lint # turbo run lint
pnpm type-check # turbo run type-check (tsc --noEmit in all packages/apps)
pnpm test # turbo run test
```
This runs (in order): `turbo run build`, `turbo run lint`, `turbo run type-check`, `turbo run test`.
## Architecture
### Formatter pipeline (packages/executable-stories-formatters)
```
Test code (story.given/when/then/json/mermaid/...)
-> Framework adapter (vitest/jest/playwright/cypress)
-> RawRun JSON
-> ACL canonicalization -> TestRunResult
-> Formatters (HTML, Markdown, JUnit, Cucumber JSON/HTML/Messages)
```
- **fn(args, deps)** pattern throughout: functions take `(args, deps)` for explicit dependency injection
- No classes except thin wrappers for backward compat (e.g., `HtmlFormatter`, `ReportGenerator`)
- `--format html` renders via `executable-stories-react` (SSR + an interactive hydration island); there is no string HTML renderer.
### HTML report CDN features (enabled by default)
- `syntaxHighlighting`: highlight.js for code blocks
- `mermaidEnabled`: Mermaid.js for live diagram rendering
Use `--html-no-syntax-highlighting` and `--html-no-mermaid` to disable; the Share button is hidden unless `--html-share` is passed. (Markdown in `section` doc entries is always parsed by the React renderer; there is no toggle.)
### Story API
All framework adapters expose the same API surface:
- **Steps**: `story.given()`, `story.when()`, `story.then()`, `story.and()`, `story.but()`
- **Aliases**: `story.arrange()`, `story.act()`, `story.assert()`, etc.
- **Docs** (object params): `story.json({ label, value })`, `story.kv({ label, value })`, `story.code({ label, content, lang? })`, `story.table({ label, columns, rows })`, `story.link({ label, url })`, `story.section({ title, markdown })`, `story.mermaid({ code, title? })`, `story.custom({ type, data })`, `story.screenshot({ path, alt? })`
- **Simple docs**: `story.note(text)`, `story.tag(names)`
**Assertions per step:** steps carry an `assertions` count so a claim nothing checked stops reading as proof. Vitest, Jest, Playwright and Ruby/Minitest observe it from the framework's own assertion counter, so tests are written unchanged. Cypress `story.expect`, Go `s.Expect`, Rust `expect_step`, pytest `story.expect`, JUnit 5 `Story.expect` and xUnit `Story.Expect` declare one, because those hosts expose no counter. Where nothing can be observed the field is omitted: absent means "cannot observe" and is deliberately not `0`. A scenario whose observable claim steps asserted nothing grades `none` in Evidence Review and is counted in the CLI summary and `--json-summary` (`unasserted`).
## Conventions
- Package scripts use **kebab-case**: `type-check`, not `typecheck`
- Story test files use `.story.test.ts` (vitest/jest) or `.story.spec.ts` (playwright) or `.story.cy.ts` (cypress)
- ESM throughout (`"type": "module"` in all package.json)
- Packages export via tsup with both ESM and CJS builds
- `@types/node` should be `^25.9.2` across all workspace packages
- **A closed union ends in `assertNever`.** Any `switch` over a discriminated union (above all `DocEntry.kind` / `ReportDocEntry.kind`, which a dozen renderers switch on) ends `default: assertNever(value, ": unhandled doc kind")`, imported from `executable-stories-core/utils/assert-never`. Adding a doc kind then fails to compile in every renderer that has not handled it, instead of rendering nothing in one of them — which is how `story.video()` shipped to all eleven adapters and was dropped by the JUnit and Cucumber JSON writers. Where a format deliberately covers only part of the union, list the excluded kinds as explicit no-op cases and keep the guard; never a bare `default` returning `""`, `null` or `undefined`. `test/doc-kind-coverage.test.ts` is the runtime half: it pushes every kind through each formatter and fails if one vanishes.
- Skill frontmatter `library_version:` is generated, not hand-edited. `pnpm version-packages` runs `changeset version` then `node scripts/sync-skill-versions.mjs`, which rewrites every `skills/*/SKILL.md` from the package manifest it names. `packages/executable-stories-init/tests/skill-sync.story.test.ts` fails when the two disagree. Non-JS packages release through `non-js-release.yml`, which does not call the script, so run it by hand after bumping a Python, Rust, Ruby, JVM, or .NET manifest.
## ESLint plugins
One ESLint plugin per framework (Jest, Vitest, Playwright). Each lives in `packages/eslint-plugin--executable-stories/`.
- **Structure:** `src/rules/*.ts`, `src/index.ts` (plugin export with rules + configs), `tests/.test.ts` per rule.
- **Testing:** Lint rules **must** be tested. Use the same pattern as [awaitly eslint-plugin](https://github.com/jagreehal/awaitly/tree/main/packages/eslint-plugin-awaitly): Vitest + `new Linter({ configType: "flat" })`, flat config with plugin and rule enabled, `linter.verify(code, config)`, assert valid (0 messages) and invalid (1+ messages, correct ruleId/message).
- **Configs:** Each plugin exports a `recommended` config. Vitest enables `require-task-for-story-init`, `require-test-context-for-story-init`, and `require-init-before-steps`. Jest/Playwright include `require-init-before-steps` plus legacy guards for older top-level-step / `doc.story` patterns.
- **No peer deps on official framework ESLint plugins** (e.g. eslint-plugin-playwright): our rules do not depend on their code. Document using our plugin alongside official ones if desired; do not require or bundle them.
## Vitest: do not export top-level `then`
Do **not** export or import a top-level symbol named `then` from the Vitest package (e.g. `import { then } from "executable-stories-vitest"`).
**Reason:** Tooling that uses `await import("...")` can treat the module namespace as a value. If that object has a `then` property, it may be treated as a thenable and `then` can be invoked unexpectedly, causing import-time side effects or broken imports.
**Decision:** The Vitest package must not expose a top-level `then`. Use `story.init(task)` and call steps on `story`:
```ts
it('Title', ({ task }) => {
story.init(task);
story.given('...');
story.when('...');
story.then('...');
});
```
## Showcase packages
Showcase is not an adapter: it runs inside the app under test (an MSW worker, a dev panel, store adapters) to put it into a named state, so a story's Given can open that state without a backend. The "no separate runtime" rule above is about the story API and still holds there; showcase's runtime is the app-side fixture layer.
- "Scenario" in showcase means an app state (a JSON file), not a test case. Keep the two apart in prose.
- Its packages load optional peers and page hooks with dynamic `import()`, so their ESLint configs turn off the repo's no-dynamic-import rule.
- `apps/showcase` unit tests run in `pnpm quality`. Its Playwright suite (`pnpm --filter showcase-example test:e2e`) does not: CI runs it in the `showcase-e2e` job inside the Playwright Docker image, which the `*-linux.png` visual baselines come from. Keep that image's version in step with `@playwright/test`.
- The CLI's skills live in `packages/executable-stories-showcase-cli/skills/` and ship in the package; `init` installs them into a user's repo. They are not part of the root `skills/` sync.
- `actions/showcase-screenshots` posts before and after images on a pull request in two jobs: `shoot` runs the PR's code with no write permission, and `publish` holds the token and runs only the base commit's code. Keep that split when changing it; `apps/showcase/tests/showcase-screenshots.test.ts` checks that `publish` only takes image files from `shoot`'s folder.
## Compatibility rule
Keep the same story structure and doc model across packages.
Framework specific behavior is allowed only when the host framework requires it.
**Feature matrix (README.md):** When adding a step/scenario modifier, doc kind, or scenario option to one package, update the Features matrix in `README.md` and note any intentional divergence (e.g. Vitest no top-level `then`, Playwright `.fail` vs Jest/Vitest `.fails`).
## Keyword resolution rules
**Auto-And conversion** applies to `Given`, `When`, `Then` when they repeat **anywhere in the same story**:
- First `given()` → renders "Given"
- Any subsequent `given()` in same story → renders "And"
- Same rule for `when()` and `then()`
**Explicit keywords** never auto-convert:
- `and()` → always renders "And"
- `but()` → always renders "But"
This matches Gherkin semantics where "But" expresses negative intent/contrast.
Example:
```ts
story('Login blocked for suspended user', () => {
given('the user account exists');
given('the account is suspended'); // → "And" (auto-converted)
when('the user submits valid credentials');
then('the user should see an error message');
but('the user should not be logged in'); // → "But" (explicit, never And)
but('the session should not be created'); // → "But" (still explicit)
});
```
## Vitest API
Vitest exports: `story`, types, reporter via subpath.
Step functions exist on the `story` object after `story.init(task)`:
```ts
it('...', ({ task }) => {
story.init(task);
story.given('...');
story.when('...');
story.then('...');
story.but('...');
});
```
Do not add top-level step exports to Vitest (see `then` issue above).
## Jest API
Jest exports `story` plus top-level step functions: `given`, `when`, `then`, `and`, `but`.
Do not change this - it's intentional for Jest.
## Playwright API
Playwright exports `story` plus top-level step functions: `given`, `when`, `then`, `and`, `but`.
Steps receive Playwright fixtures: `async ({ page }) => { ... }`.
## Framework-native tests
You can attach story metadata to a plain `it()` / `test()`:
- **Vitest:** `it("Title", ({ task }) => { story.init(task); ... });`
- **Jest:** `it("Title", () => { story.init(); ... });`
- **Playwright:** `test("Title", async ({ page }, testInfo) => { story.init(testInfo); ... });`
- **Cypress:** `it("Title", () => { story.init(); ... });` or `doc.story("Title")` when you need a separate generated scenario title.
Use this when you want a framework-native test (e.g. `it("adds two numbers", () => { expect(add(1,2)).toBe(3); })`) to still appear in the generated docs.
### Doc heading and describe in generated docs
- **Scenario heading (the line with ✅):** Comes from the test title for current `story.init` APIs. Cypress `doc.story("Title")` can override the generated scenario title.
- **Describe → ## grouping:** A `## Suite name` heading in colocated docs appears only when the framework supplies a suite path:
- **Vitest:** Always when the test runs under a `describe()` — suite path is taken from `task.suite`.
- **Jest:** Only if `expect.getState().currentTestName` contains `" > "`. In the default Jest setup this is **space-separated** (e.g. `"Describe title test name"`), so suite path is usually undefined and docs are flat. Verified in `apps/jest-example` (see test "verify currentTestName format for docs" in framework-native.story.test.ts).
- **Playwright:** Suite path comes from `test.info().titlePath`; after filtering file-like parts, describe titles are kept so colocated docs get `## Suite name` when tests run inside `test.describe()`.
## Agent artifacts and MCP
Agents should read generated artifacts, not source tests first.
**Canonical machine contract:** StoryReport v1 JSON (`story-report-json` format). Default filename: `reports/index.story-report.json` when using `--output-name index`. Generate it from `reports/by-file/` for the accumulated suite; formatting one raw run first updates that per-source state.
**Run state:** `executable-stories runs status` lists the per-file reports with ages; `runs reset` deletes them. A run declares `runScope` (`"full"` retires what it no longer names, `"filtered"` updates only what it names, absent keeps the rest); adapters that cannot read their own filter take it from a reporter option or `EXECUTABLE_STORIES_FILTERED`.
**Scenario index:** `executable-stories list reports/by-file --list-format json` — use the directory for accumulated-suite discovery and failure triage, or pass `raw-run.json` when you intentionally want only the current execution.
**Typical CI flow:**
```bash
pnpm test
executable-stories format reports/raw-run.json --format story-report-json --output-dir reports --output-name index
executable-stories list reports/by-file --list-format json > reports/scenario-index.json
```
Documentation formats render accumulated per-source state. JUnit, Cucumber, and release-manifest formats always describe only the current execution.
**Parity:** Non-JS adapters must match JS/TS semantics, doc model, and artifact outputs. See docs-site reference page `cross-language-parity` and root `pnpm run verify:*` scripts.
## Testing
- `packages/executable-stories-formatters/` has the most tests (260+) covering all formatters
- App tests are integration/example tests demonstrating the story API
- Cypress tests are excluded from `pnpm quality` (run separately)
- Tests in `packages/` use Vitest; `apps/jest-example` uses Jest
### Chromium under an agent sandbox
`apps/formatters-e2e`, `apps/playwright-example` and `apps/remotion-example` drive Chromium through Playwright. macOS Seatbelt denies the Mach port registration Chromium needs to talk to its child processes, so inside an agent sandbox the browser dies on launch:
```
FATAL:base/apple/mach_port_rendezvous_mac.cc:159] Check failed: kr == KERN_SUCCESS.
bootstrap_check_in org.chromium.Chromium.MachPortRendezvousServer.NNNNN: Permission denied (1100)
```
Set `ES_CHROMIUM_SINGLE_PROCESS=1`. All three then launch Chromium with `--single-process`, which spawns no children and so never registers that port:
```bash
ES_CHROMIUM_SINGLE_PROCESS=1 pnpm quality
```
**This no longer clears `formatters-e2e`.** Under Playwright 1.62 a single-process Chromium dies partway through the suite (SIGTRAP), and which tests fail moves between runs — `--workers=1` does not settle it. Measured on 2026-08-31: `diff-report.story.spec.ts` alone fails 2 of 5 this way, with nothing else in the run. Every test passes on a normal multi-process browser. So `ES_CHROMIUM_SINGLE_PROCESS=1` now buys a browser that launches rather than a suite that passes, and a red `formatters-e2e` under it is evidence of nothing. Run that suite outside the sandbox before believing any failure in it.
In `playwright-example` two tests still fail under single-process for a different and stable reason: a single-process browser cannot open a context that needs its own process — `screenshot-in-report` ("Video is recorded and linked in report") and `storyboard` ("Browse the catalog on mobile"), for video recording and mobile device emulation. Plain contexts are fine.
CI leaves the variable unset, so it runs a normal multi-process Chromium.
`sandbox.excludedCommands` is not the lever. It is worth knowing that listing `pnpm`, `npx` and `node` there does not lift the sandbox from this suite — commands still run sandboxed, so a Chromium failure is not evidence that your settings are wrong.
Turbo caches these suites. A run that touches nothing under `packages/executable-stories-formatters` or `packages/executable-stories-react` skips `formatters-e2e`, which is why the gate can pass once and fail on the next run.
## Agent Skills
When working in these areas, load the linked skill file into context for accurate, versioned guidance.
| Task | Skill |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bootstrapping executable-stories into a repo from zero | `skills/executable-stories-init/SKILL.md` |
| Writing Vitest story tests | `skills/vitest-story-api/SKILL.md` |
| Configuring Vitest StoryReporter | `skills/vitest-reporter-setup/SKILL.md` |
| Converting existing Vitest tests | `skills/vitest-converting-tests/SKILL.md` |
| Writing Jest story tests | `skills/jest-story-api/SKILL.md` |
| Configuring Jest reporter | `skills/jest-reporter-setup/SKILL.md` |
| Converting existing Jest tests | `skills/jest-converting-tests/SKILL.md` |
| Writing Playwright story tests | `skills/playwright-story-api/SKILL.md` |
| Configuring Playwright reporter | `skills/playwright-reporter-setup/SKILL.md` |
| Converting existing Playwright tests | `skills/playwright-converting-tests/SKILL.md` |
| Writing Cypress story tests | `skills/cypress-story-api/SKILL.md` |
| Story docs from e2e (TesterArmy) runs | `skills/e2e-story-api/SKILL.md` |
| Configuring Cypress reporter | `skills/cypress-reporter-setup/SKILL.md` |
| Converting existing Cypress tests | `skills/cypress-converting-tests/SKILL.md` |
| Migrating a CucumberJS suite | `skills/cucumber-converting-tests/SKILL.md` |
| Writing Bun (`bun:test`) story tests | `skills/bun-story-api/SKILL.md` |
| Writing Go story tests | `skills/go-story-api/SKILL.md` |
| Writing Ruby (Minitest) story tests | `skills/ruby-story-api/SKILL.md` |
| Writing JUnit 5 (Kotlin) story tests | `skills/junit5-story-api/SKILL.md` |
| Writing Rust story tests | `skills/rust-story-api/SKILL.md` |
| Writing xUnit (C#) story tests | `skills/xunit-story-api/SKILL.md` |
| Writing pytest story tests | `skills/pytest-story-api/SKILL.md` |
| Using the CLI or formatters API | `skills/formatters-cli/SKILL.md` |
| Setting up Vitest ESLint rules | `skills/eslint-vitest-rules/SKILL.md` |
| Setting up Jest ESLint rules | `skills/eslint-jest-rules/SKILL.md` |
| Setting up Playwright ESLint rules | `skills/eslint-playwright-rules/SKILL.md` |
| Shaping specifications with OOPSI decomposition | `skills/spec-discovery-oopsi/SKILL.md` |
| Mining requirements with Example Mapping | `skills/spec-example-mapping/SKILL.md` |
| Specifying business rules and decision tables | `skills/spec-rules-decision-tables/SKILL.md` |
| Specifying workflows and state transitions | `skills/spec-workflow-state/SKILL.md` |
| Reviewing executable specifications | `skills/spec-review/SKILL.md` |
| Converting existing tests to executable stories | `skills/spec-convert-tests/SKILL.md` |
| Turning a plan into planned (`it.todo`) scenarios | `skills/spec-plan-to-stories/SKILL.md` |
| Refining raw examples into precise specifications | `skills/spec-refine-examples/SKILL.md` |
| Outside-in behaviour discovery (Dan North) | `skills/spec-outside-in-behaviour/SKILL.md` |
| Writing specs as living documentation (Gojko Adzic) | `skills/spec-living-documentation/SKILL.md` |
| Authoring changes for the Evidence Review report | `skills/spec-evidence-review/SKILL.md` |
| Posting Evidence Review receipts to Linear via MCP | `skills/linear-evidence-review/SKILL.md` |
| Turning a Jira/GitHub/Linear ticket into scenarios via MCP | `skills/tracker-to-scenarios/SKILL.md` |
| Reconciling a tracker with the suite and stamping receipts | `skills/tracker-receipts/SKILL.md` |
| Filing tickets for what a run found that the board is missing | `skills/scenarios-to-tickets/SKILL.md` |
| Authoring technical/coding lessons as executable story tests | `skills/executable-lessons/SKILL.md` |
| Showing the current topic visually, from the run where possible | `skills/show-me/SKILL.md` |
| Opening app states, screenshots and clips with showcase | `packages/executable-stories-showcase-cli/skills/executable-stories-showcase/SKILL.md` |
| Building a narrated demo video from a run's storyboard frames (ffmpeg or Remotion) | `skills/demo-video/SKILL.md` |
| Recording and publishing help-centre GIFs and videos from scenarios | `skills/article-walkthrough/SKILL.md` |
| Explaining a code change as living documentation (with quiz) | `skills/explain-change/SKILL.md` |
| Explaining a whole system or feature area for onboarding | `skills/explain-system/SKILL.md` |
| Test-driving a behaviour with a story test as the red step | `skills/story-tdd/SKILL.md` |
| Reproducing a bug as a failing scenario, then fixing it | `skills/bug-to-scenario/SKILL.md` |
| Bug bashing an app: explore, triage, prove each bug | `skills/bug-bash/SKILL.md` |
| Triaging a red or flaky run into a routed worklist | `skills/failure-triage/SKILL.md` |
| Running an autonomous agent loop against run artifacts | `skills/agent-loop/SKILL.md` |
| Giving pstack (or any agent workflow) a `verify-` skill backed by the suite | `skills/stories-verify-skill/SKILL.md` |
| Scheduling an agent that drives a target one PR at a time | `skills/story-control-loop/SKILL.md` |
| Writing a PR description from the behavioural diff | `skills/story-pr/SKILL.md` |
| Choosing and wiring CI gates (PR, release, scheduled) | `skills/ci-gates/SKILL.md` |
| Auditing coverage by requirement, code, and evidence | `skills/coverage-audit/SKILL.md` |
| Bridging TestRail or Xray to the suite | `skills/test-management-bridge/SKILL.md` |
| Publishing a report a non-developer's browser agent can query | `skills/report-webmcp/SKILL.md` |
| Writing release notes from the behavioural diff | `skills/release-notes/SKILL.md` |
| Not sure which skill fits (router over every skill) | `skills/stories-guide/SKILL.md` |
| Starting new work plan-first (idea → planned scenarios → green) | `skills/stories-propose/SKILL.md` |
| Grilling a vague request into scenarios, one round at a time | `skills/spec-grilling/SKILL.md` |
| Sending open questions to an absent expert as a questionnaire | `skills/spec-questionnaire/SKILL.md` |
| Story mapping a release as journeys and planned scenarios | `skills/spec-story-mapping/SKILL.md` |
| Building a glossary the scenarios enforce | `skills/spec-domain-language/SKILL.md` |
| Pushing a run to the cloud, asking the release gate, export | `skills/executable-stories-cloud/SKILL.md` |
| Running only the tests a change can break; gating a merge | `skills/cloud-change-aware-testing/SKILL.md` |
| Importing cases from TestRail or any tool's CSV | `skills/cloud-migrate/SKILL.md` |
| Connecting an agent to the cloud over MCP; ESQ queries | `skills/cloud-mcp/SKILL.md` |