@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/skills/launch/SKILL.md

@@ -0,0 +1,915 @@
+---
+tier: lite
+name: launch
+description: "Compare variants of an idea. Ships a mock gallery with an Anthropic baseline. You pick a direction from the phone. Get the spec plus user stories. Get the decomposition plus a migration plan. Two sizes: medium and full."
+problem: "An idea is a doc. A working feature is code. The gap in between is where projects stall."
+value: "Turns an idea into a buildable plan \u2014 mock gallery and spec and INVEST stories. Ready for /build."
+inputs: [A rough idea or ticket or canvas]
+outputs: [Clickable mock gallery, Buildable spec, INVEST user stories, GRASP responsibility matrix]
+user_invocable: true
+disable_model_invocation: false
+sizes: [medium, full]
+composes_baseline: anthropic-frontend-design
+---
+
+> **Baseline composition:** Bassclef's gallery + spec authoring composes on top of Anthropic's `frontend-design` skill defaults. Adopters firing plain Claude inherit those defaults; this skill extends with luminary-driven variant generation + buildable-spec pipeline + bassclef's design-discipline + operator-facing prose discipline.
+
+# /launch (formerly /preview-build) — Build-Tier Workflow (Construction Transition)
+
+End-to-end workflow for **build tiers** (medium + full). Takes
+operator input (paragraph OR a chosen variant from `/stage`'s
+output via `base=<slug>`) and produces a PR containing:
+
+1. **Deployed clickable gallery** of N+1 variants (luminary-driven +
+   Anthropic baseline), each variant page with back-nav to master
+   gallery — same UX continuity as `/stage`
+2. **Buildable spec** (Cockburn use-cases + IA model + interaction
+   design + GRASP responsibility matrix per Larman)
+3. **ux-migration plan** linking the chosen variant to the
+   production codebase
+4. **Scaffolded Construction iteration-goal draft** ready for operator
+   review + `/build-iteration` dispatch (bassclef#335 — follow-up goal)
+
+This is the skill that takes operator intent from "I picked a
+direction" to "Construction can scaffold against this spec." The
+output is the input contract for `/build-iteration` (the next-stage
+workflow that runs autonomous Construction).
+
+## ADR-consult — fire before scope confirmation (per bassclef-upstream#424)
+
+Read every relevant ADR in `architecture/decisions/` before confirming scope. If your scope deviates from any ADR's decision or constraints, surface the deviation as the first agenda item — operator decides amend-ADR vs. revise-scope.
+
+Per `.claude/rules/adr-discipline.md`. Mechanism: `adr-discipline-check.sh` fires on substantive architectural edits (wired in `.claude/settings.json` since bet 28a WU-1). The Tier 0 test for this step greps for the literal header `## ADR-consult — fire before scope confirmation` in each of `/build /launch /spec /decompose /shape /longrun`.
+
+## When to invoke
+
+- Operator picked a variant via `/stage <quick|light>` and is ready
+  to ship: `/launch medium "<paragraph>" base=<chosen-variant-slug>`
+- Operator dispatching directly without prototype tier (skip-the-bake-off
+  for known scope): `/launch medium "<paragraph>"`
+- Audit-grade for high-stakes surfaces: `/launch full "..."`
+- **Brownfield mode (bassclef#459 sub-goal 2)** — point at an existing
+  repo instead of writing a paragraph: `/launch medium --brownfield ~/src/your-org/your-app`
+  or `/launch medium --brownfield https://github.com/your-org/your-app`.
+  Phase 1 dispatches `/interpret-input --type=repo` (Phase C extractor)
+  which walks the codebase to populate entities, actors, routes, and
+  README excerpt. Downstream phases unchanged.
+
+## Phase boundary
+
+| Axis | `/stage` (sibling) | `/launch` (this skill) |
+|------|---------------------|------------------------------|
+| Phase | Inception / Elaboration | Construction transition |
+| Operator intent | "Pick a direction" | "Ship the chosen direction" |
+| Data substrate | Stubbed | Stubbed (variants) → real (post-build) |
+| Output type | Variants for visual selection | Variants + buildable spec + GRASP + ux-migration + iteration-goal draft |
+| Cameo review | /visual-review complement evaluators | Same + spec/decomp luminary review |
+| Commitment level | None — variants throwaway | Operator decides next: `/build-iteration` or pivot |
+| Compose-with | None upstream | Optional: `/stage` output via `base=<slug>` |
+
+## What this skill is NOT
+
+- **Not a Construction-execution skill.** This produces the spec; it
+  does NOT write production code. `/build-iteration` (bassclef#335)
+  consumes this skill's output to execute Construction.
+- **Not deploy-to-prod.** The deployed gallery uses the consumer's
+  prototype-friendly Amplify branch (per `bind-subdomain` adapter);
+  the production deploy happens via `/deploy-prod` after Construction
+  ships.
+- **Not the prototype-tier workflow.** Use `/stage` for quick + light.
+
+## Hard constraints (per goal rules)
+
+- **MUST produce a PR**, never push directly to main (per
+  `.claude/rules/branching.md` + `.claude/rules/pr-strategy.md`)
+- **MUST run on a feature branch** — refuses to run from main
+- **MUST capture champion-challenger signal** in `preview-state.yml`
+  (`selected_variant` + `is_baseline` per step-11b)
+- **MUST tolerate stub-mode InputArtifacts** (Phase B is text-strict;
+  other types produce `extracted_text="deferred to Phase C"`)
+- **MUST surface spec + decomposition + ux-migration** in the deployed
+  gallery so cameos (luminary-as-perspective via /visual-review;
+  future luminary-as-agent per roadmap Stage 3) can review by default
+- **MUST scaffold Construction iteration-goal draft** as final phase
+  (operator reviews; `/build-iteration` consumes)
+- **MUST validate spec output** against `decomposition.schema.json` +
+  `iteration-goal.schema.json` — state-validate.sh enforces
+
+## Procedure
+
+### Phase -1 — Pre-flight (per bassclef#408 + bassclef#449/#450)
+
+Source the shared pre-flight helper and surface all 6 prerequisites
+upfront. Pass `--no-launch` if the dispatch is variants-only (no
+`/launch-preview` chain expected); the deploy-host check (Check 6)
+short-circuits to pass.
+
+```bash
+source "${BASSCLEF_DIR:-$REPO_ROOT}/lib/composer-preflight.sh"
+
+# Detect variants-only dispatch (--no-launch flag from operator OR
+# variant-tier modes). Default is full chain (deploy-host required).
+NO_LAUNCH_FLAG=""
+case " $* " in
+  *" --no-launch "*) NO_LAUNCH_FLAG="--no-launch" ;;
+esac
+
+PREFLIGHT_OUTPUT=$(composer_preflight_check "launch" "${ESTIMATED_TURNS:-60}" "$NO_LAUNCH_FLAG")
+PREFLIGHT_RC=$?
+echo "$PREFLIGHT_OUTPUT" | composer_preflight_render "launch"
+
+case $PREFLIGHT_RC in
+  0) ;;                    # all checks pass — proceed to Phase 0
+  1)                       # warnings — operator decides proceed/abort
+    echo ""
+    echo "Pre-flight surfaced warnings. Proceed with caution OR abort and remediate."
+    echo "Override (logged): SKIP_COMPOSER_PREFLIGHT=1"
+    ;;
+  2)                       # failures — refuse dispatch
+    echo ""
+    echo "Pre-flight refused dispatch. Resolve fail-tier checks before re-running."
+    echo "Common fix: 'hosting_platform: amplify' missing from substrate.config.md? See bassclef#449."
+    echo "Variants-only run? Re-run with --no-launch to skip deploy-host check."
+    exit 1
+    ;;
+esac
+```
+
+Override: `SKIP_COMPOSER_PREFLIGHT=1` (logged). See
+`standards/composer-prerequisites.md` for the full contract.
+
+The 6 checks are feature-branch, state-spine, personas, budget,
+skill-registry, and deploy-host. See bassclef#271, #449, #450 for
+the race + hosting-platform edge cases.
+
+`--no-launch` skips the deploy-host check for design exploration.
+Default is the full chain (deploy-host required).
+
+### Phase 0 — Pre-flight
+
+Same as `/stage` — verify feature branch + lib/state.sh + parse args via `scripts/launch/parse-input-args.sh`. The parser distinguishes legacy text mode from brownfield mode (bassclef#459 sub-goal 2 — LR3 WU-2):
+
+```bash
+PARSE_OUT=$(bash "${BASSCLEF_DIR:-$REPO_ROOT}/scripts/launch/parse-input-args.sh" "$@") || exit $?
+
+TIER=$(echo "$PARSE_OUT" | jq -r .tier)
+INPUT_TYPE=$(echo "$PARSE_OUT" | jq -r .input_type)
+INPUT_SOURCE=$(echo "$PARSE_OUT" | jq -r .input_source)
+BROWNFIELD_FLAG=$(echo "$PARSE_OUT" | jq -r .brownfield_flag)
+LOCAL_MODE=$(echo "$PARSE_OUT" | jq -r '.local_mode // false')
+REUSE_ARTIFACT_PATH=$(echo "$PARSE_OUT" | jq -r '.reuse_artifact_path // ""')
+
+# Local mode announcement (bassclef#923 A2)
+if [ "$LOCAL_MODE" = "true" ]; then
+  echo "launch: local mode — artifacts to disk + localhost gallery preview; Phase 12 skips bind-subdomain" >&2
+fi
+
+# Reuse mode announcement (bassclef-upstream#716)
+if [ -n "$REUSE_ARTIFACT_PATH" ]; then
+  echo "launch: reuse mode — using pre-shaped InputArtifact at $REUSE_ARTIFACT_PATH; Phase 1 skips interpret-input dispatch" >&2
+fi
+
+# Tier-specific notes (parser already validated tier enum)
+case "$TIER" in
+  full) echo "launch: full tier ships per-persona analysis + /synthetic-user; ensure /personas defined for consumer repo" >&2 ;;
+esac
+
+# Brownfield announcement
+if [ "$BROWNFIELD_FLAG" = "true" ]; then
+  echo "launch: brownfield mode — input source is a repo (URL or local path); Phase 1 will dispatch /interpret-input --type=repo" >&2
+fi
+```
+
+**Usage forms:**
+
+```bash
+# Legacy text mode (paragraph input)
+/launch medium "Dramatically simplify deal display..."
+
+# Local mode (bassclef#923 A2) — writes all artifacts to disk + serves
+# the prototype gallery on localhost. No vendor accounts needed. Phase
+# 12 (bind-subdomain) is replaced with scripts/launch/local-serve.sh.
+/launch medium --local "build me a wiki app for sharing recipes with family"
+
+# Reuse mode (bassclef-upstream#716) — reuse a pre-shaped InputArtifact
+# from a prior chain instead of minting a fresh one. Phase 1 validates
+# the file against input-artifact.schema.json + copies to the sprint slot
+# + skips interpret-input.sh dispatch. Downstream phases run unchanged.
+/launch medium --local --reuse-artifact docs/input-artifacts/2026-07-11-697-onboarding-ux.json
+
+# Reuse mode with equals form
+/launch medium --reuse-artifact=docs/input-artifacts/2026-07-11-697-onboarding-ux.json
+
+# Brownfield mode — local repo path
+/launch medium --brownfield ~/src/your-org/your-app
+
+# Brownfield mode — GitHub URL (cloned to temp dir by /interpret-input)
+/launch medium --brownfield https://github.com/your-org/your-app
+
+# Equivalent --brownfield= form
+/launch medium --brownfield=https://github.com/your-org/your-app
+
+# Voice-input mode (Phase V Hey-Alexa MVD) — input text originated from
+# voice dictation (macOS Fn-Fn or equivalent); intent extraction uses
+# tolerant settings for spoken-text shape (looser grammar, lower
+# confidence threshold). See standards/voice-input-pattern.md.
+/launch medium --voice-input "build me a wiki app for sharing recipes with family"
+
+# Combining flags — local + voice (e.g. friendly dictates intent on a
+# laptop without vendor accounts)
+/launch medium --local --voice-input "build me a wiki app for ..."
+```
+
+**Local mode (`--local`) — bassclef#923 A2:**
+
+`/launch --local` prints a banner first. The banner shows which picker is active:
+
+```
+/launch --local — picker uses the LLM your Claude Code session provides.
+
+  ✓ full-catalog picking — /pick-luminaries runs against the harness LLM.
+                           This is the default.
+  ✓ signal fallback — if the picker call fails, Phase 4 falls back to
+                      /luminary recommend signal scoring.
+```
+
+No separate API key needed. The skill uses whichever LLM the harness provides. Tier is about catalog size, not keys. See bassclef-web#190 and #193 for the reframe.
+
+The banner ensures every adopter sees the same three-tier story
+whether they hit it at the wiki, the README, the /onboard-repo Path B
+prereqs, the prereqs-missing menu, the `lib/luminary-pick.sh` refusal
+output, or here.
+
+When the flag is set, the chain runs identically through Phases 1-11
+(all artifacts land on disk). Phase 12 swaps deploy for a local HTTP
+server:
+
+- Phase 12-alt dispatches `bash scripts/launch/local-serve.sh
+  docs/prototypes/<sprint-slug>/` — wraps `python -m http.server` bound
+  to `127.0.0.1`, finds an open port starting at 8000
+- Phase 13 (preview-state.yml) records `local_url` instead of
+  `bind_subdomain_url` per variant; the gallery URL is the one
+  surfaced to the operator
+- Phase 0 pre-flight skips Amplify + Cloudflare adapter checks when
+  `--local` is set
+- Operator stops the server later with
+  `bash scripts/launch/local-serve-stop.sh <sprint-slug>`
+
+Local mode is the demo path for adopters without vendor accounts —
+paragraph in, full artifact chain on disk, localhost preview.
+
+**Voice-input mode (--voice-input):**
+
+Per `standards/voice-input-pattern.md` + Phase V Hey-Alexa MVD goal (`docs/iteration-bets/2026-05-12-phase-v-hey-alexa-mvd.md`):
+
+- Input text originated from voice (macOS dictation or equivalent)
+- The text is treated as the operator's intent paragraph and flows through `/interpret-input` (Phase 1) like any other text input. Conversational-shape (fragments, restarts, filler) is preserved verbatim; downstream phases consume it the same as keyboard-typed text.
+- Existing text-mode + brownfield-mode behavior unchanged when flag absent
+- Composes with `--brownfield` (rare; voice-driven brownfield refactor is plausible but not the MVD path)
+
+### Phase 1 — `/interpret-input`
+
+Dispatches `/interpret-input` with the type detected by Phase 0. Text mode preserves the existing text-mode behavior; brownfield mode invokes the Phase C extractor (LR2 WU-1, bassclef#459 sub-goal 1) which walks the repo and populates structural hints (entities, actors, routes, README excerpt).
+
+```bash
+# Generate sprint slug + InputArtifact path
+SPRINT_SLUG="$(date -u +%Y-%m-%d)-$(printf '%s' "$INPUT_SOURCE" | md5 -q 2>/dev/null | cut -c1-6 || md5sum <<<"$INPUT_SOURCE" | cut -c1-6)"
+ARTIFACT_PATH="docs/input-artifacts/${SPRINT_SLUG}-input.json"
+
+if [ -n "$REUSE_ARTIFACT_PATH" ]; then
+  # Reuse pre-shaped InputArtifact (bassclef-upstream#716)
+  # Validate against schema first; fail fast on invalid input
+  SCHEMA_PATH="${BASSCLEF_DIR:-$REPO_ROOT}/standards/state-spine/schemas/input-artifact.schema.json"
+  if command -v ajv >/dev/null 2>&1; then
+    if ! ajv validate -s "$SCHEMA_PATH" -d "$REUSE_ARTIFACT_PATH" --spec=draft2020 --strict 2>&1; then
+      echo "launch: --reuse-artifact file failed schema validation: $REUSE_ARTIFACT_PATH" >&2
+      echo "launch: run 'ajv validate -s $SCHEMA_PATH -d <path>' for details" >&2
+      exit 1
+    fi
+  else
+    echo "launch: WARN — ajv not found; skipping InputArtifact schema validation" >&2
+  fi
+
+  # Copy the pre-shaped artifact to the sprint slot
+  mkdir -p docs/input-artifacts
+  cp "$REUSE_ARTIFACT_PATH" "$ARTIFACT_PATH"
+  echo "launch: copied pre-shaped artifact from $REUSE_ARTIFACT_PATH to $ARTIFACT_PATH" >&2
+else
+  # Dispatch /interpret-input with the right type
+  bash "${BASSCLEF_DIR:-$REPO_ROOT}/scripts/interpret-input.sh" \
+    "$INPUT_SOURCE" \
+    --type="$INPUT_TYPE" \
+    --persist \
+    --slug="${SPRINT_SLUG}-input"
+fi
+```
+
+Produces `InputArtifact` at `docs/input-artifacts/<sprint-slug>-input.json`. Downstream phases (`/objectory-decompose`, `/value-prop`, `/riff-prototypes`, etc.) consume the InputArtifact unchanged — the type and structural_hints are already populated by the right extractor.
+
+**Brownfield self-test:** dispatching against bassclef itself (`/launch medium --brownfield .` from bassclef's root) returns an InputArtifact whose `structural_hints.entities_seen` contains `skill`, `rule`, `agent`, `standard` — proves the chain is wired to the Phase C extractor.
+
+### Phase 2 — `/objectory-decompose` (full BCE matrix)
+
+Same as `/stage` Phase 2 — Jacobson method via `/objectory-decompose`.
+Output: `docs/decompositions/<slug>-domain.md` with entity inventory
++ actor list + verb-goal pairs + BCE matrix.
+
+**Distinction from `/stage`**: medium + full consume the FULL BCE
+matrix downstream (in /ia-model + /interaction-design + /decompose
+steps). Quick + light only consume the verb-goal pairs (for
+/value-prop input).
+
+### Phase 3 — `/value-prop` (brief mode for medium; verbose for full)
+
+```bash
+case "$TIER" in
+  medium) /value-prop --brief "<extracted_text>" ;;     # claim + 3 RTBs
+  full) /value-prop --verbose "<extracted_text>" ;;     # full Dunford/Moore positioning
+esac
+```
+
+### Phase 3b — Deeper persona work (medium + full only)
+
+Per roadmap §"Medium tier":
+
+```bash
+/personas               # primary persona (medium); all personas (full)
+/jtbd-tasks             # top jobs (medium); all jobs (full)
+case "$TIER" in
+  full) /value-prop-canvas <persona> ;;   # per primary; per all (full)
+esac
+```
+
+These outputs feed Phase 5's spec generation.
+
+### Phase 3.5 — `/pick-luminaries` (in-turn picker for variant grounding)
+
+Runs inside the current turn. Picks N luminaries whose lens fits the operator's intent. No separate LLM call. No provider key required. Per web#193 Option A rewrite.
+
+```bash
+source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+CATALOG=$(luminary_pick_catalog)
+```
+
+Now Claude (in-turn) reads `$intent_text`, enumerates `$CATALOG`, picks `$N_VARIANTS` slugs whose lens fits. Writes JSON to `/tmp/luminary-pick.json`:
+
+```json
+{
+  "matched_luminaries": ["slug1", "slug2", "slug3"],
+  "rationale": "One short sentence per pick",
+  "picker_version": "bassclef-harness-pick-2.0",
+  "provider": "claude-code-harness"
+}
+```
+
+If the catalog helper fails (missing catalog dir), Phase 4 falls back to `/luminary recommend` signal scoring. Bassclef-private adopters who load their own `/extract-intent` skill via `additionalDirectories` override this path with richer grounding.
+
+### Phase 4 — `/riff-prototypes` (with WU-11b Anthropic baseline)
+
+Same as `/stage` Phase 4 — N+1 variants (N luminary-driven + 1
+Anthropic baseline). Variant count by tier:
+
+| Tier | N (luminary) | Total (with baseline) |
+|---|---|---|
+| medium | 3 | 4 |
+| full | 3-5 | 4-6 |
+
+**Variant assignment from Phase 3.5.** Phase 4 reads `matched_luminaries` from Phase 3.5's output and assigns the N luminary-driven variants to those slugs. The Anthropic baseline always lands regardless. Operator can override per `/riff-prototypes --luminaries=...`.
+
+### Phase 5 — `/use-case` (Cockburn formalization, medium + full)
+
+Per roadmap §"Medium tier":
+
+```bash
+/use-case "<primary-actor>" "<primary-goal>"   # consumes /objectory-decompose verb-goal pairs
+```
+
+Produces formal use-case document at `docs/use-cases/<slug>-<goal>.md`.
+Full tier: one /use-case per primary goal (not just primary).
+
+### Phase 5b — `/user-stories` (INVEST backlog tokens, medium + full)
+
+Per bassclef#358 — closes the chain drift between /use-case and
+/launch. Slices /use-case main scenario + extensions into
+INVEST-validated user stories. Each story traces back to Persona →
+JTBD → VPC → Use-case line.
+
+```bash
+/user-stories from-use-case "<uc-slug>"   # slices the use-case from Phase 5
+```
+
+Produces user-story files at `docs/user-stories/US-NNN-<slug>.md` +
+traceability matrix at `docs/user-stories/_matrix.md`. Full tier:
+walk every primary use-case + every extension through INVEST.
+
+**Why this phase exists:** /launch's downstream consumer
+(`/build`, bassclef#335) ships in stacked atomic per-step PRs.
+INVEST's "Independent" + "Small" properties are exactly what makes
+each step safely mergeable in isolation. Without this phase, Phase 14's
+step enumeration is derived ad-hoc from /spec's acceptance criteria;
+not INVEST-validated. With this phase, step enumeration ARE the
+INVEST stories, with full traceability back to persona-level value.
+
+**Distinction from /use-case (Phase 5):** /use-case = system behavior
+spec ("what must the system do for this goal, including every
+extension?"). /user-stories = backlog tokens ("what to ship in what
+order, each independently shippable?"). Both feed downstream phases:
+/use-case → /interaction-design (renders flow); /user-stories → /spec
+(step enumeration) and /build (per-story Builder dispatch).
+
+### Phase 6 — `/ia-model` (entity inventory → nav structure)
+
+```bash
+/ia-model              # consumes /objectory-decompose entities
+```
+
+Output: `docs/ia-models/<slug>.md` — nav structure + labeling + screen
+map derived from BCE entities.
+
+### Phase 7 — `/interaction-design` (state + sequence diagrams)
+
+```bash
+/interaction-design    # consumes /ia-model + /use-case
+```
+
+Output: state diagrams + sequence diagrams in `docs/interaction-design/<slug>/`.
+
+### Phase 8 — `/decompose` (GRASP responsibility assignment)
+
+```bash
+/decompose             # consumes BCE matrix from /objectory-decompose + sequence diagrams from /interaction-design
+```
+
+Output: `docs/decompositions/<slug>-grasp.md` — GRASP responsibility
+matrix + interface identification + pattern selection (GoF/Fowler).
+
+### Phase 9 — `/spec` (build-ready specification)
+
+```bash
+/spec                  # composes /value-prop + /personas + /use-case + /user-stories + /ia-model + /interaction-design + /decompose
+```
+
+Output: `docs/specs/<slug>.md` — buildable specification ready for
+Construction. Includes:
+- Acceptance criteria (testable; one per /user-stories acceptance line)
+- Scope boundary (what's in / out)
+- Open questions (operator must resolve before Construction)
+- **`## Steps enumerated` section (REQUIRED, exact heading) per
+  bassclef#367** — derived from /user-stories output (bassclef#358).
+  Each story (US-NNN) maps to one `### WU-N` entry; the step's acceptance
+  criteria inherit from the story's. INVEST-validated by construction.
+  /build's Phase 1 parser greps for this exact heading.
+
+### Phase 10 — `/prototype-gallery` (with back-nav injection)
+
+Per `/prototype-gallery` SKILL.md §"Back-nav injection (bassclef#X)":
+each variant copy in `public/prototypes/<slug>/` gets a back-nav header
+injected at copy time. Master gallery includes:
+
+- All N+1 variants with luminary attribution
+- **Spec link** (`docs/specs/<slug>.md`) — visible to operator AND
+  cameos
+- **Decomposition link** (GRASP matrix) — same
+- **ux-migration link** — same
+- Champion-challenger flag on baseline variant
+
+The gallery is THE cameo-review surface. Luminary perspectives
+(today: /visual-review complement-evaluator pairs; future: luminary-as-
+agent runtime per roadmap Stage 3) consume the gallery + spec + decomp
+to produce reviews per perspective. Reviews surface in PR body.
+
+### Phase 11 — `/ux-migration` (chosen variant → production migration plan)
+
+```bash
+/ux-migration <chosen-variant-slug>   # if base= provided, use that; else operator chooses post-gallery
+```
+
+Output: `docs/specs/ux-migration-<slug>.md` — token extraction +
+prototype-HTML→React mapping table + work packages with dependency-aware
+build order.
+
+This is the `/ux-migration` MUST gate per existing prototype-variants
+SKILL.md §"Step 7 — Selection → pipeline to Construction".
+
+### Phase 12 — Deploy or local-serve (mode-gated)
+
+**When `LOCAL_MODE != true` (extended / default):** `/bind-subdomain`
+per variant + master gallery. Same as `/stage` Phase 6, but ALSO bind
+the master gallery itself to a subdomain (e.g.,
+`gallery-<sprint-slug>.<consumer-domain>`). Each variant URL includes
+back-nav to master gallery URL. Best-effort per existing convention —
+failures don't fail the chain.
+
+**When `LOCAL_MODE == true` (bassclef#923 A2):** skip bind-subdomain
+entirely. Dispatch `scripts/launch/local-serve.sh` against the gallery
+directory. Capture the localhost URL:
+
+```bash
+LOCAL_URL=$(bash "${BASSCLEF_DIR:-$REPO_ROOT}/scripts/launch/local-serve.sh" \
+  "docs/prototypes/${SPRINT_SLUG}/")
+
+if [ -z "$LOCAL_URL" ]; then
+  echo "launch: local-serve failed to start; gallery artifacts still on disk at docs/prototypes/${SPRINT_SLUG}/" >&2
+  # Don't fail the chain — disk artifacts are the load-bearing output
+else
+  echo "launch: local gallery at ${LOCAL_URL}" >&2
+fi
+```
+
+Per-variant URLs in local mode all point at the same localhost root
+(path-based per ADR-016 prototype-gallery-url-pattern). No DNS, no
+TLS, no Amplify, no Cloudflare. Stop the server later with
+`scripts/launch/local-serve-stop.sh <sprint-slug>`.
+
+### Phase 13 — Persist preview-state.yml (build-tier shape)
+
+```yaml
+# docs/preview-state/<sprint-slug>.yml
+slug: <sprint-slug>
+input_artifact: <sprint-slug>-input
+decomposition: <sprint-slug>-domain
+spec: <sprint-slug>          # NEW vs /stage
+grasp: <sprint-slug>-grasp   # NEW vs /stage
+ux_migration: ux-migration-<sprint-slug>  # NEW vs /stage
+status: build-ready          # NEW vs /stage's "variants-ready"
+current_tier: medium  # or full
+luminaries_used: [...]
+current_variants:
+  - name: variant-a-<luminary>
+    is_baseline: false
+    bind_subdomain_url: ...
+  - name: variant-baseline-anthropic
+    is_baseline: true
+    bind_subdomain_url: ...
+selected_variant: <if base= provided, that; else null pending operator pick>
+created_at: <ISO timestamp>
+created_by_session: <session-id>
+```
+
+`status: build-ready` is the operator-readable signal that Construction
+can begin. `/build-iteration` (bassclef#335) refuses to run if
+status != build-ready.
+
+### Phase 14 — Scaffold Construction iteration-goal draft
+
+```yaml
+# docs/iteration-bets/<YYYY-MM-DD>-<sprint-slug>-construction.md (DRAFT)
+---
+slug: <YYYY-MM-DD>-<sprint-slug>-construction
+phase: Construction
+status: draft   # operator must change to "active" before /build-iteration runs
+parent_roadmap: docs/roadmaps/<roadmap-slug>.md  # if known
+parent_canvas: <if known>
+parent_bet: <launch's own goal, if part of one>
+preview_state: docs/preview-state/<sprint-slug>.yml
+spec: docs/specs/<sprint-slug>.md
+ux_migration: docs/specs/ux-migration-<sprint-slug>.md
+decomposition: docs/decompositions/<sprint-slug>-grasp.md
+references:
+  - {type: spec, id: <sprint-slug>}
+  - {type: decomposition, id: <sprint-slug>-grasp}
+  - {type: input-artifact, id: <sprint-slug>-input}
+appetite:
+  mode: scope-bounded
+  estimated_turns: <derived from /spec step enumeration>
+  stopping_criteria:
+    - All step PRs filed (count from spec)
+    - Operator merges + CI green
+    - /deploy-prod dispatches successfully
+---
+
+## Sources read
+
+- spec: docs/specs/<sprint-slug>.md
+- decomposition: docs/decompositions/<sprint-slug>-grasp.md
+- ux-migration: docs/specs/ux-migration-<sprint-slug>.md
+- preview-state: docs/preview-state/<sprint-slug>.yml
+- input-artifact: docs/input-artifacts/<sprint-slug>-input.json
+
+## What I'm NOT reading (with reason)
+
+- (operator fills in if specific exclusions apply)
+
+## Iteration Goal — Construction of <slug>
+
+**Phase**: Construction
+
+**Scope**:
+(operator reviews + tightens; spec is the source of truth)
+
+**Risk being retired**:
+(derived from spec acceptance criteria)
+
+**Business value being proven**:
+(derived from /value-prop output)
+
+**Lovability signal**:
+(derived from chosen variant's luminary signature + /value-prop)
+
+**Viability signal**:
+(derived from /spec acceptance criteria; operator confirms)
+
+**Appetite**:
+(derived from spec step enumeration; operator finalizes)
+```
+
+This is a DRAFT — operator reviews, edits, commits status:active. Then
+`/build-iteration <slug>-construction` dispatches Builder agent.
+
+### Phase 14b — Completion handoff (bassclef#941)
+
+Two templates — adopter-mode and operator-mode. Default is adopter when `--local` is set; operator-mode for non-local dispatches (which assume operator workflow with consumer repo + iteration goal ceremony).
+
+#### Adopter-mode completion (default for `--local`)
+
+After Phase 12-alt (`local-serve.sh` running) + Phase 13 (preview-state.yml on disk), emit this template directly to the adopter — no YAML edits, no frontmatter flip, no command-soup:
+
+```
+I made you N directions for your family recipe wiki. Walk through them on
+your phone or laptop at <LOCAL_URL> and tell me which one feels right.
+
+When you've picked, just tell me — "I like variant 2" or "#3 looks
+great".
+
+Here's what happens next:
+
+1. I'll write the formal artifacts for your chosen direction only:
+   - The use case — what the app does step-by-step (Cockburn style)
+   - The user stories — the small, shippable slices ("I want to add a
+     recipe", "I want to tag recipes for weeknight dinners", etc.)
+   - The information architecture — the screens, the nav, where each
+     screen lives
+   - The interaction design — what happens when you click each thing
+   - The responsibility map — which code module owns what
+   - The build spec — the checklist your app code is measured against
+   - The migration plan — how to ship it step by step
+2. Then I'll write the actual app code — add, edit, search, tag, the
+   whole thing — using those artifacts as the checklist.
+3. You'll get a working local version to play with in about 15 minutes.
+
+You're seeing N directions BEFORE I write any of those formal artifacts
+because the cheap-vs-expensive trade-off is real:
+
+- The variants you're looking at are CHEAP — same data shape, four
+  visual treatments, about 4 minutes total. Showing you four lets you
+  pick the right direction before I invest.
+- The formal write-up (use cases, user stories, IA, interaction design,
+  GRASP, spec, migration plan) is EXPENSIVE — 10-15 minutes per
+  direction. Running that seven times would burn an hour.
+- So: cheap first → you commit → expensive run, once, for the direction
+  you picked.
+
+If any depth-link inside a variant says "coming after you pick" — that's
+the contract. The link materializes once you've picked.
+
+None of them feel right? Tell me what's off and I'll generate new
+directions for you. (See /launch --refine, bassclef#942.)
+```
+
+Substitute `<LOCAL_URL>` with the URL returned by Phase 12-alt. Substitute the actual variant count (`I made you N directions...`). Substitute the actual app description (`your family recipe wiki` etc.) from the InputArtifact's `intent` field.
+
+The adopter-mode template **surfaces** (per bassclef#969):
+- The formal artifacts the chain will produce post-pick, in plain English (use case, user stories, IA, interaction design, responsibility map, build spec, migration plan)
+- The chain-ordering rationale (variants are cheap shared data; formal artifacts are expensive per-direction; cheap first → commit → expensive once)
+- The depth-link "coming after you pick" contract (per bassclef#971)
+
+The adopter-mode template **skips entirely**:
+- The DRAFT iteration-goal review framing (Sam doesn't review goals).
+- The `selected_variant:` YAML edit instruction.
+- The `status: draft → status: active` frontmatter flip instruction.
+- The bare `/build <slug>-construction` command name.
+
+#### Natural-language variant selection (talk-to-pick)
+
+Agent listens for the adopter's variant selection in natural language and auto-handles the YAML + frontmatter mechanics. Recognized phrases (case-insensitive, fuzzy):
+
+- "I like variant N" / "variant N" / "#N" / "the Nth one" / "number N"
+- "the cozy one" / "the minimal one" / "the bold one" — fuzzy-matches against variant names or luminary signatures in the gallery
+- "let's go with the first" / "the second" / "the last"
+
+When matched, the agent automatically:
+
+1. Updates `selected_variant: <N or slug>` in `docs/preview-state/<sprint-slug>.yml`
+2. Flips iteration-goal frontmatter `status: draft → active` in `docs/iteration-bets/<sprint-slug>-construction.md`
+3. Surfaces the /build dispatch with plain-English framing (per bassclef#943 — `/build` adopter-mode framing)
+
+The adopter never sees the YAML or frontmatter mechanics. The agent confirms in plain English:
+
+```
+Got it — going with the cozy notebook direction (variant 2). I'll start
+writing your app code now. About 15 minutes.
+```
+
+#### Operator-mode completion (non-`--local` or operator override)
+
+Today's YAML-edit + frontmatter-flip + bare command path stays available verbatim for operator workflows where the YAML surface is the convenient pick mechanism (scripts, batch processing, multi-variant comparisons):
+
+```
+Your next actions, in order
+
+1. Walk the gallery → pick a variant on your phone or laptop.
+2. Edit selected_variant: in docs/preview-state/<slug>.yml.
+3. Flip the iteration-goal frontmatter status: draft → status: active.
+4. Run /build <slug>-construction — Builder dispatches per step.
+
+Skipped vs full /launch chain (available if you want depth):
+- /use-case (Cockburn formalization)
+- /user-stories (INVEST backlog tokens)
+- /decompose (GRASP responsibility audit)
+```
+
+Operator-mode also surfaces the natural-language listener path as a convenience — operators can talk-to-pick too if they prefer.
+
+#### Mode selection
+
+```
+if "--local" flag is set:
+  mode = "adopter"
+else:
+  mode = "operator"
+
+# Operator can force adopter-mode for demos via --adopter-mode flag (V2).
+# Operator can force operator-mode in a --local context via --operator-mode flag.
+```
+
+#### Refine path (bassclef#942 — "none of these feel right")
+
+When the adopter walks the 4 variants and none feel right, the agent listens for refinement cues and re-runs Phase 4+ with refined intent. Two entry paths.
+
+**Natural-language listener (default in adopter mode).** Recognized phrases (case-insensitive, fuzzy):
+
+- "none of these feel right"
+- "none feel right"
+- "they all feel too X" (cold / busy / corporate / glossy / minimal)
+- "I want something more X"
+- "can you try again"
+- "let me see other options"
+- "I don't love any of these"
+
+When matched, the agent asks one short follow-up if the cues don't include a specific direction:
+
+```
+What's off? Too busy? Too cold? Missing something specific?
+```
+
+The adopter's answer becomes the refinement intent. Agent captures it into the InputArtifact's new `refinement_passes` array (schema field added at `standards/state-spine/schemas/input-artifact.schema.json`).
+
+**Explicit flag form (operator convenience):**
+
+```bash
+/launch --refine "make them feel more like a worn cookbook, less like an app"
+```
+
+The `--refine` flag carries the refinement intent directly without the conversational round-trip. Operators in scripted workflows prefer this.
+
+**Refinement execution.** Once refinement intent is captured:
+
+1. Agent appends the refinement intent to the original intent paragraph (preserves lineage; doesn't replace the original)
+2. Re-dispatches `/pick-luminaries` (Phase 3.5) — fresh LLM pick reads the combined intent + refinement context, picks different luminaries than the prior pass
+3. Re-dispatches Phase 4 (`/riff-prototypes`) — generates a new gallery with the refined picks
+4. Emits the gallery at the same `LOCAL_URL` (overwriting prior `current_variants` in `preview-state.yml`, OR writing to a new sub-path like `/refine-1/` per implementation choice)
+
+**InputArtifact lineage.** Each refinement pass records:
+
+```json
+{
+  "refinement_passes": [
+    {
+      "intent": "make them feel more like a worn cookbook, less like an app",
+      "timestamp": "2026-06-13T13:15:00Z",
+      "generated_variants": ["variant-paula-scher", "variant-ellen-lupton", "variant-jenifer-tidwell"],
+      "selected_after_refine": null
+    },
+    {
+      "intent": "still too crisp; try warmer, more handwritten",
+      "timestamp": "2026-06-13T13:24:00Z",
+      "generated_variants": ["variant-edward-tufte", "variant-eric-meyer", "variant-don-norman"],
+      "selected_after_refine": 2
+    }
+  ]
+}
+```
+
+The lineage preserves what was tried + which variant finally won.
+
+**3-pass cap.** After 3 refinement passes, the agent surfaces a step-back prompt:
+
+```
+We've tried 3 directions. Want to step back and rethink the intent
+paragraph itself? Or pick the closest variant we've generated so far
+and refine the details in /build?
+```
+
+This prevents infinite-loop refinement. The cap is configurable via `--refine-cap N` flag (default 3) for operators who want longer runs.
+
+**Composes with completion handoff.** Refined gallery uses the same adopter-mode completion template (`I made you 4 directions for your family recipe wiki...`); the natural-language pick listener still applies after refinement.
+
+### Phase 15 — Open PR
+
+PR body includes:
+- All variant URLs (with back-nav to gallery)
+- Master gallery URL
+- Spec / GRASP / ux-migration links (visible for cameo review)
+- Champion-challenger ratio summary
+- Construction iteration-goal draft path (operator's next action)
+- Bind-subdomain status per variant
+
+PR body MUST surface: "Operator's next action: review the Construction
+iteration-goal draft at <path>; if approved, run `/build-iteration
+<slug>-construction` (bassclef#335)."
+
+## Tier behavior (BUILD-only; `/stage` for prototype tiers)
+
+| Tier | Phase B MVP | Status |
+|---|---|---|
+| `quick` | ❌ Refused — use `/stage quick` | redirected |
+| `light` | ❌ Refused — use `/stage light` | redirected |
+| `medium` | ✅ Full chain (Phases 1-15). 3 variants + Anthropic baseline + buildable spec + GRASP + ux-migration + Construction iteration-goal draft. ~1 day wall time. | Phase B MVP scope |
+| `full` | ✅ Same as medium + per-persona /value-prop-canvas + per-goal /use-case + /synthetic-user pair-embodiment validation. 3-5 variants + audit-grade spec. ~3 days wall time. | Phase B MVP scope (full tier ships in same skill; differs by Phase 3b + variant count + /synthetic-user) |
+
+## Failure modes (Phase B MVP scope)
+
+Same baseline as `/stage` PLUS:
+
+| Failure | Behavior |
+|---|---|
+| `/use-case` produces empty extension list | Proceed; warn that spec may be too thin for Construction |
+| `/spec` validation fails (missing required acceptance criteria) | BLOCK; fix or operator override |
+| `/ux-migration` fails (no design tokens, no variant chosen) | BLOCK; require operator pick variant via `base=<slug>` first |
+| Construction iteration-goal draft frontmatter doesn't validate | BLOCK; state-validate.sh hook surfaces missing fields |
+
+## Rules
+
+- **PR-first, always** — same as `/stage`
+- **All state writes through accessor** — same as `/stage`
+- **Stub-mode tolerance** — same as `/stage`
+- **Champion-challenger captured** — `is_baseline` flag preserved
+- **Best-effort bind-subdomain** — same as `/stage`
+- **Spec + decomp + ux-migration always surfaced in gallery** —
+  cameo-review-by-default; non-negotiable
+- **Construction iteration-goal draft is a DRAFT** — operator MUST
+  review + commit status:active before `/build-iteration` runs
+
+## Skipping / Aborting
+
+- Same as `/stage`, plus:
+- Spec validation failure: BLOCK; operator fixes via /spec re-run
+- ux-migration step fails (no chosen variant): operator must run with
+  `base=<slug>` OR pick winner via gallery review
+
+## Relationship to other skills + standards
+
+- `/stage` — sibling (prototype tiers; same input-handler interface)
+- `/interpret-input` — Phase 1 producer (same as `/stage`)
+- `/objectory-decompose` — Phase 2 producer (same as /stage)
+- `/value-prop` — Phase 3 producer (different mode by tier)
+- `/personas`, `/jtbd-tasks`, `/value-prop-canvas` — Phase 3b
+- `/riff-prototypes` (with WU-11b baseline) — Phase 4
+- `/use-case` — Phase 5 (Cockburn formalization)
+- `/user-stories` — Phase 5b (INVEST backlog tokens, bassclef#358) — slices /use-case into stories that drive Phase 14's step enumeration
+- `/ia-model` — Phase 6 (entity → nav)
+- `/interaction-design` — Phase 7 (state + sequence)
+- `/decompose` — Phase 8 (GRASP)
+- `/spec` — Phase 9 (build-ready specification)
+- `/prototype-gallery` (with back-nav injection) — Phase 10
+- `/ux-migration` — Phase 11 (chosen variant → production)
+- `/bind-subdomain` — Phase 12 (deploy variants + gallery)
+- `/synthetic-user` — Phase 4b (full tier only)
+- `/build` (bassclef#335; renames from `/build-iteration` per bassclef#359) — DOWNSTREAM consumer; takes Construction iteration-goal draft (with INVEST step enumeration from /user-stories) + dispatches Builder agent per step
+- `/deploy-prod` — DOWNSTREAM final stage (after Construction)
+
+## What this skill enables (post-merge)
+
+```bash
+# Operator dispatches from phone:
+cd ~/src/your-org/your-app
+/launch medium "Dramatically simplify and delightfully surface deals..."
+
+# OR escalate from /stage output:
+/launch medium "..." base=<your-variant-slug>
+```
+
+Chain runs (~1 day for medium; ~3 days for full), opens PR with:
+- Deployed clickable gallery (variants + back-nav)
+- Buildable spec
+- GRASP responsibility matrix
+- ux-migration plan
+- Construction iteration-goal DRAFT
+
+Operator reviews on phone. If approved, runs `/build-iteration
+<draft-slug>` (bassclef#335) which dispatches Builder agent →
+step PRs → CI → /deploy-prod. Ends at functioning app in prod.
+
+This is the Construction-transition step in the
+"talking-out-loud → functioning app in prod" chain.
+
+## Enforcement
+
+Methodology-level. State-validate.sh hook enforces preview-state.yml
++ iteration-goal.schema.json validation. PR-first discipline enforced
+via branching.md rule + pre-build-gate hook. No additional hook
+enforcement added.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on output. See `standards/skill-output-discipline.md`.