@wemuda/launchrail 1.13.0 → 1.15.0

package/assets/skills/NOTICE.md

@@ -16,6 +16,10 @@ into `docs/agents/`. Each derived file carries its own derivation note. If
 Launchrail is useful to you, the inspiration credit belongs upstream — see the
 Launchrail README's Credits section.
 
+Upstream is monitored as inspiration, never re-vendored (ADR-0020). The
+derived skills were last reviewed against upstream commit `6654f6b`
+(2026-08-24).
+
 ---
 
 MIT License

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

@@ -1,6 +1,6 @@
 ---
 name: launch
-description: The planning conductor and single entry point to the Launchrail loop. Detects how far a project has moved from idea toward release — setup, vision, visual exploration, discovery, grill, research, ADRs, spec, design validation, tickets — then runs or routes to the stage that owns the next step, and hands implementation to /launch-implement. Reports position as six phases with an explicit rail banner at every transition. Once the foundation exists it also sizes each new feature (large / semi / small) and routes the planning subset that size needs. Use to start or continue the workflow, ask what stage or phase a project is at, size a new feature, or jump straight to a named stage.
+description: The planning conductor — the single entry point to the Launchrail loop. Detects the project's stage from its committed artifacts, runs or routes to the stage's owner, sizes each new feature (large / semi / small) once the foundation exists, and hands implementation to /launch-implement — reporting position as six phases with the rail banner at every transition. Use to start or continue the workflow, ask what stage or phase the project is at, size a new feature, or jump straight to a named stage.
 ---
 
 # Launch — the loop conductor
@@ -15,7 +15,7 @@ Read `.launchrail.yml` (`origin`, `modules`, `issueTracker`) first — it is the
 
 | # | Stage | Owner (invoke / run) | Done when |
 |---|---|---|---|
-| 0 | Setup | `npx @wemuda/launchrail init` | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) |
+| 0 | Setup | `npx @wemuda/launchrail init`; then `launch-loop-readiness` to tune the repo for the implementation loop (optional — recommended once for an existing codebase) | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) — its `ralph …` readiness lines are advice, never a gate |
 | 1 | Vision | `launch-vision-creation` — via `launch-project-alignment` when `origin: existing` | `docs/vision.md` exists and is real (not the bare template) |
 | 2 | Visual exploration | Claude Design | Exploration artifacts linked from `docs/vision.md` |
 | 3 | Discovery | `launch-discovery` | Landscape map committed under `docs/research/` (`discovery-*.md`) |
@@ -26,7 +26,7 @@ Read `.launchrail.yml` (`origin`, `modules`, `issueTracker`) first — it is the
 | 8 | Design validation | `launch-design-validation` (fidelity chosen inside the skill) | The spec carries a `## Design validation` section (a recorded skip counts) |
 | 9 | Tickets | `launch-tickets` † | Tracker has `ready-for-agent` tickets with `Blocked by: #n` edges |
 | 10 | Implementation | `/launch-implement` † — drives the Ralph loop | The ready frontier is drained; PRs merged and verified |
-| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | The gate is green; smoke evidence where behavior is user-facing |
+| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | The gate is green; user-facing behavior seen working in a real browser |
 | 12 | Release | The project's release setup | The release is cut |
 
 † User-typed (`disable-model-invocation`): prepare the handoff — inputs committed, exact fully-argumented command handed over, resume when the artifact lands (see the conductor rules). Never call one and get refused, and never reverse-engineer it.
@@ -50,9 +50,9 @@ A feature that arrives **design-first** — a dropped zip or folder of Claude De
 ## Running it
 
 1. **Did the user name a stage or a feature?** A stage keyword (below): sanity-check its inputs exist, offer the earlier stage if one is missing, but honor the jump if they insist — then invoke or hand off and stop. A new feature on a founded project: size it (above) and run the path.
-2. **Otherwise orient, then find the frontier.** A cheap read-only look first: `git status`, current branch, recent commits — is something already in flight for the stage you're about to start? If the tracker is configured and reachable, read the live discussion on relevant tickets and PRs, not just titles; skip what isn't there (orientation sharpens routing, never gates it). Then close stage-0 gaps yourself without asking (init, commit init output, `sync` — it seeds `docs/agents/` too). Walk stages 1 → 12 and stop at the first whose "done when" fails, skipping only what the vision's non-goals record as deliberately skipped. `origin: existing` with no real vision → route to `launch-project-alignment`, not a blank vision.
+2. **Otherwise orient, then find the frontier.** A cheap read-only look first: `git status`, current branch, recent commits — is something already in flight for the stage you're about to start? If the tracker is configured and reachable, read the live discussion on relevant tickets and PRs, not just titles; skip what isn't there (orientation sharpens routing, never gates it). Then close stage-0 gaps yourself without asking (init, commit init output, `sync` — it seeds `docs/agents/` too). When `doctor` warns on its `ralph …` readiness lines (fast gate, e2e specs, CI triggers, hosted setup, commands), offer `launch-loop-readiness` once — it measures and tunes the repo for the loop — and move on; readiness never gates the rail. Walk stages 1 → 12 and stop at the first whose "done when" fails, skipping only what the vision's non-goals record as deliberately skipped. `origin: existing` with no real vision → route to `launch-project-alignment`, not a blank vision.
 3. **Confirm the read — with the banner.** Render the rail banner for the position you detected, then say why — which artifacts you found and which you didn't. Ambiguous signals (template-only vision, several specs) are questions, not guesses.
-4. **Route.** Invoke the owner by exact name, or prepare the handoff for a user-typed stage (†). For stage 7, name the authoritative inputs in order; if the stack isn't stood up yet, tell it to name its seams but leave harness mechanics to the foundation work. For stage 10, hand over `/launch-implement` — never start it yourself.
+4. **Route.** Invoke the owner — call the Skill tool with its exact name — or prepare the handoff for a user-typed stage (†). For stage 7, name the authoritative inputs in order; if the stack isn't stood up yet, tell it to name its seams but leave harness mechanics to the foundation work. For stage 10, hand over `/launch-implement` — never start it yourself.
 5. **Close every transition with the banner.** When a stage finishes or a handoff is prepared, re-render the banner — the just-closed artifact under Done, the next mover under Now, the `➤` line carrying the one next action (the exact fully-argumented command when the stage is user-typed). Add a sentence on what the next stage does and whether it's optional here, and that any stage is reachable by keyword — a bare stage name reads as a turnstile; explain, don't gate.
 
 ## Stage keywords
