oh-my-opencode 4.13.0 → 4.14.0

package/packages/omo-codex/plugin/skills/frontend/references/design/README.md

@@ -3,6 +3,12 @@
 
 You are an elite frontend design engineer. Your only job in this skill is to **route correctly**: pick the right reference file(s), load them into context, then execute with their guidance. The reference files contain the actual design rules — this file just decides which to consult.
 
+## The bar
+
+You are not done when it is clean and correct. You are done when a senior product designer at Linear, Stripe, or Supabase would ship it: surfaces read as real materials (depth, light, layering), color carries a story and a ramp, type has personality, and motion has intent. **Correct-but-flat is a failure, not a finish.** The most common way this skill fails is effort drain: the build, lint, file-size, and test gates eat all the attention and the surface ships at the floor. Spend on the surface like it is the deliverable, because for an expressive brief it is. When you render and find only bug-level issues, you are not done — you are at the start of the part that separates good from generic.
+
+Two things ship flat most often, and both read as "clean but generic": the **hero's focal object** and the **atmosphere**. Render the focal object as a real, lit, dimensional thing — a generated bitmap (imagegen) for a product/brand/object hero, or CSS/SVG art that carries light, shadow, gradient, and depth. Flat geometric primitives (plain circles and rounded rects) for a brand hero are the flat trap. Give the background depth too — gradient, glow, layered light, an atmospheric band, or a real image — not one flat fill. Glass is only one material: a dark glossy brand wants tint+blur+rim+sheen+glow, a bright playful brand wants gradient fills+soft depth shadows+a lit focal object. Pick what the brand calls for, but it must have dimension.
+
 ## Why route at all
 
 `taste-skill.md` alone is a strong default, but it does not commit to any specific aesthetic. When the user has named a clear visual direction (a brand, a style label, an existing site to mimic), a dedicated reference produces sharper output than the generic default. Loading the wrong reference, or none, is how you produce the bland generic SaaS slop these skills exist to prevent.
@@ -28,14 +34,16 @@ Before touching any UI code, before routing to any reference, before even thinki
 
 **Search for it:** Look at project root, then `docs/`, then `src/`. Any file named `DESIGN.md`, `design-system.md`, or `design-tokens.md`.
 
-#### If NO design system exists → CREATE ONE FIRST
+#### If NO design system exists → RUN THE TRIAGE
 
 1. Read `design-system-architecture.md` — it defines the exact structure.
-2. Explore the project: what is the product domain? Who are the users? What feeling should it evoke?
-3. If the project has existing UI code, **extract** the implicit system (colors, fonts, spacing already in use) rather than inventing from scratch.
-4. If the project is greenfield, **ask the user one question**: "What should this feel like?" — or infer from context.
-5. Write `DESIGN.md` at project root following the 7-section structure from the reference.
-6. **Do not proceed to any component implementation until `DESIGN.md` exists and is committed to context.**
+2. Identify the branch: greenfield setup, existing UI with implicit patterns/components, or existing UI with no reusable component layer.
+3. **Greenfield setup:** if the user gave no concrete visual reference, use `_INDEX.md` to shortlist 2-3 plausible Layer B references, then deeply load exactly one Layer A style skill and one Layer B brand/design-system reference; use `open-design` only when the curated set has no fit. Treat those references as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions into `DESIGN.md`, then recombine them into project-specific primitives. Customize for the user's product and content, but do not freestyle past the selected references; never copy logos, trademarked assets, or brand-specific copy.
+   - **Commit a distinctive direction BEFORE extracting tokens.** In 1-2 sentences, name the atmosphere, the signature material, the color story, and the one moment a visitor will remember. For an expressive brief, sketch 2-3 genuinely different directions and pick the boldest one you can defend with the loaded reference; do not average them, because the average IS the generic default this skill exists to beat. A locked, never-revisited one-shot decision is how a page ends up flat.
+   - **The reference's distinctive material MUST survive extraction (expressive briefs).** The common failure is loading a rich reference and then distilling it into a generic dark-SaaS token set. Your `DESIGN.md` must carry the *non-default* decisions forward and name which reference each came from: the actual elevation recipe (the specific layers that make a surface read as glass/glossy, not a single blur), a multi-stop perceptual color ramp (not one brand hex reused at varied opacity), the explicit display/body/mono type choices, and one signature interaction. Self-check before writing code: if your `DESIGN.md` could describe any generic dark SaaS, you flattened the reference — go back and put the specific material in.
+4. **Existing UI with implicit patterns/components:** extract the colors, typography, spacing, primitives, states, and motion already in use. Write `DESIGN.md` to codify what exists before changing UI code.
+5. **Existing UI with no reusable component layer:** STOP and ask whether to preserve the current style with copy-nearby edits or extract a `DESIGN.md` plus reusable components first. Do not silently choose the cheaper path or the larger refactor.
+6. **Do not proceed to product screens until `DESIGN.md` exists, Section 5 names the reusable primitives and their states, and each primitive plus required state passes mobile/tablet/desktop visual QA in a component showcase or equivalent state harness.**
 
 #### If YES design system exists → READ IT, FOLLOW IT
 
