skillpacks 0.1.1 → 0.1.2

package/packs/product-design/codex/user-flow-map/archive/v0.5/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: user-flow-map
+description: Turn a high-level product concept, positioned goal, or goal sequence into screen flow structure with entry points, decisions/actions/states, branches, failure paths, and low-fidelity wireframe guidance before UI/spec/prototype work
+type: planning
+version: v0.5
+argument-hint: "[optional: product, flow, feature, route, or goal]"
+context_intake: deep
+visual_tier: prototype
+---
+
+## Pack Availability Guard
+
+Before telling the user to run a skill from another project-local pack, check `.agents/project.json.enabled_packs`. If the target pack is not enabled, recommend `npx skillpacks install <pack>` from the project shell, instead of the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.
+
+# User Flow Map
+
+Invoke as `$user-flow-map`.
+
+Use this skill after positioning and before UX/UI/prototype work when a product, feature, or goal sequence needs concrete user-flow structure: entry points, screens/routes, actions, decisions, branches, states, failure paths, handoffs, and low-fidelity wireframe notes. Treat the output as the root of a wireframe tree: each mapped user flow can fan out into `$ux-variations [flow]`, where the team explores alternate ways users can progress through that specific flow before any one variation is promoted into `$ui-interview`.
+
+This skill does not create polished UI, visual styling, production specs, or runnable prototypes. Keep layout and styling out of scope except for wireframe-level structural notes such as "summary panel beside task list" or "confirmation step before destructive action." Do not flatten the tree into a single UI requirements path; preserve named user flows as branch roots for downstream variation work.
+
+## Process
+
+### 0. Product-Path Scope Resolution
+
+Resolve research scope by product path before using code or app structure as a hint:
+
+1. If `$ARGUMENTS` names a non-archived `research/{slug}/` directory or a product-path ID whose `scope_path` points there, use that path. Treat `{slug}` as the product/app name, not the ICP, audience, or segment label.
+2. If `$ARGUMENTS` names only `research/_archive/{slug}/` or a manifest entry with `status: archived` or legacy `status: abandoned`, stop and warn that the path is archived; do not write or update scoped outputs there.
+3. Read `research/.progress.yaml` when present. Normalize legacy `active_path` to `active_paths` on read and write back `active_paths` on manifest updates. Treat legacy `abandoned` as `archived`; exclude `archived`, `abandoned`, `deferred`, `revisit_candidate`, `promoted`, and any `scope_path` under `research/_archive/` from active target selection.
+4. If active product paths exist in the manifest, use those paths. If multiple active paths exist, ask which one to target unless this skill explicitly supports cross-path output.
+5. If no active manifest target exists, list non-archived product directories under `research/`, excluding `research/_archive/` and dot directories. Auto-select only when exactly one exists; ask when multiple exist.
+6. If no product directories exist, use flat `research/` single-product mode.
+7. Detect monorepo/app/package structure only as a secondary hint. Suggest creating a missing `research/{slug}/` product path when code clearly exposes an app, but do not require code or monorepo detection before using `research/{slug}/`.
+
+When product path `{slug}` is active, read and write research under `research/{slug}/`, specs under `specs/{slug}/`, and treat top-level `research/*.md` files as flat-mode documents or cross-path summaries.
+
+### 1. Resolve Context
+
+Read available evidence before asking deep questions:
+
+- `.agents/project.json`, `AGENTS.md`, `CLAUDE.md`, `README.md`, and relevant task docs.
+- `research/idea-brief.md`, `research/icp.md`, `research/competitive-analysis.md`, `research/journey-map.md`, `research/positioning.md`, and product-path-scoped equivalents.
+- Existing `specs/`, including `specs/user-flow-*.md`, `specs/ui-requirements-*.md`, `specs/ui-*.md`, and `specs/ux-variations-*.md`.
+- Existing route files, component files, app shells, navigation config, screenshots, wireframes, mockups, and design artifacts when present.
+
+If `research/positioning.md` is missing for a business-product flow, recommend `$positioning` first. If `product-design` is not enabled, recommend `npx skillpacks install product-design` from the project shell.
+
+### 2. Flow Assumptions Checkpoint
+
+Before deep probing, present a concise **Flow Assumptions Checkpoint** inline as the final message text of its own turn — never only as mid-turn text in a turn that ends with a tool or command call — then ask the user to confirm, correct, or flag it in the next turn. Tag each assumption with `[from idea]`, `[from research]`, `[from positioning]`, `[from journey]`, `[from spec]`, `[from codebase]`, `[from artifact]`, or `[inferred]`.
+
+Cover:
+
+- Persona, role, and goal.
+- Entry points and triggers.
+- First success or completion condition.
+- Happy path sequence.
+- Alternate paths and branch points.
+- Decisions the user or system must make.
+- Screens/routes likely required.
+- Actions per screen.
+- States to represent: empty, loading, error, partial, success, permission-denied, offline, validation, and edge states.
+- Failure and recovery paths.
+- Cross-role, cross-device, external-system, or manual handoffs.
+- Flow boundaries and explicit non-goals.
+
+Do not proceed until the user has reviewed the checkpoint. If the user confirms it as-is, continue. If they correct an assumption, carry the correction into both deliverables.
+
+### 3. Map The Flow
+
+Build the flow map at workflow level, not visual-design level:
+
+1. Define the primary persona, goal, success condition, and triggering context.
+2. List every entry point and precondition.
+3. Write the happy path as ordered steps with the screen/route used by each step.
+4. List alternate paths, including optional setup, skip paths, backtracking, cancellation, save-for-later, review/edit, and escalation.
+5. List decision points and branch rules. Distinguish user decisions, system decisions, permissions decisions, and external/manual decisions.
+6. Create a screen/route inventory with purpose, inputs, outputs, source evidence, and downstream destination.
+7. For each screen, list required actions, available navigation, disabled/blocked rules, validation rules, and state coverage.
+8. Map failures and recovery: invalid input, no data, permissions, lost connection, backend failure, timeouts, interrupted work, and contradictory user choices.
+9. Map handoffs across roles, devices, systems, documents, notifications, approvals, payments, support, or manual operations.
+10. Add low-fidelity wireframe notes for each screen: rough regions, primary/secondary content, key controls, data groupings, progressive disclosure, and fixed/sticky elements only when structurally necessary.
+
+### 4. Coverage Checkpoint
+
+Before writing deliverables, present a **Flow Coverage Checkpoint** inline as the final message text of its own turn (never only as mid-turn text before a tool or command call):
+
+- Persona and goal covered.
+- Entry points covered.
+- Happy path covered.
+- Branches and decision points covered.
+- Screen/route inventory covered.
+- Actions per screen covered.
+- Required states covered.
+- Failure/recovery paths covered.
+- Handoffs covered.
+- Wireframe-level notes covered.
+- Layout/styling non-goals preserved.
+
+In the next turn, ask whether any flow branch, state, or handoff is missing before writing.
+
+## Deliverables
+
+Write:
+
+- `specs/user-flow-[topic].md`
+- `user-flow-[topic]-interview.md`
+
+The user-flow spec must include:
+
+- Scope, source evidence, and assumptions checkpoint.
+- Persona, goal, and success condition.
+- Entry points and preconditions.
+- Happy path.
+- Alternate paths and branches.
+- Decision-point table.
+- Screen/route inventory.
+- Per-screen action/state matrix.
+- Failure and recovery paths.
+- Handoffs and external/manual dependencies.
+- Low-fidelity wireframe notes per screen.
+- Open questions, risks, and explicit non-goals.
+- Downstream handoff choices for `$ux-variations [specific-user-flow]`.
+
+The interview log must include:
+
+- Evidence consulted.
+- The Flow Assumptions Checkpoint and user corrections.
+- Questions asked, options presented, recommendations, and user responses.
+- Flow Coverage Checkpoint and remaining gaps.
+
+After approved files are written, present this handoff choice instead of auto-running or auto-invoking the next skill:
+
+1. Stop here so the user can clear context and run `$ux-variations [specific-user-flow]` in a fresh session.
+2. Continue immediately in this session with `$ux-variations [specific-user-flow]` for the first unresolved user-flow branch.
+
+If the user chooses to continue immediately, the next skill must still execute its own required interaction gates. `user-flow-map` approval authorizes the wireframe-tree root and provides source evidence; it does not approve any UX variation branch, visual mockup, UI proposal, or implementation path.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/user-flow-map-{topic}.html`.
+
+## Archive-First Replacement Policy
+
+- Before replacing or substantively rewriting an existing canonical research/spec document (`research/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
+- Preserve the archived snapshot exactly as it existed before the change; do not edit the archived copy after creating it.
+- After the archive snapshot exists, write the updated document to the original canonical path.
+- Report both the archive path and the updated canonical path in the final output.
+- New files do not need archive snapshots. Append-only updates do not need archive snapshots unless an existing section is regenerated or rewritten.
+
+## Constraints
+
+- Keep this skill before UX variation, UI layout, and prototype work in the AFPS route.
+- Do not produce high-fidelity mockups, component styling, color palettes, design systems, production architecture, database schemas, or implementation plans.
+- Do not collapse branches or states into generic "standard flow" language. Name each branch/state or mark it explicitly out of scope.
+- Do not route directly to `$ui-interview` from an approved flow map unless the user explicitly bypasses variation exploration for a named flow. The normal route is `$user-flow-map` -> `$ux-variations [specific-user-flow]` -> `$ui-interview [specific-ux-variation]`.
+- Do not auto-run or auto-invoke downstream skills after approval. Present the stop/clear-context versus continue-now choice, and preserve the next skill's required gates either way.
+- When recommending a skill from another pack, verify pack availability through `.agents/project.json.enabled_packs`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/product-design/codex/ux-variations/ALIGNMENT-PAGE.md