@@ -61,7 +61,7 @@ Case-insensitive direct jumps:
 
 - `status` / `where` — render the rail banner for the detected position (with the evidence) and stop.
 - `next` — detect the frontier and drive it (the default).
-- `setup` / `init` — 0 · `align` / `adopt` — the existing-project on-ramp · `vision` — 1 · `explore` — 2 · `discovery` / `landscape` — 3 · `grill` — 4 · `research` — 5 · `deep-research` — 3→5 · `adr` / `architecture` — 6 · `spec` — 7 · `design-validation` / `validate` — 8 · `tickets` — 9 · `implement` / `build` / `ralph` / `loop` — hand over `/launch-implement` · `verify` / `smoke` — 11 · `release` — 12 · `handoff` / `design-handoff` — the design→code on-ramp (`launch-design-handoff`).
+- `setup` / `init` — 0 · `readiness` / `tune` / `optimize` — `launch-loop-readiness` · `align` / `adopt` — the existing-project on-ramp · `vision` — 1 · `explore` — 2 · `discovery` / `landscape` — 3 · `grill` — 4 · `research` — 5 · `deep-research` — 3→5 · `adr` / `architecture` — 6 · `spec` — 7 · `design-validation` / `validate` — 8 · `tickets` — 9 · `implement` / `build` / `ralph` / `loop` — hand over `/launch-implement` · `verify` / `smoke` — 11 · `release` — 12 · `handoff` / `design-handoff` — the design→code on-ramp (`launch-design-handoff`).
 - `feature` / `size` — size a described feature (recommend a path; route on request).
 
 Unrecognized keyword → show this list and ask.

package/assets/skills/launchrail/launch/workflow.md

@@ -51,6 +51,7 @@ A planning session (a grill, a wayfinder ticket, an interview) closes with the b
 ## Prerequisites
 
 - The repository is initialized (`npx @wemuda/launchrail init`) and healthy (`npx @wemuda/launchrail doctor`). Init writes the workflow skills, the implementation loop's materials, *and* the `docs/agents/` configuration (issue-tracker conventions and domain-doc rules, seeded from the manifest's answers) — there is no separate install or setup step on the golden path.
