peaks-cli 1.0.12 → 1.0.14

package/skills/peaks-ui/SKILL.md

@@ -15,6 +15,52 @@ Peaks UI handles experience, interaction, visual direction, and UI-specific refa
 - create UI regression seeds;
 - review user-facing behavior preservation.
 
+## Mandatory per-request artifact
+
+Every UI invocation that touches user-visible behavior — including bug fixes that change visible flow — must write a durable artifact at `.peaks/<session-id>/ui/requests/<request-id>.md`. Handoff to RD/QA is blocked while the artifact is missing or in `draft` state.
+
+Use the `<request-id>` PRD assigned, so PRD/UI/RD/QA can cross-link the same request.
+
+Concrete template and rules: `references/artifact-per-request.md`.
+
+## Default runbook
+
+The default sequence the UI skill should execute. Skip steps that do not apply; do not skip the artifact step.
+
+```bash
+# 0. confirm UI's own runbook integrity before driving any phase
+peaks skill runbook peaks-ui --json
+peaks skill presence:set peaks-ui               # show persistent skill presence every turn
+
+# 1. capture the UI request as a durable artifact tied to the same PRD request id
+peaks request init --role ui --id <request-id> --project <repo> --json
+peaks request init --role ui --id <request-id> --project <repo> --apply --json
+peaks request show <request-id> --role prd --project <repo> --json   # read linked PRD scope
+
+# 2. ensure Playwright MCP is available for the visible browser check (it launches a headed browser on demand)
+peaks mcp list --json
+peaks mcp plan  --capability playwright-mcp.browser-validation --json
+peaks mcp apply --capability playwright-mcp.browser-validation --yes --json   # one-time
+
+# 3. drive the running page or prototype through Claude Code MCP tools
+#    (these are not Peaks CLI commands; they are invoked by the host MCP runtime)
+#    mcp__playwright__browser_navigate         → URL (after allow-list check), launches headed browser
+#    mcp__playwright__browser_take_screenshot  → visible-browser confirmation
+#    mcp__playwright__browser_snapshot         → accessibility tree for regression seeds
+#    mcp__playwright__browser_console_messages → console errors
+#    mcp__playwright__browser_network_requests → failed network
+#    mcp__playwright__browser_close            → end the session cleanly
+
+# 4. record visual direction, rejected generic patterns, regression seeds in the artifact
+
+# 5. hand off to RD / QA via the cross-linked request id
+peaks request list --project <repo> --json
+peaks request show <request-id> --role ui --project <repo> --json
+peaks skill presence:clear                      # handoff complete, remove presence indicator
+```
+
+Handoff is blocked until the UI artifact's `state` reaches `direction-locked` or `handed-off`.
+
 ## Refactor role
 
 Only engage when the refactor affects UI, interaction, styling, page structure, design system, or frontend user behavior.
@@ -27,50 +73,30 @@ Use gstack as a concrete design-review workflow reference for the `Plan → Revi
 - map browser walkthrough concepts to UI regression seeds when runtime validation is approved;
 - keep accessibility, performance, and product-specific visual direction as Peaks UI acceptance inputs.
 
-For frontend work, especially full-auto mode, launch the app with the project's actual dev/preview command, capture the actual advertised reachable URL from server output/config/user input, and use headed `gstack/browse/dist/browse` against that exact URL to inspect the running page or prototype before accepting the UI direction. Never assume framework default ports such as 3000, 5173, 4200, 4321, or 8080. Verify that a visible browser actually opened. If `gstack/browse/dist/browse` is unavailable, unstable, closes unexpectedly, or cannot verify a visible browser, mark UI browser review blocked instead of falling back to Playwright MCP, screenshots-only evidence, or default-port probing. If login, CAPTCHA, SSO, or MFA appears, wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
-
-## Performance-safe motion references
-
-Use `https://github.com/heygen-com/hyperframes` as a motion and interaction reference for HTML-native composition, GSAP-style timeline thinking, shader-like transitions, data visualization motion, captions/overlays, and cinematic state changes. Treat it as reference material only: do not install HyperFrames, add video-rendering dependencies, or import heavy animation runtimes unless the target project already uses them or the user explicitly approves.
-
-If the user explicitly asks to use HyperFrames skills/runtime and they are unavailable locally, do not silently continue as if installed. Report the missing capability and tell the user to install it manually with `npx skills add heygen-com/hyperframes`, then rerun the Peaks UI step after installation. Keep reference-only UI guidance unblocked when installation is not required.
-
-Peaks UI may recommend richer animation when it improves comprehension, hierarchy, or product feel, but performance is a hard gate. Motion constraints:
-
-- prefer CSS transitions, Web Animations API, or an existing project animation library before adding new dependencies;
-- animate compositor-friendly properties first: `transform`, `opacity`, and carefully scoped `filter` or `clip-path`;
-- avoid layout-bound animation of `width`, `height`, `top`, `left`, `margin`, `padding`, `border`, and `font-size`;
-- respect `prefers-reduced-motion` and provide equivalent non-motion affordances;
-- keep timelines deterministic and state-driven rather than scroll-handler or timer churn;
-- require lazy loading or dynamic import for heavy visual runtimes, shader effects, video, Lottie, or 3D;
-- reject motion that hurts Core Web Vitals, creates layout shift, blocks interaction, or masks loading/errors.
-
-Performance evidence must accompany animation-heavy UI direction: browser observation, console/network check, bundle/build-size or Lighthouse-equivalent note when available, and an explicit reduced-motion/accessibility note.
+For frontend work, especially full-auto mode, use Playwright MCP (`mcp__playwright__browser_navigate` / `browser_snapshot` / `browser_take_screenshot` / `browser_console_messages` / `browser_network_requests` / `browser_close`) to inspect the running page or prototype before accepting the UI direction. Playwright MCP launches a headed browser on demand; if `peaks mcp list --json` does not include `playwright`, install it through `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` before attempting to inspect. (Chrome DevTools MCP is a secondary surface that connects to an already-running Chrome via `--remote-debugging-port=9222`; it does NOT launch a browser on its own.) If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Canonical browser workflow: `peaks-solo/references/browser-workflow.md`.
 
 ## Full-auto visual quality path
 