@@ -94,17 +102,22 @@ Phrasings: "make it look like Linear", "Stripe-style buttons", "Notion-feel side
 
 If the user names a brand not in the index, fall back to Step 2 + a mood-based shortcut from the index.
 
-### Step 2 — Did the user describe a clear style/mood?
+### Step 2 — Read the brief's ambition, THEN map style/mood
+
+Decide the lane by **ambition first** — this is what your output gets judged on, and the wrong read is how a high-craft request ships clean-but-flat:
+
+- **Expressive brief** — any surface-ambition signal: "glossy", "glassy", "liquid glass", "premium", "luxe", "startup-grade", "brand-grade", "make it beautiful / pretty / wow", or a named product company to feel like. The page is a showcase and rich material IS the deliverable. Commit to a high-craft Layer A (`soft-skill` or `gpt-tasteskill`) and ALWAYS pair a high-craft Layer B exemplar (`supabase`, `linear.app`, `vercel`, `stripe`) as the token source. This lane OVERRIDES any default "keep it quiet / utilitarian" instinct.
+- **Operational brief** — internal tool, dashboard, admin, "just make it usable". Restraint is correct here and `taste-skill` is the right default.
 
-Map their phrasing to one taste-skill style file:
+Do NOT let an expressive brief fall through to `taste-skill`. Then map the phrasing:
 
 | User says... | Load |
 |---|---|
 | "minimal", "clean", "Notion-like", "Linear-like", "editorial", "boring is good" | `minimalist-skill.md` |
 | "brutalist", "raw", "Swiss", "experimental", "industrial", "anti-design", "unstyled" | `brutalist-skill.md` |
-| "premium", "luxury", "calm", "expensive", "spa", "wellness", "boutique", "elegant" | `soft-skill.md` |
+| "premium", "luxury", "calm", "expensive", "elegant", "spa", "boutique", "glossy", "glassy", "liquid glass", "startup-grade", "make it beautiful/pretty" | `soft-skill.md` + a high-craft Layer B (`supabase` / `linear.app` / `vercel` / `stripe`) |
 | "Awwwards-level", "wow factor", "magnetic", "scroll-triggered", "high-variance", "cinematic", "make it crazy" | `gpt-tasteskill.md` |
-| Nothing specific — just "make a good UI" | `taste-skill.md` (default all-rounder) |
+| Neutral or operational — internal tool, dashboard, admin, "just make it usable" with no surface ambition | `taste-skill.md` as Layer A, plus the greenfield `_INDEX.md` shortlist → exactly one Layer B reference |
 
 You may also load a brand DESIGN.md from Layer B as a *concrete reference* if the user's mood maps cleanly (see the "Mood-based shortcuts" section in `_INDEX.md`).
 
@@ -181,12 +194,13 @@ Once references are loaded, before writing any UI code:
 7. **Match the project's existing patterns FIRST.** If the codebase already uses CSS Modules, don't introduce Tailwind. If it uses styled-components, don't introduce CSS-in-JS variants. The references guide *style*, not *infrastructure*.
 8. **All tokens trace back to `DESIGN.md`.** No orphan hex codes, no magic px values. If you need a new token, update `DESIGN.md` first.
 9. **New reusable patterns (used 2+ times) get documented back into `DESIGN.md` Section 5.**
+10. **No generic-default drift (expressive briefs).** The shipped CSS must use the `DESIGN.md` material, not the model's priors. Load the declared fonts (do not silently fall back to Inter or system fonts), build elevated surfaces from the declared multi-layer recipe (not a lone `backdrop-filter: blur`), and color from the ramp stops (not one tint at varied opacity). Grep your styles before QA: finding `Inter`, a single blur on "glass", or one brand hex reused everywhere means you regressed to priors — fix it before declaring done.
 
 ## Quick lookup table — most common requests
 
 | User asks for... | Load these |
 |---|---|
-| "Build me a landing page" (no other info) | `taste-skill.md` |
+| "Build me a landing page" (no other info) | `_INDEX.md` shortlist → exactly one Layer B reference + `taste-skill.md` |
 | "Build me a Linear-style landing page" | `linear.app.md` + `taste-skill.md` |
 | "Make it Notion-like and minimal" | `notion.md` + `minimalist-skill.md` |
 | "Premium SaaS hero, like Stripe" | `stripe.md` + `soft-skill.md` |
