@wemuda/launchrail 1.7.0 → 1.9.0

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

@@ -0,0 +1,89 @@
+---
+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.
+---
+
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating ticket / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+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. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Inside a Ralph dispatch the fixed point is the branch's base. If nothing determines one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`. On the rail this is the normal case: the ticket being implemented, plus whatever it links.
+2. A path the user passed as an argument.
+3. A spec under `docs/specs/`, or a file under `.scratch/`, matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written: `AGENTS.md` and `CLAUDE.md` (the agent contract carries the project's conventions), plus a `CODING_STANDARDS.md` or `CONTRIBUTING.md` where one exists.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

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

@@ -0,0 +1,44 @@
+---
+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 in docs/specs/ is drafted and the user wants design validation, a visual review, or pre-implementation sign-off.
+---
+
+# Design validation
+
+Coordinate the loop **spec → visual pass at the right fidelity → revised spec → handoff**. The goal is to catch "specified but wrong on screen" before implementation starts: flows that read fine in prose but collapse when a user has to click through them.
+
+## The fidelity ladder
+
+The stage runs at one of four levels, chosen per spec ([ADR-0016](https://github.com/wemuda/launchrail/blob/master/docs/adr/0016-design-validation-fidelity-ladder.md)):
+
+| Level | What gets made | Made by |
+|---|---|---|
+| 1 · Recorded skip | Nothing driven; the `## Design validation` section records what was assessed and why | this skill |
+| 2 · Flow diagrams | An artifact page of flow/state diagrams describing what is being made — entry points, steps, decision points, end states | this skill, in-session |
+| 3 · Screen mockups | An artifact page showing the designs — mid-fidelity mockups of the key screens and the states the spec claims to handle (empty, loading, error) | this skill, in-session |
+| 4 · Claude Design | High-fidelity designs of entire screens/pages | Claude Design — drive it, or hand off (see below) |
+
+Every level answers the same question — does the specified behavior survive contact with a screen? — at increasing cost and resolution. Claude Design is reserved for level 4: full screens properly designed. The diagram and mockup artifacts of levels 2–3 are the session's own work.
+
+## Ground rules
+
+- The spec and everything this skill writes are **project-owned** artifacts. Revise the spec in place; never fork a parallel copy that can drift.
+- Validate flows, not pixels. Even at level 4, this stage answers "does the specified behavior survive contact with a screen?", not "is the visual style final?".
+- Every design finding must land in exactly one place: a spec revision, an ADR (if it changes an architecture decision), or an explicitly recorded rejection. Findings that live only in chat are lost.
+- **Evidence is linked, not committed.** Levels 2–4 link their artifact pages / design artifacts from the spec's `## Design validation` section — the same way stage 2's exploration artifacts are linked from the vision. The committed gate stays the spec section itself; because every finding lands in the spec or an ADR anyway, the gate never depends on the links surviving. If the session cannot publish a linkable page, say so and link the most durable render it can produce — never leave the evidence chat-only.
+- Do not start implementation from this skill. The output is a validated spec and a handoff note — tickets come next.
+
+## Process
+
+1. **Locate the spec.** Find the spec under `docs/specs/` (ask if there are several). Read it plus `docs/vision.md` and any grill/research artifacts it references, so validation happens against the product's constraints rather than in a vacuum.
+2. **Extract the flows to validate.** From the spec, list the user-facing journeys it implies — entry point, steps, decision points, end state. Confirm the list with the user; three to six flows is the useful range for an MVP.
+3. **Choose the level — recommend, then confirm.** Read the spec's design surface and the manifest's `mode`, recommend one level with a one-line reason, and let the user confirm or override across all four. Mode is **advisory, never a gate**: `spike` leans toward a recorded skip, `high-rigor` leans toward mockups or Claude Design with error and edge states covered — but the user owns the call. Never pick silently.
+4. **Run the level.**
+   - **Recorded skip** — go straight to step 7 and write the section as a recorded skip: date, what was assessed, why nothing needed driving.
+   - **Flow diagrams** — build one artifact page of flow/state diagrams covering the confirmed flows, including the decision points and terminal states the spec claims.
+   - **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.
+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.** Confirm with the user that the revised spec is approved, commit it (respect the project's commit conventions), and point them at ticket creation as the next stage. See [`workflow.md`](../launch/workflow.md) for the full stage order.

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

@@ -0,0 +1,33 @@
+---
+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.
+---
+
+# Discovery research — map the option space before you narrow it
+
+The stage that keeps the grill honest. A complexity grill is a *convergent* tool: it prunes a design tree. But it can only prune the branches already on the tree — so when the stack is assumed upstream (an `EXECUTION.md`, a README, a founder's default), the grill narrows an assumption instead of the real option space, and the technical-research stage that follows only ever de-risks the first guess. Discovery is the **divergent** counterweight: before the grill narrows anything, widen the field. For each hard part of the product, surface the actual alternatives that exist so the grill has real options to choose between.
+
+Diverge here; converge in the grill; de-risk in technical research. This stage owns the *diverge*.
+
+## Ground rules
+
+- **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.
+- **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.
+
+## Process
+
+1. **Read the inputs.** `docs/vision.md` and the intended stack (from the vision, `.launchrail.yml`, an `EXECUTION.md`/README, or by asking). Note the existing design system if one was recorded during alignment — it constrains front-end options.
+2. **Carve the product into areas of genuine choice.** Not everything needs discovery — most of a stack is settled or obvious. Find the handful of areas where the option space is real *and* the decision is load-bearing: the parts a grill would otherwise narrow blindly. They usually cluster around auth/identity, data storage and access, background/async work, third-party integrations, and whatever the vision's core mechanic demands (session replay, real-time transport, payments, …). Confirm the shortlist with the user — three to six areas is the useful range; don't manufacture choice where there is none.
+3. **For each area, enumerate the real contenders.** List the actual options that fit this stack — libraries, frameworks, hosted services, vendors, and the roll-your-own baseline. For each: what it is, what it buys you, what it costs (integration effort, lock-in, license, operational burden), and where it breaks down for *this* vision. Include the boring and the build-it-yourself options; a landscape that lists only the trendy pick is not a landscape.
+4. **Go deep where it's load-bearing.** For the areas where the choice most shapes the architecture, drive `launch-research` on the specific threads — verify real capabilities against the vision's needs, maintenance and community health, license, and concrete integration cost on this stack. Where research agents aren't available in the session, say so and fall back to a clearly-marked best-effort survey — do not silently skip the depth pass.
+5. **Write the landscape map.** Commit one doc per area (or one grouped doc) under `docs/research/`, named `discovery-<area>.md`. Each area records: the contenders with their trade-offs, what's verified vs. assumed, any options ruled out with the reason, and — most importantly — the **questions this hands to the grill**: the decisions now teed up with real options behind them.
+6. **Hand to the grill.** This stage does not choose. Route to the complexity grill (`launch-grill`, stage 4), which takes the landscape as input and narrows it into surviving constraints. Tell the user what you surveyed, where the docs are, that the grill is next, and that they can jump straight there.
+
+## What this stage is not
+
+- **Not the grill.** It opens options; it doesn't close them. If you find yourself arguing for one choice, stop and hand that argument to the grill.
+- **Not technical research.** Technical research (stage 5) runs *after* the grill and de-risks the decisions it made. Discovery runs *before* the grill and widens the decisions it will make. Same research skill, opposite direction — one diverges, one converges.
+- **Not a stack rewrite.** Options that can't fit the intended stack are noted and set aside, not campaigned for. If discovery surfaces that the intended stack itself is wrong for the vision, that's a finding for the grill and possibly an ADR — raise it, don't act on it here.

package/assets/skills/launchrail/launch-grill/CONTEXT-FORMAT.md

@@ -0,0 +1,62 @@
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

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

@@ -0,0 +1,48 @@
+---
+name: launch-grill
+description: The grill — a relentless, round-based interview that stress-tests a plan, decision, or idea into surviving constraints, maintains the domain model as terms and decisions crystallise, and always ends by committing the constraints 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.
+---
+
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+# The grill
+
+Interview the user relentlessly until you reach a shared understanding — then commit what survived. The grill is the rail's *convergent* tool, and it runs anywhere the user needs to get aligned with the agent before work hardens into specs and tickets. A grill that ends in conversation and no committed file has not finished — see [the artifact](#the-artifact-closes-the-grill) below.
+
+Run every grill with the **domain-modeling discipline** ([domain-modeling.md](./domain-modeling.md)) active: challenge terms against the glossary, sharpen fuzzy language, update `CONTEXT.md` as terms resolve, and offer an ADR (the project's `docs/adr/0000-template.md` format) when a decision meets its three-part bar.
+
+## Two contexts, one grill
+
+- **The foundation grill (stage 4).** Inputs: the vision, the visual exploration, and the discovery landscape (`docs/research/discovery-*.md`). The job is to narrow the whole product's option space into the constraints everything downstream builds on. When discovery ran, the landscape map is the option space — pick from the real contenders it surfaced; don't re-assume the default that the discovery stage existed to widen past. The surviving constraints become technical research's brief (stage 5).
+- **The feature grill (delivery loop).** Every sizing path — large, semi, small — starts here: when a new feature or idea arrives, grill it *before* `launch-spec` and `launch-tickets`, so the spec synthesizes decisions actually made together rather than assumptions. Same method, narrower brief: inputs are the feature idea plus the founded artifacts it touches (vision, ADRs, existing specs, the code). Hand off to whatever the sizing path says comes next — usually straight to `launch-spec` or `launch-tickets`.
+
+## The interview
+
+Map the discussion as a **design tree**: every decision branches into the decisions that hang off it. Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Each question should be formatted like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report — ask the rest of the frontier now. The _decisions_ are the user's — put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on the decisions until the user confirms you have reached a shared understanding.
+
+## The artifact closes the grill
+
+A grill gates on a committed file, not on the conversation. When the user confirms shared understanding, write the surviving constraints to **`docs/research/grill-<topic>.md`** (feature grills take the feature's slug) and commit it. The doc records:
+
+- the decisions made, each with its one-line why;
+- the assumptions attacked, and whether they survived;
+- the options ruled out, with the reason;
+- the open questions handed onward — to technical research after a foundation grill, or into the spec after a feature grill.
+
+Everything under `docs/research/` is project-owned; Launchrail tooling never overwrites it.
+
+One exception: when another skill invokes the grill for its own artifact — a `launch-wayfinder` ticket records its resolution on the ticket — that caller's artifact replaces the `docs/research/` doc. Absent such a caller, the committed doc is never optional.

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

@@ -0,0 +1,45 @@
+<!-- Contains text derived from Matt Pocock's skills (https://github.com/mattpocock/skills), MIT — see ../NOTICE.md -->
+
+# The domain-modeling discipline
+
+Run every grill with this discipline active: build and sharpen the project's domain model *as you design*, challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is a one-line habit any skill can do; this discipline is for when the model is being changed.)
+
+## File structure
+
+Most repos have a single context: one `CONTEXT.md` at the repo root, plus `docs/adr/`. If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts and the map points to where each `CONTEXT.md` lives (with `src/<context>/docs/adr/` for context-scoped decisions). The layouts and inference rules are in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. Everything here is project-owned; Launchrail tooling never overwrites it.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+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.

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

@@ -0,0 +1,49 @@
+---
+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 the integration target with the scope.** Every loop run merges its per-ticket PRs into exactly one base (ADR-0022): **trunk** — the default branch, each ticket live the moment it merges — unless the user names a consolidation branch ("collect spec #44 on `spec/44-mvp`", "don't touch master yet") or the environment forbids pushing to the default branch (a harness-designated branch: use it, and say that constraint is why). Consolidation means the default branch stays untouched and the run ends by offering one release PR `<target> → <default>`; it is a choice the user should recognize, never a silent fallback.
+
+**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: trunk (`master`). Engine: the `ralph` workflow." 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 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.
+
+**One ticket:** build it here, watchable, under the same contract a Ralph dispatch carries (kept textually parallel with `launch-ralph` — change one, change both). One deliberate divergence: you are the session, not a subagent, so you also run the 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`.
+3. Label the ticket `ralph:building`; branch `ralph/<n>-<short-slug>` from a fresh sync of the base (the resolved integration target).
+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.
+- **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; in consolidation mode that step is *offering* the one release PR to the default branch, opened only when the user says so.

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,115 @@
+---
+name: launch-ralph
+description: The Ralph implementation loop's contract — policies, dispatch steps, the loop-owned merge gate, and the supervisor's duties when the loop runs as the ralph workflow (the default engine for any multi-ticket run). Skill-mode orchestration of fresh-context implementers lives here too, as the declared exception. 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 the build through an open PR, the loop's merge gate lands it, and nothing anyone reports is trusted until the remote confirms it.
+
+This skill is the loop's contract and its supervisor. The loop itself runs as the deterministic `ralph` workflow (`.claude/workflows/ralph.js`, installed by init; `launchrail sync` restores it) — **the workflow is the engine for every multi-ticket run**, launched with the resolved scope and integration target as JSON args and then supervised per this skill; its script state cannot be compacted away. Orchestrating dispatches from this session instead is the exception, and it is chosen out loud — name the engine and why before anything dispatches: the user asked to watch each dispatch, the Workflow tool is unavailable in this environment, or this is a targeted intervention (one parked ticket, re-run watchably). A hand-rolled fan-out that is neither is not the loop. The two forms share one policy block: change a policy here, change it in the workflow too (ADR-0005, field-revised by ADR-0010 and ADR-0022).
+
+## Policies
+
+- **Integration target: declared, singular, restated.** Every run merges its per-ticket PRs into exactly one base, named before anything dispatches and again in the close-out. **Trunk** (the default): the repository's default branch — each verified merge is immediately on mainline, and when the run ends there is nothing left to integrate. **Consolidation**: one named integration branch (e.g. `spec/44-mvp`) collects the whole campaign and the default branch is never touched; the run ends by *offering* one release PR `<target> → <default>` — opened only when the user says so. Consolidation is chosen, never fallen into: the user names a branch or asks for it, or the environment forbids pushing to the default branch — announce that constraint as the reason. A named target missing from the remote is created from the default branch's tip before preflight verifies it; a missing *default* branch stays a refusal. In consolidation mode `Closes #n` never auto-fires (auto-close only triggers from the default branch), so the explicit post-merge close is load-bearing, not belt-and-suspenders.
+- **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 (the workflow's `canary: true` encodes exactly that). Cut a batch below width when its tickets would obviously collide (same module, same files); when in doubt, narrow. Tickets that add DB migrations are a known collision: two parallel implementers both claim the next migration number — serialize them, or expect the second to renumber at pre-PR sync.
+- **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 ownership: the loop, not the implementer.** Implementers build, open the PR, and hand off at PR-open; the merge gate — CI wait, mergeability re-check, squash-merge, explicit issue close, `ralph:building` removal — belongs to the loop (you in skill mode, a per-ticket gate agent in the workflow). An implementer subagent must never sit in a CI wait: it cannot foreground-sleep, and a background sleep surfaces to its parent without resuming it — tokens burn, nothing advances. Merge ordering stays optimistic and remote-arbitrated (re-check mergeability immediately before merging, up to 3 retries if the base moves; no merge locks), and the single gate owner serializes where it matters — critical-path first, schema-touching tickets one at a time.
+- **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 integration target is resolved (trunk or a named consolidation branch — see Policies) and its branch is green on a fresh checkout: sync it (creating a named consolidation branch from the default branch's tip if the remote lacks 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 *default* 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, which branch is the base (the integration target), and these seven 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 tracker tool truncates the body (long code spans are a known trigger), fetch the full text by another route — the tracker's search API, the spec file in the repo — and never implement from a truncated ticket. 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; if the base gained DB migrations since branching, regenerate yours to follow them with the project's migration tool — never hand-edit the journal; re-run the verification gate if anything changed.
+7. Open a PR against the base, 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. Then **report PR-open and stop**: the CI wait, the merge, and the issue close belong to the loop's merge gate, not to you. Never push to the base directly.
+
+## The merge gate — owned by the loop
+
+In skill mode, you run the gate for every PR the implementers hand off (the workflow runs it as a per-ticket gate agent). Order merges yourself — critical-path first, schema-touching PRs one at a time:
+
+1. Wait for the PR's CI from *this* session, spacing checks with your own timers (a background sleep here wakes you — the orchestrator can wait; implementer subagents cannot). ~20 minutes is the budget.
+2. Green → re-check mergeability (the base may have moved since CI started), then squash-merge; if the base moves between check and merge, re-check and retry up to 3 times.
+3. Merged → read the issue back and close it explicitly if still open — in consolidation mode auto-close never fires — and remove `ralph:building`. Then verify as always: the remote's word, not yours.
+4. CI failed on the PR, or a real conflict → the ticket becomes a failed attempt with the failing check or conflicting files as its summary; the fresh retry adopts the PR (idempotency clause), repairs, and hands off again. A failure that reproduces on the base itself is systemic — stop the run, not the ticket.
+
+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). Build ending at PR-open with a separate Gate agent doing the merge is the design, not a stall. 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 campaign recap — it must let the user act without scrolling back:
+   - **Where the work lives:** the integration target and its head SHA; in consolidation mode, say explicitly that the default branch is untouched.
+   - The ticket → PR → merge-commit table; parked tickets with their failure histories; stuck tickets and what blocks them.
+   - Follow-ups and operator steps implementers punted, gathered into one list.
+   - The verification outcome with its evidence. Evidence over assertion — link what was run, never summarize what wasn't.
+   - **The single next step:** trunk — nothing; every merged ticket is live on the default branch. Consolidation — offer the one release PR `<target> → <default>` with this recap as its body, and open it only when the user says so.
+
+## Rules
+
+- Fresh context per dispatch, per retry. No exceptions.
+- One integration target and one engine per run, both declared before the first dispatch and restated in the recap.
+- Never implement, review, or repair code in the orchestrator session — dispatch instead. Running the merge gate is bookkeeping, not repair.
+- 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".