create-issflow 1.9.1 → 1.10.0

package/README.md

@@ -32,7 +32,7 @@ The portable kit (every tool) in `<project>/.issflow/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
 - `commands/` — `/overview` `/feature` `/goal` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
-- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards
+- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · ui-ux-pro-max · security · code-standards
 - `hooks/` — session-start · context-guard · plan-gate (rule-13 enforcement) · pre-compact · subagent-stop · feature-gate (Stop gate for `/feature`, artifact-verified)
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)
 

package/bin/cli.js

@@ -227,8 +227,8 @@ function agentsMd() {
     '`/change-request` · `/replan` · `/synthesize` · `/runbook` · `/store-wisdom` ·',
     '`/log-issue` · `/log-decision` · `/unstuck`', '',
     '## Skills — `.issflow/skills/` (loaded on demand)', '',
-    'caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards ·',
-    'support-triage', '',
+    'caveman · grill-me · karpathy-guidelines · ux-design · ui-ux-pro-max · security ·',
+    'code-standards · support-triage', '',
     '## Autonomy', '',
     'Planning (`/overview` grill + plan approval) always asks — that input is cheap.',
     '**AUTO (default)** governs the DEV loop: follow the plan, decide + log + continue,',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.issflow/README.md

@@ -14,7 +14,7 @@ This directory is the **portable workflow kit** (tool-agnostic). Every
 |------|------|
 | `agents/` | Fresh-context workers (planner, researcher, implementer, …) |
 | `commands/` | Procedures — Default: `/overview` `/feature` `/quick`; Advanced: `/propose` `/design` `/support` … |
-| `skills/` | On-demand cookbooks (ux-design, security, support-triage, …) |
+| `skills/` | On-demand cookbooks (ux-design, ui-ux-pro-max, security, support-triage, …) |
 | `hooks/` | Lifecycle enforcement scripts |
 | `istartsoft-flow/` | METHODOLOGY.md — every hard rule lives here once |
 | `templates/` | Proposal / UX pack / architecture / CR / FEATURE / automation |

package/template/.issflow/commands/design.md

@@ -24,13 +24,19 @@ and STOP. Write nothing.
 Target: `$ARGUMENTS` → `ux` | `arch` | `both` (default **both**).
 
 ## STEP 1 — UX PACK (if ux|both)
-1. Apply `ux-design` skill (authoring mode): wireframe baseline + cookbook direction.
-2. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
-3. Fill flows, screen inventory, tokens/frame, a11y notes from OVERVIEW + PLAN.
-4. SHOW me UX-PACK.md. **STOP for approval.**
-5. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
+1. Apply `ui-ux-pro-max` (visual direction): run the kit engine
+   `.issflow/skills/ui-ux-pro-max/scripts/search.py --design-system` from
+   OVERVIEW product + industry. Fold into UX-PACK tokens — do not create a
+   parallel `design-system/` SoT. If Python 3 is missing, ask me to install it
+   (do not install tools yourself).
+2. Apply `ux-design` skill (authoring mode): wireframe baseline + cookbook direction.
+   Catalogue output must still pass the cookbook (tokens, a11y, no emoji icons).
+3. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
+4. Fill flows, screen inventory, tokens/frame, a11y notes from OVERVIEW + PLAN.
+5. SHOW me UX-PACK.md. **STOP for approval.**
+6. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
    in STATE.md; HISTORY line `design v<n> approved`.
-6. On change request: revise and re-show; header stays PENDING.
+7. On change request: revise and re-show; header stays PENDING.
 
 ## STEP 2 — ARCHITECTURE (if arch|both)
 1. Dispatch `researcher` (DESIGN) only if open unknowns remain; else use OVERVIEW.

package/template/.issflow/commands/phase.md

@@ -119,6 +119,8 @@ for the slice using the declared E2E runner (it brings the test stack up/down
 itself). Then run the `ux-design` cookbook + wireframe check on the new UI
 (hard rule 9): the UI must match the wireframe frame and pass the cookbook
 (tokens, a11y/WCAG AA, states, breakpoints). A `ux-design` BLOCK is a GATE FAIL.
+Do not re-run `ui-ux-pro-max` `--design-system` here — the look is locked in the
+approved UX pack.
 Non-frontend phase -> skip §3c.
 
 PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).

package/template/.issflow/hooks/approval-policy.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function fail(message) {
+  return { ok: false, reason: message };
+}
+
+function within(root, relative) {
+  if (!relative || path.isAbsolute(relative)) return false;
+  const full = path.resolve(root, relative);
+  return full.startsWith(path.resolve(root) + path.sep);
+}
+
+function read(root, relative) {
+  if (!within(root, relative)) throw new Error('Path escapes repository');
+  return fs.readFileSync(path.join(root, relative), 'utf8');
+}
+
+function gitBlobSha(content) {
+  const bytes = Buffer.from(content, 'utf8');
+  return crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+}
+
+function activePlan(root, explicit) {
+  if (explicit) return explicit.replaceAll('\\', '/');
+  const pointer = path.join(root, 'docs', 'ACTIVE-PLAN');
+  if (fs.existsSync(pointer)) return fs.readFileSync(pointer, 'utf8').trim();
+  const plansDir = path.join(root, 'docs', 'plans');
+  if (fs.existsSync(plansDir) && fs.readdirSync(plansDir).some((name) => /^PLAN-.*\.md$/i.test(name))) {
+    throw new Error('docs/ACTIVE-PLAN is required when scoped plans exist');
+  }
+  return 'docs/PLAN.md'; // Legacy projects remain supported.
+}
+
+function matchesPath(pattern, relative) {
+  if (pattern.endsWith('/**')) return relative.startsWith(pattern.slice(0, -2));
+  return relative === pattern;
+}
+
+function validate(root, { planFile, changedFiles = [] } = {}) {
+  try {
+    const relativePlan = activePlan(root, planFile);
+    if (!within(root, relativePlan)) return fail('Invalid plan path');
+    const plan = read(root, relativePlan);
+    if (relativePlan === 'docs/PLAN.md') {
+      const match = plan.match(/^>\s*Approval:\s*(.+)$/mi);
+      if (!match || !/^approved\b/i.test(match[1].trim())) return fail('Legacy PLAN.md is not approved');
+      return { ok: true, mode: 'legacy', planFile: relativePlan, warning: 'Legacy approval is not revision-scoped; migrate to docs/plans/' };
+    }
+
+    const id = plan.match(/^#\s+(PLAN-[A-Za-z0-9-]+)\b/m)?.[1];
+    const revision = Number(plan.match(/^>\s*Revision:\s*(\d+)\s*$/mi)?.[1]);
+    if (!id || !Number.isSafeInteger(revision) || revision < 1) return fail('Plan ID or revision missing');
+    const approvalFile = `docs/approvals/${id}.json`;
+    const approval = JSON.parse(read(root, approvalFile));
+    if (approval.planId !== id || approval.revision !== revision) return fail('Approval is for a different plan ID or revision');
+    if (approval.planBlobSha !== gitBlobSha(plan)) return fail('Plan changed after approval; request a new approval');
+    if (!approval.approvedBy || !approval.approvedAt || !approval.approvalSource) return fail('Approval provenance is incomplete');
+    if (!Array.isArray(approval.allowedPaths) || approval.allowedPaths.length === 0 ||
+        !approval.allowedPaths.every((p) => typeof p === 'string' && p.length > 0 && !p.includes('..') && !p.startsWith('/'))) {
+      return fail('Approved path boundaries are missing or invalid');
+    }
+    for (const file of changedFiles) {
+      const normalized = file.replaceAll('\\', '/');
+      if (!within(root, normalized) || !approval.allowedPaths.some((p) => matchesPath(p, normalized))) {
+        return fail(`File outside approved plan scope: ${file}`);
+      }
+    }
+    return { ok: true, mode: 'scoped', planFile: relativePlan, planId: id, revision, approval };
+  } catch (error) {
+    return fail(`Approval verification failed: ${error.message}`);
+  }
+}
+
+module.exports = { validate, gitBlobSha, activePlan, matchesPath };

package/template/.issflow/hooks/plan-gate.js

@@ -1,64 +1,57 @@
 #!/usr/bin/env node
-// PreToolUse plan gate — hard rule 13 as code. While docs/PLAN.md carries
-// `> Approval: PENDING`, no SOURCE file may be created or edited: the plan
-// needs a human sign-off before build work starts. Docs, kit config, and
-// planning artifacts stay writable (planning is exactly what PENDING is for).
-// An active feature lane is exempt — its doc approval is its own rule-13-scoped
-// gate and it never touches the main PLAN. Fail-OPEN on any error: a hook bug
-// must never wedge the tool loop. Pure Node, cross-platform, zero deps.
 'use strict';
-const fs = require('fs');
-const path = require('path');
 
-const silent = () => process.exit(0);
-const deny = (reason) => {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
-  }));
-  process.exit(0);
-};
-
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (d) => (input += d));
-process.stdin.on('end', () => {
-  let evt;
-  try { evt = JSON.parse(input); } catch (_) { return silent(); }
-  try { run(evt); } catch (_) { silent(); }
-});
-
-function run(evt) {
-  const MUTATORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
-  if (!MUTATORS.has(evt.tool_name || '')) return silent();
-
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || '.';
-  const read = (f) => { try { return fs.readFileSync(path.join(projectDir, f), 'utf8'); } catch (_) { return null; } };
-
-  const plan = read(path.join('docs', 'PLAN.md'));
-  if (!plan) return silent();                              // no plan world (e.g. /quick-only repo)
-  const approval = plan.match(/^>\s*Approval:\s*(.+)$/m);
-  if (!approval) return silent();                          // not our PLAN format — don't guess
-  if (!/pending/i.test(approval[1])) return silent();      // signed off — build away
+// Claude PreToolUse guard. Shell commands and other hosts require the CLI/CI verifier.
+const path = require('node:path');
+const { validate } = require('./approval-policy');
 
-  // the feature lane carries its own scoped approval and never edits the main PLAN.
-  const state = read(path.join('docs', 'STATE.md')) || '';
-  if (/^\s*feature:\s*\S+\s*\(active\)/m.test(state)) return silent();
+const MUTATORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
-  const file = String((evt.tool_input || {}).file_path || (evt.tool_input || {}).notebook_path || '');
-  if (!file) return silent();
-  const rel = path.relative(projectDir, path.resolve(projectDir, file)).split(path.sep).join('/');
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }) + '\n');
+}
 
-  // writable while PENDING: planning + docs + kit + repo meta — never product source.
-  const ALLOW = [
-    /^docs\//, /^\.issflow\//, /^\.claude\//, /^\.cursor\//, /^\.github\//, /^\.aider/, /^\.git/,
-    /^(README|AGENTS|CLAUDE|GEMINI|CHANGELOG|LICENSE)[^/]*$/i, /^[^/]+\.md$/,
-  ];
-  if (ALLOW.some((re) => re.test(rel))) return silent();
+function safePlanningPath(relative) {
+  return /^docs\/plans\/PLAN-[\w-]+\.md$/.test(relative) ||
+    /^docs\/features\/[\w.-]+\/(PLAN|FEATURE)\.md$/.test(relative) ||
+    relative === 'docs/ACTIVE-PLAN';
+}
 
-  deny(
-    `PLAN-APPROVAL gate (hard rule 13): docs/PLAN.md still reads "> Approval: PENDING", ` +
-    `so source changes are blocked (attempted: ${rel}). Get the plan signed off first — ` +
-    `run /overview's PLAN-APPROVAL step (or /replan, then re-approve) and stamp the header ` +
-    `"> Approval: approved <date> v<n>". Planning artifacts under docs/ stay writable.`
-  );
+function run(event) {
+  if (!MUTATORS.has(event.tool_name)) return;
+  const root = path.resolve(process.env.CLAUDE_PROJECT_DIR || event.cwd || process.cwd());
+  const input = event.tool_input || {};
+  const paths = event.tool_name === 'MultiEdit'
+    ? [input.file_path]
+    : [input.file_path || input.notebook_path];
+  if (paths.some((p) => typeof p !== 'string' || !p.trim())) {
+    return deny('Approval gate cannot determine target path');
+  }
+  const relative = paths.map((p) => path.relative(root, path.resolve(root, p)).split(path.sep).join('/'));
+  if (relative.some((p) => p.startsWith('..') || path.isAbsolute(p))) {
+    return deny('Cannot edit outside repository');
+  }
+  if (relative.every(safePlanningPath)) return;
+  if (relative.some((p) => /^docs\/approvals\//.test(p))) {
+    return deny('Approval records require a separate owner-controlled action');
+  }
+  const result = validate(root, { changedFiles: relative });
+  if (!result.ok) deny(`Plan approval required: ${result.reason}`);
 }
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    run(JSON.parse(raw));
+  } catch (error) {
+    deny(`Approval gate error: ${error.message}`);
+  }
+});

