Launchrail

An updatable development system for taking a software idea from product intent to a verified release.

How it works · Getting started · Using it · Updating · Ownership model · Repository layout · Contributing · Credits

---

This repository is the Launchrail toolchain: the CLI, the workflow skills (shipped into projects as files), templates, and migrations that initialize other repositories and keep them current. It is not an application framework and it does not replace Claude Code, Claude Design, GitHub, Playwright, or a project's chosen stack. It is the shared rail that connects them.

How it works

Launchrail structures development as two movements. The foundation runs once per project: it turns an idea into hard constraints and recorded decisions. Then the delivery loop takes over — once per feature: size the work and plan it only as deeply as it needs (a small change goes straight from a grill to tickets; a larger one adds launch-wayfinder, a spec, and design validation first), then hand the tickets to the built-in Ralph loop to implement and verify before going around again for the next feature. Every stage leaves a committed artifact behind, and the next stage starts from that artifact, not from chat memory. Two commands cover the rail: /launch plans — it reads the committed artifacts, detects where the project is, and routes to the stage's owner — and /launch-implement builds, driving ready tickets to verified merges.

The skills are Launchrail's own complete, launch-* prefixed set (ADR-0020); the methodology of several stages is inspired by Matt Pocock's skills — see Credits. The full stage contract — inputs, artifacts, composition rules, and per-mode rigor — lives in the workflow doc.

What makes projects updatable instead of copy-once-and-rot is the second half of the system: shared capabilities are shipped as managed files and kept current on sync, shared standards are synchronized, product knowledge stays locally owned, and reusable lessons are deliberately promoted upstream.

Using it in your project

One command sets the rails:

npx @wemuda/launchrail init

init interviews you (or takes --yes), runs git init if the directory isn't a repository yet, seeds AGENTS.md and ADR conventions without touching existing content, and writes the workflow's skills into .claude/skills/ as managed files — so every collaborator, and every session whether cloud or local, gets the same skills with no plugin to install, on any agent that reads the repo (ADR-0019). Adopting an existing project is a first-class path: your files are kept, and a CLAUDE.md you already have is additively wired to the workflow imports rather than replaced (ADR-0012). The interview asks whether the project is new or existing and records it as the manifest's origin; for an existing project, launch takes an alignment on-ramp — inferring a draft vision from the code, interviewing only the gaps, and inventorying your existing design system — instead of starting from a blank vision (ADR-0013).

From there, the day-to-day driver is not the CLI — it's the launch skill inside Claude Code: open the project and run /launch. Invoke it (or just ask "what's next?") and it reads your committed artifacts, works out where the project is — no vision yet, mid-grill, spec validated, tickets ready — and runs or routes to the next stage's owner. Give it a stage name (launch design-validation) to jump straight there. The skills carry the rest of the workflow too:

