# 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` |