spec-journey

Creates, edits, compiles, and runs cross-feature User Journeys v2 for regression testing.

Updated Mar 11, 2026
One-click install
npx skills add https://github.com/julien-m/livespec --skill spec-journey-julien-m
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-journey
Source: https://github.com/julien-m/livespec/tree/main/.agent-sync/skills/spec-journey
Command: npx skills add https://github.com/julien-m/livespec --skill spec-journey-julien-m

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Cross-feature regression flows are usually tied to a single feature and get lost or duplicated, leaving no global, compiled, runnable record of end-to-end user behavior across an implemented product. ## Core Features & Use Cases - Journey lifecycle management: Create, edit, list, inspect, and impact-check global User Journeys v2 stored under .specs/journeys/ with decision and changelog evidence. - Bootstrap from existing code: Scan implemented features, specs, Gherkin, tests, routes, and Penflow contracts to propose journey candidates for already-built functionality. - Compile-once, run-native execution: Compile journeys on create or edit, then run compiled artifacts deterministically without recompilation, including XCUITest generation via xcodegen. - Use Case: After shipping several features, run $spec-journey bootstrap --from-existing to propose cross-feature regression journeys, accept candidates, and run them as non-regression tests. ## Quick Start Ask the AI to create a new cross-feature user journey with $spec-journey create and confirm the inferred features and acceptance criteria before it writes the journey.

Frequently Asked Questions about spec-journey

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a cross-feature user journey for regression testing?

Run $spec-journey create with a free-form journey intent. The command infers features, AC, and FR refs from impact and inspect evidence, shows confidence and ambiguity for correction, then writes journey.yaml under .specs/journeys/.

How to add journey coverage for already implemented features?

Use $spec-journey bootstrap --from-existing to scan implemented features, specs, Gherkin, implementation maps, tests, routes, and Penflow contracts. It proposes candidates only, and accepted candidates compile once and run once without requiring $spec-refine.

Why does journey run report journey_compiler_stale?

The stale error appears when journey.yaml changed after the last compile or after a LiveSpec migration with old compiler manifests. Re-run livespec journey compile, or use $spec-journey edit, before retrying the run.

Does spec-journey support XCUITest projects?

Yes. For XCUITest projects with project.yml or project.yaml, the compile step runs xcodegen generate so generated Swift journeys are included in the Xcode project before execution.

What selectors are allowed in journey steps?

Visible text selectors require product_contract: true. The preferred selectors are semantic IDs, test IDs, i18n keys, roles, and accessibility labels to keep journeys stable across UI changes.