create-harness-vibe-coding 0.1.8 → 0.1.10

package/templates/common/docs/harness/extension.md

@@ -4,6 +4,17 @@ Purpose: keep stack-specific agents, skills, rules, and hooks compatible with th
 
 Use during setup whenever adding assets from ECC, SuperClaude, toolboxes, or local project conventions.
 
+## Non-Invasive Extension Rules
+
+Extensions must preserve project and harness ownership boundaries.
+
+- Preserve existing `.claude/`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`, `docs/README.md`, `docs/workflows/*.md`, settings, hooks, and local rules unless the user explicitly requests an overwrite.
+- Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
+- Register added agents, skills, workflows, rules, and hooks in `MEMORY.md` and this docs router where applicable.
+- Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `docs/workflows/`, but they must not replace core harness docs.
+- Core harness docs are `docs/README.md`, `docs/harness/PLAN.md`, `docs/harness/context-loading.md`, `docs/harness/dispatch.md`, `docs/harness/agent-workflow.md`, and this file.
+- If an optional workflow needs a new command or tool, document the command and fallback in `docs/workflows/<name>.md` instead of changing core harness behavior.
+
 ## Agent Contract
 
 Every added agent must have frontmatter:
@@ -63,5 +74,6 @@ After adding assets:
 
 - list agents in `MEMORY.md#Agents`
 - list skills in `MEMORY.md#Skills`
+- list workflows by path in `MEMORY.md` or `docs/README.md`
 - update `docs/harness/PLAN.md` when the asset affects current work
 - run `node scripts/validate-harness.mjs`

package/templates/common/memory/agent-lessons-patterns.md

@@ -0,0 +1,21 @@
+# Agent Lessons And Patterns
+
+Purpose: record reusable lessons from review, debugging, validation, and handoff loops.
+
+Write here when:
+- A review/debug loop reveals a reusable prevention pattern.
+- A validation failure exposes a missing regression check.
+- A handoff, dispatch, or context-loading pattern should be repeated or avoided.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Lesson Name
+
+- Lesson: the reusable pattern.
+- Source: review finding, debug loop, failed verification, or handoff.
+- Apply when: the task shape or files where this matters.
+- Regression guard: test, validator check, docs update, or manual evidence to keep it from recurring.
+```
+
+Keep entries lightweight and actionable. Avoid secrets and speculative lessons.

package/templates/common/memory/tool-usage-reflections.md

@@ -0,0 +1,21 @@
+# Tool Usage Reflections
+
+Purpose: record repeated tool failures, better command patterns, and environment-specific fixes.
+
+Write here when:
+- The same tool/use pattern fails 3+ times in one task or across repeated tasks.
+- A more reliable command pattern replaces a brittle one.
+- The environment needs a durable fix, flag, path rule, shell syntax, or startup sequence.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Pattern Name
+
+- Trigger: what failed or repeated.
+- Better pattern: the command, tool usage, or sequence to use next time.
+- Evidence: command output summary, error text, or affected environment.
+- Scope: when this applies and when it does not.
+```
+
+Keep entries concise. Do not record secrets, credentials, private tokens, or one-off noise.

package/templates/common/memory/user-corrections-preferences.md

@@ -0,0 +1,21 @@
+# User Corrections And Preferences
+
+Purpose: record repeated user corrections, durable preferences, and common-sense course corrections.
+
+Write here when:
+- The user says "remember", "never", "next time", "always", or "I prefer".
+- The user corrects the same assumption/pattern 2+ times.
+- A correction changes how future work should be scoped, explained, verified, or handed off.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Preference Name
+
+- Correction/preference: the durable instruction.
+- Trigger: what prompted the correction.
+- Apply when: future contexts where this should guide behavior.
+- Avoid: contexts where this should not be over-applied.
+```
+
+Do not record ordinary chat. If the preference is ambiguous, ask before writing it. Never store secrets.

package/templates/common/scripts/validate-harness.mjs

@@ -10,7 +10,8 @@ if (args.has('--help') || args.has('-h')) {
   console.log(`Usage: node scripts/validate-harness.mjs [--strict]
 
 Default mode checks scaffold structure, links, agents, and skills.
---strict also fails when project fact docs still contain {{...}} placeholders.`);
+--strict also fails when project fact docs still contain unresolved {{TOKEN}} placeholders.
+Literal explanatory {{...}} text is allowed.`);
   process.exit(0);
 }
 
@@ -34,10 +35,17 @@ const commonSkills = [
   'harness-build-loop',
 ];
 
+const memoryFiles = [
+  'memory/tool-usage-reflections.md',
+  'memory/user-corrections-preferences.md',
+  'memory/agent-lessons-patterns.md',
+];
+
 const required = [
   'AGENTS.md',
   'CLAUDE.md',
   'MEMORY.md',
+  ...memoryFiles,
   '.claude/settings.json',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
@@ -80,6 +88,12 @@ const contextPacks = [
   'Verifier:',
 ];
 
+const durableCommunicationDocs = [
+  'docs/README.md',
+  'docs/harness/dispatch.md',
+  'docs/harness/context-loading.md',
+];
+
 const errors = [];
 
 function read(rel) {
@@ -97,6 +111,36 @@ function frontmatterField(text, field) {
   return match ? match[1].trim() : '';
 }
 
+function listDirectories(rel) {
+  const dir = path.join(root, rel);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name);
+}
+
+function listMarkdownFiles(rel) {
+  const dir = path.join(root, rel);
+  if (!fs.existsSync(dir)) return [];
+  const normalizedRel = rel.replaceAll(path.sep, '/');
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+    .map(entry => `${normalizedRel}/${entry.name}`);
+}
+
+function unresolvedTemplatePlaceholders(text) {
+  const placeholders = [];
+  const pattern = /\{\{([^{}\r\n]+)\}\}/g;
+
+  for (const match of text.matchAll(pattern)) {
+    const token = match[1].trim();
+    if (token === '...') continue;
+    placeholders.push(`{{${token}}}`);
+  }
+
+  return [...new Set(placeholders)];
+}
+
 for (const rel of required) {
   if (!fs.existsSync(path.join(root, rel))) {
     errors.push(`missing required file: ${rel}`);
@@ -108,10 +152,15 @@ if (fs.existsSync(path.join(root, 'docs/research/scaffolds.md'))) {
 }
 
 if (strict) {
+  console.log('Strict placeholder scope:');
+  for (const rel of projectFacts) {
+    console.log(`- ${rel}`);
+  }
+
   for (const rel of projectFacts) {
     const text = read(rel);
-    if (text.includes('{{')) {
-      errors.push(`template placeholders remain in project fact file: ${rel}`);
+    for (const placeholder of unresolvedTemplatePlaceholders(text)) {
+      errors.push(`template placeholder remains in project fact file: ${rel}: ${placeholder}`);
     }
   }
 }
@@ -123,6 +172,14 @@ if (docsReadme) {
   }
 }
 
+for (const rel of durableCommunicationDocs) {
+  requireText(rel, 'project files are the only durable communication channel', 'durable filesystem communication invariant');
+  requireText(rel, 'chat/subagent transcript state is non-authoritative', 'non-authoritative transcript invariant');
+}
+
+requireText('CLAUDE.md', 'same tool/use pattern fails 3+ times', 'tool reflection trigger');
+requireText('CLAUDE.md', 'user corrects the same assumption/pattern 2+ times', 'user correction reflection trigger');
+
 const plan = read('docs/harness/PLAN.md');
 if (plan) {
   for (const heading of ['## Current Goal', '## Phase', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Verification']) {
@@ -158,8 +215,36 @@ if (memory) {
     const rel = `.claude/skills/${skill}/SKILL.md`;
     if (!memory.includes(rel)) errors.push(`MEMORY.md missing skill registration: ${rel}`);
   }
+  for (const rel of memoryFiles) {
+    if (!memory.includes(rel)) errors.push(`MEMORY.md missing memory file registration: ${rel}`);
+  }
+}
+
+for (const workflow of listMarkdownFiles('docs/workflows')) {
+  if (!docsReadme.includes(workflow) && !memory.includes(workflow)) {
+    errors.push(`workflow is not registered in docs/README.md or MEMORY.md: ${workflow}`);
+  }
+}
+
+function requireUiSelectorContract(rel) {
+  const text = read(rel);
+  if (!text) return;
+
+  const markers = [
+    'data-testid',
+    'accessible labels/roles',
+    'inputs, buttons, filters, rows, empty/error/loading states',
+  ];
+
+  if (markers.some(marker => !text.includes(marker))) {
+    errors.push(`${rel} missing stable UI selector contract`);
+  }
 }
 
+requireUiSelectorContract('docs/workflows/browser-e2e.md');
+requireUiSelectorContract('docs/workflows/ts-react-frontend.md');
+requireUiSelectorContract('docs/features/_template.md');
+
 for (const skill of commonSkills) {
   const rel = `.claude/skills/${skill}/SKILL.md`;
   const text = read(rel);
@@ -168,6 +253,17 @@ for (const skill of commonSkills) {
   if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
 }
 
+for (const skill of listDirectories('.claude/skills')) {
+  if (commonSkills.includes(skill)) continue;
+
+  const rel = `.claude/skills/${skill}/SKILL.md`;
+  const text = read(rel);
+  if (!text) continue;
+
+  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
+  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
+}
+
 for (const agent of commonAgents) {
   const rel = `.claude/agents/${agent}.md`;
   const text = read(rel);

package/templates/optional/catalog.json

@@ -0,0 +1,43 @@
+{
+  "skills": [
+    {
+      "id": "browser-e2e",
+      "title": "Browser E2E",
+      "description": "Mandatory real-browser smoke workflow using Playwright, Chrome DevTools/CDP, or documented manual evidence.",
+      "files": ["skills/browser-e2e"],
+      "tags": ["e2e", "browser", "playwright", "cdp"]
+    },
+    {
+      "id": "ui-ux-review",
+      "title": "UI/UX Review",
+      "description": "Screenshot-driven responsive, accessibility, and visual polish review workflow.",
+      "files": ["skills/ui-ux-review"],
+      "tags": ["ui", "ux", "accessibility", "review"]
+    },
+    {
+      "id": "github-pr-review",
+      "title": "GitHub PR Review",
+      "description": "GitHub CLI based PR diff, checks, review findings, and CI evidence workflow.",
+      "files": ["skills/github-pr-review"],
+      "tags": ["github", "pr", "review", "ci"]
+    },
+    {
+      "id": "python-backend",
+      "title": "Python Backend",
+      "description": "Python backend workflow for FastAPI or similar APIs with unittest or pytest verification.",
+      "files": ["skills/python-backend"],
+      "tags": ["python", "fastapi", "unittest", "pytest", "api"]
+    },
+    {
+      "id": "ts-react-frontend",
+      "title": "TypeScript React Frontend",
+      "description": "TypeScript React workflow for typecheck, component tests, builds, and browser smoke.",
+      "files": ["skills/ts-react-frontend"],
+      "tags": ["typescript", "react", "vite", "frontend"]
+    }
+  ],
+  "presets": {
+    "web-app": ["ts-react-frontend", "browser-e2e", "ui-ux-review"],
+    "fullstack": ["ts-react-frontend", "python-backend", "browser-e2e", "github-pr-review"]
+  }
+}

package/templates/optional/skills/browser-e2e/.claude/skills/browser-e2e/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: browser-e2e
+description: Mandatory real-browser smoke and end-to-end verification using Playwright, Chrome DevTools/CDP, or documented manual browser evidence.
+---
+
+# Browser E2E
+
+## When To Use
+
+Use this skill when a change affects browser-visible behavior, navigation, forms, routing, layout, or client-side integration. Web/UI acceptance requires loading the app in a real browser before claiming the UI is done.
+
+## Docs To Load
+
+- `docs/workflows/browser-e2e.md`
+- `docs/harness/PLAN.md`
+- Existing project test, build, and run instructions.
+
+## Required Inputs
+
+- Target URL or command to start the app.
+- User flows or pages to verify.
+- Expected behavior and supported viewport/browser scope.
+- Selector contract: stable accessible labels/roles and `data-testid` hooks for critical inputs, buttons, filters, rows, empty/error/loading states, and other targetable UI states.
+
+## Allowed Writes
+
+- Browser test files in the project's existing test locations.
+- Evidence artifacts such as screenshots, traces, or reports in existing artifact folders.
+- Notes in `docs/harness/PLAN.md` when the active task asks for plan tracking.
+
+## Output Format
+
+Return changed files, commands run, browser evidence paths, verified flows, failures, and follow-up risks.
+Include the selectors used for CDP/Playwright/manual verification.
+
+## PLAN.md Updates
+
+Update `docs/harness/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
+
+## dispatch.md Usage
+
+Use `docs/harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

package/templates/optional/skills/browser-e2e/docs/workflows/browser-e2e.md

@@ -0,0 +1,42 @@
+# Browser E2E Workflow
+
+## Required Evidence
+
+- App start command and URL.
+- Real-browser load of the changed app before any web/UI acceptance claim.
+- Console, runtime, and network check result, including whether React/Vite/client startup errors or failed requests appeared.
+- Stable accessible labels/roles and stable test hooks such as `data-testid` are required for critical UI controls and states: inputs, buttons, filters, rows, empty/error/loading states.
+- CDP, Playwright, and manual verification must target those selectors for the critical interaction path instead of brittle DOM paths.
+- Viewports and browsers checked.
+- Screenshot, trace, video, or documented manual screenshot artifact for each critical UI flow.
+- Final pass/fail result with exact command output summary.
+
+## Chrome DevTools / CDP / MCP Checklist
+
+- Start the app with the project command and record the URL and port.
+- Open a real browser target through available CDP, MCP, browser automation, or manual tooling.
+- Wait for a stable app selector, route, or page-ready state, not just HTTP 200.
+- Capture runtime exceptions, console errors, and failed network requests before and after the flow.
+- Interact through stable accessible labels/roles or `data-testid`, not brittle DOM paths.
+- Verify at least one critical flow end-to-end in the real browser target.
+- Save screenshot, trace, video, or result artifact paths and record them in `docs/harness/PLAN.md` or the feature doc.
+- Clean up any dev server or browser processes started for verification.
+
+## Common Commands
+
+```powershell
+npm run dev
+npx playwright test
+npx playwright test --headed
+npx playwright show-report
+```
+
+If Playwright is not installed, prefer an existing browser test command from `package.json`. Chrome DevTools/CDP, manual screenshot evidence, or framework-specific tools are acceptable when the method, URL, flow, console/runtime/network result, and artifacts are documented.
+
+## Fallback
+
+When no browser automation is available, run the app locally in a real browser, inspect critical flows manually, capture screenshots, and report console or network errors. Do not claim web/UI acceptance from typecheck, build, or unit tests alone. Do not install new dependencies unless the user approves.
+
+## Windows Notes
+
+Use PowerShell syntax for environment variables, for example `$env:PORT='3000'; npm run dev`. Quote paths that contain spaces.

package/templates/optional/skills/github-pr-review/.claude/skills/github-pr-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: github-pr-review
+description: GitHub pull request review workflow using available GitHub CLI, local git diff, checks, and CI evidence.
+---
+
+# GitHub PR Review
+
+## When To Use
+
+Use this skill when reviewing a GitHub pull request, responding to PR feedback, checking CI status, or summarizing review findings.
+
+## Docs To Load
+
+- `docs/workflows/github-pr-review.md`
+- `docs/harness/PLAN.md`
+- Repository contribution, test, and review guidelines.
+
+## Required Inputs
+
+- PR number, branch, or comparison range.
+- Review goal: bug hunt, approval readiness, CI diagnosis, or feedback response.
+- Expected test and check requirements.
+
+## Allowed Writes
+
+- Local files needed to address approved review feedback.
+- Review notes or evidence in existing docs only when requested.
+- `docs/harness/PLAN.md` when tracking review work.
+
+## Output Format
+
+Return findings first by severity with file and line references, then open questions, tests/checks run, and change summary if edits were made.
+
+## PLAN.md Updates
+
+Update `docs/harness/PLAN.md` only when the PR review is part of a tracked implementation plan.
+
+## dispatch.md Usage
+
+Use `docs/harness/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.

package/templates/optional/skills/github-pr-review/docs/workflows/github-pr-review.md

@@ -0,0 +1,28 @@
+# GitHub PR Review Workflow
+
+## Required Evidence
+
+- PR URL or number and base/head refs.
+- Diff or changed-file summary.
+- CI/check status and relevant failing logs.
+- Review findings with exact file and line references when available.
+
+## Common Commands
+
+```powershell
+gh pr view --web
+gh pr view --json number,title,baseRefName,headRefName,mergeStateStatus,statusCheckRollup
+gh pr diff
+git diff --stat
+npm test
+```
+
+Use repository-specific test commands when they differ from npm.
+
+## Fallback
+
+If `gh` is unavailable or unauthenticated, use local git refs, remote URLs, and `git diff` against the target branch. Ask for missing PR context only when it cannot be inferred.
+
+## Windows Notes
+
+Quote branch names containing special characters. In PowerShell, pipe JSON output to tools that are available locally, or read it directly if `jq` is not installed.

package/templates/optional/skills/python-backend/.claude/skills/python-backend/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: python-backend
+description: Python backend workflow for API changes, service logic, FastAPI-style routes, and unittest or pytest verification.
+---
+
+# Python Backend
+
+## When To Use
+
+Use this skill when changing Python API routes, service logic, persistence boundaries, background jobs, or backend tests.
+
+## Docs To Load
+
+- `docs/workflows/python-backend.md`
+- `docs/harness/PLAN.md`
+- Project backend README, API docs, dependency files, and test configuration.
+
+## Required Inputs
+
+- Target behavior, endpoint, service, or bug.
+- Existing test command and runtime setup.
+- Database, environment variable, or fixture constraints.
+
+## Allowed Writes
+
+- Python source, tests, fixtures, and backend docs in the task scope.
+- Local evidence artifacts such as test output snippets.
+- `docs/harness/PLAN.md` when the task requires plan tracking.
+
+## Output Format
+
+Return files changed, API or behavior summary, tests run, important logs, migration/config notes, and remaining risks.
+
+## PLAN.md Updates
+
+Update `docs/harness/PLAN.md` only when executing a tracked plan item or recording required validation evidence.
+
+## dispatch.md Usage
+
+Use `docs/harness/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.

package/templates/optional/skills/python-backend/docs/workflows/python-backend.md

@@ -0,0 +1,34 @@
+# Python Backend Workflow
+
+## Required Evidence
+
+- Python executable, version, and dependency manager detected.
+- Unit/integration test command and result.
+- API smoke evidence for changed endpoints when applicable.
+- Migration, fixture, or environment assumptions.
+
+## Common Commands
+
+```powershell
+python --version
+py --version
+python3 --version
+python -m unittest discover -s tests
+py -m unittest discover -s tests
+python3 -m unittest discover -s tests
+python -m pytest
+python -m pytest tests
+uv run pytest
+poetry run pytest
+python -m uvicorn app.main:app --reload
+```
+
+Prefer commands already documented by the project. When no project-specific command is documented, detect an available Python executable in the current shell (`python`, then `py`, then `python3`) and run the matching `-m unittest discover -s tests` or pytest command. `unittest` is first-class for standard-library test suites; do not require pytest when the project already uses unittest.
+
+## Fallback
+
+If unittest, pytest, or the app runner is unavailable, run targeted Python modules, import checks, or framework-specific tests that already exist. Do not create or install a new backend stack without approval.
+
+## Windows Notes
+
+Virtual environment activation is usually `.\\.venv\\Scripts\\Activate.ps1`. If script execution is blocked, use the environment's Python executable directly, for example `.\\.venv\\Scripts\\python.exe -m unittest discover -s tests` or `.\\.venv\\Scripts\\python.exe -m pytest`.

package/templates/optional/skills/ts-react-frontend/.claude/skills/ts-react-frontend/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ts-react-frontend
+description: TypeScript React frontend workflow for components, state, routing, typecheck, tests, builds, and browser smoke evidence.
+---
+
+# TypeScript React Frontend
+
+## When To Use
+
+Use this skill when changing React components, hooks, routes, client state, styling, build configuration, or frontend tests.
+For user-visible changes, typecheck, build, and unit tests are not enough; include real-browser smoke or screenshot evidence before claiming acceptance.
+
+## Docs To Load
+
+- `docs/workflows/ts-react-frontend.md`
+- `docs/harness/PLAN.md`
+- Existing frontend README, package scripts, design system, and test setup.
+
+## Required Inputs
+
+- Screen, component, or flow being changed.
+- Expected behavior and acceptance criteria.
+- Existing package manager and verification commands.
+- Selector contract: stable accessible labels/roles and `data-testid` hooks for critical inputs, buttons, filters, rows, empty/error/loading states, and other targetable UI states.
+
+## Allowed Writes
+
+- Frontend source, styles, tests, and focused docs in task scope.
+- Generated evidence such as screenshots or test reports in existing artifact paths.
+- `docs/harness/PLAN.md` when tracking a plan item.
+
+## Output Format
+
+Return changed files, UI behavior summary, commands run, browser or test evidence, and unresolved risks.
+Include selectors added or verified for CDP/Playwright/manual checks.
+
+## PLAN.md Updates
+
+Update `docs/harness/PLAN.md` only when executing a tracked task or recording required validation evidence.
+
+## dispatch.md Usage
+
+Use `docs/harness/dispatch.md` when independent frontend tasks can run in parallel, such as components, tests, and browser checks.

package/templates/optional/skills/ts-react-frontend/docs/workflows/ts-react-frontend.md

@@ -0,0 +1,35 @@
+# TypeScript React Frontend Workflow
+
+## Required Evidence
+
+- Package manager and scripts detected.
+- Typecheck, lint, test, or build results according to project conventions.
+- Real-browser smoke or screenshot evidence for user-visible changes.
+- Console/runtime error check result for the changed screen or flow.
+- Notes on responsive behavior and important interaction states.
+- Stable accessible labels/roles and stable test hooks such as `data-testid` are required for critical UI controls and states: inputs, buttons, filters, rows, empty/error/loading states.
+
+Typecheck, build, and unit tests are necessary signals but are not enough for user-visible React changes. Before claiming UI acceptance, load the app in a real browser by Playwright, Chrome DevTools/CDP, or a documented manual run and capture screenshot/trace/console evidence.
+For TS/React UI work, capture the selector contract in the feature doc before implementation so tests and manual checks can target stable selectors instead of component internals or brittle DOM paths.
+
+## Common Commands
+
+```powershell
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run dev
+pnpm test
+yarn test
+```
+
+Use the package manager and scripts already present in the repository.
+
+## Fallback
+
+If no formal checks exist, run the closest available build or dev command, inspect the changed UI manually, and document the missing automation. Do not add dependencies unless the task requires it and the user approves.
+
+## Windows Notes
+
+Use PowerShell syntax for environment variables: `$env:VITE_API_URL='http://localhost:8000'; npm run dev`. Quote paths and prefer package scripts over shell-specific command chains.

package/templates/optional/skills/ui-ux-review/.claude/skills/ui-ux-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ui-ux-review
+description: Screenshot-driven UI and UX review for responsive behavior, accessibility, visual polish, and task clarity.
+---
+
+# UI/UX Review
+
+## When To Use
+
+Use this skill when reviewing or changing user-facing screens, layouts, visual hierarchy, interaction states, accessibility, or responsive behavior.
+
+## Docs To Load
+
+- `docs/workflows/ui-ux-review.md`
+- `docs/harness/PLAN.md`
+- Existing design system, component, or style documentation.
+
+## Required Inputs
+
+- Screens, routes, or components under review.
+- Target users and primary tasks.
+- Breakpoints, themes, and accessibility expectations.
+
+## Allowed Writes
+
+- UI code and style files already in scope for the task.
+- Screenshot or audit artifacts in existing evidence folders.
+- `docs/harness/PLAN.md` when the review is part of a tracked plan.
+
+## Output Format
+
+Return prioritized findings with file or screen references, evidence, recommended fixes, commands run, and residual risks.
+
+## PLAN.md Updates
+
+Update `docs/harness/PLAN.md` only for tracked review tasks or when recording required evidence.
+
+## dispatch.md Usage
+
+Use `docs/harness/dispatch.md` only for independent review streams such as separate routes or breakpoints.