Skip to content
Back to search

journeysfirst

An open format and toolkit for defining, running and verifying user journeys.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/santorilabs/journeysfirst with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/santorilabs/journeysfirst'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/santorilabs--journeysfirst/badge.svg)](/listings/santorilabs--journeysfirst)

HTML

<a href="/listings/santorilabs--journeysfirst"><img src="/api/listings/santorilabs--journeysfirst/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Ask your agent to do it. Copy this to your agent:

Set up Journeys First in this repo: https://github.com/santorilabs/journeysfirst/blob/main/docs/get-started-for-agents.md

It tells you its plan first, and stops before it runs anything.

Or do it yourself (Node 20 or newer):

npm install --save-dev journeysfirst @playwright/test
npx playwright install --only-shell chromium
npx journeysfirst init

Or only the skills: `npx skills add santorilabs/journeysfirst --skill '*' --agent claude-code codex -y`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 159 lines
  1. <p align="center">
  2. <img src="assets/banner.png" alt="Journeys First: an open format and toolkit for defining, running and verifying user journeys" width="100%" />
  3. </p>
  4. # Journeys First
  5. [![npm](https://img.shields.io/npm/v/journeysfirst.svg)](https://www.npmjs.com/package/journeysfirst)
  6. [![Changelog](https://img.shields.io/badge/changelog-CHANGELOG.md-blue)](CHANGELOG.md)
  7. [![Tests](https://github.com/santorilabs/journeysfirst/actions/workflows/test.yml/badge.svg)](https://github.com/santorilabs/journeysfirst/actions/workflows/test.yml)
  8. [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  9. [![skills.sh installs](https://skills.sh/b/santorilabs/journeysfirst)](https://skills.sh/santorilabs/journeysfirst)
  10. **Built for agent-first product development**: agents build your product, and **agents use it too.**
  11. An open format and skills for writing the contracts your product keeps: what each user, person or agent, must be able to do.
  12. Your agents build to them, and check their work against what your users experience.
  13. - **Format:** journeys in plain sentences, and a run file with proof for every check.
  14. - **Skills:** onboard, build, write, run, review, fix.
  15. - **Runner:** replays each journey as a Playwright test.
  16. - **Review page:** watch each run step by step, as each user.
  17. Everything lives in your repo and runs wherever your code runs: your machine, CI or your own cloud.
  18. ## The problem
  19. Tests are not enough for verification, so you ask your agents to verify and show you proof. You get screenshots and videos, but it's still not enough.
  20. Models are trained to finish the task in front of them. Left on their own, they [say it's done when it isn't](https://metr.org/blog/2025-06-05-recent-reward-hacking/), or get it done by [breaking something else](https://metr.org/notes/2026-03-10-many-swe-bench-passing-prs-would-not-be-merged-into-main/).
  21. - **Your agent picks what to check.** It checks the task you gave it. Nothing tells it what else your product has to keep doing. So you get regressions (no test failures, but real user experience failures).
  22. - **It checks as that one user,** the one in the task. Other users that are affected, people or agents, don't get checked. Other relevant user journeys are often skipped too.
  23. - **The proof isn't kept as a check.** Your next change isn't held to it.
  24. We built this to automate most of our product development without worrying about user experience regressions.
  25. ## Where it fits
  26. Journeys First works on top of what you already have: your tests, your agent's own checks, and Playwright. It fills 2 gaps:
  27. - **Every affected user, including agents.** A journey names every user a change affects and checks each from their own login.
  28. - **A contract over one-time proof.** A journey says what each user should get, not which buttons to click. It stays in your repo, and every run keeps proof for every check.
  29. | Kind | Examples | What it does | Limits |
  30. |---|---|---|---|
  31. | Self-check skills | [pstack](https://github.com/cursor/plugins/tree/main/pstack), [Showboat](https://github.com/simonw/showboat) | Agents drive your app from a feature map and show you proof. | Describes each feature from one user's point of view. Every rerun is a full agent run. |
  32. | Check-and-save tools | [Shiplight](https://www.shiplight.ai/yaml-tests), [Playwright test agents](https://playwright.dev/docs/test-agents) | Agents turn their check into a test that runs on every PR. | Browser tests only, so no agent as a user. |
  33. | Test code | [Playwright](https://playwright.dev/docs/browser-contexts), [Cucumber](https://cucumber.io/docs/gherkin/) | Tests several users in one test. | Fixed code checks of each step. They break when the UI changes, so someone keeps updating them. |
  34. | AI QA services | [QA Wolf](https://www.qawolf.com/how-it-works), [QA.tech](https://qa.tech/use-cases/multi-user-testing) | Test your app for you, with several users. | Your agent can't use it while it builds. External service. |
  35. | Spec tools | [Spec Kit](https://github.com/github/spec-kit), [Kiro](https://kiro.dev/docs/specs/correctness/) | Write down what to build. | Agents build and verify against the current task, not everything your product promises. |
  36. | MCP eval tools | [promptfoo](https://www.promptfoo.dev/docs/providers/mcp/), [mcp-eval](https://github.com/lastmile-ai/mcp-eval) | Test your MCP server on its own. | Check the agent's side only, not what people see after. |
  37. ## A journey is the contract
  38. A journey is a contract anchored on the user experience. It lives in your repo, so your agents use it from building the product to verifying it.
  39. A journey proves your change. Then it stays, and every later change is held to it.
  40. Your agent can turn it into code checks so it runs faster, and read the run logs to speed up later runs, for example by writing code helpers. But the journey stays the promise you keep to your users.
  41. ## When to use
  42. It's most useful for production apps that are more complex: several kinds of users, agents using it through MCP, and flows that depend on each other.
  43. - **Changes to production apps:** we tested agents adding a new feature to an existing open source app with several kinds of users. Agents with journeys verified as every user role in 3 of 3 runs and kept a video in 2, against 1 of 3 and none without. We also replayed 2 real bugs from Immich and Docmost, and agents with journeys caught both regressions.
  44. - **New apps from 1 prompt:** without Journeys First, agents said done without opening the app, and 2 of 6 apps shipped unclickable. With it, the agent opened and used each app as each user first.
  45. It costs more: builds took 3 to 4 times longer and cost 3 to 4 times as much. [All results](docs/results.md).
  46. ## Example
  47. A real run: your agent books a meeting through an MCP server, then you and your teammate each check your own calendar. [Watch it (30 s)](assets/review.mp4).
  48. The journey, `journeys/book-through-mcp.journey.yaml`:
  49. ```yaml
  50. format: journeysfirst/v1
  51. title: Book a meeting through the MCP server
  52. promise: Your agent can book a meeting with a teammate through our MCP server, and you both see it on your calendars.
  53. users: [agent, teammate] # "you" is always there, so only the others are listed
  54. start: Your calendar and your teammate's are empty tomorrow at 10. Your agent is connected to our MCP server.
  55. steps:
  56. - You ask your agent to book 30 minutes with your teammate tomorrow at 10.
  57. - The agent books the meeting through the MCP server.
  58. - check: The agent's answer to you matches what was saved.
  59. id: answer-matches # added by your agent; stays the same if you reword the check
  60. - You open your calendar.
  61. - check: You see the meeting tomorrow at 10, with your teammate invited.
  62. id: you-see-it
  63. - Your teammate opens their calendar.
  64. - check: Your teammate sees the same meeting tomorrow at 10.
  65. id: teammate-sees-it
  66. ```
  67. You write it in plain sentences, with no selectors or URLs. Your agent works those out when it runs it, and saves them in a script. Every run keeps the proof: a screenshot for each line, a video for each user, and a [`run.json`](spec/run-results-v1.md#example) with every check.
  68. https://github.com/user-attachments/assets/8d8912ba-3d1c-472b-a1af-b98645e558f5
  69. ## Install
  70. Ask your agent to do it. Copy this to your agent:
  71. ```text
  72. Set up Journeys First in this repo: https://github.com/santorilabs/journeysfirst/blob/main/docs/get-started-for-agents.md
  73. ```
  74. It tells you its plan first, and stops before it runs anything.
  75. Or do it yourself (Node 20 or newer):
  76. ```bash
  77. npm install --save-dev journeysfirst @playwright/test
  78. npx playwright install --only-shell chromium
  79. npx journeysfirst init
  80. ```
  81. Or only the skills: `npx skills add santorilabs/journeysfirst --skill '*' --agent claude-code codex -y`
  82. ## Try it
  83. Want to see it catch something? The example app has a bug you can turn on: the link keeps working after you turn sharing off.
  84. ```bash
  85. git clone https://github.com/santorilabs/journeysfirst.git
  86. cd journeysfirst && npm install && npx playwright install --only-shell chromium
  87. cd examples/share-by-link
  88. npm test # passes
  89. npm run test:bug # fails: the viewer still sees the deck
  90. npx journeysfirst review journey-runs # both runs at http://127.0.0.1:4400
  91. ```
  92. ## Use it
  93. Just ask your agent. It picks the right skill:
  94. | Ask your agent | Skill |
  95. |---|---|
  96. | "Set up Journeys First here." | [journey-onboard](skills/journey-onboard/SKILL.md) |
  97. | "Build a site where study groups share notes." | [journey-build](skills/journey-build/SKILL.md) |
  98. | "Write a journey for inviting a teammate." | [journey-write](skills/journey-write/SKILL.md) |
  99. | "Run the journeys this change touches." | [journey-run](skills/journey-run/SKILL.md) |
  100. | "Review the last run." | [journey-review](skills/journey-review/SKILL.md) |
  101. | "That run failed. Fix it." | [journey-fix](skills/journey-fix/SKILL.md) |
  102. After the first run, a replay is a plain Playwright test: `npx playwright test`. It needs no model, unless one of the users is an agent. For every command, run `npx journeysfirst --help`.
  103. ## Limitations
  104. - It's 0.0.x, so things may still break between releases.
  105. - It only runs web apps for now.
  106. - You set up the test accounts and start states. Onboarding tells you what it needs.
  107. - Onboarding drafts your top journeys, so it can miss one, like a single privacy setting. You or your agent add the rest as you work.
  108. - Your agent writes the check code, so read the checks in review like you would any test.
  109. ## More
  110. [Overview](docs/overview.md) · [Journey format](spec/journey-format-v1.md) · [Run results](spec/run-results-v1.md) · [How the code fits](docs/how-it-fits.md) · [Run in code](docs/run-in-code.md) · [Publish a run](docs/publish.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
  111. If a journey catches a bug in your app, or misses one, [open an issue](https://github.com/santorilabs/journeysfirst/issues/new/choose) with the journey.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.