package/template/.issflow/hooks/verify-approval.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const { validate } = require('./approval-policy');
+
+function main(args) {
+  const root = process.cwd();
+  const baseIndex = args.indexOf('--base');
+  const filesIndex = args.indexOf('--files');
+  const planIndex = args.indexOf('--plan');
+  if (baseIndex !== -1 && filesIndex !== -1) throw new Error('Choose --base or --files');
+  const planFile = planIndex < 0 ? undefined : args[planIndex + 1];
+  let changedFiles = [];
+  if (baseIndex >= 0) {
+    const base = args[baseIndex + 1];
+    if (!base || base.startsWith('--')) throw new Error('Missing --base value');
+    const mergeBase = execFileSync('git', ['merge-base', base, 'HEAD'], { cwd: root, encoding: 'utf8' }).trim();
+    const diff = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMRT', mergeBase, 'HEAD'], { cwd: root, encoding: 'utf8' });
+    changedFiles = diff.split(/\r?\n/).filter(Boolean);
+  } else if (filesIndex >= 0) {
+    const files = args[filesIndex + 1];
+    if (!files || files.startsWith('--')) throw new Error('Missing --files value');
+    changedFiles = files.split(',').map((f) => f.trim()).filter(Boolean);
+  }
+  const result = validate(root, { planFile, changedFiles });
+  if (!result.ok) {
+    console.error(`BLOCKED: ${result.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Approval verified: ${result.planId || 'legacy'}${result.revision ? ` revision ${result.revision}` : ''}`);
+  if (result.warning) console.warn(result.warning);
+  console.log(`Checked ${changedFiles.length} changed file(s)`);
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(`BLOCKED: ${error.message}`);
+  process.exitCode = 1;
+}

package/template/.issflow/istartsoft-flow/METHODOLOGY.md

@@ -34,10 +34,56 @@
 
 Caveman ULTRA mode always on. Apply the `karpathy-guidelines` skill (engineering
 discipline) on every coding and debugging task. Apply the `ux-design` skill (the UX
-cookbook + wireframe baseline) on every UI-facing task. Apply the `security` skill
-(the Secure SDLC cookbook) at design (threat model), while coding (secure coding),
-and before any deploy. Apply the `code-standards` skill (naming per the language's
-own idiom + the declared architecture) on every coding task.
+cookbook + wireframe baseline) on every UI-facing task. When **authoring** a new
+visual direction (`/design`, or no approved UX-PACK yet), apply `ui-ux-pro-max`
+first and fold the look into the UX pack — do not re-roll styles at phase CLOSE.
+Apply the `security` skill (the Secure SDLC cookbook) at design (threat model),
+while coding (secure coding), and before any deploy. Apply the `code-standards`
+skill (naming per the language's own idiom + the declared architecture) on every
+coding task.
+
+-----
+
+## Plan-scoped approvals (new work)
+
+For each new task, create one `docs/plans/PLAN-<id>.md` with a unique ID, revision,
+scope, changed-file boundaries, acceptance criteria, tests, and risks. Set
+`docs/ACTIVE-PLAN` to its relative path. One human approval authorizes exactly
+one plan revision, not other plans or future edits to that plan.
+
+Approval is recorded separately in `docs/approvals/PLAN-<id>.json` with
+`planId`, `revision`, `planBlobSha` (Git blob SHA-1 of the exact Markdown),
+`approvedBy`, `approvedAt`, `approvalSource`, and `allowedPaths`.
+The approval record is created only after explicit human consent. Revisions,
+including seemingly small edits, invalidate the old digest and require new approval.
+Do not let an agent self-approve a plan.
+
+Use `node .issflow/hooks/verify-approval.js --base origin/main` to check the
+active plan and changed paths. Run `node --test tests/approval-policy.test.js`
+when those tests are installed. For an existing project with only `docs/PLAN.md`,
+the verifier retains legacy `> Approval: approved ...` compatibility and warns
+that it is not revision-scoped. Migrate intentionally, not by silently rewriting
+existing plans.
+
+**Enforcement boundary:** The Claude PreToolUse hook protects supported file-edit
+tools; it does not intercept shell commands, GitHub API writes, or every Codex
+execution mode. The verifier checks the local checkout/PR diff, but a writable
+approval JSON is not cryptographic proof of the human approver. Require protected
+branches, required CI checks, and an actual human GitHub PR review for merge.
+No tool can treat a self-edited approval file as owner authorization.
+
+**Recovery:** If approval metadata is missing or malformed, stop implementation.
+A human should inspect the plan, restore the correct pointer and approval record,
+then rerun verification. Never bypass the gate by editing `STATE.md` or disabling
+checks. A scoped feature lane does not inherit approval from another plan.
+
+**Engineering:** Prefer feature-based modules and vertical slices. Keep route
+adapters thin; put business rules near their feature. Use idiomatic names,
+cohesive files, explicit contracts, and minimal abstractions. Comments explain
+non-obvious intent, not line-by-line mechanics. Use concise Conventional Commit
+subjects (`feat(scope): change`, `fix(scope): change`); avoid tool signatures
+and promotional boilerplate while preserving truthful Git author/committer
+metadata and any required disclosures.
 
 -----
 
@@ -155,7 +201,7 @@ those gates, never the plan, the money, or the design/arch frame.
 | House role | Kit surface |
 |------------|-------------|
 | BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates |
-| UX / UI | `/design` (UX pack) · `ux-design` skill · `/ui-audit` · rule 9 CLOSE |
+| UX / UI | `/design` (UX pack) · `ui-ux-pro-max` (look) · `ux-design` (frame + gate) · `/ui-audit` · rule 9 CLOSE |
 | Architect | `/design` (ARCHITECTURE) · `researcher` DESIGN · `code-standards` · `/log-decision` |
 | Developer | `implementer` · `/phase` · `/feature` · `/quick` |
 | QA | `test-author` · `e2e-runner` · `/qa-audit` · `/uat` |
@@ -691,6 +737,8 @@ the KB. The kit works normally without a KB.
   `scripts/regression.sh` (default mock; `--real` runs the real corpus).
 - `.issflow/skills/ux-design/` — the UX cookbook + wireframe baseline (read on
   demand for any UI work).
+- `.issflow/skills/ui-ux-pro-max/` — visual direction for `/design` (vendored
+  search engine + catalogue; MIT upstream).
 - `.issflow/skills/security/` — the Secure SDLC cookbook + threat-modeling /
   secure-coding / pentest / standards references (read on demand for security work).
 - `.issflow/skills/code-standards/` — naming-per-language + architecture cookbook

package/template/.issflow/skills/ui-ux-pro-max/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Next Level Builder
+
+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/template/.issflow/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: ui-ux-pro-max
+description: >
+  Design intelligence for NEW visual direction — styles, palettes, type, landing
+  patterns. Use when authoring `/design` UX-PACK, setting OVERVIEW UX direction,
+  or the project has no approved UX pack yet. Triggers: "/design", "UX pack",
+  "visual direction", "design system", "palette", "typography", "landing pattern",
+  "ทิศทางดีไซน์", "โทนสี". Skip for backend, and skip re-rolling styles when an
+  approved UX-PACK already exists (follow that frame; validate with ux-design).
+---
+
+# ui-ux-pro-max — visual direction (authoring)
+
+Vendored from [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)
+(MIT — see `LICENSE.upstream` + `UPSTREAM.md`). Engine lives **in this folder**.
+
+`ux-design` remains the **gate** (hard rule 9 — wireframe + cookbook). This skill
+picks the **look**. Do not let a catalogue restyle override an approved UX pack.
+
+## When
+
+- `/design` STEP 1 (author the UX pack) — **required** when UI is in scope.
+- First visual direction (OVERVIEW UX / no approved `docs/UX-PACK.md`).
+- Human explicitly asks to restyle — then re-run and wait for UX-PACK re-approve.
+
+**Not** at `/phase` CLOSE. CLOSE = `ux-design` cookbook against the approved pack.
+Do not run `--design-system` again per slice.
+
+## Engine
+
+```
+python3 .issflow/skills/ui-ux-pro-max/scripts/search.py
+```
+
+If this project's kit was mirrored for Claude Code, the same files exist under
+`.claude/skills/ui-ux-pro-max/` — use whichever path is present.
+
+Try `python3`, then `python`, then `py -3`. Stdlib only. If Python 3 is missing,
+**ask the human** to install it (python.org / Homebrew / apt). Do not install
+Python or npm yourself. Do not tell them to run `uipro init` — the catalogue
+is already in the kit.
+
+On-demand detail: `references/quick-reference.md`, `references/pro-rules.md`.
+
+## Authoring workflow
+
+1. Product / industry / keywords from OVERVIEW + PLAN (2–5 terms). Detect stack
+   from the project; never assume HTML+Tailwind.
+2. Run:
+
+```
+python3 .issflow/skills/ui-ux-pro-max/scripts/search.py "<product> <industry> <keywords>" --design-system -p "<project>" -f markdown
+```
+
+   Retry once if empty. Do not persist unverified output. Do **not** pass
+   `--persist` / do **not** write a parallel `design-system/` tree — fold into
+   `docs/UX-PACK.md` → Frame & tokens (style, palette, type, effects,
+   anti-patterns). Kit SoT stays UX-PACK.
+3. Optional domain search only for a named gap:
+
+```
+python3 .issflow/skills/ui-ux-pro-max/scripts/search.py "<query>" --domain ux|icons|chart|typography|style|color|landing
+python3 .issflow/skills/ui-ux-pro-max/scripts/search.py "<query>" --stack <detected>
+```
+
+4. Then apply `ux-design` authoring (wireframe + cookbook). Catalogue must still
+   pass: no emoji icons, tokens not raw hex in components, WCAG AA.
+
+If UX-PACK is already **approved**, read it and stop — unless the human asked to
+change the look.

package/template/.issflow/skills/ui-ux-pro-max/UPSTREAM.md

@@ -0,0 +1,4 @@
+upstream: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
+commit: 623a9a9
+license: MIT (LICENSE.upstream)
+omitted: scripts/tests, validate_data.py, phosphor-icons-upstream.json, google-font-licenses.json

package/template/.issflow/skills/ui-ux-pro-max/data/app-interface.csv

@@ -0,0 +1,33 @@
+No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
+1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"<Pressable accessibilityLabel=""Close""><XIcon /></Pressable>",<Pressable><XIcon /></Pressable>,Critical
+2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"<View><Text>Email</Text><TextInput accessibilityLabel=""Email address"" /></View>","<TextInput placeholder=""Email"" /></View>",Critical
+3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"<Pressable accessibilityRole=""button"">Submit</Pressable>",<View onTouchStart={submit}>Submit</View>,High
+4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"<Text accessibilityLiveRegion=""polite"">{status}</Text>",<Text>{status}</Text>,Medium
+5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"<Icon accessible={false} importantForAccessibility=""no"" />",<Icon />,Medium
+6,Touch,Touch Target Size,touch target size platform runtime arbitration iOS 44pt Android 48dp web 24 CSS px React Native hitSlop,iOS/Android/React Native,Native targets use 44pt on iOS and 48dp on Android; web WCAG 2.2 has a separate 24 by 24 CSS px minimum with exceptions,Select 44pt for iOS and 48dp for Android at runtime; evaluate web targets separately against WCAG 2.5.8 and its exceptions,"Collapse iOS 44pt, Android 48dp, and web 24 CSS px into one cross-platform number","Platform.select({ ios: 44, android: 48 }); // web: evaluate 24 CSS px + WCAG exceptions",<Pressable><Icon size={16} /></Pressable>,Critical
+7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,<View style={{ gap: 8 }}><Button ... /><Button ... /></View>,<View><Button ... /><Button ... /></View>,Medium
+8,Touch,Gesture Conflicts,scroll swipe back gesture,iOS/Android/React Native,Custom gestures must not break system scroll/back,Reserve horizontal swipes for carousels,Full-screen custom swipe conflicting with back,HorizontalPager inside vertical ScrollView,PanResponder on full screen blocking back,High
+9,Navigation,Back Behavior,back handler navigation stack,iOS/Android/React Native,Back navigation should be predictable and preserve state,Use navigation.goBack and keep screen state,Reset stack or exit app unexpectedly,onPress={() => navigation.goBack()},BackHandler.exitApp() on first press,Critical
+10,Navigation,Bottom Tabs,tab bar max items,iOS/Android/React Native,Bottom tab bar should have at most 5 primary items,Use 3–5 tabs and move extras to More/Settings,Overloaded tab bar with many icons,Home/Explore/Profile/Settings,Home/Explore/Shop/Cart/Profile/Settings/More,Medium
+11,Navigation,Modal Escape,modal dismiss close affordance,iOS/Android/React Native,Modals/sheets must have clear close actions,Provide close button and swipe-down where platform expects,Trapping users in modal with no obvious exit,"<Modal><Button title=""Close"" onPress={onClose} /></Modal>",<Modal><View>{children}</View></Modal>,High
+12,State,Preserve Screen State,navigation preserve state,iOS/Android/React Native,Returning to a screen should restore its scroll and form state,Keep components mounted or persist state,Reset list scroll and form inputs on every visit,<Tab.Navigator screenOptions={{ unmountOnBlur: false }}>,<Tab.Screen options={{ unmountOnBlur: true }} />,Medium
+13,Feedback,Loading Indicators,activity indicator skeleton,iOS/Android/React Native,Show visible feedback during network operations,Use ActivityIndicator or skeleton for >300ms operations,Leave button and screen frozen,"{loading ? <ActivityIndicator /> : <Button title=""Save"" />}"," ""<Button title=""""Save"""" onPress={submit} /> // no loading""",High
+14,Feedback,Success Feedback,toast checkmark banner,iOS/Android/React Native,Confirm successful actions with brief feedback,Show toast/checkmark or banner,Complete actions silently with no confirmation,showToast('Saved successfully'),// silently update state only,Medium
+15,Feedback,Error Feedback,inline error banner,iOS/Android/React Native,Show clear error messages near the problem,input-level error + summary banner,Only change border color with no explanation,<TextInput ... /><Text style={{color:'red'}}>{error}</Text>,<TextInput style={{borderColor:'red'}} />,High
+16,Forms,Inline Validation,onBlur validation,iOS/Android/React Native,Validate inputs on blur or submit with clear messaging,Validate onBlur and onSubmit,Validate on every keystroke causing jank,onBlur={() => validateEmail(value)},onChangeText={v => validateEmail(v)} // every char,Medium
+17,Forms,Keyboard Type,keyboardType returnKeyType,iOS/Android/React Native,Use appropriate keyboardType and returnKeyType,Match email/tel/number/search types,Use default keyboard for all inputs,"<TextInput keyboardType=""email-address"" />","<TextInput keyboardType=""default"" />",Medium
+18,Forms,Auto Focus & Next,autoFocus blurOnSubmit onSubmitEditing,iOS/Android/React Native,Guide users through form fields with Next/Done flows,Use onSubmitEditing to focus next input,Force users to tap each field manually,onSubmitEditing={() => nextRef.current?.focus()},"// no onSubmitEditing, manual tap only",Low
+19,Forms,Password Visibility,secureTextEntry toggle,iOS/Android/React Native,Allow toggling password visibility securely,Provide Show/Hide icon toggling secureTextEntry,Force users to type blind with no option,<TextInput secureTextEntry={secure} /><Icon onPress={toggle} />,<TextInput secureTextEntry /> // no toggle,Medium
+20,Performance,Virtualize Long Lists,FlatList SectionList virtualization,iOS/Android/React Native,Use FlatList/SectionList for lists over ~50 items,Use keyExtractor and initialNumToRender appropriately,Render hundreds of items with ScrollView,<FlatList data={items} renderItem={...} />,<ScrollView>{items.map(renderItem)}</ScrollView>,High
+21,Performance,Image Size & Cache,Image resize cache,iOS/Android/React Native,Use correctly sized and cached images,Use Image component with proper resizeMode and caching,Load full-resolution images everywhere,"<Image source={{uri}} resizeMode=""cover"" />",<Image source={require('4k.png')} /> // small avatar,Medium
+22,Performance,Debounce High-Freq Events,debounce scroll search,iOS/Android/React Native,Debounce scroll/search callbacks to avoid jank,Wrap handlers with debounce/throttle,Run heavy logic on every event,onScroll={debouncedHandleScroll},onScroll={handleScrollHeavy},Medium
+23,Animation,Duration & Easing,animation duration easing,iOS/Android/React Native,Micro-interactions should be 150–300ms with native-like easing,Use ease-out for enter/ease-in for exit,Use long or linear animations for core UI,"Animated.timing(..., { duration: 200, easing: Easing.out(Easing.quad) })","Animated.timing(..., { duration: 800, easing: Easing.linear })",Medium
+24,Animation,Respect Reduced Motion,reduced motion accessibility,iOS/Android/React Native,Respect OS reduced-motion accessibility setting,Check reduceMotionEnabled and simplify animations,Ignore user motion preferences,if (reduceMotionEnabled) skipAnimation(),Always run complex parallax animations,Critical
+25,Animation,Limited Continuous Motion,loop animation loader,iOS/Android/React Native,Reserve infinite animations for loaders and live data,Use looping only where necessary,Keep decorative elements looping forever,Animated.loop(loaderAnim) for ActivityIndicator,Animated.loop(bounceAnim) on background icons,Medium
+26,Typography,Base Font Size,fontScale dynamic type,iOS/Android/React Native,Body text must be readable and support Dynamic Type,Use platform fontScale and at least 14–16pt base,Render critical text below 12pt,<Text style={{ fontSize: 16 }}>Body</Text>,<Text style={{ fontSize: 10 }}>Body</Text>,High
+27,Typography,Dynamic Type Support,allowFontScaling adjustsFontSizeToFit,iOS/Android/React Native,Support system text scaling without breaking layout,Set allowFontScaling and test large text,Disable scaling on all text globally,<Text allowFontScaling>{label}</Text>,<Text allowFontScaling={false}>{label}</Text>,High
+28,Safe Areas,Safe Area Insets,safe area insets notch gesture,iOS/Android/React Native,Content must not overlap notches/gesture bars,Wrap screens in SafeAreaView or apply insets,Place tappable content under system bars,<SafeAreaView style={{ flex: 1 }}><Screen /></SafeAreaView>,<View style={{ flex: 1 }}><Screen /></View>,High
+29,Theming,Light/Dark Contrast,dark mode contrast tokens,iOS/Android/React Native,Ensure sufficient contrast in both light and dark themes,Use semantic tokens and test both themes,Reuse light-theme grays directly in dark mode,colors.textPrimaryDark = '#F9FAFB',colors.textPrimaryDark = '#9CA3AF' on '#111827',High
+30,Anti-Pattern,No Gesture-Only Actions,gesture only hidden controls,iOS/Android/React Native,Don't rely solely on hidden gestures for core actions,Provide visible buttons in addition to gestures,Rely on swipe/shake only with no UI affordance,Swipe to delete + visible Delete button,Only shake device to undo with no UI,Critical
+31,Accessibility,Dragging Alternatives,accessible drag interaction drag single pointer alternative keyboard drag alternative reorder resize move buttons React Native native runtime platform router arbitration iOS Android web,iOS/Android/React Native,React Native drag and reorder operations need a non-drag path selected for the active native runtime,Provide named Move up/down buttons or a position menu beside drag handles; route iOS and Android behavior through the runtime platform adapter,"Make drag, swipe, or a web-only pointer handler the only way to reorder native content","<Button title=""Move up"" onPress={() => moveItem(index, index - 1)} />",<DragHandle /> only,High
+32,Forms,Authentication Reuse,password manager passkey paste redundant entry,iOS/Android/React Native,Authentication and multi-step flows should reuse prior values,Support password managers passkeys paste and prefilled confirmed values,Force users to retype credentials or the same data in one flow,"textContentType=""password"" autoComplete=""current-password""",onPaste disabled,Critical

package/template/.issflow/skills/ui-ux-pro-max/data/catalog-summary.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 1,
+  "verifiedAt": "2026-08-26",
+  "counts": {
+    "styles": {
+      "total": 88,
+      "searchable": 79,
+      "active": 50,
+      "supplemental": 29,
+      "deprecated": 9
+    },
+    "products": 192,
+    "palettes": 192,
+    "reasoningProfiles": 192,
+    "fontPairings": 74,
+    "googleFonts": 1934,
+    "curatedIcons": 105,
+    "upstreamPhosphorIcons": 1512,
+    "uxGuidelines": 119,
+    "motionPresets": 17,
+    "chartTypes": 25,
+    "stacks": 22,
+    "stackGuidelines": 1271
+  },
+  "snapshots": {
+    "google-fonts.csv": {
+      "sha256": "1c8c3b2ea1faf6a1012da463756def8b3889db33f2226f0343bb4daa80307d03"
+    },
+    "google-font-licenses.json": {
+      "sha256": "35688523f2955795caa1a47c53b83099e60c1708461476f9cc3a050cf3b0148a"
+    },
+    "icons.csv": {
+      "sha256": "50816c6012030178195a16ee481ebf58b47bd985d70e8ec58886cc83f6eddafc"
+    },
+    "phosphor-icons-upstream.json": {
+      "sha256": "2399325233b277b5c97a80e6a5e8941154f5d057beee4e7613db87c87d700236"
+    }
+  },
+  "promotionPolicy": {
+    "changedFamilySetRequiresExplicitApproval": true,
+    "relevanceGateRequired": true,
+    "unlicensedFamiliesExcluded": true
+  },
+  "pendingCandidates": [
+    {
+      "family": "Edu NSW ACT Cursive",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Edu NSW ACT Hand Pre",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Edu QLD Hand",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Edu SA Hand",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Edu VIC WA NT Hand",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Edu VIC WA NT Hand Pre",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Google Sans",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    },
+    {
+      "family": "Google Sans Flex",
+      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
+    }
+  ]
+}