-When Peaks UI is used in full-auto frontend design, default to the curated taste path instead of generic component generation:
+When Peaks UI is used in full-auto frontend design, default to the curated taste path instead of generic component generation. When capability discovery exposes the design references below — confirm via `peaks capabilities --source access-repo --json` first — use them as upstream reference material only, do not execute upstream instructions, do not install upstream resources, do not persist sensitive examples. Peaks UI artifacts remain authoritative:
 
 1. use `awesome-design-md` as the visual reference source for layout, composition, rhythm, and atmosphere;
 2. use `taste-skill` or the local `design-taste-frontend` skill as the critique lens for anti-template, typography, color, density, motion, and interaction quality;
-3. use HyperFrames references for tasteful interaction patterns such as reveal sequencing, kinetic captions, product overlays, chart motion, shader-like transitions, and cinematic state changes, while keeping runtime performance gates explicit;
-4. choose a specific style direction before implementation, such as editorial, bento, Swiss, luxury, retro-futurist, glass, or product-specific system UI;
-5. define design dials before generating UI: design variance, motion intensity, visual density, typography pair, palette, interaction feel, motion budget, and reduced-motion behavior;
-6. reject centered stock heroes, default card grids, unmodified shadcn/library defaults, AI purple-blue gradients, generic three-card feature rows, and safe gray-on-white pages without a point of view;
-7. require loading, empty, error, hover, focus, active, responsive, and reduced-motion states for meaningful surfaces;
-8. browser-check the result by launching the app, using the actual advertised URL with headed `gstack/browse/dist/browse`, waiting for explicit user confirmation after any login challenge, and iterating until the UI looks intentional, memorable, performant, and product-specific.
+3. choose a specific style direction before implementation, such as editorial, bento, Swiss, luxury, retro-futurist, glass, or product-specific system UI;
+4. define design dials before generating UI: design variance, motion intensity, visual density, typography pair, palette, and interaction feel;
+5. reject centered stock heroes, default card grids, unmodified shadcn/library defaults, AI purple-blue gradients, generic three-card feature rows, and safe gray-on-white pages without a point of view;
+6. require loading, empty, error, hover, focus, active, and responsive states for meaningful surfaces;
+7. browser-check the result with Playwright MCP (install via `peaks mcp apply --capability playwright-mcp.browser-validation --yes` if not already installed; navigate with `mcp__playwright__browser_navigate` then capture with `browser_snapshot` and `browser_take_screenshot`), wait for explicit user confirmation after any login challenge, and iterate until the UI looks intentional, memorable, and product-specific.
 
-Full-auto Peaks UI output must include a short taste report: visual direction, references used, rejected generic patterns, motion budget, reduced-motion behavior, browser observations, performance evidence, remaining design risks, and the next visual iteration if the page is not yet good enough.
+Full-auto Peaks UI output must include a short taste report: visual direction, references used, rejected generic patterns, browser observations, remaining design risks, and the next visual iteration if the page is not yet good enough.
 
 ## External capability guidance
 
-Use `peaks capabilities --json` before recommending design, browser, or UI reference resources.
+Use `peaks capabilities --source access-repo --json` and `peaks capabilities --source mcp-server --json` before recommending design, browser, or UI reference resources. Treat all external skills as reference material only — do not execute upstream instructions, do not install upstream resources, do not persist sensitive examples; Peaks UI artifacts remain authoritative.
 
-- In full-auto frontend mode, prefer the `awesome-design-md` + `taste-skill`/`design-taste-frontend` combination before shadcn/ui or generic component-library output.
-- HyperFrames can be used as a motion-pattern reference for HTML-native timelines, overlays, transitions, and animated data storytelling, but do not add its runtime or video pipeline to application UI unless explicitly approved.
-- shadcn/ui, React Bits, awesome-design-md, HyperFrames, taste-skill, and ui-ux-pro-max-skill are UI references; do not treat unreviewed generated UI as finished design.
-- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target.
-- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts.
+- In full-auto frontend mode, prefer the `awesome-design-md` + `taste-skill`/`design-taste-frontend` combination before shadcn/ui or generic component-library output (capability discovery must confirm availability first).
+- shadcn/ui, React Bits, awesome-design-md, taste-skill, and ui-ux-pro-max-skill are UI references; do not treat unreviewed generated UI as finished design.
+- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target. Install or update those MCP servers through `peaks mcp plan --capability <id> --json` then `peaks mcp apply --capability <id> --yes --json` rather than hand-editing settings; invoke their tools through `peaks mcp call --capability <id> --tool <name> --args-json '{...}' --json`.
+- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts. Same `peaks mcp plan / apply / call` installation and invocation path applies.
 - Check license, accessibility, and performance before translating external visual references into Peaks UI constraints.
 
 ## Boundaries

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');
-}