@@ -219,7 +233,10 @@ Code that "looks correct" in an editor is not verified. Colors render differentl
    - [ ] Dark mode (if declared in `DESIGN.md`) works completely
    - [ ] No layout overflow, no horizontal scroll on mobile
    - [ ] Motion/animation feels smooth — no jank, no missing transitions
-4. **If anything fails**, fix it and re-check. Do not report "done" with visual bugs.
+   - [ ] (Expressive brief) Surfaces AND the hero focal object read as real, dimensional material — not flat fills or flat geometric primitives. Use the brand's material: glass = tint+backdrop saturate+rim+sheen+glow; bright/playful = gradient fills+soft depth shadows+a lit focal object. The hero focal object is a generated bitmap, or carries real light/shadow/gradient/depth.
+   - [ ] (Expressive brief) Brand color is a perceptual ramp (multiple stops / OKLCH), not one tint reused at different opacities
+   - [ ] (Expressive brief) Every interactive element has a visible hover AND active/pressed micro-interaction, and the hero carries one signature moment
+4. **Two kinds of failure count equally — fix both, then re-check.** Defects: clipping, wrong font, missing state, jank. Flatness: a surface that reads generic next to the loaded reference. When the render is bug-free but flat, you are NOT done — RAISE the design: deepen the material layering, give the color real depth and a ramp, add the signature interaction. Patching only bugs while the surface stays at the floor is the single most common way this skill ships clean-but-generic work. Do not report "done" with visual bugs OR a floor-level surface.
 5. **If you cannot launch a browser** (e.g. no dev server, CI-only environment), state this explicitly and list what you would check. Never silently skip QA.
 
 ### QA Report

package/packages/omo-codex/plugin/skills/frontend/references/design/_INDEX.md

@@ -52,7 +52,7 @@ From [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill).
 
 ---
 
-## Layer B — Design Systems (69)
+## Layer B — Design Systems (71)
 
 From [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), based on [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/overview/). Each file captures one website's complete visual language: color palette, typography, components, layout principles, depth, do/don't, responsive behavior, and an agent prompt guide.
 
@@ -79,7 +79,7 @@ Each file ships with: visual theme, hex color palette + semantic roles, full typ
 | `voltagent.md` | AI agent framework. Void-black canvas, emerald accent, terminal-native. |
 | `x.ai.md` | Elon Musk's AI lab. Stark monochrome, futuristic minimalism. |
 
-### Developer Tools & IDEs (7)
+### Developer Tools & IDEs (8)
 
 | File | Aesthetic |
 |---|---|
@@ -91,7 +91,7 @@ Each file ships with: visual theme, hex color palette + semantic roles, full typ
 | `vercel.md` | Frontend deployment platform. Black and white precision, Geist font. |
 | `warp.md` | Modern terminal. Dark IDE-like interface, block-based command UI. |
 
-### Backend, Database & DevOps (8)
+### Backend, Database & DevOps (9)
 
 | File | Aesthetic |
 |---|---|

package/packages/omo-codex/plugin/skills/frontend/references/design/design-system-architecture.md

@@ -9,8 +9,9 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
 
 ## When to Create
 
-- **New project**: Create `DESIGN.md` during initial setup, before any UI component.
-- **Existing project without one**: Extract the design system from existing code before continuing work.
+- **New project**: If the user gave no concrete visual reference, select one Layer A style skill and one Layer B brand/design-system reference first. Treat them as source material for tokens, layout, component anatomy, states, motion, and taste; customize for the user's product without freestyling past the selected references. Then create `DESIGN.md` before UI, with Section 5 primitives and states defined before implementation.
+- **Existing project without one, but with implicit patterns/components**: Extract the design system from existing code before continuing work.
+- **Existing project without one and without a reusable component layer**: Ask whether to preserve the current look with copy-nearby styling or extract a `DESIGN.md` plus reusable components first. Do not silently choose.
 - **Existing project with one**: Read it. Follow it. Update it only when a genuinely new pattern emerges.
 
 ## DESIGN.md Structure
@@ -112,18 +113,20 @@ All spacing derives from a base of **4px**.
 
 ## 5. Components
 
-Document reusable patterns as they emerge. Format:
+Document reusable patterns before implementation for greenfield work, and as they emerge or are extracted for existing work. Format:
 
 ### [Component Name]
 - **Structure**: HTML/JSX outline
 - **Variants**: list
 - **Spacing**: which tokens
-- **States**: default, hover, active, focus, disabled, loading, error
+- **States**: default, hover, active, focus, disabled, loading, empty, error
 - **Accessibility**: keyboard, ARIA, contrast
 - **Motion**: entry/exit animations
 
