@wemuda/launchrail 1.7.0 → 1.8.0

package/assets/skills/NOTICE.md

@@ -0,0 +1,41 @@
+# Attribution
+
+The skills in this directory are Launchrail's own — one complete, `launch-`
+prefixed workflow (ADR-0020), managed by `launchrail sync`.
+
+Several of them absorb methodology and contain text derived from
+[Matt Pocock's skills](https://github.com/mattpocock/skills), used and adapted
+under the MIT License reproduced below:
+
+- `launch-research`, `launch-grill` (including its `domain-modeling.md` and
+  `CONTEXT-FORMAT.md`), `launch-wayfinder`, `launch-spec`, `launch-tickets`,
+  `launch-code-review`
+
+The same applies to the issue-tracker and domain-doc files Launchrail seeds
+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.
+
+---
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,67 @@
+---
+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. 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 a project is at, size a new feature, or jump straight to a named stage.
+---
+
+# Launch — the loop conductor
+
+One command for the whole rail. You are the **conductor**, not a stage: find where the project sits, then run or hand off to the skill that owns the next step. Every stage has exactly one owner; [`workflow.md`](workflow.md) is the contract for who owns what and for the conductor rules — compose owners by name, gate on committed artifacts, prepare handoffs for user-typed stages, keep detection read-only. Follow those rules; this file only tells you how to route.
+
+## The stage map
+
+Read `.launchrail.yml` (`mode`, `origin`, `modules`, `issueTracker`) first — it is the source of truth for configuration; `npx @wemuda/launchrail status` for what's installed and current.
+
+| # | Stage | Owner (invoke / run) | Done when |
+|---|---|---|---|
+| 0 | Setup | `npx @wemuda/launchrail init` | Manifest + lockfile committed; `doctor` green (`docs/agents/` is seeded by init) |
+| 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`) |
+| 4 | Complexity grill | `launch-grill` | Grill constraints committed under `docs/research/` |
+| 5 | Technical research | `launch-research`, fed the grill constraints | Research notes committed under `docs/research/` |
+| 6 | Architecture decisions | ADRs (`docs/adr/0000-template.md`) | `docs/adr/NNNN-*.md` beyond the template |
+| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | A spec exists under `docs/specs/` |
+| 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 |
+| 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.
+
+`deep-research` = stages 3 → 4 → 5 as one arc: discovery widens the option space, the grill narrows it, research de-risks what survives. The workflow doc's stage notes carry the judgment calls for stages 3, 4, 8, and 10.
+
+## Sizing the next feature
+
+Once the foundation exists (a real vision, ADRs beyond the template) and the user brings **one new feature**, the frontier question changes from "what stage is next" to "how much planning does this feature deserve." Size it — propose with your reasoning, let the user correct you; they see scope the artifacts don't show:
+
+| Size | Looks like | Planning path |
+|---|---|---|
+| **Large** | A new subsystem or cross-cutting change; real unknowns; decisions worth an ADR | discovery *(new tech territory only)* → `launch-wayfinder` → grill → `launch-spec` → design validation → `launch-tickets` |
+| **Semi** | Self-contained feature, some design surface, a handful of tickets | grill → `launch-spec` → design validation *(optional)* → `launch-tickets` |
+| **Small** | Well-understood change, little or no design surface, one or few tickets | grill → `launch-tickets` |
+
+Judgment calls: the grill here is feature-scoped (same `launch-grill`, narrower brief); discovery earns a place only when the feature opens genuinely new tech territory — a vendor category or storage engine the project hasn't used; design validation is for real UI surface; a genuine architecture decision gets an ADR before tickets. Between two sizes pick the smaller — it's cheaper to add a stage than to over-plan a small change. `mode` calibrates on top: `spike` may drop `launch-spec` and design validation (record the skip); `high-rigor` bumps one notch. Every size ends at `/launch-implement`.
+
+## 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 `mode` permits. `origin: existing` with no real vision → route to `launch-project-alignment`, not a blank vision.
+3. **Confirm the read.** Say where you think the project is and 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.
+5. **Leave an explained map.** Current stage, the next one with a sentence on what it does and whether it's optional here, then the rest of the arc to the destination — and that any stage is reachable by keyword. A bare stage name reads as a turnstile; explain, don't gate.
+
+## Stage keywords
+
+Case-insensitive direct jumps:
+
+- `status` / `where` — report the detected stage 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.
+- `feature` / `size` — size a described feature (recommend a path; route on request).
+
+Unrecognized keyword → show this list and ask.
+
+## Mode calibration
+
+`mode` calibrates rigor, not stage order: `spike` may skip stages 2–5 and 8 when the vision's non-goals record it (don't nag); `standard-mvp` skips nothing silently; `high-rigor` skips nothing, wants an ADR per stage-6 decision, and design validation covers error and edge states. When a stage looks skipped, check the vision's non-goals before deciding — and if you can't tell, ask.

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

@@ -0,0 +1,77 @@
+# The Launchrail core workflow
+
+How a project moves from idea to verified, released software through committed artifacts. The rail is one complete, self-contained skill set — every stage owner is a Launchrail `launch-*` skill, written to the rail's artifact contract ([ADR-0020](https://github.com/wemuda/launchrail/blob/master/docs/adr/0020-independent-skill-set.md); several absorb methodology from [Matt Pocock's skills](https://github.com/mattpocock/skills), credited in `NOTICE.md`). The stage table below is the contract for which skill owns which stage and what artifact it must leave behind, and the conductor rules further down are the contract for how the `launch` conductor (and any agent working the rail) behaves between stages.
+
+## Running it
+
+Two commands cover the whole rail:
+
+- **`/launch`** — plan. It detects which stage the project has reached from its committed artifacts and runs or routes to that stage's owner; it takes a stage name (`vision`, `discovery`, `design-validation`, …) to jump straight there, and it sizes each new feature once the foundation exists ([ADR-0009](https://github.com/wemuda/launchrail/blob/master/docs/adr/0009-launch-orchestrator-skill.md), [ADR-0018](https://github.com/wemuda/launchrail/blob/master/docs/adr/0018-implement-front-door.md)).
+- **`/launch-implement`** — build. The single entry point for stage 10: it drives ready tickets to verified merges through the project's selected loop — the whole frontier, a spec's tickets, the next N ("max 5"), or one ticket at a time.
+
+## 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.
+
+## Stages
+
+| # | Stage | Tool | Input | Committed artifact |
+|---|---|---|---|---|
+| 1 | Vision | Launchrail `vision-creation` skill | The idea, the user | `docs/vision.md` |
+| 2 | Visual exploration | Claude Design | Vision | Exploration artifacts (linked from the vision) |
+| 3 | Discovery research | Launchrail `discovery` skill (composes `launch-research`) | Vision + intended stack | Landscape/options map in `docs/research/` (`discovery-*.md`) |
+| 4 | Complexity grill | `launch-grill` | Vision + exploration + discovery | Grill constraints in `docs/research/` |
+| 5 | Technical research | `launch-research` | **Grill constraints** | Research notes in `docs/research/` |
+| 6 | Architecture decisions | ADRs (seeded template) | Research | `docs/adr/NNNN-*.md` |
+| 7 | MVP specification | `launch-wayfinder` / `launch-spec` † | Vision, ADRs, research | `docs/specs/` |
+| 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 |
+| 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.
+
+Stage notes:
+
+- **Stages 3 → 4 → 5 are one arc** (`deep-research`): discovery *diverges* — it maps the real option space for the vision's hard parts (all the auth vendors, not one) and never picks winners; the grill *converges* — it narrows that landscape into constraints; research de-risks what survives. Don't collapse discovery into the grill outside `spike` mode: a grill with no discovery narrows whatever stack was assumed upstream, the exact failure discovery exists to prevent ([ADR-0015](https://github.com/wemuda/launchrail/blob/master/docs/adr/0015-discovery-research-stage.md)).
+- **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.
+- **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.
+
+## Sizing the work in the delivery loop
+
+The stages above take a fresh project to its first release. After that, the delivery loop repeats once per feature, and `launch` sizes each feature so its planning depth matches the work ([ADR-0014](https://github.com/wemuda/launchrail/blob/master/docs/adr/0014-start-feature-conductor.md), folded into `launch` by [ADR-0018](https://github.com/wemuda/launchrail/blob/master/docs/adr/0018-implement-front-door.md)):
+
+- **Large feature** — discovery when it opens new tech territory, `launch-wayfinder` to break it down, a grill, `launch-spec`, design validation, then `launch-tickets`.
+- **Semi feature** — a grill, `launch-spec`, optionally design validation, then `launch-tickets`.
+- **Small feature** — a grill straight to `launch-tickets`.
+
+Every size ends the same way: `/launch-implement`, gated by `launchrail verify`. Sizing changes *how many* planning stages a feature needs, never *who owns* them.
+
+## Adopting an existing project
+
+When `.launchrail.yml` records `origin: existing`, stage 1 is reached through the Launchrail `project-alignment` skill: it inventories what the codebase already has, infers a draft vision from the code, interviews only the gaps, and detects the existing design system as the baseline for stages 2 and 8, then hands to `vision-creation` to commit ([ADR-0013](https://github.com/wemuda/launchrail/blob/master/docs/adr/0013-existing-project-alignment.md)). Alignment is an on-ramp onto the same rail, not a second workflow.
+
+## Conductor rules
+
+The contract for `launch`, `/launch-implement`, and any agent driving the rail. The conductors execute these rules; this document owns them.
+
+- **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.
+- **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.
+- **`ready-for-agent` marks tickets, never specs.** The implementation loop's frontier is every open issue wearing that label, and it cannot tell prose from work — a spec or research note published to the tracker takes a different label (e.g. `spec`), or the loop will dispatch the document as work. Relabel before anyone starts the loop.
+- **Implementation is never started unprompted.** Stage 10 belongs to the user: conductors hand over `/launch-implement` and explain; they do not launch it.
+- **Everything the workflow produces is project-owned.** Vision, research, ADRs, specs, tickets — Launchrail tooling never overwrites them.
+- **Setup gaps are action, not conversation.** Known, additive fixes (commit untracked init output, run `init` when the manifest is missing, `sync` when loop materials are absent) get applied and reported; questions are saved for product artifacts, where intent is genuinely unknowable. Init owns installs — never improvise a dependency install from the web.
+
+## Stage-skipping by project mode
+
+The manifest's `mode` calibrates rigor, not stage order:
+
+- `spike` — stages 2–5 and 8 may be skipped deliberately; record the skip in the vision's non-goals.
+- `standard-mvp` — the default path; skip nothing silently.
+- `high-rigor` — no skips; ADRs for every stage-6 decision, and design validation covers error and edge states, not just happy paths.
+
+When a stage looks skipped, check the vision's non-goals before deciding whether it's deliberate — and if you still can't tell, ask.

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

@@ -0,0 +1,49 @@
+---
+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).
+---
+
+# Browser smoke testing
+
+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.
+
+## 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.

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.