@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-ux-variations-research.md`; product-path mode uses `research/{slug}/_working/preliminary-ux-variations-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-ux-variations-research.md`; product-path mode uses `research/{slug}/_working/preliminary-ux-variations-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Variation-specific gates.** Render surfaced assumptions, variation manifest, concept selection, evaluation method, fixed-versus-variable scope, output-location/change-scope decisions, and coverage checkpoint as gates before writing final variation plans. Apply the shared artifact-destination/proposed-file-changes de-duplication rule: combine them into one visual gate when they ask only the same path-destination question, and render separate gates when destination approval differs from downstream mutation scope, timing, or allowed files.
 

package/packs/product-design/codex/ux-variations/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.19 - 2026-06-13
+
+- Moved pre-prototype UX variation plans and interview logs from `specs/` to `design/`.
+- Updated default and layout-mode inputs to read `design/user-flow-*`, `design/ui-requirements-*`, and scoped flow-tree manifests.
+- Required ordinary UX branch status to live in the design flow-tree manifest, with `research/.progress.yaml` reserved for materially different product paths.
+
+## v0.18 - 2026-06-12
+
+- Reframed default `ux-variations` work as expanding one selected user flow into alternate progression branches before UI proposal work.
+- Preserved `--layout-mode` as an explicit bounded mode for fixed flow/content contracts, while routing default progression branches to `$ui-interview [specific-ux-variation]`.
+- Added branch-routing deliverable guidance covering parent flow, sibling flow/variation dependencies, and next UI-interview branch.
+
+## v0.17 - 2026-06-12
+
+- Standardized active pack and skill install guidance on `npx skillpacks install <pack-or-skill>` instead of agent-native `/pack install` or `$pack install` recommendations.
+
 ## v0.16 - 2026-06-11
 
 - Added npm-aware install-route wording for product-testing recommendations while preserving Codex `$pack install ...` routes.