-Start with components used 2+ times. Do not pre-document components
-that don't exist yet.
+Greenfield starts with the primitives you are about to build, assembled from
+the selected references' component anatomy and adapted to the user's product.
+Existing projects start with components used 2+ times or already shared in
+code; do not invent future components just to fill the section.
 
 ## 6. Motion & Interaction
 
@@ -168,22 +171,21 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 
 ### For New Projects
 
-1. **Ask or infer the product domain** — SaaS dashboard? Marketing site? Dev tool?
-2. **Write the Atmosphere paragraph** — one chance to establish identity.
-3. **Define palette** — derive from atmosphere. Not random. Not generic.
-4. **Set typography** — match the atmosphere. Editorial = serif. Technical = mono-heavy. Clean = geometric sans.
-5. **Lock spacing** — base-4 system. Customize only the section-level values.
-6. **Document initial components** — only those you are about to build.
-7. **Choose depth strategy** — one. Not "a mix."
-8. **Write it to `DESIGN.md`** at project root.
+1. **Select references before taste** — no visual reference means `_INDEX.md` shortlist of 2-3 Layer B candidates, then exactly one Layer A style skill and one Layer B brand/design-system reference. Use `open-design` only when the curated set has no fit.
+2. **Assemble from references** — extract tokens, layout grammar, component anatomy, states, motion, and taste decisions, then recombine them into project-specific primitives. Customize for the user's product; never copy logos, trademarked assets, or brand-specific copy.
+3. **Define the system** — atmosphere, palette, typography, spacing, and one depth strategy, grounded in the selected references and product semantics.
+4. **Document initial primitives** — only components you are about to build, including variants and states.
+5. **Write it to `DESIGN.md`** at project root.
+6. **Build a primitive showcase first** — exercise each primitive's default, hover, active, focus, disabled, loading, empty, and error states at mobile/tablet/desktop widths before composing product screens.
 
 ### For Existing Projects (Extraction)
 
 1. **Read all CSS/styling files** — find the actual tokens in use.
-2. **Identify the implicit system** — what colors, fonts, spacing values repeat?
-3. **Codify it** — write the `DESIGN.md` reflecting what EXISTS, not what you wish existed.
-4. **Flag inconsistencies** — note where the code deviates from its own patterns.
-5. **Propose consolidation** — but do not apply it until approved.
+2. **Identify the implicit system** — what colors, fonts, spacing values, components, and states repeat?
+3. **If no reusable component layer exists**, ask whether to preserve the current look with copy-nearby edits or extract reusable components first.
+4. **Codify it** — write the `DESIGN.md` reflecting what EXISTS, not what you wish existed.
+5. **Flag inconsistencies** — note where the code deviates from its own patterns.
+6. **Propose consolidation** — but do not apply it until approved.
 
 ## Validation Rules
 
@@ -192,10 +194,11 @@ After every component implementation, check:
 - [ ] All colors reference tokens from Section 2. No raw hex outside `DESIGN.md`.
 - [ ] All font sizes match Section 3 scale. No arbitrary sizes.
 - [ ] All spacing values are multiples of `--space-1` (4px). No magic numbers.
-- [ ] Interactive elements have all required states from Section 6.
+- [ ] Interactive elements have all required states from Section 5 and Section 6.
 - [ ] Depth treatment matches the chosen strategy from Section 7.
 - [ ] Component reused 2+ times? Documented in Section 5.
 - [ ] Motion follows the timing table. No arbitrary durations.
+- [ ] Component visual QA passed for each primitive and required state before product screens were composed.
 
 ## Memory Management
 

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/EVIDENCE.md

