peaks-cli 1.0.12 → 1.0.13

package/skills/peaks-ui/references/artifact-per-request.md

@@ -0,0 +1,71 @@
+# UI per-request artifact contract
+
+Every UI invocation must leave one durable artifact under the workflow-local workspace so design and frontend behavior decisions are traceable later.
+
+## Required path
+
+```
+.peaks/<session-id>/ui/requests/<request-id>.md
+```
+
+Use the same `<request-id>` PRD assigned (`YYYY-MM-DD-<kebab-slug>`) so the PRD/UI/RD/QA records can be cross-linked.
+
+## Required content
+
+```markdown
+# UI Request <request-id>
+
+- linked-prd: .peaks/<session-id>/prd/requests/<request-id>.md
+- scope: full new surface | iteration on existing surface | regression fix | visual refresh
+- design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
+
+## Affected surfaces
+
+- pages / routes / components / modals / states (loading, empty, error, hover, focus, active, responsive)
+- explicit out-of-scope surfaces (do not modify)
+
+## UX flow and page states
+
+- entry points, primary flow, secondary flows, exit points
+- state machine per surface when state transitions matter
+
+## Visual constraints
+
+- typography pair: ...
+- palette: ...
+- density and motion intensity dials: ...
+- rejected generic patterns (centered stock hero, default card grid, AI gradients, etc.)
+
+## Interaction constraints
+
+- keyboard, focus order, ARIA roles, gesture support, accessibility minima
+
+## UI regression seeds
+
+- list of visible regressions QA must check against the prior state
+- browser paths and visible assertions QA can use directly
+
+## Browser evidence
+
+- sanitized observations only — no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs with PII / SSO / MFA material
+- where the Playwright MCP browser evidence is stored (`mcp__playwright__browser_take_screenshot` / `take_snapshot` outputs, sanitized)
+
+## Handoff
+
+- to peaks-rd: <link to RD request artifact>
+- to peaks-qa: <link to QA request artifact>
+
+## Status
+
+- created: <ISO timestamp>
+- last update: <ISO timestamp>
+- state: draft | direction-locked | handed-off | blocked
+```
+
+## Rules
+
+- Do not skip the UI artifact when the request touches user-visible behavior. Even bug fixes that change visible flow require a UI request artifact.
+- Tasteful direction is a constraint, not a suggestion: record the chosen direction and the rejected generic patterns so QA can fail a regression that drifts toward them.
+- Sanitize before writing — same rules as PRD/RD/QA.
+- Do not commit unless the user or active profile authorizes durable retention.
+- Handoff to RD/QA is blocked while state is `draft`.

package/skills/peaks-ui/references/workflow.md

@@ -8,23 +8,20 @@ Use this path before generating or accepting frontend UI:
 
 1. Pull visual direction from `awesome-design-md` style references or equivalent curated design markdown.
 2. Apply `taste-skill`/`design-taste-frontend` critique rules to set design variance, motion intensity, visual density, typography, palette, and interaction feel.
-3. Use HyperFrames as a reference for HTML-native timeline ideas, kinetic overlays, animated captions, data motion, shader-like transitions, and cinematic state changes, without installing its runtime unless explicitly approved. If the workflow requires actual HyperFrames skills/runtime and they are missing, mark the step blocked and tell the user to install manually with `npx skills add heygen-com/hyperframes` before continuing that path.
-4. Produce a concrete visual direction, not vague “clean modern” language.
-5. Define a motion budget: allowed animated properties, max intensity, reduced-motion behavior, lazy-loading expectations, and performance evidence required.
-6. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
-7. Require meaningful loading, empty, error, hover, focus, active, responsive, and reduced-motion states.
-8. Launch the app with the project command, capture the actual advertised URL from server output/config/user input, and use headed `gstack/browse/dist/browse` on that URL to inspect real browser output; visible browser confirmation is mandatory, default framework ports must not be guessed, gstack instability blocks the browser gate instead of falling back to Playwright MCP, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
-9. If the browser view looks generic, visually weak, broken, inaccessible, slow, janky, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
+3. Produce a concrete visual direction, not vague “clean modern” language.
+4. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
+5. Require meaningful loading, empty, error, hover, focus, active, and responsive states.
+6. Use Playwright MCP on the running page or prototype to inspect real browser output (install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if not yet present; open with `mcp__playwright__browser_navigate` / `navigate_page`, capture with `take_snapshot` and `take_screenshot`); visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
+7. If the browser view looks generic, visually weak, broken, inaccessible, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
 
 ## Outputs
 
 - UX flow;
 - page state map;
 - visual direction with references;
-- design dials, motion budget, and rejected generic patterns;
+- design dials and rejected generic patterns;
 - interaction constraints;
-- headed `gstack/browse/dist/browse` browser observations when frontend output exists;
+- Playwright MCP browser observations when frontend output exists (`mcp__playwright__browser_snapshot`, `take_screenshot`, `list_console_messages`, `list_network_requests`);
 - UI regression seeds;
-- accessibility and reduced-motion notes;
-- performance evidence for animation-heavy UI;
+- accessibility notes;
 - taste report.

package/scripts/strip-internal-exports.mjs

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const distSrcRoot = join(packageRoot, 'dist', 'src');
-const internalExportPattern = /\/\*\* @internal \*\/\r?\nexport const testInternals = \{[\s\S]*?\r?\n\};\r?\n?/g;
-
-function getJavaScriptFiles(directory) {
-  return readdirSync(directory).flatMap((entry) => {
-    const path = join(directory, entry);
-    const stats = statSync(path);
-    if (stats.isDirectory()) {
-      return getJavaScriptFiles(path);
-    }
-    return stats.isFile() && path.endsWith('.js') ? [path] : [];
-  });
-}
-
-for (const filePath of getJavaScriptFiles(distSrcRoot)) {
-  const source = readFileSync(filePath, 'utf8');
-  if (!source.includes('testInternals')) {
-    continue;
-  }
-
-  const strippedSource = source.replace(internalExportPattern, '');
-  if (strippedSource === source || strippedSource.includes('testInternals')) {
-    throw new Error(`Failed to strip internal test export from ${filePath}`);
-  }
-  writeFileSync(filePath, strippedSource, 'utf8');
-}