package/packs/product-design/codex/ux-variations/SKILL.md

@@ -2,7 +2,7 @@
 name: ux-variations
 description: Interview and plan multiple UX and UI variations for a product, page, or flow, including onboarding, typical workflows, sharing, collaboration, return use, and interface alternatives users can compare before locking a direction — and concrete visual/layout UI variations with UAT before consolidation
 type: planning
-version: v0.16
+version: v0.19
 argument-hint: "[optional: app, page, flow, feature, or existing UI spec]"
 visual_tier: prototype
 ---
@@ -11,13 +11,13 @@ visual_tier: prototype
 
 Invoke as `$ux-variations`.
 
-Use this skill when the user wants to explore multiple UX/UI directions before committing to a final experience. This skill interrogates the full user journey: onboarding, first success, typical workflows, sharing and collaboration, return use, notifications, handoffs, failure recovery, and the interface patterns that support those moments. It then creates variation plans for flows, layouts, navigation models, interaction patterns, component choices, content density, visual tone, and behavior so the user can compare, test, and lock one direction.
+Use this skill when the user wants to explore multiple UX/UI directions before committing to a final experience. In the default product-design tree, this skill expands one specific user flow from `$user-flow-map` into alternate progression branches: different ways users can enter, advance, recover, hand off, complete, or abandon the flow. It then creates variation plans for flow progression, layout implications, navigation models, interaction patterns, component choices, content density, visual tone, and behavior so the user can compare, test, and decide which branch should move into `$ui-interview`.
 
