oh-my-opencode 4.13.0 → 4.14.0

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/agent_sessions/sqlite_scanners.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import TypeAlias
+
+from .jsonio import as_map, parse_json_text, text
+from .timeparse import file_time, unix_millis
+from .transcript import content_text, env_path, existing, flat_parallel, recent
+from .types import Json, JsonMap, Session
+
+SqlValue: TypeAlias = str | int | float | bytes | None
+SqlRow: TypeAlias = tuple[SqlValue, ...]
+
+
+def scan_kodu(extra_roots: tuple[Path, ...], workers: int) -> list[Session]:
+    appdata = env_path("APPDATA")
+    roots = _roots(
+        [
+            Path.home() / "Library" / "Application Support" / "Code" / "User" / "globalStorage" / "kodu-ai.claude-dev-experimental",
+            Path.home() / ".config" / "Code" / "User" / "globalStorage" / "kodu-ai.claude-dev-experimental",
+            *(path / "Code" / "User" / "globalStorage" / "kodu-ai.claude-dev-experimental" for path in (appdata,) if path is not None),
+        ],
+        extra_roots,
+        ("kodu-ai.claude-dev-experimental",),
+    )
+    paths = [root / "db" / "Azad.db" for root in roots if (root / "db" / "Azad.db").exists()]
+    return flat_parallel(recent(paths), workers, _kodu_db)
+
+
+def scan_cursor_cli(extra_roots: tuple[Path, ...], workers: int) -> list[Session]:
+    roots = _roots([Path.home() / ".cursor"], extra_roots, (".cursor",))
+    paths = [path for root in roots for path in (root / "chats").glob("*/*/store.db")]
+    return flat_parallel(recent(paths), workers, _cursor_db)
+
+
+def _kodu_db(path: Path) -> list[Session]:
+    try:
+        with sqlite3.connect(path) as conn:
+            tasks = _fetch_all(
+                conn,
+                "select id, name, dir_absolute_path, created_at, updated_at, tokens_in, tokens_out, cache_reads, cache_writes, cost from tasks"
+            )
+            return [_kodu_session(path, conn, row) for row in tasks]
+    except sqlite3.Error:
+        return []
+
+
+def _kodu_session(path: Path, conn: sqlite3.Connection, row: SqlRow) -> Session:
+    sid = _row_text(row, 0) or ""
+    messages = _fetch_all(
+        conn,
+        "select role, content, model_id, started_at, finished_at, tokens_in, tokens_out, cache_reads, cache_writes, cost from messages where task_id = ? order by started_at",
+        (sid,),
+    )
+    first_user = last_user = ""
+    model = None
+    for message in messages:
+        model = model or _row_text(message, 2)
+        if _row_text(message, 0) == "user":
+            prompt = _content(_row_text(message, 1))
+            first_user = first_user or prompt
+            last_user = prompt
+    return Session(
+        "kodu",
+        sid,
+        str(path),
+        _row_text(row, 2),
+        unix_millis(_row_int(row, 3)),
+        unix_millis(_row_int(row, 4)) or file_time(path),
+        None,
+        model,
+        first_user,
+        _usage(row, (5, "input"), (6, "output"), (7, "cacheRead"), (8, "cacheWrite"), (9, "cost_total")),
+        last_user_message=last_user,
+    )
+
+
+def _cursor_db(path: Path) -> list[Session]:
+    try:
+        with sqlite3.connect(path) as conn:
+            rows = _fetch_all(conn, "select data from blobs")
+    except sqlite3.Error:
+        return []
+    first_user = last_user = ""
+    for row in rows:
+        data = _json_blob(_row_bytes(row, 0))
+        if data is None or data.get("role") != "user":
+            continue
+        prompt = _cursor_prompt(_content(data.get("content")))
+        if prompt:
+            first_user = first_user or prompt
+            last_user = prompt
+    if not first_user:
+        return []
+    return [
+        Session(
+            "cursor-cli",
+            path.parent.name,
+            str(path),
+            None,
+            file_time(path),
+            file_time(path),
+            "cursor",
+            None,
+            first_user,
+            {"blob_count": len(rows)},
+            last_user_message=last_user,
+        )
+    ]
+
+
+def _content(value: Json | None) -> str:
+    parsed = parse_json_text(value) if isinstance(value, str) else value
+    return content_text(parsed) or (value if isinstance(value, str) else "")
+
+
+def _json_blob(value: bytes | None) -> JsonMap | None:
+    if value is None:
+        return None
+    try:
+        decoded = value.decode()
+    except UnicodeDecodeError:
+        return None
+    return as_map(parse_json_text(decoded))
+
+
+def _cursor_prompt(value: str) -> str:
+    start = value.find("<user_query>")
+    end = value.find("</user_query>")
+    if start >= 0 and end > start:
+        return value[start + len("<user_query>") : end].strip()
+    if value.lstrip().startswith("<user_info>"):
+        return ""
+    return value.strip()
+
+
+def _usage(row: SqlRow, *fields: tuple[int, str]) -> JsonMap:
+    result: JsonMap = {}
+    for index, key in fields:
+        value = _row_number(row, index)
+        if value is not None:
+            result[key] = value
+    return result
+
+
+def _fetch_all(conn: sqlite3.Connection, sql: str, params: tuple[str, ...] = ()) -> list[SqlRow]:
+    rows: list[SqlRow] = conn.execute(sql, params).fetchall()
+    return rows
+
+
+def _row_text(row: SqlRow, index: int) -> str | None:
+    value = row[index] if index < len(row) else None
+    return text(value) if not isinstance(value, bytes) else None
+
+
+def _row_bytes(row: SqlRow, index: int) -> bytes | None:
+    value = row[index] if index < len(row) else None
+    return value if isinstance(value, bytes) else None
+
+
+def _row_number(row: SqlRow, index: int) -> int | float | None:
+    value = row[index] if index < len(row) else None
+    return value if isinstance(value, int | float) else None
+
+
+def _row_int(row: SqlRow, index: int) -> int | None:
+    value = row[index] if index < len(row) else None
+    return value if isinstance(value, int) else None
+
+
+def _roots(defaults: list[Path], extra_roots: tuple[Path, ...], children: tuple[str, ...]) -> list[Path]:
+    candidates = [*defaults]
+    for root in extra_roots:
+        candidates.append(root)
+        candidates.extend(root / child for child in children)
+    return existing(candidates)

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/agent_sessions/timeparse.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+def date_bound(value: str | None, end: bool = False) -> datetime | None:
+    if value is None:
+        return None
+    text = value.strip().lower()
+    now = datetime.now(timezone.utc)
+    if text == "today":
+        base = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    elif text == "yesterday":
+        base = (now - timedelta(days=1)).replace(hour=0, minute=0, second=0, microsecond=0)
+    elif text.endswith("d") and text[:-1].isdigit():
+        base = (now - timedelta(days=int(text[:-1]))).replace(hour=0, minute=0, second=0, microsecond=0)
+    else:
+        parts = [int(part) for part in text.split("-")]
+        base = datetime(parts[0], parts[1] if len(parts) > 1 else 1, parts[2] if len(parts) > 2 else 1, tzinfo=timezone.utc)
+    if not end:
+        return base
+    if text in {"today", "yesterday"} or text.endswith("d") or len(text.split("-")) == 3:
+        return base + timedelta(days=1)
+    if len(text.split("-")) == 2:
+        return datetime(base.year + (base.month // 12), (base.month % 12) + 1, 1, tzinfo=timezone.utc)
+    return datetime(base.year + 1, 1, 1, tzinfo=timezone.utc)
+
+
+def parse_stamp(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def unix_seconds(value: int | float | None) -> str | None:
+    return datetime.fromtimestamp(value, timezone.utc).isoformat() if value is not None else None
+
+
+def unix_millis(value: int | None) -> str | None:
+    return datetime.fromtimestamp(value / 1000, timezone.utc).isoformat() if value is not None else None
+
+
+def file_time(path: Path) -> str | None:
+    try:
+        return datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).isoformat()
+    except OSError:
+        return None

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/agent_sessions/transcript.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from heapq import nlargest
+from pathlib import Path
+from typing import Callable
+
+from .jsonio import as_map, iter_jsonl, parse_json_text, text
+from .timeparse import file_time
+from .types import Json, JsonMap, Session
+
+MAX_PLATFORM_FILES = 2000
+
+
+def jsonl_parallel(paths: list[Path], workers: int, platform: str, fallback_id: Callable[[Path], str]) -> list[Session]:
+    if not paths:
+        return []
+    sessions: list[Session] = []
+    with ThreadPoolExecutor(max_workers=min(workers, max(len(paths), 1))) as pool:
+        futures = [pool.submit(jsonl_session, platform, path, fallback_id(path)) for path in paths]
+        for future in as_completed(futures):
+            sessions.append(future.result())
+    return sessions
+
+
+def flat_parallel(paths: list[Path], workers: int, read: Callable[[Path], list[Session]]) -> list[Session]:
+    if not paths:
+        return []
+    sessions: list[Session] = []
+    with ThreadPoolExecutor(max_workers=min(workers, max(len(paths), 1))) as pool:
+        futures = [pool.submit(read, path) for path in paths]
+        for future in as_completed(futures):
+            sessions.extend(future.result())
+    return sessions
+
+
+def jsonl_session(platform: str, path: Path, fallback_id: str) -> Session:
+    sid = fallback_id
+    cwd = provider = model = first_user = parent = agent = None
+    last_user = ""
+    created = updated = None
+    usage: JsonMap = {}
+    for data in iter_jsonl(path):
+        event_type = data.get("type")
+        session_line_id = text(data.get("id")) if event_type == "session" else None
+        sid = text(data.get("sessionId")) or session_line_id or sid
+        cwd = cwd or text(data.get("cwd"))
+        created = created or text(data.get("timestamp"))
+        updated = text(data.get("timestamp")) or updated
+        provider = provider or text(data.get("provider"))
+        model = model or text(data.get("modelId")) or text(data.get("model"))
+        payload = as_map(data.get("payload"))
+        if event_type == "session_meta" and payload is not None:
+            sid = text(payload.get("id")) or sid
+            cwd = cwd or text(payload.get("cwd"))
+            provider = provider or text(payload.get("model_provider"))
+            source_parent, source_agent = spawn_info(payload.get("source"))
+            parent = parent or source_parent
+            agent = agent or source_agent or nick_role(text(payload.get("agent_nickname")), text(payload.get("agent_role")))
+        message = as_map(data.get("message")) or payload or {}
+        provider = provider or text(message.get("provider"))
+        model = model or text(message.get("model"))
+        prompt = user_text(data, message)
+        if prompt:
+            first_user = first_user or prompt
+            last_user = prompt
+        merge_usage(usage, as_map(message.get("usage")) or as_map(data.get("usage")))
+    return Session(platform, sid, str(path), cwd, created or file_time(path), updated or created or file_time(path), provider, model, first_user or "", usage, parent, agent, last_user)
+
+
+def spawn_info(source: Json | None) -> tuple[str | None, str | None]:
+    data = as_map(parse_json_text(source) if isinstance(source, str) else source)
+    if data is None:
+        return None, None
+    subagent = data.get("subagent")
+    if isinstance(subagent, str):
+        return None, subagent
+    subagent_map = as_map(subagent)
+    spawn = as_map(subagent_map.get("thread_spawn")) if subagent_map is not None else None
+    if spawn is None:
+        return None, None
+    return text(spawn.get("parent_thread_id")), nick_role(text(spawn.get("agent_nickname")), text(spawn.get("agent_role")))
+
+
+def nick_role(nickname: str | None, role: str | None) -> str | None:
+    if nickname and role:
+        return f"{nickname} ({role})"
+    return nickname or role
+
+
+def user_text(data: JsonMap, message: JsonMap) -> str:
+    if data.get("type") == "user":
+        value = content_text(data.get("content"))
+        if value:
+            return value
+    if message.get("role") == "user":
+        return content_text(message.get("content"))
+    return ""
+
+
+def content_text(value: Json | None) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts = [text(item.get("text")) or text(item.get("content")) or "" for item in value if isinstance(item, dict)]
+        return "\n".join(part for part in parts if part)
+    return ""
+
+
+def merge_usage(target: JsonMap, value: JsonMap | None) -> None:
+    if value is None:
+        return
+    for key in ("totalTokens", "total_tokens", "input", "output", "cacheRead", "cacheWrite"):
+        if key in value:
+            target[key] = value[key]
+    cost = as_map(value.get("cost"))
+    if cost is not None and "total" in cost:
+        target["cost_total"] = cost["total"]
+
+
+def existing(paths: list[Path]) -> list[Path]:
+    seen: set[Path] = set()
+    result: list[Path] = []
+    for path in paths:
+        if str(path) and path.exists() and path not in seen:
+            seen.add(path)
+            result.append(path)
+    return result
+
+
+def recent(paths: list[Path]) -> list[Path]:
+    return nlargest(MAX_PLATFORM_FILES, paths, key=modified_time)
+
+
+def modified_time(path: Path) -> float:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def stem_id(path: Path, marker: str) -> str:
+    return path.stem.split(marker)[-1].split("_")[-1]
+
+
+def env_path(name: str) -> Path | None:
+    value = os.environ.get(name)
+    return Path(value).expanduser() if value else None

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/agent_sessions/types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeAlias
+
+
+Json: TypeAlias = str | int | float | bool | None | list["Json"] | dict[str, "Json"]
+JsonMap: TypeAlias = dict[str, Json]
+
+
+@dataclass(frozen=True, slots=True)
+class Options:
+    platforms: frozenset[str]
+    roots: tuple[Path, ...]
+    queries: tuple[str, ...]
+    date_from: str | None
+    date_to: str | None
+    cwd: str | None
+    model: str | None
+    limit: int
+    workers: int
+    include_subagents: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Session:
+    platform: str
+    id: str
+    path: str
+    cwd: str | None
+    created_at: str | None
+    updated_at: str | None
+    provider: str | None
+    model: str | None
+    first_user_message: str
+    usage: JsonMap
+    parent_id: str | None = None
+    agent: str | None = None
+    last_user_message: str = ""
+
+    def to_json(self) -> JsonMap:
+        return {
+            "platform": self.platform,
+            "id": self.id,
+            "path": self.path,
+            "cwd": self.cwd,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "provider": self.provider,
+            "model": self.model,
+            "first_user_message": self.first_user_message[:300],
+            "last_user_message": (self.last_user_message or self.first_user_message)[:300],
+            "usage": self.usage,
+            "parent_id": self.parent_id,
+            "agent": self.agent,
+        }

package/packages/omo-codex/plugin/skills/coding-agent-sessions/scripts/find-agent-sessions.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+# --- How to run ---
+# python3 scripts/find-agent-sessions.py list --limit 20
+# python3 scripts/find-agent-sessions.py search "commit" --from 7d
+# python3 scripts/find-agent-sessions.py get <session-id>
+from __future__ import annotations
+
+import sys
+import runpy
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+if __name__ == "__main__":
+    _ = runpy.run_module("agent_sessions.cli", run_name="__main__")

package/packages/omo-codex/plugin/skills/frontend/ATTRIBUTION.md

@@ -9,10 +9,12 @@ below. Modifications to the original files are noted where applicable.
 
 These third-party references are NOT committed to this repository. Each upstream is
 tracked as a pinned git submodule under `packages/shared-skills/upstreams/<name>`, and the
-build materializes the referenced files verbatim, path-mapped into this skill's
-`references/` tree, when packaging the published artifact. The `Pinned upstream commit`
-line in each section below records the exact submodule commit that the materialization
-reads.
+build materializes the referenced files path-mapped into this skill's `references/` tree,
+when packaging the published artifact. The file bodies are copied verbatim, except
+materialized `SKILL.md` frontmatter may normalize an unquoted single-line `description:`
+scalar into a JSON-quoted YAML string so Codex/OpenCode frontmatter parsing remains
+deterministic; the description text itself is unchanged. The `Pinned upstream commit` line
+in each section below records the exact submodule commit that the materialization reads.
 
 ---
 
@@ -63,11 +65,12 @@ The taste-skill files and image-generation skills under `frontend/references/des
 (`taste-skill.md`, `gpt-tasteskill.md`, `minimalist-skill.md`, `brutalist-skill.md`,
 `soft-skill.md`, `redesign-skill.md`, `image-to-code-skill.md`, `output-skill.md`,
 `stitch-skill.md`, `imagegen-frontend-web.md`, `imagegen-frontend-mobile.md`,
-`imagegen-brandkit.md`) are path-mapped verbatim copies of the per-skill `SKILL.md` files
-from the taste-skill project (each `skills/<name>/SKILL.md` is renamed to
+`imagegen-brandkit.md`) are path-mapped copies of the per-skill `SKILL.md` files from the
+taste-skill project (each `skills/<name>/SKILL.md` is renamed to
 `references/design/<name>.md`; `imagegen-brandkit.md` maps from `skills/brandkit/SKILL.md`).
 They are not committed here; the build materializes them from the pinned submodule under
-`packages/shared-skills/upstreams/taste-skill`.
+`packages/shared-skills/upstreams/taste-skill`. Only the allowed frontmatter description
+quoting normalization described above may alter these materialized `SKILL.md` files.
 
 - Source: https://github.com/Leonxlnx/taste-skill
 - Pinned upstream commit: 06d6028b5c623016c59ce8536f578e5a1127b499
@@ -140,7 +143,48 @@ SOFTWARE.
 
 ---
 
-## 4. Project-original files
+## 4. designpowers (Owl-Listener) — design operating-layer references
+
+The designpowers reference corpus under `frontend/references/designpowers/vendor/` is
+path-mapped from the designpowers project. It is not committed here; the build
+materializes the selected files from the pinned submodule under
+`packages/shared-skills/upstreams/designpowers`. The materialized set includes the
+upstream `LICENSE`, ten `agents/*.md` role-reference files, and selected
+`skills/*/SKILL.md` files. Bridge/state/router integration skills are intentionally
+excluded; see `frontend/references/designpowers/UPSTREAM.md` for the allowlist and
+exclusion list. Only the allowed frontmatter description quoting normalization described
+above may alter these materialized `SKILL.md` files.
+
+- Source: https://github.com/Owl-Listener/designpowers
+- Pinned upstream commit: cb00757da9d554591fa78d27aa1854d60a05c4f7
+
+```
+MIT License
+
+Copyright (c) 2026 MC Dean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## 5. Project-original files
 
 `frontend/SKILL.md`, `frontend/references/design/README.md`, `_INDEX.md`,
 `design-system-architecture.md`, `react-dev-tooling-skill.md`,

package/packages/omo-codex/plugin/skills/frontend/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: frontend
-description: "MUST USE for ANY frontend, web UI, UX, or visual work — building, styling, or redesigning pages/components, React project setup, performance audits, design QA. Routes three rulesets: design (anti-slop taste router over 12 taste skills + 69 brand DESIGN.md refs — Apple, Stripe, Linear, Notion, Vercel, Claude, Nike — plus React dev tooling gate: react-grab, react-scan, react-doctor), perfection (Lighthouse 100 in every category via real Playwright Chromium audits, NEVER the lighthouse CLI, never by weakening UX), ui-ux-db (searchable 50+ styles, 97 palettes, 57 font pairings, 99 UX guidelines). Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, taste, premium, luxury, minimal, brutalist, Awwwards, anti-slop, polish, DESIGN.md, mockup, react setup, react-scan, react-doctor, lighthouse, performance, Core Web Vitals, LCP, CLS, INP, SEO, accessibility, a11y, WCAG, audit my site, make this faster, color palette, font pairing, looks generic, make it pretty, like X brand."
+description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand."
 ---
 
 # Frontend
 
-This file is a router, not a rulebook. The rules live in three rulesets under `references/`; your first job is to load the smallest set of files that covers the request, state which you loaded in one sentence, then execute under their guidance. Loading nothing and freestyling produces the generic AI-slop output this skill exists to prevent; loading everything wastes context and creates contradictory instructions.
+This file is a router, not a rulebook. The rules live in four rulesets under `references/`; your first job is to load the smallest set of files that covers the request, state which you loaded in one sentence, then execute under their guidance. Loading nothing and freestyling produces the generic AI-slop output this skill exists to prevent; loading everything wastes context and creates contradictory instructions.
+
+**The bar is not clean-and-correct — it is work a senior designer at Linear, Stripe, or Supabase would ship.** Correct-but-flat is a failure, not a finish. Protect the surface as hard as you protect the build: design is a first-class deliverable, not a one-shot decision you lock and walk away from.
 
 ## Phase 0 — Route (before any UI work)
 
@@ -14,9 +16,21 @@ This file is a router, not a rulebook. The rules live in three rulesets under `r
 | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
 | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
 | Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
+| Design operating-layer work: personas, cognitive accessibility, design critique, design debt, handoff, synthetic user testing, or designpowers-style guidance | `references/designpowers/README.md`. This is an internal frontend ruleset, not a separate skill. It enriches `/frontend` routing with design brief, role-reference, accessibility, evidence, and debt language while preserving the `design` and `perfection` gates. |
 
 **For implementation work, design + perfection load together.** A page that hits Lighthouse 100 but looks like AI slop has failed; a page that looks beautiful but ships a 2 MB bundle has failed. Both win or neither does.
 
+## Design System and Component Workflow
+
+Every implementation must choose one of these branches before UI code changes:
+
+1. **Concrete visual reference:** if the user supplies a screenshot, generated mockup, Stitch/Imagen output, Figma export, overview, or annotated reference packet, treat it as the visual contract. Load `references/design/image-to-code-skill.md` plus the relevant design/perfection files, extract the reference's exact tokens, layout geometry, copy, spacing, states, and responsive intent into `DESIGN.md`, then implement reusable primitives against that contract. Final QA must run `/visual-qa` in reference-fidelity mode: compare the actual UI against the reference packet pixel-by-pixel and verify the code is an extensible design-system implementation, not a screenshot-matched one-off.
+2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, use `references/design/_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. Define Section 5 primitives with variants, default/hover/active/focus/disabled/loading/empty/error states, accessibility, and motion before code. Build them first in a component showcase or state harness; each primitive and required state must pass mobile/tablet/desktop visual QA before product screens.
+3. **Existing project with `DESIGN.md` or a component system:** read it, follow it, and update it before implementation only when the requested work needs a new token, primitive, state, motion rule, accessibility constraint, accepted debt, or reference-fidelity requirement.
+4. **Existing project with UI but no `DESIGN.md` and no reusable component layer:** STOP and ask the user one focused question: should you preserve the current look with copy-nearby styling, or extract a real `DESIGN.md` plus reusable components before continuing? Do not silently choose.
+
+When `references/designpowers/README.md` is loaded for implementation, redesign, or design-system work, feed its personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
+
 ## Ruleset 1 — design (`references/design/`)
 
 The reference library has one architecture file, 12 taste skills (Layer A — *how to execute*), and 69 brand design systems (Layer B — *what it should look like*). Most non-trivial tasks load **one Layer A + one Layer B**. `README.md` carries the full routing flow, stacking rules, anti-patterns, and the mandatory browser-based Design QA phase; `_INDEX.md` catalogs all 81 files with mood-to-brand mappings — read it whenever routing is not obvious from the tables below.
@@ -31,11 +45,11 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
 
 | File | Read when the user says… |
 |---|---|
-| `taste-skill.md` | Nothing style-specific — "make a good UI". The default all-rounder. |
-| `gpt-tasteskill.md` | "Awwwards-tier", "wow factor", "cinematic", "scroll-triggered", or `taste-skill` results felt too safe. |
+| `taste-skill.md` | Neutral or operational UI with no surface ambition — internal tools, dashboards, "just make it usable". The safe default; do NOT settle here when the brief signals glossy / premium / startup-grade craft. |
+| `gpt-tasteskill.md` | "Awwwards-tier", "wow factor", "cinematic", "scroll-triggered" marketing/landing experiences. |
 | `minimalist-skill.md` | "minimal", "clean", "Notion-like", "Linear-like", "editorial". |
 | `brutalist-skill.md` | "brutalist", "raw", "Swiss", "experimental", "anti-design". |
-| `soft-skill.md` | "premium", "luxury", "calm", "expensive", "spa", "boutique", "elegant". |
+| `soft-skill.md` | "premium", "luxury", "calm", "expensive", "elegant", AND glossy / glassy / liquid-glass / startup-grade product surfaces — pair with a high-craft Layer B (`supabase`, `linear.app`, `vercel`, `stripe`). |
 | `redesign-skill.md` | Improving EXISTING UI — "this looks bad", "fix the design". Audit-first workflow; never use on greenfield. |
 | `image-to-code-skill.md` | "Generate the design first, then code it." Pair with one imagegen file below. |
 | `output-skill.md` | Stacks on any style skill when output is incomplete — placeholders, `// TODO`, half-done components. |
@@ -79,23 +93,30 @@ python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --stack <stac
 
 Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `web` `prompt`. Stacks: `html-tailwind` (default) `react` `nextjs` `vue` `svelte` `astro` `swiftui` `react-native` `flutter` `shadcn` `jetpack-compose`.
 
+## Ruleset 4 — designpowers (`references/designpowers/`)
+
+`README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it when a frontend task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
+
 ## Quick routes — most common requests
 
 | Request | Load |
 |---|---|
-| "Build a landing page" (no direction given) | `design/README.md` + `design/taste-skill.md` + `perfection/README.md` |
+| "Build a landing page" (no direction given) | `design/README.md` + `design/_INDEX.md` shortlist → exactly one Layer B reference + `design/taste-skill.md` + `perfection/README.md` |
 | "Linear-style landing page" | `design/README.md` + `design/linear.app.md` + `design/taste-skill.md` + `perfection/README.md` |
 | "Premium SaaS hero like Stripe" | `design/README.md` + `design/stripe.md` + `design/soft-skill.md` + `perfection/README.md` |
 | "Improve this existing dashboard" | `design/README.md` + `design/redesign-skill.md` + `perfection/README.md` |
+| "Build this screenshot / Imagen mock / Stitch output exactly" | `design/README.md` + `design/image-to-code-skill.md` + `perfection/README.md` + `/visual-qa` reference-fidelity mode |
 | "Audit my site" / "make this page faster" | `perfection/README.md` (+ `perfection/react-perf-tooling.md` if React) |
 | "Mockup image of a fintech app" — no code | `design/imagegen-frontend-mobile.md` (+ a Layer B brand if named) |
 | "What palette/fonts fit a wellness brand?" | `ui-ux-db/README.md` → search CLI |
 | "Set up this React project" | `design/README.md` + `design/react-dev-tooling-skill.md` |
+| "Use designpowers", "make the design workflow stronger", "add personas/accessibility/debt/handoff" | `design/README.md` + `designpowers/README.md` (+ `perfection/README.md` if implementation or audit follows) |
 
-## Shared axioms (all three rulesets agree — apply always)
+## Shared axioms (all four rulesets agree — apply always)
 
 - **No design system = no UI work.** `DESIGN.md` exists before components do; every color, font size, and spacing value traces back to a token in it.
-- **Never weaken UX to buy points.** No dropping animations, hiding content, or simplifying interactions for a score or a deadline.
+- **Concrete reference = contract.** When a screenshot, generated mockup, overview, or annotated reference exists, the implementation must match its pixels, copy, component structure, and responsive intent unless the user explicitly accepts a deviation.
+- **Never weaken UX OR flatten the surface to buy points.** No dropping animations, hiding content, simplifying interactions, or replacing rendered/lit material with flat fills and flat geometric primitives for a Lighthouse score or a deadline. Hit 100 AND keep the surface dimensional — both, or neither.
 - **No emojis as icons.** SVG icon sets only (Lucide, Heroicons, Radix, Phosphor).
 - **GPU-composited animation only** — `transform`, `opacity`, `filter`; never animate layout properties.
 - **Verify in a real browser before declaring done.** Screenshots at 375 / 768 / 1280px; hover, focus, loading, empty, and error states all exercised.