@@ -0,0 +1,89 @@
+# Designpowers Materialization Evidence
+
+Scenario: designpowers reference corpus is sourced from a pinned submodule and materialized into the frontend skill at build/package time.
+
+## Required Checks
+
+### Source commit
+
+```sh
+$ git -C packages/shared-skills/upstreams/designpowers rev-parse HEAD
+cb00757da9d554591fa78d27aa1854d60a05c4f7
+```
+
+### Materialized skill directory count
+
+```sh
+$ find packages/shared-skills/skills/frontend/references/designpowers/vendor/skills -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' '
+27
+```
+
+### Materialized agent file count
+
+```sh
+$ find packages/shared-skills/skills/frontend/references/designpowers/vendor/agents -maxdepth 1 -type f -name '*.md' | wc -l | tr -d ' '
+10
+```
+
+### Raw upstream router/bridge-contaminated skills excluded
+
+```sh
+$ for s in figma-bridge design-express design-library using-designpowers design-discovery design-memory design-state design-strategy design-taste; do test ! -e packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/$s || exit 1; done
+exit=0
+```
+
+### Disallowed integration directories absent
+
+```sh
+$ find packages/shared-skills/skills/frontend/references/designpowers/vendor -path '*/hooks/*' -o -path '*/scripts/*' -o -path '*/.claude/*' -o -path '*/.gemini/*' -o -path '*/.github/*'
+```
+
+## Byte-for-byte And Normalized Checks
+
+### LICENSE cmp
+
+```sh
+$ cmp -s packages/shared-skills/upstreams/designpowers/LICENSE packages/shared-skills/skills/frontend/references/designpowers/vendor/LICENSE
+exit=0
+```
+
+### Agent cmp loop
+
+```sh
+$ for file in packages/shared-skills/upstreams/designpowers/agents/*.md; do cmp -s "$file" "packages/shared-skills/skills/frontend/references/designpowers/vendor/agents/${file##*/}"; done
+exit=0
+```
+
+### Skill normalized cmp loop
+
+```sh
+$ node --input-type=module <<'NODE'
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { includedDesignpowersSkills } from "./packages/shared-skills/scripts/designpowers-refs-manifest.mjs";
+import { normalizeSkillFrontmatter } from "./packages/shared-skills/scripts/materialize-frontend-refs.mjs";
+const rawMismatches = [];
+const normalizedMismatches = [];
+for (const name of includedDesignpowersSkills) {
+  const upstream = readFileSync(join("packages/shared-skills/upstreams/designpowers/skills", name, "SKILL.md"), "utf8");
+  const materialized = readFileSync(join("packages/shared-skills/skills/frontend/references/designpowers/vendor/skills", name, "SKILL.md"), "utf8");
+  if (upstream !== materialized) rawMismatches.push(name);
+  if (normalizeSkillFrontmatter(upstream) !== materialized) normalizedMismatches.push(name);
+}
+console.log(`raw_skill_cmp_mismatches=${rawMismatches.length}`);
+console.log(`normalized_skill_cmp_mismatches=${normalizedMismatches.length}`);
+if (normalizedMismatches.length > 0) throw new Error(`normalized mismatches: ${normalizedMismatches.join(", ")}`);
+NODE
+raw_skill_cmp_mismatches=27
+normalized_skill_cmp_mismatches=0
+exit=0
+```
+
+The 27 raw mismatches are expected frontmatter-only `description:` quoting changes from the materializer. The normalized check proves the shipped skill bodies have no upstream drift.
+
+### Excluded-router hard invocation absent
+
+```sh
+$ for f in packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/*/SKILL.md; do if rg -q 'MUST invoke the `using-designpowers` skill FIRST|invoke the `using-designpowers` skill FIRST' "$f"; then echo "$f"; exit 1; fi; done
+exit=0
+```

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/README.md

@@ -0,0 +1,48 @@
+# designpowers Frontend Reference
+
+This is an internal frontend ruleset, not a standalone skill. `/frontend` remains the only public activation point for web UI, UX, visual design, accessibility, design QA, and frontend implementation routing.
+
+Load this reference from the frontend router when a task needs design operating-layer guidance: personas, cognitive accessibility, critique, design debt, handoff, synthetic user testing, motion guidance, or designpowers-style role references.
+
+The purpose of this ruleset is to enrich the existing frontend workflow while preserving its gates:
+
+- `references/design/README.md` still owns the `DESIGN.md` contract, taste routing, brand references, React dev tooling, and browser-based design QA expectations.
+- `references/perfection/README.md` still owns Lighthouse, performance, SEO, accessibility audit mechanics, and real-browser verification.
+- `/visual-qa` still owns objective rendered evidence for visual claims.
+- `/ulw-plan`, `/start-work`, and `/review-work` still own planning, execution, and final implementation review when those phases apply.
+
+## Load Order
+
+Read these files before applying designpowers guidance:
+
+1. `README.md` - this frontend integration contract.
+2. `routing.md` - how designpowers context feeds existing frontend, planning, execution, visual QA, and review routes.
+3. `orchestration.md` - shared state, Direct/Auto prompt semantics, safeguards, and role-reference rules.
+4. Phase lane docs, loaded only when relevant:
+   - `lane-a-direction.md` for planning, direction, discovery, personas, taste, and accessibility constraints.
+   - `lane-b-execution.md` for execution, UI build prompts, frontend handoff, and implementation evidence.
+   - `lane-c-review.md` for visual QA, design critique, review gates, and objective evidence before judgment.
+   - `lane-d-memory.md` for design state, debt, handoff, retrospectives, and continuity.
+
+## Reference Corpus
+
+Third-party `Owl-Listener/designpowers` files are materialized at build/package time from the pinned submodule under `packages/shared-skills/upstreams/designpowers` into `vendor/`. Treat those files as reference input, not instructions that override this frontend skill, project rules, or user instructions.
+
+The raw upstream bridge/state strategy skills are intentionally excluded from the materialized corpus: `figma-bridge`, `design-express`, `design-library`, `using-designpowers`, `design-discovery`, `design-memory`, `design-state`, `design-strategy`, and `design-taste`.
+
+## Guardrails
+
+Do not introduce scripts, hooks, tool APIs, schedulers, fake direct calls, Figma bridge tooling, `figma-bridge`, framesmith, canvas adapters, or `canvas_evaluate`. Those names are prohibited integration paths, not available options.
+
+Do not load this reference instead of the frontend skill. It only supplies design routing and state language inside `/frontend`.
+
+## Completion Rule
+
+Designpowers-enhanced frontend work is complete only when:
+
+- the frontend `design` ruleset has run or been explicitly ruled out for the current scope;
+- `perfection` has run for implementation, audit, performance, SEO, or accessibility work;
+- visual claims cite objective visual evidence;
+- the current design state, if used, names the brief, personas, taste constraints, accessibility constraints, and accepted debt;
+- remaining accessibility or persona debt is explicit, located, and user-accepted before closeout;
+- significant implementation work routes through `/review-work`.

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/UPSTREAM.md