-In the normal AFPS product route, use `$user-flow-map` first to lock screen flow, decisions, branches, states, and low-fidelity wireframe notes, then use `$ui-interview --requirements-only` to lock the per-screen content/data/action contract, then run `$ux-variations --layout-mode`.
+In the normal AFPS product route, use `$user-flow-map` first to establish the wireframe-tree root and name the user-flow branches. Then run `$ux-variations [specific-user-flow]` to explore alternate ways users can progress through that selected flow. After a variation branch is ready for UI treatment, route that branch to `$ui-interview [specific-ux-variation]` for visual mockup, alignment, approval/rejection, and next-branch routing.
 
-Use `$user-flow-map` first when the interface has no credible flow structure. Use `$ui-interview --requirements-only` first when the flow exists but the page content, actions, and states are not specified. Use this skill directly only when a user-flow map plus UI requirements, current implementation, screenshot, prototype, or clear feature scope already exists.
+Use `$user-flow-map` first when the interface has no credible flow structure. Use this skill directly only when a user-flow map, current implementation, screenshot, prototype, explicit user prompt, or clear feature scope already identifies the flow being varied. Do not require a finalized UI requirements spec before default UX variation work; the point is to compare alternative progression paths before a single branch becomes a UI proposal.
 
-When invoked with `--layout-mode` (or when the user says "layout mode", "layout variations", or "UI variations"), this skill operates at the concrete component/layout level — it varies HOW the same content is presented visually, not WHAT the user flow is. Layout-mode takes a fixed flow contract from `specs/user-flow-[topic].md` plus a fixed content contract from `specs/ui-requirements-[topic].md` or equivalent and generates 2-5 concrete visual/spatial approaches. Each variation must be specified well enough to build as a lightweight implementation, then evaluated through `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `$pack install product-testing` inside Codex, or `npx skillpacks install product-testing` from the project shell, first) before `$consolidate-variations`.
+When invoked with `--layout-mode` (or when the user says "layout mode", "layout variations", or "UI variations"), this skill operates at the concrete component/layout level — it varies HOW the same content is presented visually, not WHAT the user flow is. Layout-mode is an explicit bounded mode for cases where both the flow and content contract are already fixed; otherwise default to progression-path UX variations. Layout-mode takes a fixed flow contract from `design/user-flow-[topic].md` plus a fixed content contract from `design/ui-requirements-[topic].md` or equivalent and generates 2-5 concrete visual/spatial approaches. Each variation must be specified well enough to build as a lightweight implementation, then evaluated through `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `npx skillpacks install product-testing` from the project shell, first) before `$consolidate-variations`.
 
 ## Process
 
@@ -33,19 +33,29 @@ Resolve research scope by product path before using code or app structure as a h
 6. If no product directories exist, use flat `research/` single-product mode.
 7. Detect monorepo/app/package structure only as a secondary hint. Suggest creating a missing `research/{slug}/` product path when code clearly exposes an app, but do not require code or monorepo detection before using `research/{slug}/`.
 