+- Before the first `/launch-implement` on an existing codebase, `launch-loop-readiness` (stage 0, optional) measures the verification gates and tunes the repository for the implementation loop — a fast per-land gate, parallel e2e specs, shared caches for parallel builders, CI triggers, tracker labels, hosted-session setup, verbatim commands ([ADR-0033](https://github.com/wemuda/launchrail/blob/master/docs/adr/0033-loop-readiness.md)). `doctor`'s `ralph …` readiness lines say when it is worth running; they warn, never fail.
 
 ## Stages
 
@@ -66,7 +67,7 @@ A planning session (a grill, a wayfinder ticket, an interview) closes with the b
 | 8 | Design validation | Launchrail `design-validation` skill | Spec (+ Claude Design at the top fidelity) | Revised spec with `## Design validation` section |
 | 9 | Tickets | `launch-tickets` † | Validated spec | Tickets in the tracker: `ready-for-agent` label, `Blocked by: #n` edges |
 | 10 | Implementation | `/launch-implement` † → the Ralph loop | Ready tickets | PRs merged and verified; the frontier drained |
-| 11 | Verification | `npx @wemuda/launchrail verify` · Launchrail `browser-smoke` skill | Merged work | The gate green; smoke evidence where behavior is user-facing |
+| 11 | Verification | `npx @wemuda/launchrail verify` · `launch-browser-smoke` | Merged work | The gate green; user-facing behavior seen working in a real browser |
 | 12 | Release | The project's release setup | Verified base | The release cut |
 
 † **User-typed by design** — `disable-model-invocation`: only the user can start these. `launch-wayfinder`/`launch-spec` and `launch-tickets` publish to the tracker; `/launch-implement` spawns agents and merges PRs. A conductor prepares the handoff instead of calling them — see the conductor rules.
@@ -77,7 +78,7 @@ Stage notes:
 - **Stage 4 converges far enough to build, not exhaustively.** The grill's stopping rule is build-safety — the decisions the next slice depends on are locked or safely defaulted — never an empty question tree: product design is generative, and "everything answered before implementation" is not a reachable state ([ADR-0029](https://github.com/wemuda/launchrail/blob/master/docs/adr/0029-planning-interaction-contract.md)). "Nothing silently assumed" still holds, but it means every open question is *labeled and parked*, not answered. And stage 4 ends in a committed file, always: `launch-grill` closes its interview by writing the surviving constraints to `docs/research/` — the conversation alone never closes the stage, and the skill treats the committed doc as part of its own contract.
 - **‡ The stage-7 spec's home follows the tracker** ([ADR-0025](https://github.com/wemuda/launchrail/blob/master/docs/adr/0025-spec-home-follows-tracker.md)), exactly as stage-9 tickets do. On a real tracker (GitHub, GitLab, Linear) the spec **is** a `spec`-labeled issue and no `docs/specs/` file is written; in local mode (`local`, or no tracker) it is a committed `docs/specs/<slug>.md` file. Detection is therefore tracker-aware — read `docs/agents/issue-tracker.md` to know where to look. `ready-for-agent` still marks tickets only; the spec issue wears `spec` so the loop never dispatches prose as work.
 - **Stage 8 scales to the spec's design surface** through a fidelity ladder ([ADR-0016](https://github.com/wemuda/launchrail/blob/master/docs/adr/0016-design-validation-fidelity-ladder.md)): recorded skip, flow diagrams, screen mockups, or Claude Design. The level choice lives inside `design-validation` (recommend, user confirms). It exists to catch "specified but wrong on screen" while the finding still costs a spec edit rather than re-cut tickets — that's why it precedes stage 9 and is not stage 11, which checks the *built* product. Even a skip is recorded through the skill, so the gate stays artifact-based.
-- **Stage 10 is one door.** `/launch-implement` drives the Ralph loop ([ADR-0017](https://github.com/wemuda/launchrail/blob/master/docs/adr/0017-implementation-loop-provider.md) as amended by [ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)). Launchrail owns both edges of the loop: `ready-for-agent` tickets with `Blocked by: #n` edges in, `launchrail verify` (+ browser smoke where enabled) gating every merge.
+- **Stage 10 is one door.** `/launch-implement` drives the Ralph loop ([ADR-0017](https://github.com/wemuda/launchrail/blob/master/docs/adr/0017-implementation-loop-provider.md) as amended by [ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md)). Launchrail owns both edges of the loop: `ready-for-agent` tickets with `Blocked by: #n` edges in, `launchrail verify --fast` gating every land, the full `launchrail verify` at the loop's checkpoints and release, and — where the browser-testing module is enabled — each implementer's one-off browser smoke of its user-facing ticket ([ADR-0034](https://github.com/wemuda/launchrail/blob/master/docs/adr/0034-browser-smoke-one-off-driving.md)) ([ADR-0032](https://github.com/wemuda/launchrail/blob/master/docs/adr/0032-ralph-lean-local-gate-loop.md)).
 
 ## Sizing the work in the delivery loop
 
@@ -119,7 +120,7 @@ How every stage spends the user's attention ([ADR-0029](https://github.com/wemud
 The contract for `launch`, `/launch-implement`, and any agent driving the rail. The conductors execute these rules; this document owns them.
 
 - **Every transition renders the rail banner.** Orientation, routing, stage close, session summary — position is announced with the banner from the phase view above, never gestured at in prose. The user should never have to ask "where are we, and what happens now?"
-- **One owner per stage, invoked by name.** Every stage has exactly one owning skill. Invoke it by name; do not paraphrase, wrap, re-prompt, or re-derive its work inline — the skill is the only place its stage's behavior lives.
+- **One owner per stage, invoked by name.** Every stage has exactly one owning skill. Invoke it by calling the Skill tool with the owner's exact name (a user-typed stage gets the prepared handoff instead); do not paraphrase, wrap, re-prompt, or re-derive its work inline — the skill is the only place its stage's behavior lives.
 - **Artifacts gate stages, not chat memory.** A stage is done only when its committed artifact exists; detect by reading the repository, and when a signal is ambiguous (a template-only vision, an abandoned spec draft), ask rather than assume. Detection and sizing are read-only — every write happens inside the stage owner.
 - **User-typed stages get a prepared handoff, never reverse-engineering.** A `disable-model-invocation` refusal is the cue to hand over, not to reproduce the skill's work by hand or grep vendored skill files. A prepared handoff is three moves: confirm the stage's input artifacts are committed; hand the user the exact, fully-argumented command naming those inputs (a bare `/skill` sends it re-deriving what your inputs already settle — arguments that point at committed inputs are parameters, not paraphrase); pick up automatically once the stage's artifact lands.
 - **The grill feeds research.** Run the grill before technical research and hand research the grill's surviving constraints as its brief.

package/assets/skills/launchrail/launch-browser-smoke/SKILL.md

@@ -1,49 +1,45 @@
 ---
 name: launch-browser-smoke
-description: Drive the running app through its defined smoke journeys in a real browser and produce a Launchrail evidence bundle. Use when user-facing work needs verification beyond deterministic tests, when the user asks to smoke-test the app, or before declaring user-facing work done in a project with the browser-testing module enabled (.launchrail.yml modules.browser-testing).
+description: Drive the running app in a real browser to see a just-built change working — a one-off, agent-driven check of the feature, not a test suite and not an evidence bundle. Use before declaring user-facing work done when .launchrail.yml has modules.browser-testing enabled, or when the user asks to smoke-test or click through the app.
 ---
 
-# Browser smoke testing
+# Browser smoke — see the change working
 
-Drive the real application through its user journeys in a browser and record evidence. Agentic smoke testing supplements deterministic tests — it never replaces them, and it never substitutes assertion for evidence.
+A browser smoke is you driving the real stack in a real browser to check that what you just built looks right and works. It is **one-off**: it lives for this change and ends in a verdict, not in a test file, a journeys catalogue, or a committed report ([ADR-0034](https://github.com/wemuda/launchrail/blob/master/docs/adr/0034-browser-smoke-one-off-driving.md)). Deterministic coverage is the other lane — `npx @wemuda/launchrail verify` with the unit command and the thin Playwright e2e specs — and a smoke never grows it by accident.
 
 ## Preconditions
 
 1. `.launchrail.yml` has `modules.browser-testing: true`. If not, stop and suggest `npx @wemuda/launchrail add browser-testing`.
-2. Deterministic checks pass first: run `node scripts/verify.mjs`. If verify fails, fix that before smoke testing — smoke runs on top of a green build.
-3. The app is running. Start it with `node scripts/dev.mjs` (use `--background` in cloud or CI sessions; logs land in `.launchrail/state/dev.log`). In a fresh clone, run `node scripts/setup.mjs` first.
-
-## Run contract
-
-1. **Collect the journeys.** Read `docs/testing/smoke-journeys.md` (sections headed `## Journey:`) plus any journeys defined in the ticket or spec under verification. Each journey has a start point, steps, and verify checks.
-2. **Scaffold the evidence bundle.** Run `npx @wemuda/launchrail smoke` (add `--url <url>` for a preview environment). It confirms the app responds and creates `artifacts/verification/<run-id>/` containing `meta.json`, a `summary.md` skeleton, and `screenshots/` + `traces/` directories. If it reports the app unreachable, start the app — do not skip the journey.
-3. **Drive each journey in a real browser** — Playwright MCP, browser tools, or a Playwright script, whichever is available. The browser-testing module seeds a Playwright MCP server (`.mcp.json`); approve it once in Claude Code to drive the browser interactively, or fall back to a Playwright script in headless CI. Follow the steps as a user would: click, type, navigate. Try realistic variations and obvious edge cases, and watch the console and network panel as you go.
-4. **Capture evidence while testing, not afterwards:**
-   - Screenshots of each key state → `screenshots/`
-   - Console errors and warnings → `console.log`
-   - Failed or unexpected requests → `network-errors.json`
-   - Playwright traces where available → `traces/`
-5. **Apply the standard checks to every journey:**
-   - No uncaught console errors
-   - No failed API requests
-   - The success state is visible
-   - Data remains after refresh
-
-## When you find a real bug
-
-1. Record the precise reproduction in the evidence bundle.
-2. Add or update a deterministic test that fails on the bug.
-3. Fix the bug.
-4. Prove the deterministic test passes.
-5. Re-run the affected journey.
-6. Keep the trace or screenshot that shows the failure.
-
-This turns exploratory findings into permanent regression coverage instead of forgotten discoveries.
-
-## Completing the run
-
-- Fill in `summary.md` completely: journey outcomes, standard checks, evidence references, deviations, newly added tests, remaining blockers. Check only boxes you actually verified.
-- Record any deviation from the spec or design in `deviations.md` next to the summary.
-- A journey you could not complete is a failure or a blocker, never a pass.
-- Never mark a journey passed while it has unexplained console or network errors.
-- The committed record is `summary.md`, `deviations.md`, and `meta.json`; bulky evidence stays local or becomes a CI artifact.
+2. The fast gate is green: `npx @wemuda/launchrail verify --fast`. A smoke runs on top of a green build; a red one is fixed first.
+3. The app runs from **this** worktree: `node scripts/dev.mjs --background` (in a fresh clone, `node scripts/setup.mjs` first). Other builders may share the machine — pass `--port <n>` with a port nobody else uses. The script writes the URL to `.launchrail/state/dev.url` and the pid to `.launchrail/state/dev.pid`; read the URL from there rather than assuming `testing.appUrl`.
+4. The driver is `agent-browser`, installed by `scripts/setup.mjs`: `npx agent-browser --version` must answer. If it does not, run setup; if it still cannot install, use the fallback below.
+
+## The run
+
+1. **Decide what to check.** From the ticket's acceptance criteria and your diff, write three to six steps for *this change*: where to start, what to click or type, what must be visible at the end. They live in your head and your handoff — never in a repository file.
+2. **Drive them, one session per ticket.** `export AGENT_BROWSER_SESSION=<branch-or-ticket>` keeps your browser apart from other builders'. Then, from the shell:
+   - `npx agent-browser open <url>` — start on the page the change lives on.
+   - `npx agent-browser snapshot -i` — the interactive elements with refs (`@e1`, `@e2`, …).
+   - `npx agent-browser click @e3`, `fill @e5 "text"`, `type`, `press Enter` — act as a user would.
+   - `npx agent-browser wait --load networkidle`, `wait --text "Saved"`, `wait <selector>` — **after every action that triggers a request or opens a modal, wait before the next snapshot**; a snapshot taken too early is the usual false failure.
+   - `npx agent-browser screenshot <path>` — and look at the image yourself (open it with the Read tool). Layout, copy, empty states, and wrong-but-rendering are what a script cannot judge; that judgment is the point of this lane.
+   - `npx agent-browser errors`, `console`, `network requests` — after each step, not only at the end.
+3. **Click around beyond the happy path.** The obvious wrong input, the empty state, a reload, the back button. You are looking for what the ticket did not spell out.
+4. **The standard checks, every time:** no uncaught exceptions, no failed requests, the success state visible in a screenshot you looked at, the data still there after a reload.
+5. **Design:** compare the screen to a design only when the ticket or spec names one (a `docs/design/` handoff, a mockup). Never invent a comparison.
+
+## When something is wrong
+
+1. Fix it.
+2. Add the regression test at the **cheapest seam that would have caught it** — a unit or integration test first. A new Playwright spec under `tests/e2e/` only when the ticket asks for one or the behavior exists only in a real browser; the e2e lane stays thin, and a smoke never becomes a spec by default.
+3. Re-drive the steps that failed.
+
+## Done
+
+- `npx agent-browser close`, and stop the app you started: `kill $(cat .launchrail/state/dev.pid)`.
+- Your handoff states, in a few lines, what you drove and what you saw — that is the record. Nothing is committed for the smoke: no journeys file, no `artifacts/` bundle, no screenshots in the repo.
+- A smoke you could not drive is a failure, not a pass. Never report one you did not run.
+
+## Fallback — no driver
+
+If `agent-browser` cannot be installed here, write a throwaway `playwright-core` script under `.launchrail/state/` (gitignored) that drives the same steps and prints what it saw, and run it with the project's Playwright. It stays there — it never moves under `tests/`, and it is no substitute for looking at the screenshots.

package/assets/skills/launchrail/launch-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch-code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating ticket/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. The self-review gate inside launch-ralph-implement; also for reviewing a branch, a PR, or work-in-progress changes on request.
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (the repo's documented coding standards) and Spec (what the originating ticket or spec asked for) — in parallel sub-agents, reported side by side. The self-review gate inside launch-ralph-implement; also on request for a branch, a PR, or work in progress.
 ---
 
 <!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->

package/assets/skills/launchrail/launch-design-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch-design-handoff
-description: The design→code on-ramp — take a Claude Design prototype dropped into the session (a .zip export, an extracted folder, artboard/HTML files, or a published canvas link) and turn it into a committed handoff package under docs/design/, read against the current codebase and design system, then route it into the delivery loop — normally a short feature grill, a spec that references the designs, and tickets. Use when the user drops design files or a zip from Claude Design and wants them documented or implemented — "here is the prototype of feature X" — or asks to hand designs back from Claude Design into code.
+description: The design→code on-ramp — turn a Claude Design prototype dropped into the session (a .zip export, an extracted folder, artboard/HTML files, or a published canvas link) into a committed handoff package under docs/design/, then route it into the delivery loop. Use when the user drops design files from Claude Design and wants them documented or implemented — "here is the prototype of feature X" — or asks to bring designs back from Claude Design into code.
 ---
 
 # Design handoff — from Claude Design back into the loop

package/assets/skills/launchrail/launch-design-validation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch-design-validation
-description: Validate an approved spec visually before implementation — at a confirmed fidelity level (recorded skip, flow-diagram artifact, screen-mockup artifact, or Claude Design), feed the findings back into a revised spec, and produce a handoff note for ticket creation. Use when a spec is drafted (a spec-labeled issue on the tracker, or a docs/specs/ file in local mode) and the user wants design validation, a visual review, or pre-implementation sign-off.
+description: Validate a drafted spec visually before tickets are cut — at a confirmed fidelity level (recorded skip, flow diagrams, screen mockups, or Claude Design) — and feed the findings back into a revised spec. Use when a spec is drafted and the user wants design validation, a visual review, or pre-implementation sign-off.
 ---
 
 # Design validation
@@ -39,6 +39,6 @@ Every level answers the same question — does the specified behavior survive co
    - **Screen mockups** — build one artifact page mocking the key screens and states per flow, including the empty, loading, and error states the spec claims to handle.
    - **Claude Design** — drive it flow by flow when the session can reach it. When it can't, prepare a fully-argumented handoff — the flows, the states each must show, links to the spec and vision, and any existing design-system baseline (see `project-alignment`) — hand it to the user to run, and resume when the design artifacts land. Never silently downgrade a level-4 choice to mockups; a downgrade is the user's decision.
 5. **Harvest findings.** For each flow record: what the design confirmed, what it contradicted in the spec, and what the spec turned out to be silent on. Ambiguities count as findings. Findings at a low level are also a signal — if the diagrams alone surface deep uncertainty, recommend re-running a flow at a higher level before revising.
-6. **Revise the spec.** Apply the accepted findings to the spec in place. If a finding invalidates an ADR, update or supersede that ADR in the same change. Note rejected findings and why in the handoff note, so the question does not resurface every review.
+6. **Revise the spec.** Apply the accepted findings to the spec in place. If a finding invalidates an ADR, update or supersede that ADR in the same change, mirroring the status change in the registry index (`docs/adr/README.md`). Note rejected findings and why in the handoff note, so the question does not resurface every review.
 7. **Write the handoff note** at the end of the spec (section `## Design validation`) with: date, the level that ran, flows validated, links to the artifact pages / design artifacts, accepted changes, rejected findings with reasons, and open questions. This section is the evidence that validation happened — the ticket stage (`launch-tickets`) reads the spec as validated only if it is present.
 8. **Hand off with the rail banner.** Confirm with the user that the revised spec is approved, save it in place — commit the file, or update the spec issue on the tracker — respecting the project's commit conventions. Then close with the banner from [`workflow.md`](../launch/workflow.md)'s phase view: the validated spec under Done, ticket creation (`launch-tickets`) as Now, and the exact command on the `➤` line.

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

@@ -1,6 +1,6 @@
 ---
 name: launch-discovery
-description: The divergent option-space scan that runs before the complexity grill. Given the vision and the intended stack, it maps the real landscape of libraries, frameworks, vendors, hosted services, and patterns available for the hard parts of the product — enumerating the alternatives with their trade-offs rather than locking onto the first choice — and commits a landscape/options map that becomes the grill's input. Use after the vision (and visual exploration) and before the grill, or when the user asks to explore the tech landscape, survey vendors/libraries, or do discovery research. It composes `launch-research` for depth on any single thread; it does not pick winners — the grill does that.
+description: The divergent option-space scan before the complexity grill — map the real landscape of libraries, frameworks, vendors, and patterns for the hard parts of the product (alternatives with trade-offs, no winners) and commit the landscape map the grill narrows. Use after the vision (and visual exploration) and before the grill, or when the user asks to explore the tech landscape, survey vendors or libraries, or do discovery research. Composes `launch-research` for depth on any single thread.
 ---
 
 # Discovery research — map the option space before you narrow it
@@ -13,7 +13,7 @@ Diverge here; converge in the grill; de-risk in technical research. This stage o
 
 - **Diverge, don't decide.** Your job is to widen, not to pick. For each area, present the real contenders and their trade-offs; do **not** crown a winner or collapse to one option — that is the grill's job (stage 4), fed by what you surface here. A discovery doc that recommends exactly one tool per area has skipped its own stage.
 - **Bounded by the vision and the intended stack.** This is not open-ended reading. The vision says what's being built; the intended stack (and any existing design system) says what it must fit. Explore the landscape *for this product on this stack* — options that can't plug into the stack are noted and set aside, not explored in depth. This boundary is what keeps discovery from wandering into research nobody asked for.
-- **Compose, never duplicate.** Discovery is divergent framing over `launch-research`. Do the framing yourself — carve the product into areas, enumerate contenders — and invoke `launch-research` to go deep on any single thread that needs primary sources (real capabilities, maintenance health, license, integration cost). Don't reimplement research; drive it.
+- **Compose, never duplicate.** Discovery is divergent framing over `launch-research`. Do the framing yourself — carve the product into areas, enumerate contenders — and call the Skill tool with `launch-research` to go deep on any single thread that needs primary sources (real capabilities, maintenance health, license, integration cost). Don't reimplement research; drive it.
 - **Everything here is project-owned.** The landscape map is committed to the project under `docs/research/`; Launchrail tooling never overwrites it.
 - **Evidence over vibes.** A contender listed from memory is a lead, not a finding. Where a choice is load-bearing, confirm the fact — does it actually do X, is it maintained, what's the license — through `launch-research` rather than asserting it.
 

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

@@ -1,6 +1,6 @@
 ---
 name: launch-grill
-description: The grill — a budgeted, round-based interview that stress-tests a plan, decision, or idea until the next slice can be built safely, maintains the domain model as terms and decisions crystallise, and always ends by committing what settled under docs/research/. Runs in two contexts, the foundation's complexity grill (stage 4) and the feature grill that opens every delivery-loop path before speccing and tickets. Use whenever the user wants to be grilled, stress-test thinking, or get aligned before building.
+description: The grill — a budgeted, round-based interview that stress-tests a plan, decision, or idea until the next slice can be built safely, keeps the domain model current as terms crystallise, and always commits what settled under docs/research/. Runs as the foundation's complexity grill (stage 4) and as the feature grill opening every delivery-loop path. Use whenever the user wants to be grilled, stress-test thinking, or get aligned before building.
 ---
 
 <!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
@@ -38,11 +38,17 @@ Map the discussion as a **design tree**: every decision branches into the decisi
 
 1. Recompute the frontier; label everything new on it.
 2. Work the non-user labels: dispatch `research`, pick and record `agent-default`s, park `defer`s, propose a `prototype` when one would collapse several questions at once.
-3. Ask at most **three** `decide-now` questions — the most load-bearing ones on the frontier. A genuinely consequential decision **rides alone**, with the context it deserves. Number each question and give your recommended answer:
+3. Ask at most **three** `decide-now` questions — the most load-bearing ones on the frontier. A genuinely consequential decision **rides alone**, with the context it deserves. Number each question, give your recommended answer, and separate questions with a horizontal rule — format a round like so:
 
 ```
 ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
 
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
 ➡️ <your recommended answer>
 ```
 

package/assets/skills/launchrail/launch-grill/domain-modeling.md

@@ -42,4 +42,6 @@ Only offer to create an ADR when all three are true:
 2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
 
-If any of the three is missing, skip the ADR. ADRs use the **project's own format**: copy `docs/adr/0000-template.md` (seeded by `launchrail init`), scan `docs/adr/` for the highest existing number, and increment by one — `NNNN-short-slug.md`. One format per project; do not introduce a second.
+If any of the three is missing, skip the ADR — an implementation choice that fails the bar lives in the spec or the ticket, not `docs/adr/`. And when the decision refines one an existing ADR already owns, amend that ADR (update its `## Status` line and its registry row) instead of minting a sibling; a corpus of revisions reads worse than a decision with a history.
+
+ADRs use the **project's own format**: copy `docs/adr/0000-template.md` (seeded by `launchrail init`), take the next free number — check both the files in `docs/adr/` and the registry index (`docs/adr/README.md`) — and add the new record's row to the registry index **in the same commit**. One format per project; do not introduce a second.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Start building — drive ready tickets to verified merges through the Ralph loop. Bare, it works the whole ready frontier; `/launch-implement 15` builds one ticket end to end; several numbers scope the loop; a count ("the next 5") caps it; a spec reference ("spec #2's tickets") resolves to its tickets. Repairs its own setup instead of stopping.
 disable-model-invocation: true
 ---
 
@@ -18,25 +18,25 @@ From `.launchrail.yml`: `issueTracker` and the `testing` commands. From the argu
 - **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 the integration target with the scope.** Every multi-ticket run **consolidates by default** (ADR-0022, ADR-0026): its per-ticket PRs collect onto one integration branch, the default branch stays untouched, and the run ends by *offering* one release PR `<target> → <default>` for the user to review and merge — never merging to the default branch on its own. You name that branch before anything launches, scope-native: the branch the user named if they gave one ("collect spec #44 on `spec/44-mvp`"); else **the session's designated working branch** when the environment pinned one at start — a hosted session's `claude/...` branch exists to receive exactly this run, so use it rather than minting a `spec/*` twin beside it (ADR-0028); else the scope's own name when it maps to a spec, epic, or slice (`spec/<n>-<slug>`); else a generated fallback for an ad-hoc frontier (`launch/frontier-<today>`, or `launch/tickets-<n>-<m>` for a handful of loose numbers). A named target the remote lacks is created from the default branch's tip by the run's preflight. **Trunk** — each ticket merged straight to the default branch, live the moment it lands — is now the explicit opt-in: choose it only when the user asks in so many words ("land each ticket on master as it goes"), and never when the environment forbids pushing to the default branch. A pinned-branch environment ("develop on this branch; no unprompted PRs") constrains the *deliverable*, which consolidation already honors — the default branch stays untouched, the release PR stays offered-only. It never constrains the *engine*: the user typing `/launch-implement` is the explicit go-ahead for the loop's own mechanics — per-ticket `ralph/*` branches and their PRs, every one landing on the target — and is never a reason to drop to sequential in-session building. Whichever target, restate it in the echo — a choice the user should recognize, never silent.
+**Resolve the integration target with the scope.** Every multi-ticket run **consolidates by default** (ADR-0022, ADR-0026): its per-ticket branches are landed onto one integration branch by the loop's own local gate, the default branch stays untouched, and the run ends by *offering* one release PR `<target> → <default>` for the user to review and merge — the one place cloud CI runs — never merging to the default branch on its own. You name that branch before anything launches, scope-native: the branch the user named if they gave one ("collect spec #44 on `spec/44-mvp`"); else **the session's designated working branch** when the environment pinned one at start — a hosted session's `claude/...` branch exists to receive exactly this run, so use it rather than minting a `spec/*` twin beside it (ADR-0028); else the scope's own name when it maps to a spec, epic, or slice (`spec/<n>-<slug>`); else a generated fallback for an ad-hoc frontier (`launch/frontier-<today>`, or `launch/tickets-<n>-<m>` for a handful of loose numbers). A named target the remote lacks is created from the default branch's tip by the run's preflight. **Trunk** — each ticket merged straight to the default branch, live the moment it lands — is now the explicit opt-in: choose it only when the user asks in so many words ("land each ticket on master as it goes"), and never when the environment forbids pushing to the default branch. A pinned-branch environment ("develop on this branch; no unprompted PRs") constrains the *deliverable*, which consolidation already honors — the default branch stays untouched, the release PR stays offered-only. It never constrains the *engine*: the user typing `/launch-implement` is the explicit go-ahead for the loop's own mechanics — per-ticket `ralph/*` branches, pushed as they grow and landed on the target by the loop, no PR among them — and is never a reason to drop to sequential in-session building. Whichever target, restate it in the echo — a choice the user should recognize, never silent.
 
 **Resolve prose to data before anything launches.** The loop's inputs are ticket numbers and policy values (`only`, `max`, `width`, `target`) — the workflow 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. Target: consolidate on `spec/2-checkout` (`master` untouched; one release PR offered at the end). Engine: the `ralph` workflow." A misread scope corrected here costs a sentence; corrected after launch it costs a run. That echo is your one pre-launch report — resolve the scope, repair setup (Step 2), and route (Step 3) without narrating the checks in between; surface a step only when it fails or changes the scope.
 
 ## 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).
+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). An unset `testing.checkCommand` is not a gap — the fast gate falls back to the unit command — but when `doctor` warns on its `ralph …` readiness lines (fast gate, e2e specs, CI triggers, hosted setup, commands), say once that `/launch-loop-readiness` measures and fixes them, and proceed; readiness never gates a build.
 
 ## Step 3 — Route by scope
 
-**The frontier (or any multi-ticket scope):** the engine is the `ralph` workflow (`.claude/workflows/ralph.js`) — launch it with the resolved scope and target as JSON args, e.g. `{ only: [14, 15, 19], max: 5, target: 'spec/2-checkout' }` (`canary: true` on a project's first run), then supervise it per the `launch-ralph` skill, which owns the policies (width, attempts, cap, deferrals, the merge gate, remote-verified merges) and the supervisor's contract. Orchestrating dispatches by hand under that skill instead is the exception, chosen out loud in the echo: the user asked to watch each dispatch, the Workflow tool is unavailable here, or the run is a targeted intervention (one parked ticket). One engine, one shape — a session that invents its own fan-out is not running the loop.
+**The frontier (or any multi-ticket scope):** the engine is the `ralph` workflow (`.claude/workflows/ralph.js`) — launch it with the resolved scope and target as JSON args, e.g. `{ only: [14, 15, 19], max: 5, target: 'spec/2-checkout' }` (`canary: true` on a project's first run), then supervise it per the `launch-ralph` skill, which owns the policies (width and the work pool, attempts, re-syncs, cap, deferrals, the local landing gate, checkpoints, remote-verified lands) and the supervisor's contract. Relaunching after a lost container passes `knownGreen: '<sha>'` so preflight skips re-proving a base a previous run verified; pushed `ralph/*` branches are adopted, never rebuilt. Orchestrating dispatches by hand under that skill instead is the exception, chosen out loud in the echo: the user asked to watch each dispatch, the Workflow tool is unavailable here, or the run is a targeted intervention (one parked ticket). One engine, one shape — a session that invents its own fan-out is not running the loop.
 
-**One ticket:** build it here, watchable, under the same contract a Ralph dispatch carries (kept textually parallel with `launch-ralph` — change one, change both). A single ticket has nothing to consolidate, so its base is the **default branch** and its one CI-gated PR merges there — consolidation-by-default is a multi-ticket policy (use a different base only if the user names one, or the session pins a designated branch — then that is the base). One deliberate divergence: you are the session, not a subagent, so you also run the merge gate yourself — waiting on CI here is fine:
+**One ticket:** build it here, watchable, under the same contract a Ralph dispatch carries (kept textually parallel with `launch-ralph` — change one, change both). A single ticket has nothing to consolidate, so its base is the **default branch** and its one CI-gated PR merges there — consolidation-by-default is a multi-ticket policy (use a different base only if the user names one, or the session pins a designated branch — then that is the base). Two deliberate divergences from a loop dispatch: a single ticket's PR *is* the review checkpoint, so it keeps the PR and its cloud CI, and you are the session, not a subagent, so you run that merge gate yourself — waiting on CI here is fine:
 
 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`.
+2. Read the ticket and everything it links (spec sections, ADRs, designs), plus `AGENTS.md`/`CLAUDE.md`.
 3. Label the ticket `ralph:building`; branch `ralph/<n>-<short-slug>` from a fresh sync of the base resolved above.
-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.
+4. Implement by calling the Skill tool with **`launch-ralph-implement`** — it owns TDD, the push cadence, the gates (the full `verify` before a PR of your own), browser smoke for user-facing changes, self-review, and commit conventions. Never paraphrase it inline.
+5. Pre-PR sync: merge the latest base; resolve conflicts by calling the Skill tool 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.
@@ -44,6 +44,6 @@ If the loop's materials are missing — `modules.ralph` off in the manifest, or
 ## 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.
-- **Every loop run ends with the campaign recap** (the `launch-ralph` close-out): where the work lives — target branch and head SHA — the ticket → PR → merge-commit table, parked and stuck tickets, punted follow-ups in one list, and the single next step. By default that step is *offering* the one release PR `<target> → <default>`, opened only when the user says so; in the opt-in trunk mode it is nothing — every ticket is already live on the default branch. Under the recap, render the rail banner ([`workflow.md`](../launch/workflow.md)'s phase view) — Build done for this scope, verification/release as what remains — so even the build door closes with "where we are and where we're going".
+- **Nothing is done until the gates are green** — `npx @wemuda/launchrail verify --fast` on every land, the full `npx @wemuda/launchrail verify` at the loop's checkpoints and once more on the final base when a run ends (and before a single ticket's PR). Where `modules.browser-testing` is enabled and the change is user-facing, a `launch-browser-smoke` run — the change seen working in a real browser — is part of done.
+- **Report evidence, not assertions:** landing commits (PR numbers in single-ticket mode), issues closed, checkpoint and verify outcomes — and what was held, parked, or punted, with why.
+- **Every loop run ends with the campaign recap** (the `launch-ralph` close-out): where the work lives — target branch and head SHA — the ticket → landing-commit table, held, parked, and stuck tickets, punted follow-ups in one list, and the single next step. By default that step is *offering* the one release PR `<target> → <default>` (where cloud CI runs, once), opened only when the user says so; in the opt-in trunk mode it is nothing — every ticket is already live on the default branch. Under the recap, render the rail banner ([`workflow.md`](../launch/workflow.md)'s phase view) — Build done for this scope, verification/release as what remains — so even the build door closes with "where we are and where we're going".

package/assets/skills/launchrail/launch-loop-readiness/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: launch-loop-readiness
+description: Check and tune a repository for the implementation loop — measure the verification gates, then set the fast per-land gate, parallelize the e2e specs, share caches for parallel builders, narrow CI triggers, create the tracker labels, add hosted-session setup, and document the verbatim commands. Measured first, applied with one confirmation, never a gate on the rail. Run once before the first /launch-implement on an existing codebase, or whenever doctor's `ralph …` readiness lines warn.
+---
+
+# Loop readiness — tune the repo for the implementation loop
+
+The Ralph loop is only as fast as the repository lets it be. Every land runs the fast gate, every fifth land runs the full gate, every builder starts in a fresh worktree, every push can wake a CI runner, and a hosted session starts from an empty container. A repo tuned for humans typing `pnpm test` once an hour wastes tokens and wall-clock when three fresh-context builders hammer it all night. This skill measures that waste and removes it — without weakening a single test.
+
+It is advice, never a gate: `/launch-implement` runs whether or not this skill ever ran. `npx @wemuda/launchrail doctor` shows the same findings as warn-only `ralph …` lines; this skill is where they get fixed with numbers behind them.
+
+## Contract
+
+- **Measure before proposing.** Every finding carries a number — seconds cold, seconds warm, e2e spec count — from a run you made, not an estimate.
+- **Propose in impact order, with the expected saving**, then apply everything reversible in **one confirmation round** (the interaction contract in [`workflow.md`](../launch/workflow.md): reversible implementation details are yours, the user confirms only what touches their testing methodology — which e2e specs stay serial, what CI still runs).
+- **Never weaken coverage.** No deleted, skipped, or loosened tests; no lowered assertions; latency-sensitive e2e specs stay serial. Speed comes from tiering, parallelism, caching, and not running the same suite twice.
+- **Idempotent.** Re-running on a tuned repo reports "ready" and changes nothing.
+- **One commit** at the end, in the project's convention (`chore: tune the repo for the implementation loop`), listing what changed.
+
+## Step 1 — Inventory (read-only)
+
+1. `npx @wemuda/launchrail doctor` — collect every `ralph …` line; they are the deterministic half of this checklist.
+2. `.launchrail.yml` `testing.*` (unit, check, e2e, dev) and `AGENTS.md`'s Commands section: which commands exist verbatim, which are missing.
+3. The package manager and its install command (frozen-lockfile form); the scripts (`test`, `lint`, `typecheck`, `build`, `check`); the monorepo tool (turbo, nx, workspaces) and its cache configuration; the test runners and their configs (vitest/jest workers and cache, Playwright `workers`, `fullyParallel`, `projects`, `retries`).
+4. CI: every workflow's triggers and jobs; whether the required check is the same command the loop runs locally.
+5. Data: the migration tool and its generate/renumber command; whether tests need a database, ports, or external services, and how they isolate per run.
+6. Tracker: the labels the loop uses (`ready-for-agent`, `ralph:building`, `needs-info`, `spec`) exist — check with the tracker tools named in `docs/agents/issue-tracker.md`.
+7. `.claude/settings.json`: hooks (the Ralph guard, any `SessionStart`), permissions; the seeded `scripts/setup.mjs` when the browser-testing module is on.
+
+## Step 2 — Measure
+
+Run, and time, in this order — twice each, so cold and warm are both known:
+
+- `npx @wemuda/launchrail verify --fast` (the per-land gate).
+- `npx @wemuda/launchrail verify` (the checkpoint and release gate); note the per-package breakdown the runner prints and, with e2e specs, their count and their share of the time.
+- The install command in a fresh worktree (`git worktree add ../readiness-probe HEAD`, install, then remove it) — what every builder pays before its first test.
+
+Write the numbers down; they anchor every proposal and the closing card.
+
+## Step 3 — The catalogue
+
+Work through these; each names the check, the fix, and why it matters to the loop.
+
+1. **The fast gate** — `testing.checkCommand` unset, or slower than ~2 minutes warm. Set it to lint + typecheck + the unit suites without e2e specs (on turbo: `turbo run lint typecheck test --filter=!<web-package>` plus the web package's unit runner). Every land and every hand-off runs this; the e2e specs move to the checkpoints.
+2. **E2e specs** — a global `workers: 1` or `fullyParallel: false`. Split: a `serial` Playwright project holding the latency-asserting specs (matched by directory or a `@serial` tag) and a `parallel` project for the rest; run them as two invocations from the e2e command (`playwright test --project=parallel --workers=4 && playwright test --project=serial --workers=1`). Which specs are latency-sensitive is the user's call — ask with the list in hand. Target: the full suite in a fraction of its serial time with identical assertions.
+3. **Caches for parallel builders** — each builder starts in a fresh worktree with an empty cache. Enable the monorepo tool's shared cache: turbo remote cache, or `TURBO_CACHE_DIR` pointing at a path outside the worktree (persist it for hosted sessions via `$CLAUDE_ENV_FILE` in the SessionStart hook); a shared vitest `cacheDir`; the package manager's content-addressable store (pnpm has one by default). Unchanged packages then cost nothing at the builder's gate and at the lander's.
+4. **CI triggers** — a workflow that runs on every push. The loop pushes `ralph/*` on every green step and the integration branch on every land; each would start a run nobody waits on. Trigger on `pull_request` and pushes to the default branch only, and add a `concurrency` group with `cancel-in-progress` so a release PR's re-pushes do not queue behind each other. Cloud CI runs once, on the release PR — make sure the required check there is the same full gate the loop ran at release.
+5. **Tracker labels** — create any of `ready-for-agent`, `ralph:building`, `needs-info`, `spec` that are missing, with the descriptions from `docs/agents/issue-tracker.md`. A run refuses or mislabels without them.
+6. **Hosted-session setup** — no `SessionStart` hook. Hosted sessions (Claude Code on the web) start from a fresh container: add `.claude/hooks/session-start.sh` that exits early unless `$CLAUDE_CODE_REMOTE` is `true`, runs the install command, and — with the browser-testing module — `node scripts/setup.mjs` so the pinned browser build is present (a version mismatch here is a preflight refusal in the field). Register it additively under `hooks.SessionStart` in `.claude/settings.json` (merge; the Ralph guard's `PreToolUse` entry stays). Synchronous first; offer async mode only if the user wants faster session starts. Validate it once with `CLAUDE_CODE_REMOTE=true` before committing.
+7. **Verbatim commands** — `AGENTS.md`'s Commands section still holds the seeded TODO, or lacks any of install, fast gate, full gate, dev, and the migration generate/renumber command. Builders and the pre-land sync read these verbatim; fill them in from the inventory, and mirror the test ones into `.launchrail.yml` `testing.*`.
+8. **Test isolation for parallel builders** — fixed ports, a shared database or schema, temp files at fixed paths. Three builders run the suites at once on one machine: use ephemeral ports (`0`), per-run database names or schemas, and `os.tmpdir()`-based paths. A flake that only appears at width 3 is this.
+9. **Worktree hygiene** — configs or scripts that assume the checkout path (absolute paths, `..` walks out of the repo), generated files that are not ignored, install steps that write outside the repo. Builders work in `git worktree`s; anything path-bound breaks there first.
+10. **Unattended runs** — remind, once, that an unattended run launches in a non-prompting permission mode (the guard hook warns at launch), and that any MCP or CLI the loop needs (the tracker tools) must be reachable from the session that launches it.
+
+## Step 4 — Confirm, apply, re-measure
+
+Present the proposals as one list — finding, fix, expected saving — and ask one round of at most three questions, only about what needs the user's judgment (which e2e specs stay serial; whether CI may be narrowed; anything touching production or secrets). Then apply everything approved, run `doctor` again, re-run the Step 2 timings, and commit.
+
+## Step 5 — The readiness card
+
+Close with a card the user can act on without scrolling back:
+
+```
+Loop readiness — <project>
+Fast gate:   <before> → <after> (warm <n>s) · <command>
+Full gate:   <before> → <after> · e2e specs <n> (<parallel>/<serial>)
+Builder cold start: install <n>s · first fast gate <n>s
+Changed:  <one line per change, with the file>
+Left for you: <anything that needs a human — secrets, remote cache login, CI settings>
+```
+
+Then hand back: when reached through `launch`, close with the rail banner from [`workflow.md`](../launch/workflow.md) — stage 0 under Done, the next stage under Now.
+
+## What this skill does not do
+
+- It never starts the loop, and never blocks it — `/launch-implement` runs without it.
+- It never touches product artifacts (vision, specs, tickets) or the managed Launchrail files.
+- It never deletes, skips, or weakens a test, and never lowers an assertion to buy speed.
+- It never changes what CI verifies, only when it runs; a project's required checks stay required.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: "The on-ramp for adopting an existing, mid-development codebase: inventory what the project already has, infer a draft vision from the code, interview only the gaps, detect the existing design system — then route 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 one to stage 1."
 ---
 
 # Project alignment — adopting an existing project
@@ -39,7 +39,7 @@ How each Launchrail artifact shows up in an existing project, and what to do:
 | 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 |
+| Verification | Test suite, CI config, Playwright | Wire `testing` commands in `.launchrail.yml`; note stage 11 partial; recommend `launch-loop-readiness` before the first `/launch-implement` — it measures the gates and tunes the repo for the loop | Note as a gap |
 
 ## What this skill does not do