super-ux 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+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.3.0] - 2026-07-19
+
+### Added
+
+- npx installer: `npx github:ssheleg/super-ux --cursor [project-dir]`
+  (`bin/super-ux.js`, cross-platform Node CLI, no dependencies) — same
+  behavior as `install.sh`, plus `package.json` for npm/npx distribution.
+- Validator now checks `package.json` (name, bin shebang, files whitelist)
+  and includes its version in the version-sync check.
+
+## [0.2.0] - 2026-07-19
+
+### Added
+
+- `/ux` — one-command entry point: inspects the project, installs the hard
+  rule and seeds/initializes the scenario base if anything is missing,
+  otherwise prints a status report and suggests exactly one next action.
+  Idempotent; `/ux-init`, `/ux-update`, `/ux-audit`, `/ux-rule` remain as
+  direct controls.
+
+## [0.1.0] - 2026-07-19
+
+### Added
+
+- Claude Code plugin `super-ux`: skills `ux-scenarios` (maintain the scenario
+  base) and `ux-audit` (scenario audit loop); commands `/ux-init`,
+  `/ux-update`, `/ux-audit`, `/ux-rule`.
+- Scenario format contract v1
+  (`plugins/super-ux/skills/references/scenario-format.md`).
+- Cursor rules: `cursor/rules/super-ux.mdc` (always-on hard rule),
+  `ux-scenarios.mdc`, `ux-audit.mdc`.
+- Templates: scenario base skeleton, audit report skeleton, CLAUDE.md hard
+  rule snippet.
+- `install.sh --cursor <project-dir>` installer for Cursor projects.
+- Repo validator (`test/validate.py`) and GitHub Actions CI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssheleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# super-ux
+
+Scenario-driven UI development for AI agents (Claude Code + Cursor).
+
+AI agents generate poor interfaces because they build UI without a model of
+user behavior: screens appear feature by feature, while error states, empty
+states, and cross-feature flows get invented ad hoc or skipped. **super-ux**
+fixes the process, not the symptom — a versioned base of UX scenarios becomes
+the source of truth for all user-facing behavior. Scenarios are written and
+validated *before* UI is built, updated in the same change as any behavior
+change, and used as the checklist for recurring, evidence-backed audits of
+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]
+    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
+```
+
+## 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 |
+
+The format all of them share is locked in
+[scenario-format.md](plugins/super-ux/skills/references/scenario-format.md):
+scenario entries with stable `SCN-NNN` IDs, personas, per-feature and
+per-product completeness checklists, the `draft → validated → implemented`
+lifecycle, audit verdicts and severities.
+
+## The hard rule
+
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
+- Any change touching user-facing behavior updates the scenario base **in the
+  same change**.
+- Any new feature or project **starts** with scenarios: draft, validate
+  against the existing base, approve — only then design and build UI.
+
+## Install
+
+### Claude Code
+
+```
+/plugin marketplace add ssheleg/super-ux
+/plugin install super-ux@super-ux
+```
+
+Then in your project: `/ux`. That's it — it installs the hard rule, seeds
+`docs/ux/`, builds the scenario base if empty, and on every later run just
+reports status and the next action.
+
+### Cursor
+
+```sh
+npx github:ssheleg/super-ux --cursor /path/to/your/project
+```
+
+(or clone and run `./install.sh --cursor <dir>` — same behavior.) Copies the
+three rules into `.cursor/rules/` and seeds `docs/ux/scenarios.md`. An
+existing scenario base is never overwritten; re-run with `--force` to update
+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).
+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.
+
+## Development
+
+`python3 test/validate.py` checks repo consistency (manifests, versions,
+front-matter, templates, links); CI runs it on every push and PR. Versioning
+is semver; bump `marketplace.json` + `plugin.json` + `CHANGELOG.md` together
+— the validator enforces the sync.
+
+## По-русски (коротко)
+
+Проблема: агенты генерируют плохие интерфейсы, потому что строят UI без
+модели поведения пользователя. super-ux делает базу UX-сценариев
+(`docs/ux/scenarios.md`) источником правды: сценарии пишутся и валидируются
+**до** интерфейса, обновляются тем же изменением, что и поведение, и служат
+чек-листом для регулярных аудитов кода (`/ux-audit`) с вердиктами
+PASS/PARTIAL/FAIL/BLOCKED и доказательствами `file:line`. Установка: в
+Claude Code — `/plugin marketplace add ssheleg/super-ux`, в Cursor —
+`npx github:ssheleg/super-ux --cursor <проект>`. Дальше одна команда — `/ux`: сама ставит
+правило и базу, а при повторных запусках показывает статус и следующий шаг.
+
+## License
+
+MIT © ssheleg

package/bin/super-ux.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/*
+ * super-ux installer CLI.
+ * Cross-platform equivalent of install.sh: copies Cursor rules into a target
+ * project and seeds the docs/ux skeleton. Claude Code needs no installer —
+ * see usage.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function usage() {
+  console.log(`super-ux installer
+
+Usage:
+  npx github:ssheleg/super-ux --cursor [project-dir] [--force]
+  npx super-ux --cursor [project-dir] [--force]        (once published to npm)
+
+Copies cursor/rules/*.mdc into <project-dir>/.cursor/rules/ (default:
+current directory) and seeds docs/ux/scenarios.md from templates/ if absent.
+An existing scenario base is NEVER overwritten. Existing rule files are
+skipped unless --force is given.
+
+Claude Code (no installer needed):
+  /plugin marketplace add ssheleg/super-ux
+  /plugin install super-ux@super-ux
+  Then in your project: /ux`);
+}
+
+function fail(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+function installCursor(target, force) {
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    fail(`'${target}' is not a directory`);
+  }
+
+  const rulesSrc = path.join(ROOT, 'cursor', 'rules');
+  const rulesDst = path.join(target, '.cursor', 'rules');
+  fs.mkdirSync(rulesDst, { recursive: true });
+
+  let installed = 0;
+  let skipped = 0;
+  const rules = fs.readdirSync(rulesSrc).filter((f) => f.endsWith('.mdc')).sort();
+  if (rules.length === 0) fail(`no .mdc rules found in ${rulesSrc}`);
+
+  for (const name of rules) {
+    const dst = path.join(rulesDst, name);
+    if (fs.existsSync(dst) && !force) {
+      console.log(`skip:    ${dst} exists (use --force to overwrite)`);
+      skipped += 1;
+    } else {
+      fs.copyFileSync(path.join(rulesSrc, name), dst);
+      console.log(`install: ${dst}`);
+      installed += 1;
+    }
+  }
+
+  const base = path.join(target, 'docs', 'ux', 'scenarios.md');
+  if (fs.existsSync(base)) {
+    console.log(`keep:    ${base} exists (never overwritten)`);
+  } else {
+    fs.mkdirSync(path.join(target, 'docs', 'ux', 'audits'), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, 'templates', 'scenarios.md'), base);
+    console.log(`seed:    ${base}`);
+  }
+
+  console.log(`done: ${installed} installed, ${skipped} skipped`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    usage();
+    return;
+  }
+  if (args[0] !== '--cursor') {
+    console.error(`error: unknown mode '${args[0]}'`);
+    usage();
+    process.exit(1);
+  }
+  const force = args.includes('--force');
+  const dirArg = args[1] && args[1] !== '--force' ? args[1] : '.';
+  installCursor(path.resolve(dirArg), force);
+}
+
+main();

package/cursor/rules/super-ux.mdc

@@ -0,0 +1,17 @@
+---
+description: "super-ux hard rule: scenario-driven UI development"
+alwaysApply: true
+---
+
+# UX scenarios — hard rule (super-ux)
+
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
+- 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.

package/cursor/rules/ux-audit.mdc

@@ -0,0 +1,34 @@
+---
+description: "Audit the codebase against docs/ux/scenarios.md: apply for UX audits, scenario compliance checks, pre-release UX verification, or when asked to verify that all buttons/states/errors exist"
+alwaysApply: false
+---
+
+# ux-audit — Scenario Audit Loop
+
+Verify the code delivers every scenario in `docs/ux/scenarios.md`. Output: a
+report in `docs/ux/audits/YYYY-MM-DD[-scope].md` + updated `Last audit`
+column in the base. If the base is missing, create it first (ux-scenarios
+rule) — there is nothing to audit against.
+
+**Evidence discipline:** every verdict cites `file:line`. Cannot verify →
+verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
+
+## Loop
+
+1. Read the base; scope = all | feature:<name> | ID range; note the git SHA
+   of scenarios.md for the report header; skip retired scenarios.
+2. Batch by feature, ~5–8 scenarios per batch; list batches up front.
+3. Per scenario check against the code: entry point reachable; every step
+   implemented; every listed UI element present and wired; every listed
+   state (loading/empty/error/success) has a rendering branch; every error
+   surfaced honestly (no silent catch, no fake success) with the described
+   recovery; expected result observably occurs. Gaps → findings
+   `[AUD-YYYY-MM-DD-NN] (critical|major|minor) description -> suggested fix`.
+4. Verdicts: PASS (complete), PARTIAL (flow exists, gaps), FAIL (missing or
+   broken), BLOCKED (cannot verify — say why).
+5. Write the report batch by batch: header (scope, method, base SHA),
+   Summary (totals, top issues, prioritized next actions), per-batch
+   verdicts with evidence, findings-register table.
+6. Update the base: `Last audit` = `YYYY-MM-DD VERDICT`; validated →
+   implemented where PASSed. Do not edit scenario content during an audit.
+7. Offer (don't auto-run) to turn FAIL/PARTIAL findings into a work plan.

package/cursor/rules/ux-scenarios.mdc

@@ -0,0 +1,48 @@
+---
+description: "Maintain docs/ux/scenarios.md (the UX scenario base): apply when creating or updating UX scenarios, starting any new feature or project, changing user-facing behavior, or onboarding a codebase into scenario-driven development"
+alwaysApply: false
+---
+
+# ux-scenarios — Maintain the Scenario Base
+
+`docs/ux/scenarios.md` describes everything the user can do, see, and hit —
+every feature, button, state, error, result. Keep it true.
+
+## File structure (scenario-format v1)
+
+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`,
+`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),
+`Errors & recovery` (each failure: what the user sees, how they recover),
+`Status` (draft|validated|implemented|retired), `Coverage` (file:line or
+`none yet`).
+
+Rules: IDs `SCN-NNN`, sequential, never reused; retired entries are kept,
+never deleted. Lifecycle: draft → validated (human approval) → implemented
+(audit-confirmed); changed scenarios drop back to draft.
+
+Per-feature completeness: happy path, every error path, empty state, visible
+loading, destructive-action confirmation, returning-user variant.
+Per-product: first-run onboarding, every core flow, settings, multi-entity
+flows (e.g. second project), account/data lifecycle.
+
+## Workflows
+
+- **Init (greenfield):** no code yet — interview the user (personas, jobs,
+  features), draft the full base, get approval. UI only after validation.
+- **Init (existing code):** inventory sweep (routes/screens, interactive
+  elements, state branches, error paths, onboarding, settings) → scenarios
+  covering everything found, `Coverage` filled with evidence; report both
+  gap directions (code without scenario, checklist item without code).
+- **Update:** for any behavior change — adjust affected scenarios in the
+  SAME change; add scenarios for new behavior; retire untrue ones; keep the
+  Index in sync. Behavior fitting no scenario → stop and escalate.
+- **Validate:** integrity (IDs, index sync, personas, statuses), coverage
+  vs checklists, conflicts between scenarios; for a new feature idea —
+  which existing scenarios it touches/contradicts/duplicates, reconcile
+  before any UI work.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "super-ux",
+  "version": "0.3.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" },
+  "files": ["bin", "cursor", "templates", "README.md", "LICENSE", "CHANGELOG.md"],
+  "repository": "github:ssheleg/super-ux",
+  "homepage": "https://github.com/ssheleg/super-ux",
+  "license": "MIT",
+  "author": "ssheleg",
+  "engines": { "node": ">=16" },
+  "keywords": ["ux", "scenarios", "audit", "ui", "user-flows", "scenario-driven", "claude-code", "cursor"]
+}

package/templates/audit-report.md

@@ -0,0 +1,26 @@
+# UX Audit — YYYY-MM-DD
+
+- **Scope:** all
+- **Method:** static code trace
+- **Base version:** <git SHA of scenarios.md at audit time>
+
+## Summary
+
+- Totals: PASS 0 / PARTIAL 0 / FAIL 0 / BLOCKED 0
+- Top issues:
+- Recommended next actions (prioritized):
+
+<!-- One "## Batch N" section per scenario batch:
+
+## Batch 1: <feature> (SCN-001..SCN-005)
+
+### SCN-001 — PASS|PARTIAL|FAIL|BLOCKED
+- **Evidence:** file:line, file:line
+- **Findings:**
+  - [AUD-YYYY-MM-DD-01] (critical|major|minor) <finding> -> <suggested fix>
+-->
+
+## Findings register
+
+| # | Scenario | Severity | Finding | Suggested fix |
+|---|----------|----------|---------|---------------|

package/templates/claude-rule.md

@@ -0,0 +1,11 @@
+## UX scenarios — hard rule (super-ux)
+
+- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior.
+- Any change that touches user-facing behavior MUST update
+  `docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
+  coverage).
+- 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.
+- Use the `ux-scenarios` skill to maintain the base and `ux-audit` to verify
+  the codebase against it.

package/templates/scenarios.md

@@ -0,0 +1,38 @@
+# UX Scenarios
+
+<!-- Managed with super-ux (scenario-format v1). Update in the same change as any user-facing behavior change. -->
+
+## Index
+
+| ID | Title | Feature | Persona | Status | Last audit |
+|----|-------|---------|---------|--------|------------|
+
+## Personas
+
+<!-- Every persona referenced below, 1-3 sentences each: who they are, what
+they know, what they want. Example:
+
+### new-user
+Opens the product for the first time. Knows nothing about it; wants to reach
+first value with zero reading.
+-->
+
+## Scenarios
+
+<!-- Group scenarios by feature under "## <feature>" headings. Entry shape
+(see scenario-format v1 for field rules):
+
+### SCN-001: <Title>
+- **Persona:** <persona-id>
+- **Feature:** <feature>
+- **Entry point:** <where the user starts>
+- **Preconditions:** <state required, or "none">
+- **Steps:**
+  1. <one user action per step>
+- **Expected result:** <what the user observes on success>
+- **UI elements:** <every button, field, link, dialog, toast involved>
+- **States covered:** <loading | empty | error | success>
+- **Errors & recovery:** <each failure: what the user sees, how they recover>
+- **Status:** draft
+- **Coverage:** none yet
+-->