@wemuda/launchrail 1.7.0 → 1.8.0

package/assets/skills/launchrail/launch-implement/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: launch-implement
+description: Start building — the single entry point for implementation (stage 10). Drives ready tickets to verified merges through the Ralph loop. `/launch-implement` works the whole ready frontier; `/launch-implement 15` builds one ticket end to end in this session; several numbers scope the loop to just those tickets; a count ("the next 5") caps the run; a spec or slice reference ("spec #2's tickets") resolves to its tickets. It repairs its own setup (missing loop materials install via `launchrail sync`) instead of stopping. Only ever started explicitly by the user.
+disable-model-invocation: true
+---
+
+# Implement — the one door to building
+
+Everything before this skill produces tickets; this skill turns them into verified, merged code. The user never has to know how the engine runs behind the door: read the manifest, fix the setup if it's incomplete, and route. The engine (`launch-ralph`) stays where it is — you compose it, never reimplement it.
+
+## Step 1 — Read the project and resolve the scope
+
+From `.launchrail.yml`: `issueTracker` and the `testing` commands. From the arguments, the scope — in whatever form the user gave it:
+
+- **no arguments** → the whole ready frontier (every open ticket labeled `ready-for-agent` whose blockers are settled);
+- **one ticket number** → that ticket, built end to end in this session;
+- **several numbers** → the loop, scoped to those tickets and the order their `Blocked by: #n` edges impose;
+- **a count** — "the next 5", "max 5" → the loop with a merge cap. Don't hand-pick which five: the cap is a stop condition, and the frontier decides the order — the loop stops after that many *verified merges* and leaves the rest ready;
+- **a spec, slice, or epic reference** — "spec #2's tickets", "the rest of slice 1" → resolve it to explicit numbers against the live tracker: the open tickets that belong to it (a "Part of: #n" line, the spec issue's ticket list, or a label), plus any open in-set blockers so the scope stays dependency-closed. Combinations compose: "the next 5 of spec #2" → that spec's tickets *and* a cap of 5.
+
+**Resolve prose to data before anything launches.** The loop's inputs are ticket numbers and policy values (`only`, `max`, `width`) — the workflow form takes them as JSON args and refuses a natural-language string by design. Translating the user's words into that scope, against live tracker state, is *your* job, and it ends with an echo before any dispatch: "Scope: #14, #15, #19 — the remaining slice-1 tickets; #19 builds after #14. Cap: none." A misread scope corrected here costs a sentence; corrected after launch it costs a run.
+
+## Step 2 — Repair setup, don't gatekeep
+
+If the loop's materials are missing — `modules.ralph` off in the manifest, or `.claude/workflows/ralph.js` absent — run `npx @wemuda/launchrail sync` (additive and idempotent; its migration installs them) and say what it did. Never answer the user's "build this" with "first go run a command" for anything this skill can run itself. What you cannot repair, report precisely: no tracker configured (`issueTracker: none`), or an empty verification contract (no `testing` commands — `verify` fails on an empty contract and the loop refuses a start it cannot gate).
+
+## Step 3 — Route by scope
+
+**The frontier (or a resolved scope):** run the loop under the `launch-ralph` skill — it owns the policies (width, attempts, cap, deferrals, remote-verified merges) and the orchestrator's contract. For a wide dependency graph or a long run, prefer its workflow form (`.claude/workflows/ralph.js`) — the skill explains when — passing the resolved scope as JSON args, e.g. `{ only: [14, 15, 19], max: 5, width: 1 }`.
+
+**One ticket:** build it here, watchable, under the same contract a Ralph dispatch carries (kept textually parallel with `launch-ralph` — change one, change both):
+
+1. **Dependency gate:** every ticket on the `Blocked by:` line is closed with its work merged. An open blocker stops you before any code — name it and offer to build it first.
+2. Read the ticket and everything it links (spec sections, ADRs, journeys), plus `AGENTS.md`/`CLAUDE.md`.
+3. Label the ticket `ralph:building`; branch `ralph/<n>-<short-slug>` from a fresh sync of the base.
+4. Implement by the **`launch-ralph-implement`** contract — TDD, the `verify` gate, browser smoke for user-facing changes, self-review, commit conventions. Name the skill; don't paraphrase it.
+5. Pre-PR sync: merge the latest base; resolve conflicts with `launch-resolving-merge-conflicts`; re-run the gate if anything changed.
+6. Open a PR titled from the ticket with `Closes #<n>`; adopt an existing `ralph/<n>-*` branch or PR rather than opening a second.
+7. Wait for CI (Monitor or a background sleep, never a foreground busy-wait); fix what the branch broke; merge; confirm on the remote that the PR merged and the issue closed — close it explicitly if squash-merge didn't. Remove `ralph:building`.
+8. **Integrity:** no placeholders, no stubs, never delete or weaken a test to get green, never claim verification you didn't run.
+
+## Ground rules
+
+- **Only the user starts this.** Conductors and other skills hand over the command (`/launch-implement`); they never invoke it. The engines behind it inherit the same rule — reaching them through this door *is* the explicit user start.
+- **Nothing is done until `npx @wemuda/launchrail verify` is green** — per ticket, and once more on the final base when a loop run ends. Where `modules.browser-testing` is enabled and the change is user-facing, a `launch-browser-smoke` journey is part of done.
+- **Report evidence, not assertions:** PR numbers, merge commits, issues closed, the verify outcome — and what was parked or punted, with why.

package/assets/skills/launchrail/launch-project-alignment/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: launch-project-alignment
+description: The on-ramp for adopting an existing, mid-development codebase into the Launchrail loop. Instead of starting from a blank vision, it inventories what the project already has, infers a draft vision from the code, interviews only about the gaps, and detects an existing design system — then routes the real gaps back into the normal workflow. Use when initializing Launchrail on a project that already has code (`origin: existing` in `.launchrail.yml`), when the user asks to adopt, align, or onboard an existing project, or when `launch` sends an existing project to stage 1.
+---
+
+# Project alignment — adopting an existing project
+
+The Launchrail loop is written for a project that starts from an idea. A project already mid-development starts somewhere in the middle: it may already have a working app, a design system, tests, even docs — but none of Launchrail's artifacts. This skill is the **on-ramp**: it aligns what you already have with the artifacts the loop expects, inferring what the code already answers and asking only about what it doesn't. It is not a parallel workflow — it gets an existing project to a real vision and a clear map of gaps, then hands back to `launch`.
+
+## Ground rules
+
+- **Align, don't rebuild.** The goal is to reach the loop's frontier with the least work, not to re-derive decisions the codebase already embodies. This is a short pass, not a from-scratch run.
+- **Infer, then confirm — never fabricate certainty.** You may propose a vision, a target user, a design-system baseline from reading the code. Mark every inference as inferred, show your evidence, and get the user's sign-off before committing anything. A confident guess presented as fact is worse than an open question.
+- **Ask only what the repository can't answer.** Read the README, `package.json`, the directory structure, routes/models/entrypoints, and existing docs first. Spend the user's attention on genuine gaps and open questions, not on things the code already states.
+- **Compose, never duplicate.** This skill does not own any artifact. The vision is written and committed by `launch-vision-creation`; ADRs, specs, tickets, and design validation stay owned by their stages. This skill front-loads the inference and the gap interview, then routes to those owners. It mirrors the composition contract in [`workflow.md`](../launch/workflow.md).
+- **Additive and non-destructive.** Everything you touch (a drafted vision, the `AGENTS.md` project-purpose line) is project-owned. Never overwrite existing product knowledge; if `docs/vision.md` already exists, this is a revision, not a rewrite.
+
+## Process
+
+1. **Confirm the on-ramp applies.** Read `.launchrail.yml`. This skill is for `origin: existing`; if the manifest says `origin: new`, say so and route to `launch-vision-creation` instead — a blank start doesn't need alignment.
+2. **Inventory the project against the artifact map** (below). Read the repo — README, `package.json`/manifest, folder layout, entrypoints, routes, data models, config, existing `docs/`. Produce an **alignment map**: for each Launchrail artifact, mark it *present*, *partial*, or *missing*, with the evidence you found. This map is what you report at the end.
+3. **Align the vision** — the one artifact worth inferring:
+   - If `docs/vision.md` exists and is real (not the bare template), read it and note where it's thin or stale. This becomes a revision.
+   - If it's missing or template-only, **draft an inferred vision** from the inventory: what the product appears to be, who it seems to serve, what it does today, and the assumptions and non-goals the code implies. Mark clearly what is inferred vs. observed, and list the open questions the code can't resolve (the real target user, the bet, the success signal).
+   - **Interview the user on those gaps only** — a few questions at a time, in their language. Don't re-ask what you inferred with confidence; confirm it.
+   - **Hand the result to `launch-vision-creation`** to finalize and commit as a *revision* — it owns the template, the commit, and the `AGENTS.md` project-purpose sync. The interview is already done; it should confirm and commit, not re-interview from scratch.
+4. **Detect the design system.** Look for an existing one: design tokens, a theme or Tailwind config, a component library, Storybook, a CSS framework, or Figma links in the docs. If a real design system exists, record it as the **baseline** for visual exploration (stage 2) and design validation (stage 8) — link it from the vision — so those stages extend what's there instead of exploring from zero. If none exists, note it as a genuine stage-2 gap.
+5. **Map the remaining artifacts, don't manufacture them.** For ADRs, the MVP spec, tickets, and the verification setup, record present/partial/missing in the alignment map. Do not back-fill them here — each has an owning stage. Where a project already has, say, architecture docs or a test suite, note that the corresponding stage is largely satisfied so `launch` doesn't send the user to redo it.
+6. **Report and hand back.** Present the alignment map: what's already aligned, what you inferred and the user confirmed, and the real gaps in loop order. Then route to `launch` to drive the first real gap. Leave the user a clear picture of where their existing project sits on the rail and what's next.
+
+## The artifact map
+
+How each Launchrail artifact shows up in an existing project, and what to do:
+
+| Artifact | Detect in an existing repo | If present | If missing |
+|---|---|---|---|
+| Vision (`docs/vision.md`) | The file; else infer from README, deps, routes/models | Revise where thin | Infer a draft, gap-interview, hand to `vision-creation` |
+| Design system | Tokens, theme/Tailwind config, component lib, Storybook, Figma links | Record as the baseline; link from the vision | Note as a stage-2 gap |
+| Architecture decisions (`docs/adr/`) | ADRs beyond the template; or de-facto decisions in code/docs | Note stage 6 as largely satisfied | Note as a gap; capture load-bearing existing decisions as ADRs later |
+| MVP spec (`docs/specs/`) | Spec docs, PRDs, design docs | Note stage 7 as partial/satisfied | Real gap — owned by the spec stage |
+| Tickets | The tracker in `.launchrail.yml` (issues/backlog) | Note stage 9 as partial | Real gap — owned by `launch-tickets` |
+| Verification | Test suite, CI config, Playwright | Wire `testing` commands in `.launchrail.yml`; note stage 11 partial | Note as a gap |
+
+## What this skill does not do
+
+- It does not run the whole loop. It reaches a confirmed vision and a gap map, then hands to `launch`.
+- It does not write ADRs, specs, or tickets, or start Ralph. Those stay with their owners and are user-driven.
+- It does not overwrite anything the project already owns.

package/assets/skills/launchrail/launch-ralph/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: launch-ralph
+description: Orchestrate the bounded Ralph implementation loop — dispatch fresh-context implementer subagents over the ready ticket frontier, verify every claimed merge against the remote, and gate completion on the project's verification contract. Also the supervisor's contract when the loop runs as the ralph workflow. The engine behind /launch-implement (the user-typed front door) — never invoke it on your own initiative; reach it through that door or an explicit user request to run the loop.
+---
+
+# Ralph — the autonomous implementation loop
+
+The user starts this loop through `/launch-implement` (or by asking for it in so many words); it is never started unprompted — a campaign spawns many agents and merges PRs, so the start is always a human decision.
+
+You are the orchestrator. **You do not write code. You do not read diffs. You do not fix failing branches yourself.** You compute what's ready, dispatch, verify, and keep a running log. Tracker state and subagent reports in, decisions out.
+
+One agent implementing a whole backlog in a single session degrades — context fills with diffs and half-remembered state, and quality drops with every ticket. This loop inverts that: every ticket gets a fresh-context implementer subagent that owns it end to end, merge included, and nothing an implementer reports is trusted until the remote confirms it.
+
+This skill is the watchable, checkpointed frontend of the loop. The same loop exists as a deterministic workflow (`.claude/workflows/ralph.js`, installed by init; `launchrail sync` restores it) — prefer the workflow when the dependency graph is wide or the run is long (script state cannot be compacted away); prefer this skill when you want to watch each dispatch, the graph is a chain, or something is already going wrong. The two share one policy block: change a policy here, change it in the workflow too (ADR-0005, field-revised by ADR-0010).
+
+## Policies
+
+- **Width: 3** implementers at once. Width multiplies conflict rate and shared-machine load, not just throughput — use 1 until a run has landed tickets cleanly on this project. Cut a batch below width when its tickets would obviously collide (same module, same files); when in doubt, narrow.
+- **Cap: none** by default. The user may bound a run ("the next 5"): stop once that many merges have been *verified*, keeping every batch within the remainder so the run cannot overshoot. Failed and deferred dispatches never consume the cap — their slots go to other tickets. Hitting the cap ends the run cleanly: the rest of the frontier stays ready (reported, never parked), and close-out runs as usual.
+- **Attempts: 2** — retry a failed ticket once with a fresh context, then park it.
+- **Deferrals are not attempts.** An implementer that stops at its dependency gate (a declared blocker had not actually landed) hands the attempt back and is retried after the blocker lands — capped at 2 deferrals, then it counts as a real failure.
+- **Max rounds: 25** — a backstop, not a target; deferral rounds spend from it too. Stop and report if the frontier hasn't drained.
+- **Checkpoints: none** by default — run to completion, report once. The user may ask for a pause after each round instead.
+- **Review gate:** the implementer's own self-review via `/launch-code-review`, inside `launch-ralph-implement`.
+- **Verification gate:** `npx @wemuda/launchrail verify` — per ticket before the PR, and once more on the final base before the loop may report success.
+- **Merge ordering: optimistic, arbitrated by the remote.** Implementers re-sync immediately before merging and retry up to 3 times if the base moved. No merge locks.
+- **Labels:** tickets enter as `ready-for-agent`, are marked `ralph:building` while owned, and leave as closed or `needs-info` (parked).
+
+## Preconditions — refuse to start if any fails
+
+1. `.launchrail.yml` exists with `issueTracker` not `none`, and the tracker is reachable **from this environment**: check whether the CLI the project docs assume (e.g. `gh`) is installed here; if not, identify the substitute (e.g. GitHub MCP tools) and name it in every dispatch.
+2. Open tickets labeled `ready-for-agent` exist and carry explicit `Blocked by: #n` edges (or the tracker's native blocking relations). No tickets with edges → nothing to orchestrate; point the user at `launch-tickets`. If anything wearing `ready-for-agent` is plainly not an implementable ticket — a published spec, research notes, an epic — stop and have it relabeled (e.g. `spec`) before starting: the frontier is computed from the label alone and cannot tell prose from work.
+3. The base branch exists on the remote and is green on a fresh checkout: sync it, run the install command, then `npx @wemuda/launchrail verify` — report actual exit codes, not the reassuring summary line; a broken base poisons every implementer after it. A missing base branch is a refusal, not a cue to guess another. An **empty verification contract fails `verify` and is a refusal condition**: a run whose completion nothing can verify must not start. Tell the user to configure `testing` commands in `.launchrail.yml` first.
+4. The verbatim local commands are known (from `AGENTS.md` / `.launchrail.yml`), including which checks belong to CI rather than the shared local machine.
+
+## The loop
+
+Sync → compute frontier → dispatch batch → verify → handle outcomes → back to sync.
+
+- **You resolve blocking edges yourself,** deterministically, from tracker state — read each ticket's `Blocked by` line verbatim and parse the `#n` references; never ask a subagent what's ready, and never let one paraphrase the edges. A single misread edge silently builds a ticket on a dependency that hasn't landed. The frontier is every ticket that is open, labeled `ready-for-agent`, not `needs-info`, not already attempted twice, and whose blockers are all settled (closed before the run, or merged and verified by this run). Parked tickets never block the loop; anything behind them is reported as stuck.
+- Dispatch up to *width* frontier tickets, **spawning the batch's subagents in a single message** so they run concurrently.
+- **Verify every claimed merge against the remote** before it counts: PR merged, its merge commit actually in the base branch's history, issue closed. A subagent's report is a claim, not evidence. Use a cheap, separate check (tracker API only — a PR description or comment is not evidence).
+
+## The dispatch prompt
+
+Each implementer prompt is self-contained — assume it knows nothing about this session or the other implementers. It carries: the ticket number and title, the verbatim commands, how to reach the tracker from this environment, and these eight steps:
+
+1. **Dependency gate:** before anything else, confirm every ticket on the `Blocked by` line is closed with its work merged into the base. If any blocker is still open, do not build on a missing dependency — report "blocked" naming the open blocker, and stop. A deferral, not a failure; the loop retries after the blocker lands.
+2. Read the ticket and everything it links (spec sections, ADRs, journeys), plus `AGENTS.md`/`CLAUDE.md`. If the ticket is already closed, report "already-done" and stop.
+3. Label the ticket `ralph:building` so a lost session leaves a trace.
+4. Branch from a fresh sync of the base: `ralph/<n>-<short-slug>`.
+5. Implement by invoking the **`launch-ralph-implement`** skill — it owns TDD, the verification gate, browser smoke for user-facing changes, self-review via `/launch-code-review`, and commit conventions. Name the skill; do not paraphrase it.
+6. Pre-PR sync: merge the latest base into the branch; resolve conflicts with the **`launch-resolving-merge-conflicts`** skill; re-run the verification gate if anything changed.
+7. Open a PR titled from the ticket with `Closes #<n>` in the body. Never open a second PR for a ticket — adopt an existing one. Opening against an up-to-date base means CI tests the state that will actually land.
+8. Wait for CI if the repository has it — space polls with the Monitor tool or a background sleep, never a foreground sleep or busy loop; ~20 minutes is the budget. Fix what the branch broke and push; a failure that reproduces on the base itself is "ci-red" — systemic, not this ticket's problem. Re-sync immediately before merging (up to 3 retries if the base moves), then squash-merge. Squash-merge does not reliably fire `Closes` — read the issue back, close it explicitly if still open, and remove `ralph:building`.
+
+Every dispatch — retries included — also carries these two clauses verbatim:
+
+> **Integrity.** No placeholders, no stubs, no "simplified for now". Never delete, skip, or weaken a test to get a green run; if a test is genuinely wrong, fix it deliberately and say so in the PR body. Never claim verification passed without having run it.
+
+> **Idempotency.** This step can be replayed after an interruption, so check before acting: if the ticket is already closed, report "already-done"; if a `ralph/<n>-*` branch or open PR already exists, adopt it and continue — don't restart. Never open a second PR for a ticket.
+
+## Outcome handling
+
+- **Verified merge** → one log line; the ticket settles and may unblock others.
+- **Blocked (deferred)** → the dependency gate stopped the build. Hand the attempt back and retry in a later round; after 2 deferrals it becomes a real failure. A deferral costs a round, never an attempt.
+- **First failure** → delete the failed branch, then re-dispatch later with a *fresh context* plus the failure summary. A failed attempt's context is assumed poisoned — never resume it.
+- **Claimed merged, remote disagrees** — including merged-but-issue-still-open — → a failure like any other; the retry adopts the merged PR (idempotency clause), finishes the bookkeeping, and settles cleanly.
+- **Second failure** → park: comment both failure summaries on the ticket, remove `ralph:building`, add `needs-info`, move on.
+- **Systemic failure** — the base breaks, the tracker becomes unreachable, or the *same* infrastructure error hits different tickets → stop the whole run and report; another retry won't fix it.
+
+## Supervising a workflow run
+
+When the Ralph loop runs as the `ralph` workflow instead of through this skill, you are still on the hook — the script runs headless, but a human is watching *you*, not it. Babysit the run like a deploy:
+
+0. **Launch it unattended-safe.** An unattended run must start in a non-prompting permission mode (bypass / autonomous). In an interactive mode (default / plan / acceptEdits) a single benign permission prompt — an un-allowlisted MCP or Bash call — stalls the whole run, and an idle ephemeral container can be reclaimed mid-ticket, leaving a half-finished ticket. A guard hook warns at launch, but switching modes before you walk away is yours to do.
+1. **Read the resolved scope back, immediately.** The first `log()` lines state it ("Scoped to #11, #12", "Stopping after 5 verified merge(s)", or "No scope — building the whole ready frontier"). An unscoped run when the user asked for three tickets is the cheapest failure to catch and the most expensive to miss — stop and relaunch if it is wrong. Scan the listed numbers for anything that is not an implementable ticket: a spec or research issue wearing `ready-for-agent` will be built as if it were work (the workflow excludes and logs obvious cases, but the label is the fix — have it corrected).
+2. **Establish ground truth from the remote, never from the run's own reports.** On every check-in read the workflow journal (`journal.jsonl`) *and* the tracker/PRs. A merge is real only when the commit is on the base branch and the issue is closed.
+3. **Arm check-ins across the long waits.** If the session can schedule a self-message, arm one a few minutes out (confirm scope and the first dispatches) and a longer fallback (catch completion or a stall). The workflow's completion notification is the primary signal; the check-ins are the backstop so the run survives an interruption.
+4. **Know the healthy shapes so you don't cry wolf.** A ticket can appear twice in Build — that is the retry policy, or a *deferral* because its dependency had not landed yet (not a failure). A ticket only truly fails after two real attempts, then it parks.
+5. **Intervene by exception, not by reflex.** Parked ticket → dispatch a fresh scoped run for just that one. Stall (an agent stops writing, CI never returns) → diagnose from the journal. Wrong scope or wrong base → stop, fix, relaunch. Otherwise stay out of the way; the loop is built to self-correct.
+6. **Report once at the end, concretely** — PR numbers, merge commits, issues closed, the verification outcome, anything punted — then disarm the check-ins.
+
+## Loop close-out — verification-gated completion
+
+When the frontier drains (or max rounds / a stop condition hits):
+
+1. Sync a fresh base and run `npx @wemuda/launchrail verify`. **The loop may not report success while this fails** — report "unverified" with the failures instead.
+2. If `.launchrail.yml` has `modules.browser-testing: true` and any merged ticket changed user-facing behavior, dispatch one smoke run per the `launch-browser-smoke` skill and reference its evidence bundle (`artifacts/verification/<run-id>/`).
+3. Report the release evidence summary: merged tickets (PR and merge commit each), parked tickets with their failure histories, stuck tickets and what blocks them, follow-ups implementers punted, and the verification outcome with its evidence. Evidence over assertion — link what was run, never summarize what wasn't.
+
+## Rules
+
+- Fresh context per dispatch, per retry. No exceptions.
+- Never implement, review, or repair code in the orchestrator session — dispatch instead.
+- Name the skills (`launch-ralph-implement`, `launch-resolving-merge-conflicts`, `launch-browser-smoke`); never paraphrase their contents into a prompt.
+- Blocking edges are parsed from the verbatim `Blocked by` line, by you — never resolved by a model in between.
+- Nothing counts as merged until the remote says so; nothing counts as done until `verify` is green.
+- A deferral is not a failure; a failure is never silently retried without its summary.
+- Width is a lever, not a goal. Narrow it whenever tickets might collide.

package/assets/skills/launchrail/launch-ralph-implement/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: launch-ralph-implement
+description: Implement a single ticket end to end under the Launchrail completion contract — TDD, the deterministic verification gate, browser smoke for user-facing changes, self-review, and conventional commits. Used by Ralph loop dispatches and by /launch-implement's single-ticket mode.
+---
+
+# Implement one ticket
+
+The per-ticket implementation contract. Ralph dispatches name this skill so the contract lives in one place — every implementer, on every run, gets the same one.
+
+1. **Read before coding.** The ticket, every artifact it links (spec sections, ADRs, smoke journeys), and `AGENTS.md`/`CLAUDE.md`. The commands you run come from `.launchrail.yml` (`testing.*`) and `AGENTS.md`, verbatim.
+2. **TDD at the seams the ticket names.** Write the failing test first where the ticket or spec defines behavior. Typecheck and run single test files as you go; save full-suite runs for the gate — the machine may be shared with other implementers.
+3. **The gate:** `npx @wemuda/launchrail verify` must exit 0 before the work is done. Never delete, skip, or weaken a test to get there; if a test is genuinely wrong, fix it deliberately and say so in the PR body.
+4. **User-facing behavior, with `modules.browser-testing` enabled:** update or add the affected journey in `docs/testing/smoke-journeys.md` and drive it per the `launch-browser-smoke` skill. A journey you could not complete is a failure, not a pass.
+5. **Self-review:** run `/launch-code-review` on the result and fix what it finds before handing off.
+6. **Commit to the current branch** following the project's commit conventions (Conventional Commits when `.launchrail.yml` says so). Update any artifact the change invalidates (spec, ADR, journey) in the same change.
+
+Done means: the gate is green, the review found nothing unaddressed, and the evidence (test output, journey results) exists — not that the code "should work".

package/assets/skills/launchrail/launch-research/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: launch-research
+description: Investigate a question against high-trust primary sources and commit the findings as a Markdown file. Owns stage 5 (technical research, fed the grill's surviving constraints) and provides research depth wherever the rail needs facts gathered — docs, API surfaces, maintenance health, licenses — by a background agent while the session keeps working.
+---
+
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Commit it where the repo keeps such notes. On the rail that is `docs/research/` — stage-5 notes sit beside the grill constraints and the `discovery-*.md` landscape maps, and everything there is project-owned. Match a different convention only if the repo clearly has one, and say where the file landed.
+
+When this runs as **stage 5**, its brief is the grill's surviving constraints: de-risk the decisions the grill made — verify the chosen option really does what the decision assumes — don't reopen them. When `launch-discovery` drives it, the brief is one divergent thread: real capabilities, maintenance and community health, license, and concrete integration cost on this stack.

package/assets/skills/launchrail/launch-resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: launch-resolving-merge-conflicts
+description: Resolve merge conflicts without losing either side's behavior — the named protocol for parallel implementers landing against a moving base. Use when a merge or rebase reports conflicts, especially inside the Ralph loop.
+---
+
+# Resolving merge conflicts
+
+When parallel work lands against the same base, conflicts are ordinary work with a procedure — not failure. The one unforgivable resolution is the silent one that discards somebody's behavior.
+
+1. **Sync deliberately.** Fetch and merge the latest base into your branch (rebase only if it is the project's stated convention). Read the conflict list before touching anything.
+2. **Understand both sides.** For each conflicted file, find out what the other side's change was *for* — read its commit message, PR, or ticket if needed. You are merging intents, not text blocks.
+3. **Preserve both behaviors.** The resolved code must do what your change does *and* what theirs does. Taking "ours" or "theirs" wholesale is only correct when the two changes are genuinely the same fix.
+4. **Regenerate, don't hand-merge, generated files.** Lockfiles and other generated artifacts are re-created by their tool after resolving the source of truth — never merged line by line.
+5. **Prove it.** After resolving, run the verification gate (`npx @wemuda/launchrail verify`). A resolution that was never run is not a resolution.
+6. **Escalate ambiguity.** If both sides changed the same logic and any resolution you can see loses behavior, stop and report the conflict (which files, which intents collide) instead of guessing. In the Ralph loop that is the `conflict` outcome — a legitimate result, unlike a quiet wrong merge.

package/assets/skills/launchrail/launch-spec/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: launch-spec
+description: Turn the current conversation into a spec committed under docs/specs/ — no interview, just synthesis of what has already been discussed and decided. Owns stage 7's synthesis half (launch-wayfinder owns the breakdown of work too big for one session).
+disable-model-invocation: true
+---
+
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know: the vision, the grill's surviving constraints, the research notes, and the ADRs are the inputs; a conductor handing off this stage names them.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary (`CONTEXT.md`) throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better — the ideal number is one.
+
+   Check with the user that these seams match their expectations.
+
+3. Write the spec using the template below and **commit it under `docs/specs/`** (`<feature-slug>.md`) — the committed file is stage 7's artifact, and it is project-owned. If the project's tracker should carry a copy, publish it labeled **`spec`** — never `ready-for-agent`: that label marks implementable tickets, the implementation loop computes its frontier from it, and it cannot tell prose from work.
+
+The spec then flows on: design validation (stage 8) revises it in place, and `launch-tickets` (stage 9) breaks it into tickets.
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

package/assets/skills/launchrail/launch-tickets/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: launch-tickets
+description: Break a validated spec, plan, or the current conversation into tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker with the ready-for-agent label — the exact input contract the implementation loop's frontier is computed from. Owns stage 9.
+disable-model-invocation: true
+---
+
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+# To tickets
+
+Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. The output is the implementation loop's input: open tickets wearing `ready-for-agent` with explicit `Blocked by: #n` edges are the frontier `/launch-implement` drives.
+
+The issue tracker configuration lives in `docs/agents/issue-tracker.md`, seeded by `launchrail init` from the manifest — `npx @wemuda/launchrail sync` re-seeds it if it's missing.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path under `docs/specs/`, an issue number or URL) as an argument, fetch it and read its full body and comments. A spec that ran design validation carries a `## Design validation` section — the revised spec is the one to ticket.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary (`CONTEXT.md`), and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the configured tracker
+
+Publish the approved tickets. **How** depends on the tracker configured in `docs/agents/issue-tracker.md` — the tickets are the same either way, only the shape of the blocking edges changes:
+
+- **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
+- **A real issue tracker (GitHub, GitLab, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the **`ready-for-agent`** label unless instructed otherwise — the tickets are agent-grabbable by construction. Only tickets wear that label: a spec or research note published to the tracker takes a different label (e.g. `spec`), or the loop will dispatch the document as work.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<local-ticket-template>
+
+# <NN> — <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately".
+
+**Status:** ready-for-agent
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</local-ticket-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None — can start immediately".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.

package/assets/skills/launchrail/launch-vision-creation/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: launch-vision-creation
+description: Turn a raw product idea into a committed docs/vision.md capturing product intent, target users, assumptions, non-goals, and success signals. Use when a project has no vision document yet, when the user describes a new product idea, or when they ask to write or revise the vision.
+---
+
+# Vision creation
+
+Produce `docs/vision.md`: a short, honest statement of what this product is, who it serves, and what it deliberately is not. It is the first artifact of the Launchrail loop and the input to design exploration, discovery research, and the complexity grill.
+
+## Ground rules
+
+- `docs/vision.md` is **project-owned**: it belongs to the user and their repository. If it already exists, this run is a revision — read it first and change only what the user wants changed. Never regenerate it wholesale.
+- Capture broad intent, not a feature list. The vision states the problem and the bet; screens, endpoints, and data models come later in the loop.
+- Short beats complete. One to two pages. A vision nobody rereads is worthless.
+- Every assumption must be explicit and falsifiable — the complexity grill stage exists to attack them, so write them down in attackable form.
+- Non-goals carry as much weight as goals. A vision that excludes nothing decides nothing.
+
+## Process
+
+1. **Read what exists.** Check for `docs/vision.md`, a README, and any notes the user points at. Do not ask questions the repository already answers.
+2. **Interview the user** — briefly, a few questions at a time, in their language:
+   - What problem hurts, and for whom? How do those people cope today?
+   - Why this, why now — what is the bet that makes this worth building?
+   - Who is the first concrete user (a person or team you could name), as opposed to the eventual market?
+   - What is deliberately out of scope for the MVP?
+   - What observable signal would say the bet is working — and what would say it failed?
+   - Which assumption, if wrong, kills the product?
+3. **Draft** `docs/vision.md` using the template below. Use the user's words where they were precise; sharpen where they were vague, and say so.
+4. **Challenge the draft once.** Before presenting it, check: is any "goal" actually a feature? Is any assumption untestable as written? Is the non-goals section empty or evasive? Fix what you find.
+5. **Present and iterate** until the user approves.
+6. **Sync the agent contract.** If the seeded `AGENTS.md` still carries the TODO under `## Project purpose`, replace it with a one-paragraph distillation of the approved vision — what this is, who it serves, what it is not. Touch only that section: `AGENTS.md` belongs to the project, and the rest of it is not this skill's business.
+7. **Commit** `docs/vision.md` and the `AGENTS.md` update together (respect the project's commit conventions).
+8. **Hand off.** Point the user at the next stages of the loop: visual exploration in Claude Design to make the intent concrete, discovery research (`launch-discovery`) to map the real options for the vision's hard parts, then the complexity grill (`launch-grill`) to attack the assumptions just recorded. See [`workflow.md`](../launch/workflow.md) for the full stage order.
+
+## Template
+
+```markdown
+# Vision — <product name>
+
+## Problem
+Who hurts, how, and how they cope today.
+
+## Bet
+The one-sentence wager this product makes, and why now.
+
+## First users
+The concrete person or team this serves first — not the eventual market.
+
+## What the MVP must prove
+The smallest outcome that validates the bet.
+
+## Assumptions
+Numbered, falsifiable statements. Each one is an attack surface for the grill.
+
+## Non-goals
+What this product deliberately does not do, and for how long that holds.
+
+## Success signals
+Observable signals that the bet is working — and the signal that would call it failed.
+```