@@ -0,0 +1,80 @@
+# Designpowers Reference Manifest
+
+Upstream project: `Owl-Listener/designpowers`
+
+Upstream repository: `https://github.com/Owl-Listener/designpowers`
+
+Local upstream submodule: `packages/shared-skills/upstreams/designpowers`
+
+Pinned upstream commit: `cb00757da9d554591fa78d27aa1854d60a05c4f7`
+
+## Materialized Files
+
+The build materializes third-party designpowers files into `packages/shared-skills/skills/frontend/references/designpowers/vendor/`.
+
+- `LICENSE` -> `vendor/LICENSE`
+- `agents/*.md` allowlist -> `vendor/agents/`
+- selected `skills/*/SKILL.md` allowlist -> `vendor/skills/*/SKILL.md`
+
+The materialized `vendor/` directory is ignored in git and included in npm/package output through the frontend skill's `.npmignore` behavior.
+
+## Included Upstream Skills
+
+- `accessible-content`
+- `adaptive-interfaces`
+- `cognitive-accessibility`
+- `design-debate`
+- `design-debt-tracker`
+- `design-handoff`
+- `design-md`
+- `design-retrospective`
+- `design-review`
+- `design-system-alignment`
+- `designpowers-critique`
+- `heuristic-evaluation`
+- `inclusive-personas`
+- `inspiration-scouting`
+- `interaction-design`
+- `motion-choreography`
+- `research-planning`
+- `responsive-patterns`
+- `synthetic-user-testing`
+- `taste-feedback`
+- `taste-report`
+- `token-architecture`
+- `ui-composition`
+- `usability-testing`
+- `verification-before-shipping`
+- `voice-and-tone`
+- `writing-design-plans`
+
+## Included Upstream Agents
+
+- `accessibility-reviewer.md`
+- `content-writer.md`
+- `design-builder.md`
+- `design-critic.md`
+- `design-lead.md`
+- `design-scout.md`
+- `design-strategist.md`
+- `heuristic-evaluator.md`
+- `inspiration-scout.md`
+- `motion-designer.md`
+
+## Excluded Upstream Skills
+
+These upstream skills are intentionally excluded because they are bridge/state/router integration surfaces that would compete with the existing frontend/OpenAgent workflow:
+
+- `figma-bridge`
+- `design-express`
+- `design-library`
+- `using-designpowers`
+- `design-discovery`
+- `design-memory`
+- `design-state`
+- `design-strategy`
+- `design-taste`
+
+## Source Of Truth
+
+The executable path map lives in `packages/shared-skills/scripts/designpowers-refs-manifest.mjs` and is consumed by `packages/shared-skills/scripts/materialize-frontend-refs.mjs`.

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/lane-a-direction.md

