super-ux 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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

package/README.md

@@ -33,10 +33,12 @@ flowchart LR
 | Piece | Purpose |
 |---|---|
 | 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-scenarios` | Maintain `docs/ux/scenarios.md`: scenarios derived from stories/journeys with `Traces:`, updated on every change, validated for conflicts, coverage, and traceability |
+| 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-init` `/ux-update` `/ux-audit` `/ux-rule` | Direct controls; `/ux-rule` installs the hard rule into the project's CLAUDE.md |
+| `/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 |

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.7.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)
+-->