super-ux 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to this project are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-07-23
+
+### Added
+
+- **ux-flows skill** — the HOW layer (`docs/ux/flows.md`): task analysis →
+  mermaid user flows (screens, explicit branches, recoverable error edges,
+  all entry points) → screen/state tables → optional ASCII wireframes and
+  storyboards. Workflows: Design (forward), Reverse (backwards mode for
+  existing products, `inferred` tags with file:line evidence), Update,
+  Improve (heuristic evaluation → traced before/after redesign proposals).
+- **ux-design-principles.md** — the agent's thinking playbook: the 7-step
+  pipeline (research → define → structure → specify → visualize → build →
+  verify) with forward and backwards modes, task-analysis method, flow and
+  screen rules, heuristics PRN-01..10 (after Nielsen) and cognitive
+  principles PRN-11..16 with audit questions, the improvement procedure,
+  wireframe/storyboard conventions, anti-patterns.
+- **ux-contract v3** — scenarios become use cases: steps as `user action ->
+  system response`, new `Alt paths` field, `Traces` includes `FLW-NN`;
+  traceability now covers flows (every node and edge needs a scenario).
+- `ux-audit`: verifies code against flow diagrams (nodes reachable, edges
+  wired, states present); new `heuristics` scope (`[PRN-NN]` findings).
+- `/ux-flows` command; `/ux` menu grows to 11 actions including "Improve
+  existing UX"; `/ux-init` now chains foundation → flows → scenarios.
+
+## [0.7.0] - 2026-07-20
+
+### Added
+
+- **Best-practices catalog** (`skills/references/best-practices.md`) — a
+  living, tag-indexed catalog (48 entries seeded from "48 Laws of
+  Subscription App Success", Botsi 2025): each practice has an ID (BP-NNN),
+  own-words summary, mechanism, applicability, and tags (stage / mechanism /
+  domain / effect) so agents can select what fits the product. Growable per
+  in-file rules.
+- Integration: `ux-scenarios` consults the catalog when drafting (practices
+  applied only when they serve a traced job); `ux-foundation` uses it for
+  journey opportunities; `ux-audit` gains an optional practices pass
+  (suggestion findings `[BP-NNN]`, never blockers); `/ux` menu gains a
+  "Best-practices review" action.
+
+## [0.6.0] - 2026-07-20
+
+### Added
+
+- **ux-foundation skill** — the WHY layer: personas, Jobs to Be Done (with
+  forces and success metrics), customer journey maps (stage / action /
+  touchpoint / emotion / pain / opportunity), user stories (INVEST,
+  Given/When/Then acceptance criteria). New file contract
+  `docs/ux/foundation.md`, template, `/ux-foundation` command, Cursor rule.
+- **ux-contract v2** — scenarios gain a `Traces:` field (story/job/journey
+  stage) and traceability rules: every must/should story covered, every
+  scenario serves a story or job; orphans are findings.
+- **Full-context audits** — `ux-audit` loads traced acceptance criteria as
+  checks and judges whether the implementation serves the job, not just
+  renders elements; new `coverage` scope audits the chain itself; fix plans
+  prioritized by Frequency × Severity × Solvability.
+- **`/ux` action menu** — single entry point now reports status across all
+  three layers and offers the applicable actions (init/update foundation,
+  build scenarios, validate chain, audit, coverage audit, plan fixes) with
+  one recommended default.
+
 ## [0.5.0] - 2026-07-19
 
 ### Changed

package/README.md

@@ -1,5 +1,9 @@
 # super-ux
 
+[![npm](https://img.shields.io/npm/v/super-ux)](https://www.npmjs.com/package/super-ux)
+[![CI](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 Scenario-driven UI development for AI agents (Claude Code + Cursor).
 
 AI agents generate poor interfaces because they build UI without a model of
@@ -13,25 +17,31 @@ the codebase.
 
 ```mermaid
 flowchart LR
-    A[Feature idea] --> B[Draft scenarios]
-    B --> C{Validate vs existing base:\nconflicts, overlaps, gaps}
-    C -->|approved| D[Design & build UI]
+    W[Personas + JTBD\n+ journeys + stories] --> B[Derive scenarios\nwith Traces]
+    A[Feature idea] --> V{Which job? Which stage?\nValidate vs base}
+    W --> V
+    V -->|approved| D[Design & build UI]
     D --> E[Update scenarios\nin the same change]
-    E --> F[/ux-audit: batched check\nof code vs every scenario/]
-    F --> G[Audit report + findings]
-    G --> H[Plan fixes] --> D
+    E --> F[/ux-audit: code vs scenarios\nwith story acceptance criteria/]
+    B --> F
+    F --> G[Report + findings]
+    G --> H[Prioritized fix plan\nFreq × Severity × Solvability] --> D
 ```
 
 ## What's inside
 
 | Piece | Purpose |
 |---|---|
-| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: init (greenfield interview or existing-code inventory sweep), update on every change, validate for conflicts and coverage |
-| skill `ux-audit` | Batched audit loop: trace every scenario through the code, verdicts PASS/PARTIAL/FAIL/BLOCKED with `file:line` evidence, report into `docs/ux/audits/` |
-| `/ux` | **The one command**: sets everything up if missing (rule, `docs/ux/`, initial base), otherwise status report + one suggested next action. Idempotent |
-| `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls over the skills; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
-| `cursor/rules/*.mdc` | The same methodology for Cursor (always-on hard rule + two agent-requested rules) |
-| `templates/` | Skeletons for the scenario base, the audit report, and the CLAUDE.md rule snippet |
+| skill `ux-foundation` | The WHY layer (`docs/ux/foundation.md`): personas, Jobs to Be Done with forces, customer journey maps, user stories with Given/When/Then acceptance criteria |
+| skill `ux-flows` | The HOW layer (`docs/ux/flows.md`): task analysis, mermaid user flows (branches, error recovery, entry points), screen states, optional wireframes; heuristic UX evaluation and traced redesign proposals for existing products |
+| skill `ux-scenarios` | Maintain `docs/ux/scenarios.md`: use-case scenarios (action → system response, alt paths) covering every flow node/edge, `Traces:` to stories and flows, validated for conflicts, coverage, and traceability |
+| skill `ux-audit` | Batched audit loop with full context: code vs every scenario + its story's acceptance criteria; verdicts PASS/PARTIAL/FAIL/BLOCKED with `file:line` evidence; `coverage` scope audits the chain itself |
+| `/ux` | **The one command**: sets up whatever is missing, then status across all layers + a menu of applicable actions with one recommended default. Idempotent |
+| `/ux-foundation` `/ux-flows` `/ux-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
+| [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward + backwards), task analysis, flow rules, heuristics PRN-01..16, improvement procedure, anti-patterns |
+| `cursor/rules/*.mdc` | The same methodology for Cursor (always-on hard rule + three agent-requested rules) |
+| `templates/` | Skeletons for the foundation, scenario base, audit report, and the CLAUDE.md rule snippet |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of proven UX/growth practices (seeded with 48 subscription-app laws); agents filter by stage/domain tags and apply what serves a traced job |
 
 The format all of them share is locked in
 [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md):
@@ -99,16 +109,20 @@ rules after a new release.
 
 ## Typical cycle
 
-1. `/ux` — first run sets everything up and builds the base (greenfield:
-   interview first, UI later; existing code: inventory sweep, scenarios for
-   everything found, gaps flagged in both directions).
+1. `/ux` — first run sets everything up: foundation first (greenfield:
+   interview about personas, jobs, journeys; existing code:
+   reverse-engineer them), then scenarios derived from the stories with
+   full traceability.
 2. Work normally; every user-facing change updates the base in the same
    change (the always-on rule catches it; `/ux-update` for manual control).
-3. `/ux` any time — status + the one next action; `/ux-audit` — batched
-   verification of code vs scenarios; report lands in
-   `docs/ux/audits/YYYY-MM-DD.md`, statuses update in the base.
-4. Turn FAIL/PARTIAL findings into a plan with your planning workflow; build;
-   repeat.
+   New feature ideas are validated against the chain first: which job,
+   which journey stage, which story.
+3. `/ux` any time — status across layers + action menu; `/ux-audit` —
+   batched verification of code vs scenarios (with acceptance criteria);
+   `/ux-audit coverage` — chain gaps. Reports land in
+   `docs/ux/audits/YYYY-MM-DD.md`.
+4. Findings become a prioritized fix plan (Frequency × Severity ×
+   Solvability) via your planning workflow; build; repeat.
 
 ## Development
 
@@ -120,11 +134,15 @@ is semver; bump `marketplace.json` + `plugin.json` + `CHANGELOG.md` together
 ## По-русски (коротко)
 
 Проблема: агенты генерируют плохие интерфейсы, потому что строят UI без
-модели поведения пользователя. super-ux делает базу UX-сценариев
-(`docs/ux/scenarios.md`) источником правды: сценарии пишутся и валидируются
-**до** интерфейса, обновляются тем же изменением, что и поведение, и служат
-чек-листом для регулярных аудитов кода (`/ux-audit`) с вердиктами
-PASS/PARTIAL/FAIL/BLOCKED и доказательствами `file:line`. Установка: в
+модели поведения пользователя. super-ux строит цепочку: **персоны → JTBD →
+карта пути → user stories → UX-сценарии → аудиты → планы фиксов**.
+Foundation (`docs/ux/foundation.md`) отвечает на «зачем», сценарии
+(`docs/ux/scenarios.md`) — источник правды поведения, трассируются к
+stories. Всё пишется и валидируется **до** интерфейса, обновляется тем же
+изменением, что и поведение. Аудиты (`/ux-audit`) проверяют код против
+сценариев вместе с acceptance criteria, вердикты PASS/PARTIAL/FAIL/BLOCKED
+с доказательствами `file:line`; `/ux-audit coverage` ищет дыры в самой
+цепочке. Установка: в
 Claude Code — `/plugin marketplace add ssheleg/super-ux`, в Cursor —
 `npx super-ux --cursor <проект>`. Дальше одна команда — `/ux`: сама ставит
 правило и базу, а при повторных запусках показывает статус и следующий шаг.

package/cursor/rules/super-ux.mdc

@@ -5,13 +5,16 @@ alwaysApply: true
 
 # UX scenarios — hard rule (super-ux)
 
-- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
+  `docs/ux/foundation.md` (personas, JTBD, journeys, user stories) is the WHY
+  layer scenarios trace to.
 - Any change that touches user-facing behavior MUST update
   `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
   coverage). New user-facing behavior with no scenario is a blocker, not a
   warning.
-- Any new feature or project STARTS with scenarios: draft them, validate
-  against existing scenarios (conflicts, overlaps, gaps), get them approved —
-  only then design and build UI.
-- Scenario maintenance workflows: see the `ux-scenarios` rule. Codebase
-  audits against the base: see the `ux-audit` rule.
+- Any new feature or project STARTS with the chain: which job does it serve,
+  which journey stage, which story — then scenarios, validated against the
+  existing base (conflicts, overlaps, gaps), approved — only then design and
+  build UI. An idea serving no job is challenged, not silently accepted.
+- Workflows: `ux-foundation` rule (WHY layer), `ux-scenarios` rule
+  (scenario base), `ux-audit` rule (evidence-backed audits).

package/cursor/rules/ux-flows.mdc

@@ -0,0 +1,47 @@
+---
+description: "Design or improve user flows (docs/ux/flows.md): apply for task analysis, flow diagrams, screen states, wireframes, heuristic UX evaluation, or any 'improve/fix the UX' request"
+alwaysApply: false
+---
+
+# ux-flows — Design HOW Users Move
+
+`docs/ux/flows.md` is the HOW layer between foundation (stories) and
+scenarios: task analysis + mermaid user flows + screen states. IDs
+`FLW-NN`, sequential, never reused; superseded flows kept with a note.
+
+## Flow entry (ux-contract v3)
+
+Fields: `Traces` (story/job IDs), `Goal` (observable end state), `Entry
+points` (ALL of them), `Success exit`, `Task analysis` (numbered
+user-visible micro-steps), mermaid `flowchart` (screens as
+`Screen: <name>`, decisions as diamonds, `*_err` error nodes with labeled
+recovery edges), `Screens & states` table (each screen:
+loading/empty/error/success + key elements, one primary action).
+
+## Design rules
+
+- One flow = one user goal. Task analysis first: cut/merge/default-away
+  every step that doesn't serve the job; pull first value as early as
+  possible; happy path ≤5 steps or justified.
+- Every decision an explicit branch; every error edge lands on recovery —
+  dead ends are defects; all entry points enumerated.
+- Wireframes optional (`docs/ux/wireframes/FLW-NN.md`, ASCII hierarchy +
+  primary action, not pixels); storyboard only when usage context drives
+  design.
+- Backwards mode (existing product): reconstruct flows as they ARE from
+  code with file:line evidence, tag `inferred` until confirmed; gaps
+  between is/should become the improvement backlog.
+
+## Improving existing UX
+
+Walk flows against heuristics: system status visible; user's words not
+jargon; undo/cancel/back everywhere; consistency; error prevention over
+error messages; recognition over recall; shortcuts for frequent users;
+minimalist screens; recovery-oriented error text; help in context;
+progressive disclosure; smart defaults; limited choices; familiar
+patterns; prominent primary targets; polished peaks and endings.
+
+Violations: `[PRN-NN] node — issue — severity`. Redesign proposals MUST
+trace to a pain/job/story, cite the principle/practice, show flow
+before → after, and state the expected observable effect. Prioritize
+Frequency × Severity × Solvability. Cascade approved changes to scenarios.

package/cursor/rules/ux-foundation.mdc

@@ -0,0 +1,47 @@
+---
+description: "Maintain docs/ux/foundation.md (personas, Jobs to Be Done, customer journeys, user stories): apply when defining who the users are and why they use the product, during product discovery, or when scenarios need a WHY layer to trace to"
+alwaysApply: false
+---
+
+# ux-foundation — The WHY Layer
+
+`docs/ux/foundation.md` holds the chain scenarios trace to: **Personas
+(P-NN) → Jobs to Be Done (JTBD-NN) → Customer journeys (JRN-NN) → User
+stories (ST-NNN)**. IDs sequential, never reused; dropped entries kept, not
+deleted.
+
+## Formats (ux-contract v2)
+
+- **Persona `P-NN`:** 1–3 sentences, grounded in data/observation,
+  recognizable by a real user.
+- **JTBD `JTBD-NN`:** `When <situation>, I want to <motivation>, so I can
+  <outcome>` + personas + type (functional|emotional|social) + forces
+  (push/pull/anxiety/habit) + success metric (user outcome, never a
+  feature).
+- **Journey `JRN-NN`** (persona × job): stage table — `# | Stage | User
+  action | Touchpoint | Emotion (1-5) | Pain | Opportunity`; end-to-end
+  (before/during/after product); opportunity priority = Frequency ×
+  Severity × Solvability.
+- **Story `ST-NNN`:** `As <persona>, I want <capability>, so that
+  <benefit>` + Traces (JTBD, JRN/stage) + Given/When/Then acceptance
+  criteria + priority (must|should|could) + status
+  (proposed|validated|delivered|dropped). Quality bar: INVEST.
+
+## Workflows
+
+- **Init (interview):** greenfield — ask one question at a time: who uses
+  it; what situation triggers the job; what outcome = success; walk the
+  path end-to-end; derive stories from pains and outcomes.
+- **Init (reverse):** existing product — reverse-engineer jobs/personas
+  from the UI and scenarios; tag entries observed vs inferred; flag
+  features serving no job and jobs with no support.
+- **Update:** locate by ID, update, mark dropped (never delete), then
+  cascade: list scenarios tracing to changed IDs and update them in the
+  same change.
+- **Validate:** integrity (IDs, references), quality (no features in JTBD,
+  INVEST, observable criteria), coverage (persona→job→journey→story chain
+  complete; must/should stories have scenarios).
+
+Evidence beats opinion: mark unvalidated guesses as assumptions
+(desirability/viability/feasibility/usability) and test risky ones before
+building on them.

package/cursor/rules/ux-scenarios.mdc

@@ -14,7 +14,12 @@ Title, then header comment, then: **Index** table
 (`| ID | Title | Feature | Persona | Status | Last audit |`), **Personas**
 (1–3 sentences each), **Scenarios** grouped by feature.
 
-Scenario entry fields (exact names): `Persona`, `Feature`, `Entry point`,
+When `docs/ux/foundation.md` exists, scenarios derive from it: draft per
+user story / journey stage, fill `Traces:` (e.g. `ST-001 (JTBD-01,
+JRN-01/#2)`), enforce traceability — every must/should story covered by ≥1
+scenario, every scenario serves ≥1 story or job.
+
+Scenario entry fields (exact names): `Persona`, `Feature`, `Traces`, `Entry point`,
 `Preconditions`, `Steps` (numbered, one user action each), `Expected result`
 (observable), `UI elements` (every button/field/link/dialog/toast involved —
 this is what audits check), `States covered` (loading|empty|error|success),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code + Cursor): scenario base, scenario-first hard rule, evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"

package/templates/flows.md

@@ -0,0 +1,29 @@
+# User Flows
+
+<!-- Managed with super-ux (ux-contract v3). The HOW layer: task analysis
+and user flows. Scenarios in scenarios.md trace to FLW-IDs and must cover
+every node and edge. -->
+
+<!-- ### FLW-01: <user goal>
+- **Traces:** ST-001 (JTBD-01, JRN-01/#2)
+- **Goal:** <observable end state for the user>
+- **Entry points:** <all of them: screen, deep link, push, empty-state CTA>
+- **Success exit:** <where the user lands on success>
+- **Task analysis:**
+  1. <user-visible micro-step; cut everything that doesn't serve the job>
+- **Flow:**
+
+```mermaid
+flowchart TD
+  A[Screen: <name>] -->|<action>| B{<decision?>}
+  B -->|ok| C[Screen: <next>]
+  B -->|fail| B_err[<error + recovery>]
+  B_err --> A
+```
+
+- **Screens & states:**
+  | Screen | States | Key elements |
+  |--------|--------|--------------|
+  | <name> | loading, empty, error, success | <elements, one primary action> |
+- **Wireframe:** wireframes/FLW-01.md (optional)
+-->

package/templates/foundation.md

@@ -0,0 +1,39 @@
+# UX Foundation
+
+<!-- Managed with super-ux (ux-contract v2). The WHY layer: personas, jobs
+to be done, customer journeys, user stories. Update when the understanding
+of users changes; scenarios in scenarios.md trace to the IDs defined here. -->
+
+## Personas
+
+<!-- ### P-01: <name>
+1-3 sentences: who they are, what they know, what they want. Grounded in
+data/observation, recognizable by a real user. -->
+
+## Jobs to Be Done
+
+<!-- ### JTBD-01: <short job name>
+- **Statement:** When <situation>, I want to <motivation>, so I can <expected outcome>.
+- **Personas:** P-01
+- **Type:** functional | emotional | social
+- **Forces:** push: <...>; pull: <...>; anxiety: <...>; habit: <...>
+- **Success metric:** <observable user outcome, not a feature>
+-->
+
+## Customer journeys
+
+<!-- ### JRN-01: <persona> — <job> (JTBD-01)
+| # | Stage | User action | Touchpoint | Emotion (1-5) | Pain | Opportunity |
+|---|-------|------------|------------|---------------|------|-------------|
+-->
+
+## User stories
+
+<!-- ### ST-001: <short name>
+- **Story:** As <persona>, I want <capability>, so that <benefit>.
+- **Traces:** JTBD-01, JRN-01/#2
+- **Acceptance criteria:**
+  - Given <precondition>, when <action>, then <observable result>.
+- **Priority:** must | should | could
+- **Status:** proposed
+-->