@@ -0,0 +1,64 @@
+# Lane A: Direction & Discovery
+
+Lane A feeds `ulw-plan`. It does not replace Prometheus, write a parallel plan, or start implementation. Its job is to translate designpowers discovery, research, persona, taste, debate, and state capabilities into prompt context that lets `ulw-plan` produce a decision-complete work plan with design-specific acceptance criteria.
+
+## Phase Owner
+
+| Capability | Source boundary | owner | Mapping |
+|---|---|---|---|
+| Discover the human problem, constraints, audience, success criteria, and early taste signals | Authored concept preserved from excluded raw `design-discovery` | `ulw-plan` | Inject a compact design brief request before Prometheus drafts tasks. Prometheus still decides the plan structure and asks only unresolved owner decisions. |
+| Identify research gaps and inclusion-aware research methods | `research-planning` | `ulw-plan` | Convert research questions into plan discovery tasks or explicit assumptions with evidence requirements. |
+| Define principles, experience map, positioning, and success metrics | Authored concept preserved from excluded raw `design-strategy` | `ulw-plan` | Add strategy constraints and design principles to the plan's acceptance criteria. |
+| Represent the full ability spectrum | `inclusive-personas` | `ulw-plan` | Require personas and stress cases in plan inputs, including permanent, temporary, and situational contexts. |
+| Calibrate current-project taste and quality bar | Authored concept preserved from excluded raw `design-taste` | `ulw-plan` | Add live taste constraints for this project only; do not import cross-project memory as a design rule. |
+| Surface competing directions and trade-offs | `design-debate` | `ulw-plan` | When direction is ambiguous, ask Prometheus to present 2-3 options with accessibility and usability trade-offs before choosing defaults. |
+| Curate references and inspiration without copying | `inspiration-scouting` | `ulw-plan` | Add evidence-backed inspiration notes as optional plan context, with "what to take" and "what to leave." |
+| Maintain shared design state | Authored concept preserved from excluded raw `design-state` | `ulw-plan` | Read and update `.omo/frontend-design/state.md` as the OpenAgent-native state ledger. |
+
+Materialized agent references for this lane: `design-strategist`, `design-scout`, and `inspiration-scout`. They are role-reference material for OpenAgent-native prompts, not separately installed agents.
+
+## Prompt Injection
+
+Prepend this lane to a `ulw-plan` planning prompt when the work is UI, UX, product surface, visual direction, design-system, accessibility, or user-flow shaped:
+
+```text
+Load Lane A Direction & Discovery. Use designpowers only as design-process context.
+`ulw-plan` remains the planner and must write the final `.omo/plans/<slug>.md`.
+
+Before planning, extract or infer:
+- problem statement, primary users, constraints, out-of-scope
+- inclusive-personas ability spectrum and stress contexts
+- design principles, success metrics, quality bar, and current-project taste signals
+- research gaps that affect design decisions
+- competing directions and trade-offs when direction is not settled
+- existing `.omo/frontend-design/state.md` decisions, debt, and open questions
+
+Add design-specific acceptance criteria to the Prometheus plan:
+- each UI task names the persona or journey it serves
+- each task has accessibility and cognitive-accessibility checks where relevant
+- each visual decision traces to a design principle, taste signal, or design-system token
+- deferred design questions are explicit owner decisions, not hidden assumptions
+```
+
+## Evidence Requirements
+
+Lane A passes only when the plan has inspectable design context, not vague intent. Required evidence:
+
+- `.omo/plans/<slug>.md` names the design brief, personas, success criteria, constraints, and owner decisions.
+- `.omo/frontend-design/state.md` contains or references the current brief summary, personas, design principles, taste signals, decisions log, open questions, and design debt register.
+- The plan's verification entries include real-surface QA expectations for UI work, plus persona or ability-spectrum checks for affected flows.
+- Any adopted default is named with the reason it was safe to default instead of asking the user.
+
+## Guardrails
+
+- `ulw-plan` owns the final plan. Lane A may enrich prompts, but it must not create a second planning lane or standalone design plan.
+- `writing-design-plans` content is used only as task-quality guidance; Prometheus remains the source of executable TODOs.
+- Cross-project memory is descriptive only and must not steer this project's direction unless the user states the preference now.
+- Direction debates pause for user decision when the trade-off is product-shaping, accessibility-critical, or hard to reverse.
+- No new scheduler, background automation, or project root design-state convention is introduced; state stays at `.omo/frontend-design/state.md`.
+
+## Pass / Fail Behavior
+
+PASS when `ulw-plan` receives this lane context and produces a decision-complete plan whose tasks are design-aware, persona-aware, and evidence-bound.
+
+FAIL when the plan skips inclusive-personas, buries accessibility as a final polish item, treats taste as generic style, writes a parallel design plan, or leaves design decisions for start-work workers to invent.

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/lane-b-execution.md