-When product path `{slug}` is active, read and write research under `research/{slug}/`, specs under `specs/{slug}/`, and treat top-level `research/*.md` files as flat-mode documents or cross-path summaries.
+When product path `{slug}` is active, read and write research under `research/{slug}/`, pre-prototype design artifacts under `design/{slug}/`, finalized post-prototype implementation specs under `specs/{slug}/`, and treat top-level `research/*.md` and `design/*.md` files as flat-mode documents or cross-path summaries.
+
+### 0b. Design Flow Tree Manifest
+
+Use `design/flow-tree.schema.json` as the machine-readable contract for the pre-prototype product-design tree.
+
+- Product-path mode reads and updates `design/{slug}/flow-tree-{topic}.yaml`.
+- Flat mode reads and updates `design/flow-tree-{topic}.yaml`.
+- Add one `ux_variations[]` entry under the selected parent user-flow branch for each proposed progression branch. Each entry must include `id`, `label`, `status`, and artifact references.
+- Keep UX variation branch state in the design manifest. Do not write ordinary UX branch state to `research/.progress.yaml`; use that file only when a variant or route experiment creates a materially different product path or product line.
 
 1. **Resolve context**
    - Read `.agents/project.json` if it exists.
    - Read `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `docs/`, `specs/`, `research/`, task files, screenshots, route files, and component implementations when present.
    - Read `research/.progress.yaml` when present. Normalize `active_path` (singular legacy) to `active_paths` (plural list) when reading; treat legacy `abandoned` as `archived` and exclude archived/deferred/revisit/promoted paths plus `research/_archive/` scopes from active target selection. Use `active_paths` as the product/app focuses and treat deferred `product_paths[]` as parked product directions, not required UX variants.
-   - Prefer existing `specs/user-flow-*.md` plus `specs/ui-requirements-*.md` as the normal AFPS layout-mode inputs.
-   - Also read `specs/ui-*.md`, product specs, journey maps, ICP research, positioning research, and user feedback as source evidence.
+   - Prefer existing `design/user-flow-*.md`, product-path-scoped equivalents, and `design/**/flow-tree-*.yaml` as the normal AFPS input; select one named user-flow branch as the variation surface.
+   - Also read `design/ui-*.md`, product specs, journey maps, ICP research, positioning research, finalized implementation specs, and user feedback as source evidence.
    - If no credible flow structure exists, run or recommend `$user-flow-map` before developing variants.
-   - If flow exists but no credible content/data/action contract exists, run or recommend `$ui-interview --requirements-only` before developing layout-mode variants.
+   - If the user explicitly requests layout-mode and no credible content/data/action contract exists, run or recommend `$ui-interview --requirements-only` before developing layout-mode variants.
 
 2. **Define the decision surface**
-   - Identify what the user is deciding: whole app experience, onboarding, activation, typical workflow, sharing flow, collaboration model, purchase flow, editor, dashboard, settings, mobile experience, page layout, or another bounded surface.
+   - Identify what the user is deciding: the selected user flow, onboarding, activation, typical workflow, sharing flow, collaboration model, purchase flow, editor, dashboard, settings, mobile experience, page layout, or another bounded surface.
+   - Identify the parent user-flow branch, the upstream `user-flow-map` source, and any sibling user flows or prior UX/UI proposals that this variation must coordinate with.
    - Identify which dimensions are allowed to vary:
      - First-run onboarding and activation
      - Core workflow sequencing
@@ -65,7 +75,8 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Copy tone
      - Mobile behavior
    - Identify fixed constraints: brand, stack, design system, must-keep components, accessibility, launch scope, performance, and business requirements.
-   - **Layout-mode addition**: In layout-mode, read `specs/user-flow-[topic].md` as the fixed screen-flow contract and `specs/ui-requirements-[topic].md` as the fixed content contract. The WHAT and flow order are locked; only the HOW varies. Layout dimensions that can vary:
+   - **Default progression-mode addition**: For each selected user flow, identify which parts may vary: entry route, sequencing, step granularity, user choice points, system automation, handoff points, review/edit loops, save-for-later behavior, cancellation, recovery, permissions, notifications, and completion criteria. Preserve the parent flow boundary while allowing progression branches to differ meaningfully.
+   - **Layout-mode addition**: In layout-mode, read `design/user-flow-[topic].md` as the fixed screen-flow contract and `design/ui-requirements-[topic].md` as the fixed content contract. The WHAT and flow order are locked; only the HOW varies. Layout dimensions that can vary:
      - Container pattern: card grid, data table, list, kanban, timeline, tree, masonry
      - Detail pattern: sidebar panel, full-page route, modal, drawer, inline expand, popover
      - Navigation: top-nav, side-nav, tab-based, breadcrumb-driven, command-palette, hybrid
@@ -78,6 +89,7 @@ When product path `{slug}` is active, read and write research under `research/{s
    - Tag assumptions with `[from spec]`, `[from codebase]`, `[from research]`, `[from artifact]`, or `[inferred]`.
    - Cover:
      - Target users and usage context
+     - Parent user flow and selected branch scope
      - Primary job or workflow
      - First-run moment, activation event, and "aha" threshold
      - Typical repeat-use workflow
@@ -85,7 +97,7 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Return triggers, notifications, and re-engagement assumptions
      - Cross-device, cross-role, or external handoff assumptions
      - Existing pain points or uncertainty
-     - Decisions that are locked versus open
+     - Decisions that are locked versus open, including which parts of the parent flow may vary
      - Evaluation criteria
      - Required variants and desired breadth
      - Prototype fidelity and implementation budget
@@ -96,11 +108,13 @@ When product path `{slug}` is active, read and write research under `research/{s
 4. **Interview for variation goals**
    - Codex interview cadence is one primary decision question per turn by default. Use short follow-up bullets only when they clarify the same variation decision, not to batch unrelated questions.
    - Default to maximally contrasting archetypes. Do not ask how different variants should be — assume dramatic contrast unless the user explicitly requests graduated steps.
-   - Default evaluation method is: build each variation, then run `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `$pack install product-testing` inside Codex, or `npx skillpacks install product-testing` from the project shell, first) so the user has task-based evidence before consolidation.
+   - Default evaluation method is: build each variation, then run `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `npx skillpacks install product-testing` from the project shell, first) so the user has task-based evidence before consolidation.
    - When presenting a design decision with 3+ plausible answers during the interview, always include "Make this a variant axis (test all approaches)" as an option. When the user has already chosen "test all" for a prior question in the same session, default subsequent ambiguous decisions to variant axes without asking.
    - Establish:
      - Assume solo evaluator building and gut-checking unless the user states otherwise
+     - Which user flow from the wireframe tree is being expanded
      - What they must be able to accomplish
+     - Which progression moments can vary: entry, sequencing, decision points, handoffs, recovery, completion, and re-entry
      - How a new user arrives, signs up, understands the product, and reaches first value
      - What the normal repeat workflow looks like after onboarding
      - What users create, save, share, export, invite others into, or hand off
@@ -168,7 +182,9 @@ When product path `{slug}` is active, read and write research under `research/{s
    - For each variation, define:
      - Name and design thesis
      - Target user fit
+     - Parent user flow and branch relationship
      - Page and flow changes
+     - Progression model: how the user advances through the flow and how this differs from sibling variations
      - Onboarding and activation model
      - Typical workflow sequence
      - Sharing, collaboration, and permissions model
@@ -184,7 +200,7 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Strengths, risks, and failure modes
      - Implementation complexity
      - What to prototype first
-     - What user signal would make this the winner
+     - What user signal would make this branch ready for `$ui-interview`
    - **Layout-mode variation spec additions**: In layout-mode, each variation spec must also include:
      - Content-to-component mapping: which content requirement maps to which UI component
      - Page regions with approximate proportions (e.g., sidebar 280px, content fluid, detail panel 400px)
@@ -203,8 +219,9 @@ When product path `{slug}` is active, read and write research under `research/{s
 8. **Plan experimentation**
    - Recommend serial full buildout of all approved variants when the user is using layout-mode or explicitly wants to compare built interfaces. Do not recommend building a subset first unless the user asks for a smaller experiment.
    - For prototype-stage product or feature work, prefer numerous small route-based experiments over one merged prototype when multiple workflows, layouts, densities, copy approaches, navigation models, or interaction patterns remain plausible. Name the route for each experiment, such as `/experiments/table-first`, `/experiments/command-first`, or the project's equivalent, and keep shared production infrastructure out of those routes unless explicitly approved.
-   - If route experiments imply materially different products, apps, ICPs, or product lines, update `research/.progress.yaml` with experiment product-path entries instead of making every divergent path a required UX variation. Include `id`, `label`, `source_skill: ux-variations`, `scope_path`, `status`, `reason`, `archive_reason`, `archived_at`, `promoted_at`, `evidence_refs`, `revisit_trigger`, `next_skill`, `pipeline_stage: ux-variations`, and `last_touched`.
-   - After variants are built, recommend `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `$pack install product-testing` inside Codex, or `npx skillpacks install product-testing` from the project shell, first) before `$consolidate-variations`. Consolidation is premature until evaluation evidence exists or the user explicitly says they reviewed the variants and is ready to converge.
+- If route experiments imply materially different products, apps, ICPs, or product lines, update `research/.progress.yaml` with experiment product-path entries instead of making every divergent path a required UX variation. Include `id`, `label`, `source_skill: ux-variations`, `scope_path`, `status`, `reason`, `archive_reason`, `archived_at`, `promoted_at`, `evidence_refs`, `revisit_trigger`, `next_skill`, `pipeline_stage: ux-variations`, and `last_touched`.
+   - Product paths are not git branches; keep route-experiment product-path tracking in `research/.progress.yaml` distinct from git workflow branch terminology.
+   - After progression variants are specified, route the next selected branch to `$ui-interview [specific-ux-variation]` for visual mockup and approval/rejection. If variants are built before UI interview, recommend `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `npx skillpacks install product-testing` from the project shell, first) before `$consolidate-variations`. Consolidation is premature until evaluation evidence exists or the user explicitly says they reviewed the variants and is ready to converge.
    - Define the cheapest useful validation method:
      - Static mockups for visual direction
      - Clickable prototype for navigation and flow
@@ -227,9 +244,11 @@ When product path `{slug}` is active, read and write research under `research/{s
 
 ## Deliverables
 
-- Write the variation plan to `specs/ux-variations-[topic].md`.
-- Write the interview log to `ux-variations-[topic]-interview.md`.
-- Update `research/.progress.yaml` only when variant or route experiments create materially different product paths; downstream research remains active-path-only until a path is activated.
+- Write the variation plan to `design/ux-variations-[topic].md` in flat mode or `design/{slug}/ux-variations-[topic].md` in product-path mode.
+- Write the interview log to `design/ux-variations-[topic]-interview.md` in flat mode or `design/{slug}/ux-variations-[topic]-interview.md` in product-path mode.
+- Update the scoped flow-tree manifest with UX variation branch IDs, statuses, artifact references, and the recommended next `$ui-interview [specific-ux-variation]` branch.
+- Update `research/.progress.yaml` only when variant or route experiments create materially different product paths; downstream research remains active-path-only until a path is activated. Do not use `research/.progress.yaml` for ordinary UX branch approve/reject/retry state.
+- Include a branch-routing section that names the parent user flow, each UX variation branch, sibling flow/variation dependencies, and the recommended next `$ui-interview [specific-ux-variation]` branch.
 
 ### Alignment Page
 
@@ -238,15 +257,18 @@ When this skill produces durable deliverables (research, specs, plans, reports,
 ## Constraints
 
 - Do not present superficial variants that differ only by color palette, typography, or decorative treatment.
+- Do not treat default UX variation work as only visual layout exploration. Default variations should compare different ways users progress through a named user flow.
 - Do not choose a winner for the user unless the evidence clearly supports it and the user asked for a recommendation.
 - Do not defer all decisions to testing. State a recommended variant or experiment when evidence is sufficient.
 - Do not ignore implementation cost. A compelling variation still needs a prototype path and selection criteria.
-- Do not route directly from built UI variants to `$consolidate-variations`; insert `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `$pack install product-testing` inside Codex, or `npx skillpacks install product-testing` from the project shell, first) unless the user explicitly confirms they have already evaluated the variants.
+- Do not route directly from built UI variants to `$consolidate-variations`; insert `$uat --variant-evaluation` (check `.agents/project.json.enabled_packs` for `product-testing` — if `product-testing` is not enabled, recommend `npx skillpacks install product-testing` from the project shell, first) unless the user explicitly confirms they have already evaluated the variants.
+- Do not skip `$ui-interview` for a UX variation branch that needs a proposed UI, HTML visual mockup, or approval/rejection decision.
 - Do not enforce shared design constraints across variations. Each variation independently decides layout, density, color, navigation, and component choices. Only technical stack is shared unless the user explicitly locks a shared constraint.
+- Do not write pre-prototype UX variation plans to `specs/`. `design/` is the canonical home for flow maps, UX variation plans, UI branch packets, branch decisions, mockup references, and flow-tree manifests.
 
 ## Archive-First Replacement Policy
 
-- Before replacing or substantively rewriting an existing canonical research/spec document (`research/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
+- Before replacing or substantively rewriting an existing canonical research/design/spec document (`research/**/*.md`, `design/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
 - Preserve the archived snapshot exactly as it existed before the change; do not edit the archived copy after creating it.
 - After the archive snapshot exists, write the updated document to the original canonical path.
 - Report both the archive path and the updated canonical path in the final output.