• launch-project-alignment — the on-ramp for an existing codebase: infer a vision from the code, interview only the gaps, inventory the design system, then join the loop
• launch-vision-creation, launch-discovery, launch-grill, launch-research — vision, then the divergent landscape scan, the grill (the convergent interview that runs both as the foundation's complexity grill and per-feature before speccing, keeping the glossary and ADRs honest as it goes), and primary-source research
• launch-wayfinder, launch-spec, launch-tickets, launch-design-validation — break big work into decision maps, synthesize the spec, validate it visually, and cut tracer-bullet tickets with blocking edges
• launch-browser-smoke — drives a real browser journey and leaves a traceable evidence bundle (with the browser-testing module)
• launch-implement — the one door to building: /launch-implement drives ready tickets to verified merges through the Ralph loop (a ticket number builds just that one; "the next 5 of spec #2" scopes and caps a run)
• launch-ralph, launch-ralph-implement, launch-code-review, launch-resolving-merge-conflicts — the verification-gated loop engine behind that door, installed by init

The CLI is the maintenance surface you return to between sessions:

npx @wemuda/launchrail status                # versions, drift, pending migrations
npx @wemuda/launchrail diff                  # preview upstream changes
npx @wemuda/launchrail sync                  # apply managed updates + run migrations
npx @wemuda/launchrail add browser-testing   # enable a module
npx @wemuda/launchrail doctor                # repository and environment checks
npx @wemuda/launchrail verify                # deterministic verification gate
npx @wemuda/launchrail smoke                 # scaffold a browser-smoke evidence bundle
npx @wemuda/launchrail eject <module|file>   # opt out of management (vendor mode: --all)

Initialized projects carry two files: .launchrail.yml (configuration) and .launchrail-lock.json (versions, checksums, applied migrations; committed to the repo). Full walkthrough: docs/getting-started.md. Committed, unedited example of what init produces: examples/hello-launchrail.

Updating a project

New Launchrail release out? Two steps, from the project root:

1. Sync the project files — applies the release's managed files (the workflow skills included) and migrations; your own files are never touched:

npx -y @wemuda/launchrail@latest sync

2. Commit the result:

git add -A && git commit -m "chore: sync launchrail"

Done — the skills update with the files in one sync (no separate plugin step, and teammates just git pull), and the next /launch runs with everything the release added (the CHANGELOG says what that is). Keep the @latest: npx caches, and a stale cached CLI reports "everything up to date" against old templates. Want to see the changes before applying? npx -y @wemuda/launchrail@latest diff — read-only, like status and sync --dry-run. The why and the edge cases — ordering, conflicts, migrations — live in docs/getting-started.md.

The ownership model

Every file Launchrail touches in a consuming project belongs to exactly one class — and no feature is allowed to blur the lines:

Class	Who owns it	What Launchrail may do
Managed	Launchrail	Replace it on sync
Seeded	The project, after creation	Create it once, then never touch it
Project-owned	The project, always	Nothing

Every write supports dry-run, is checksum-aware, and is idempotent: re-running init or sync never duplicates blocks or destroys local work. A managed file you edit locally keeps your edits — sync reports the conflict instead of overwriting — and launchrail eject permanently opts a file or module out of management (ADR-0006).

Repository layout

launchrail/
├── assets/                  # Logo and other repo media
├── packages/
│   └── cli/                 # @wemuda/launchrail — the npx entry point
│       └── assets/skills/   # The workflow skills: launchrail/ (the complete launch-* set) + NOTICE.md (attribution)
├── templates/               # Files seeded into consuming projects (added as built)
├── examples/
│   └── hello-launchrail/    # Committed, unedited output of `launchrail init` on a tiny app
└── docs/
    ├── adr/                 # Architecture decision records
    ├── getting-started.md   # Installation and day-2 guide
    └── releasing.md         # How releases are cut

Directories marked "added as built" are created when their first real content lands.

Development

Requires Node ≥ 22 and pnpm.

pnpm install
pnpm build
pnpm --filter @wemuda/launchrail exec launchrail --help

Status

The toolchain is stable and versioned. The full surface — init/doctor, the workflow skills, browser testing, the Ralph loop, and the sync engine — is covered by the test suite, including integration tests against real temporary Git repositories. Releases are automated: Conventional Commits drive release-please, and the changelog is generated from the commit history (ADR-0008, docs/releasing.md). The CLI is published to npm as @wemuda/launchrail. Shipped history lives in CHANGELOG.md.

Contributing

See CONTRIBUTING.md. The short version:

• Commits follow Conventional Commits (type(scope): summary); see ADR-0002. Releases and the changelog are generated from them (docs/releasing.md).
• Meaningful decisions are recorded as ADRs in docs/adr/.
• The agent operating contract lives in AGENTS.md.
• Security issues go through SECURITY.md, not public issues.

Credits

Launchrail's skill set is its own, but much of its methodology traces to Matt Pocock. The grill, research, wayfinding, spec, ticket, and code-review stages absorb the shape — and, in places, the MIT-licensed text — of his skills repository (ADR-0020); the derived skills carry the attribution in NOTICE.md, and upstream is monitored so improvements there keep informing the rail.

If Launchrail is useful to you, the credit belongs upstream first: star mattpocock/skills, watch Matt's YouTube channel, follow @mattpocockuk on X, and check out AI Hero.

License

MIT (ADR-0007). Everything Launchrail writes into your repository — seeded files, managed files, rendered templates — is yours, with no attribution or license obligation attached.