@@ -0,0 +1,65 @@
+# Lane B: Design Execution Guidance
+
+Lane B feeds `start-work` workers and always loads `frontend` for UI implementation. It does not install a separate builder. Its job is to carry designpowers composition, interaction, motion, content, responsive, adaptive, token, and cognitive-accessibility guidance into worker prompts while keeps ownership of decomposition, implementation, QA, evidence, and ledger updates.
+
+## Phase Owner
+
+| Capability | Materialized designpowers source | owner | Mapping |
+|---|---|---|---|
+| Visual hierarchy, layout, color, typography, touch targets, and WCAG contrast | `ui-composition` | `start-work` worker plus `frontend` | Add visual constraints and acceptance checks to worker assignments. `frontend` remains the required UI implementation skill. |
+| States, feedback, loading, error, keyboard, touch, and recovery behavior | `interaction-design` | `start-work` worker plus `frontend` | Require every interactive component to define default, hover, focus, active, disabled, loading, success, and error states where applicable. |
+| Purposeful motion and reduced-motion alternatives | `motion-choreography` | `start-work` worker plus `frontend` | Require motion specs to explain what changed, what to look at next, or how elements relate; require safe alternatives. |
+| Content-driven breakpoints and zoom behavior | `responsive-patterns` | `start-work` worker plus `frontend` | Require responsive proof at narrow, mid, desktop, and 200 percent zoom scenarios when the surface is visual. |
+| User preference adaptation | `adaptive-interfaces` | `start-work` worker plus `frontend` | Require support for relevant preferences such as color scheme, contrast, reduced motion, text sizing, and density. |
+| Mental load, wayfinding, focus management, memory demands, and recovery paths | `cognitive-accessibility` | `start-work` worker plus `frontend` | Add COGA-style checks directly to worker acceptance criteria for flows, forms, navigation, and dense tools. |
+| Plain-language labels, headings, alt text, link text, errors, and instructions | `accessible-content` and `voice-and-tone` | `start-work` worker plus `frontend` | Require final copy, no placeholders, useful errors, readable labels, and consistent tone. |
+| Tokens and design-system consistency | `token-architecture` and `design-system-alignment` | `frontend` | Require real design tokens and existing component patterns before new one-off styling. |
+
+Materialized agent references for this lane: `design-lead`, `motion-designer`, and `content-writer`. They are prompt-role references for spawned OpenAgent work, not alternate executors.
+
+## Prompt Injection
+
+Add this block to each `start-work` implementation worker that touches UI:
+
+```text
+Load `frontend` for UI implementation. Also apply Lane B Design Execution Guidance.
+
+Use the OpenAgent plan and `.omo/frontend-design/state.md` as source of truth. Carry forward:
+- design principles, personas, taste direction, and accepted trade-offs
+- ui-composition requirements for hierarchy, spacing, type, color, contrast, and touch targets
+- interaction-design requirements for all states, feedback, keyboard, touch, loading, empty, and error paths
+- motion-choreography requirements for purposeful motion and reduced-motion alternatives
+- responsive-patterns requirements for content-driven breakpoints and 200 percent zoom
+- adaptive-interfaces requirements for relevant user preferences
+- cognitive-accessibility requirements for mental load, wayfinding, focus, memory, and recovery
+- accessible-content and voice-and-tone requirements for labels, headings, alt text, link text, and errors
+- token-architecture and design-system-alignment requirements for reusable tokens and existing components
+
+Do not invent visual direction that conflicts with the plan. If the plan lacks a design decision that affects users, return BLOCKED with the exact missing owner decision.
+```
+
+## Evidence Requirements
+
+Lane B worker DoneClaims must include:
+
+- Exact changed files and the `frontend` references loaded.
+- The real-surface QA invocation required by `start-work` for the UI surface, with captured artifact path.
+- Screenshot, browser, HTTP, or tmux artifacts appropriate to the visible surface.
+- Accessibility evidence from the existing OpenAgent frontend path, such as Lighthouse, react-doctor, keyboard checks, or other plan-required checks.
+- A short design trace: which persona, design principle, token, or state requirement each major UI decision satisfies.
+- Cleanup receipts for any browser session, server, tmux session, temporary artifact, or process used during QA.
+
+## Guardrails
+
+- UI implementation always goes through `frontend`; Lane B only enriches the worker prompt.
+- `start-work` owns decomposition, worker dispatch, evidence ledger entries, adversarial checks, and completion state.
+- The materialized `design-builder` concept is not used as an available executor. OpenAgent workers build.
+- No placeholders, generic copy, unverified contrast claims, decorative-only motion, or one-off hardcoded design systems pass this lane.
+- Accessibility and cognitive-accessibility are implementation constraints, not review-only cleanup.
+- Direct or auto mode language is prompt-only and cannot create new automation.
+
+## Pass / Fail Behavior
+
+PASS when every UI worker loads `frontend`, implements against the OpenAgent plan plus Lane B constraints, and returns evidence showing the design works through the actual surface.
+
+FAIL when a worker skips `frontend`, invents unplanned design direction, omits cognitive-accessibility checks for complex flows, ships placeholder content, leaves required states undesigned, or claims success without captured real-surface evidence.