From b0d31c6b60dba4e254b7f52ff4d2e9d7a1c735d0 Mon Sep 17 00:00:00 2001
From: yangshu <yangshu2087@gmail.com>
Date: Wed, 1 Apr 2026 18:15:59 -0700
Subject: [PATCH 1/3] feat: add frontend design review workflow

---
 .../skills/frontend-design-review/SKILL.md    | 83 +++++++++++++++++++
 AGENTS.md                                     |  9 ++
 2 files changed, 92 insertions(+)
 create mode 100644 .agents/skills/frontend-design-review/SKILL.md

diff --git a/.agents/skills/frontend-design-review/SKILL.md b/.agents/skills/frontend-design-review/SKILL.md
new file mode 100644
index 0000000..076392b
--- /dev/null
+++ b/.agents/skills/frontend-design-review/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: frontend-design-review
+description: Review or implement front-end UI work with a design-first workflow. Use when the task involves page or component design quality, translating Figma or screenshot references into code, refining spacing or typography or responsive behavior, validating UI states, or checking visual polish before merge.
+---
+
+# Frontend Design Review
+
+Use this skill when Codex should behave like a design-aware front-end implementer instead of a generic code editor.
+
+## Inputs to gather first
+
+Read the highest-signal design inputs available before changing code:
+
+1. Figma links or node IDs
+2. Repository design files under `design/`
+3. Screenshots or reference images
+4. Existing component library and tokens
+5. Product spec or acceptance notes in repo docs, Notion, or Google Drive
+
+If a design source is missing, say so explicitly and continue with the strongest remaining source instead of pretending the design is fully specified.
+
+## Working rules
+
+1. Start from system constraints, not ad hoc CSS:
+   - identify framework, styling approach, component library, and token source
+   - prefer existing components and tokens over one-off values
+2. Break UI work into four layers:
+   - layout
+   - components
+   - states
+   - responsive behavior
+3. Cover non-happy paths by default:
+   - loading
+   - empty
+   - error
+   - hover
+   - focus-visible
+   - active
+   - disabled
+4. Keep accessibility in scope:
+   - semantic HTML first
+   - keyboard reachability
+   - visible focus states
+   - contrast awareness
+5. When implementing from Figma, preserve intent rather than copying every raw pixel token if that would fight the local design system.
+
+## Verification loop
+
+Do not stop at “the code compiles.” Run a visual loop when possible:
+
+1. Launch the narrowest relevant preview or dev server.
+2. Inspect the page in a browser using the available browser automation skill.
+3. Check at least these widths when the UI is responsive:
+   - 375
+   - 768
+   - 1024
+   - 1440
+4. Look for:
+   - overflow or clipped content
+   - spacing inconsistency
+   - typography hierarchy issues
+   - broken alignment
+   - console errors
+   - missing interactive states
+5. If visual verification is not possible, state that gap explicitly.
+
+## Preferred local workflow
+
+In repositories that follow the workspace conventions:
+
+- inspect `design/design-system.md` if present
+- inspect `design/tokens.example.json` or the real token file if present
+- inspect `docs/ui-acceptance-checklist.md`
+- update `docs/agent-handoff.md` before pausing if design work is in progress
+
+## Output standard
+
+When summarizing work, include:
+
+1. what design inputs were used
+2. what UI layers changed
+3. what states and breakpoints were checked
+4. what remains visually unverified
diff --git a/AGENTS.md b/AGENTS.md
index 2ea3507..e7d8439 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -60,6 +60,15 @@
 - Do not merge raw Stitch or AI Studio output straight to `main` without an explicit Codex or human cleanup pass.
 - When work starts from Stitch or AI Studio, record the artifact paths and intended next step in `docs/agent-handoff.md` before switching tools or opening a PR.
 
+## Front-end design workflow
+
+- For front-end tasks, prefer a design-first loop: design inputs -> implementation -> browser verification -> UI review.
+- Start with the highest-signal design artifact available: Figma, checked-in design docs, screenshots, or reference shots.
+- Keep front-end repo guidance close to the code by checking in `design/README.md`, `design/design-system.md`, and `docs/ui-acceptance-checklist.md` where UI work happens.
+- Use the workspace skill `frontend-design-review` for UI implementation and polish work that needs spacing, typography, states, responsive behavior, and visual verification.
+- Prefer tokenized values and reusable components over one-off CSS when refining UI.
+- When Context7 is authenticated, prefer it for current framework and component-library docs during front-end work.
+
 ## Codex and Cursor shared protocol
 
 - Treat checked-in repository files as the shared baton between Codex and Cursor. Do not rely on chat memory to transfer state.

From ff5f72799e8fc697ab0d01d39d0b64b0ca8b7481 Mon Sep 17 00:00:00 2001
From: yangshu <yangshu2087@gmail.com>
Date: Wed, 8 Apr 2026 06:46:30 -0700
Subject: [PATCH 2/3] docs(codex): add capability governance and audit tooling

---
 AGENTS.md                           |   2 +
 docs/codex-capability-governance.md | 167 +++++++++++++++++++
 docs/codex-capability-registry.md   |  74 +++++++++
 scripts/codex-capability-audit.sh   | 243 ++++++++++++++++++++++++++++
 4 files changed, 486 insertions(+)
 create mode 100644 docs/codex-capability-governance.md
 create mode 100644 docs/codex-capability-registry.md
 create mode 100755 scripts/codex-capability-audit.sh

diff --git a/AGENTS.md b/AGENTS.md
index e7d8439..e12e2c8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,8 @@
 - Use the team skill `webpage-capture-markdown` when a webpage should be preserved as a local markdown artifact instead of only summarized in chat.
 - Use `systematic-debugging` before proposing fixes for bugs, failures, or unexpected behavior.
 - Use `requesting-code-review` before merge or after major implementation work.
+- Use `docs/codex-capability-governance.md` and `docs/codex-capability-registry.md` as the workspace source of truth for capability layering, ownership, and retirement rules.
+- Run `scripts/codex-capability-audit.sh` before expanding the default skill/plugin/profile surface.
 - Activate vendored `playwright-best-practices` only when writing or stabilizing Playwright tests beyond basic browser automation.
 - Keep `skills-lock.json` in sync with installed or vendored marketplace skills.
 - Prefer preparing a safe upgrade plan and verification steps before changing binaries under `/Applications`.
diff --git a/docs/codex-capability-governance.md b/docs/codex-capability-governance.md
new file mode 100644
index 0000000..92fb494
--- /dev/null
+++ b/docs/codex-capability-governance.md
@@ -0,0 +1,167 @@
+# Codex Capability Governance
+
+This document defines how Codex capabilities are added, routed, measured, and retired in this workspace.
+
+## Goals
+
+- Keep default Codex behavior stable, predictable, and fast enough for daily work.
+- Make heavy or domain-specific capabilities explicit instead of accidental.
+- Ensure every capability change is auditable, reversible, and measured against real work.
+
+## Governance principles
+
+1. **Default-first**
+   - Govern the default stack first: default model, reasoning tier, global AGENTS rules, enabled global skills, enabled MCP/plugin set, and execution guardrails.
+   - Anything not needed by most tasks should not live in the default layer.
+
+2. **Layered capability model**
+   - **L0 Core stable**: defaults that shape nearly every session. Changes here require the highest caution.
+   - **L1 Workspace standard**: team-shared skills and scripts used across repositories in this workspace.
+   - **L2 Project-local**: repository- or product-specific capabilities. Keep them inside the target repo instead of `~/.agents/skills`.
+   - **L3 Experimental / on-demand**: vendored third-party skills, alpha/preview paths, and anything that may help but should not influence routing by default.
+
+3. **Explicit routing beats implicit magic**
+   - A capability should have a clear trigger, a clear non-trigger, and a clear owner.
+   - If a skill/plugin cannot explain when it must be used and when it must not be used, it should not enter L0.
+
+4. **Single-source guardrails**
+   - Personal defaults: `~/.codex/config.toml`
+   - Personal guardrails: `~/.codex/AGENTS.md`
+   - Workspace policy: this repo's `AGENTS.md` and `docs/`
+   - Runtime pressure decision: `/Users/yangshu/Codex/scripts/codex-runtime-health.sh`
+
+5. **Capability changes must be reversible**
+   - Prefer disable/archive over delete.
+   - Document rollback path before promoting a capability into the default stack.
+
+## Capability lifecycle
+
+### 1) Propose
+
+For any new skill, plugin, MCP, routing rule, or default model change, first answer:
+
+- What repeated problem does it solve?
+- Is it default-worthy or only useful in a subset of tasks?
+- What is its trigger boundary?
+- What is the rollback path?
+
+### 2) Classify
+
+Assign the capability to one layer before rollout:
+
+- L0 if nearly every session benefits and wrong activation cost is low.
+- L1 if it is team-shared but not global-default critical.
+- L2 if it belongs to a product, repo, or business workflow.
+- L3 if it is exploratory, vendored, or cost/risk sensitive.
+
+### 3) Validate
+
+Before promoting a change into L0/L1, validate with:
+
+- `codex --version`
+- `codex features list`
+- `codex mcp list`
+- `/Users/yangshu/Codex/scripts/check-codex-upgrade.sh`
+- representative real tasks, not only synthetic checks
+
+### 4) Measure
+
+Track at least these quality signals:
+
+- one-pass completion rate
+- done-criteria pass rate
+- verification evidence rate
+- profile/skill routing correctness
+- high-pressure downgrade correctness
+
+Record these on a recurring scorecard or task sample set so capability changes are measured against real work.
+
+### 5) Retire
+
+Move a capability out of the default path if any of these are true:
+
+- repeated misrouting or accidental activation
+- high overlap with another capability
+- low usage over time
+- it reduces task quality or creates extra process noise
+
+Retirement order:
+
+1. remove from default path
+2. move to disabled/archive or project-local scope
+3. delete only when clearly obsolete
+
+## Operating rules by layer
+
+### L0 Core stable
+
+Examples:
+
+- default model + reasoning
+- default profiles (`quick`, `fast`, `deep`, `research`, `codex53`)
+- personal AGENTS rules
+- runtime guardrails
+
+Rules:
+
+- keep small
+- change rarely
+- always verify locally after edits
+
+### L1 Workspace standard
+
+Examples:
+
+- workspace shared skills under `.agents/skills`
+- handoff / upgrade / governance scripts in `scripts/`
+- docs that define collaboration rules
+
+Rules:
+
+- every item needs an owner and a narrow purpose
+- keep names and triggers stable
+- prefer curated subsets over full third-party skill dumps
+
+### L2 Project-local
+
+Examples:
+
+- 007 analytics/publishing skills
+- OpenClaw-specific publishing flows
+- repo-specific UI or release skills
+
+Rules:
+
+- keep inside the relevant repo under `.agents/skills`
+- do not reactivate as global skills unless reuse is proven across projects
+
+### L3 Experimental / on-demand
+
+Examples:
+
+- vendored third-party skills under `vendor/skills`
+- preview workflows or high-cost browser/tool chains
+- alpha model paths and exploratory plugins
+
+Rules:
+
+- opt-in only
+- keep behind explicit activation or explicit profile/tool choice
+- never silently influence default routing
+
+## Weekly governance cadence
+
+Run:
+
+```bash
+/Users/yangshu/Codex/scripts/codex-capability-audit.sh
+/Users/yangshu/Codex/scripts/check-codex-upgrade.sh
+```
+
+Review and act on:
+
+- default model/reasoning drift
+- global skill creep
+- disabled archive growth
+- duplicate or overlapping plugin entries
+- stale experimental capabilities that should be promoted or retired
diff --git a/docs/codex-capability-registry.md b/docs/codex-capability-registry.md
new file mode 100644
index 0000000..7dc0e07
--- /dev/null
+++ b/docs/codex-capability-registry.md
@@ -0,0 +1,74 @@
+# Codex Capability Registry
+
+Snapshot date: 2026-04-08  
+Scope: personal defaults + this workspace + known project-local extensions
+
+## L0 Core stable
+
+| Capability | Source of truth | Current state | Owner | Notes |
+|---|---|---|---|---|
+| Default model + reasoning | `~/.codex/config.toml` | Active, needs review | user | Current default is `gpt-5.4` with top-level `xhigh` reasoning; governance should review whether default should stay this heavy. |
+| Routing profiles (`quick`, `fast`, `deep`, `research`, `codex53`) | `~/.codex/config.toml` | Active | user | Use explicit profiles instead of one-size-fits-all routing. |
+| Global guardrails | `~/.codex/AGENTS.md` | Active | user | Personal execution, verification, and maintenance rules. |
+| Upgrade verification | `scripts/check-codex-upgrade.sh` | Active | workspace | Stable-channel and installer parity check. |
+| Handoff refresh | `scripts/update-agent-handoff.sh` | Active | workspace | Shared baton between Codex and Cursor. |
+| Vendored skill activation | `scripts/manage-vendored-skill.sh` | Active | workspace | Keeps third-party skills opt-in. |
+
+## L1 Workspace standard
+
+| Capability | Source of truth | Current state | Owner | Notes |
+|---|---|---|---|---|
+| `frontend-design-review` | `.agents/skills/frontend-design-review` | Active | workspace | UI/design-first implementation and polish. |
+| `repo-codex-bootstrap` | `.agents/skills/repo-codex-bootstrap` | Active | workspace | Lightweight Codex repo bootstrap. |
+| `repo-postcheck-summary` | `.agents/skills/repo-postcheck-summary` | Active | workspace | Narrow verification and concise summaries. |
+| `requesting-code-review` | `.agents/skills/requesting-code-review` | Active | workspace | Review gate before merge or major completion. |
+| `systematic-debugging` | `.agents/skills/systematic-debugging` | Active | workspace | Root-cause-first debugging flow. |
+| `webpage-capture-markdown` | `.agents/skills/webpage-capture-markdown` | Active | workspace | Save external web context as local markdown. |
+| `worktree-safety` | `.agents/skills/worktree-safety` | Active | workspace | Avoid wrong repo/worktree operations. |
+
+## L2 Project-local
+
+| Capability | Source of truth | Current state | Owner | Notes |
+|---|---|---|---|---|
+| 007 attribution/SEO/distribution skills (6) | `/Users/yangshu/.openclaw/workspace/projects/007-cryptorebate-restored/.agents/skills` | Active | 007 project | Correctly moved out of global user scope. |
+| Product shell workflow | `~/.agents/skills/product-shell-first` | Active, candidate for project/workspace review | user | Cross-project today, but may belong in a narrower layer depending on reuse. |
+
+## L3 Experimental / on-demand
+
+| Capability | Source of truth | Current state | Owner | Notes |
+|---|---|---|---|---|
+| `playwright-best-practices` vendored skill | `vendor/skills/playwright-best-practices` + `skills-lock.json` | On-demand | workspace | Keep disabled by default; activate only for serious Playwright work. |
+| Disabled archive: `openclaw-wechat-draft-publisher` | `~/.agents/skills-disabled/2026-04-08-global-slimming` | Archived | user | Good example of reversible retirement instead of deletion. |
+| Superpowers symlink set in `~/.agents/skills` | user skill directory symlinks | Active, but not workspace-owned | user | Useful, but treat as personal layer rather than workspace policy. |
+
+## Enabled MCP / plugin surface (current snapshot)
+
+### MCP servers
+
+- `notion`
+- `openaiDeveloperDocs`
+- `context7`
+- `cloudflare-api`
+
+### Plugins enabled in personal config
+
+- `github@openai-curated`
+- `notion@openai-curated`
+- `googledrive@openai-curated`
+- `gmail@openai-curated`
+- `google-drive@openai-curated`
+- `slack@openai-curated`
+- `linear@openai-curated`
+- `google-calendar@openai-curated`
+- `vercel@openai-curated`
+- `canva@openai-curated`
+- `cloudflare@openai-curated`
+- `figma@openai-curated`
+- `stripe@openai-curated`
+
+## Immediate governance watchlist
+
+1. Review top-level default reasoning (`xhigh`) against daily latency/quality goals.
+2. Review duplicate Google Drive plugin naming (`googledrive` vs `google-drive`).
+3. Keep global user custom skills narrow; current active custom dirs are intentionally low.
+4. Promote project-local skills into workspace/global layers only after repeated multi-project reuse.
diff --git a/scripts/codex-capability-audit.sh b/scripts/codex-capability-audit.sh
new file mode 100755
index 0000000..8ff5d2a
--- /dev/null
+++ b/scripts/codex-capability-audit.sh
@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MODE="text"
+if [[ "${1:-}" == "--json" ]]; then
+  MODE="json"
+fi
+
+python3 - "$REPO_ROOT" "$MODE" <<'PY'
+from __future__ import annotations
+import json
+import re
+import sys
+from pathlib import Path
+from collections import defaultdict
+
+repo_root = Path(sys.argv[1])
+mode = sys.argv[2]
+user_config = Path('/Users/yangshu/.codex/config.toml')
+user_skills_root = Path('/Users/yangshu/.agents/skills')
+disabled_root = Path('/Users/yangshu/.agents/skills-disabled')
+project_root = Path('/Users/yangshu/.openclaw/workspace/projects')
+skills_lock = repo_root / 'skills-lock.json'
+workspace_skills_root = repo_root / '.agents' / 'skills'
+
+text = user_config.read_text(encoding='utf-8') if user_config.exists() else ''
+
+TOP_KEYS = {
+    'model', 'model_reasoning_effort', 'plan_mode_reasoning_effort', 'review_model',
+    'service_tier', 'web_search', 'approval_policy', 'sandbox_mode'
+}
+PROFILE_KEYS = {
+    'model', 'model_reasoning_effort', 'plan_mode_reasoning_effort', 'service_tier',
+    'web_search', 'approval_policy', 'sandbox_mode'
+}
+
+def strip_quotes(v: str) -> str:
+    v = v.strip()
+    if len(v) >= 2 and v[0] == v[-1] == '"':
+        return v[1:-1]
+    return v
+
+section = None
+current_profile = None
+current_plugin = None
+current_mcp = None
+
+top = {}
+profiles = defaultdict(dict)
+plugins = {}
+mcp_servers = []
+
+for raw in text.splitlines():
+    line = raw.strip()
+    if not line or line.startswith('#'):
+        continue
+    m = re.match(r'^\[(.+)\]$', line)
+    if m:
+        inner = m.group(1)
+        section = inner
+        current_profile = None
+        current_plugin = None
+        current_mcp = None
+        pm = re.match(r'^profiles\.(.+)$', inner)
+        if pm:
+            current_profile = pm.group(1)
+        mm = re.match(r'^mcp_servers\.(.+)$', inner)
+        if mm:
+            current_mcp = mm.group(1)
+            mcp_servers.append(current_mcp)
+        pl = re.match(r'^plugins\."(.+)"$', inner)
+        if pl:
+            current_plugin = pl.group(1)
+            plugins.setdefault(current_plugin, {'enabled': None})
+        continue
+
+    if '=' not in line:
+        continue
+    key, value = [x.strip() for x in line.split('=', 1)]
+    value = strip_quotes(value)
+
+    if current_profile:
+        if key in PROFILE_KEYS:
+            profiles[current_profile][key] = value
+        continue
+    if current_plugin:
+        if key == 'enabled':
+            plugins[current_plugin]['enabled'] = value
+        continue
+    if current_mcp:
+        continue
+    if key in TOP_KEYS:
+        top[key] = value
+
+def skill_name_from_dir(p: Path) -> str:
+    return p.name
+
+custom_global_dirs = []
+symlinked_global = []
+if user_skills_root.exists():
+    for child in sorted(user_skills_root.iterdir(), key=lambda p: p.name.lower()):
+        if child.is_symlink():
+            symlinked_global.append({'name': child.name, 'target': str(child.resolve())})
+        elif child.is_dir() and (child / 'SKILL.md').exists():
+            custom_global_dirs.append(child.name)
+
+workspace_skills = []
+if workspace_skills_root.exists():
+    for p in sorted(workspace_skills_root.glob('*/SKILL.md')):
+        workspace_skills.append(p.parent.name)
+
+project_local = []
+if project_root.exists():
+    for p in sorted(project_root.glob('*/.agents/skills/*/SKILL.md')):
+        project_local.append({
+            'project': p.parents[3].name,
+            'skill': p.parent.name,
+            'path': str(p.parent),
+        })
+
+disabled_archives = []
+if disabled_root.exists():
+    for archive in sorted([p for p in disabled_root.iterdir() if p.is_dir()], key=lambda p: p.name):
+        skills = [p.name for p in sorted(archive.iterdir(), key=lambda p: p.name.lower()) if p.is_dir()]
+        disabled_archives.append({'archive': archive.name, 'skills': skills})
+
+vendored = {}
+if skills_lock.exists():
+    try:
+        vendored = json.loads(skills_lock.read_text(encoding='utf-8')).get('skills', {})
+    except Exception:
+        vendored = {}
+
+normalized_plugins = defaultdict(list)
+for name in plugins:
+    normalized_plugins[re.sub(r'[^a-z0-9]', '', name.lower())].append(name)
+plugin_alias_collisions = [names for names in normalized_plugins.values() if len(names) > 1]
+
+suggestions = []
+if top.get('model_reasoning_effort') == 'xhigh':
+    suggestions.append('Review top-level default reasoning: xhigh is heavy for everyday use; consider high as the default and keep xhigh in deep only.')
+if len(custom_global_dirs) > 4:
+    suggestions.append('Global custom skill dirs are growing; migrate project-specific skills back into repo-local .agents/skills.')
+if plugin_alias_collisions:
+    suggestions.append('Review plugin alias duplication: ' + '; '.join(', '.join(group) for group in plugin_alias_collisions))
+if disabled_archives:
+    suggestions.append('Disabled archives exist; periodically decide whether to restore, migrate, or delete archived skills.')
+if vendored:
+    suggestions.append('Keep vendored skills opt-in only; do not silently promote them into the default routing layer.')
+if not suggestions:
+    suggestions.append('Capability surface looks reasonably bounded; keep auditing before adding new default behavior.')
+
+report = {
+    'repo_root': str(repo_root),
+    'top_level_defaults': top,
+    'profiles': dict(profiles),
+    'mcp_servers': mcp_servers,
+    'enabled_plugins': sorted([k for k, v in plugins.items() if str(v.get('enabled', '')).lower() == 'true']),
+    'custom_global_skill_dirs': custom_global_dirs,
+    'symlinked_global_skills': symlinked_global,
+    'workspace_skills': workspace_skills,
+    'project_local_skills': project_local,
+    'disabled_archives': disabled_archives,
+    'vendored_skills': vendored,
+    'suggestions': suggestions,
+}
+
+if mode == 'json':
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    raise SystemExit(0)
+
+print('Codex Capability Audit')
+print('======================')
+print(f'Repo root:              {repo_root}')
+print(f'User config:            {user_config}')
+print('')
+print('Top-level defaults:')
+for key in ['model', 'model_reasoning_effort', 'plan_mode_reasoning_effort', 'review_model', 'service_tier', 'web_search', 'approval_policy', 'sandbox_mode']:
+    print(f'- {key}: {top.get(key, "<unset>")}')
+
+print('\nProfiles:')
+for name in ['quick', 'fast', 'deep', 'research', 'codex53', 'safe']:
+    data = profiles.get(name)
+    if not data:
+        continue
+    summary = ', '.join(f'{k}={data[k]}' for k in ['model', 'model_reasoning_effort', 'service_tier', 'web_search'] if k in data)
+    print(f'- {name}: {summary}')
+
+print('\nEnabled MCP servers:')
+for name in mcp_servers:
+    print(f'- {name}')
+
+print('\nEnabled plugins:')
+for name in report['enabled_plugins']:
+    print(f'- {name}')
+
+print('\nGlobal custom skill dirs:')
+if custom_global_dirs:
+    for name in custom_global_dirs:
+        print(f'- {name}')
+else:
+    print('- (none)')
+
+print('\nGlobal symlinked skills:')
+if symlinked_global:
+    for item in symlinked_global:
+        print(f"- {item['name']} -> {item['target']}")
+else:
+    print('- (none)')
+
+print('\nWorkspace skills:')
+for name in workspace_skills:
+    print(f'- {name}')
+
+print('\nProject-local skills:')
+if project_local:
+    by_project = defaultdict(list)
+    for item in project_local:
+        by_project[item['project']].append(item['skill'])
+    for project, names in sorted(by_project.items()):
+        print(f"- {project}: {', '.join(names)}")
+else:
+    print('- (none found)')
+
+print('\nDisabled archives:')
+if disabled_archives:
+    for archive in disabled_archives:
+        print(f"- {archive['archive']}: {', '.join(archive['skills']) if archive['skills'] else '(empty)'}")
+else:
+    print('- (none)')
+
+print('\nVendored/on-demand skills:')
+if vendored:
+    for name, meta in sorted(vendored.items()):
+        print(f"- {name}: {meta.get('source')}")
+else:
+    print('- (none)')
+
+print('\nGovernance suggestions:')
+for s in suggestions:
+    print(f'- {s}')
+PY

From 69b58c39f69542a7125c89e0180d5e4c8214a338 Mon Sep 17 00:00:00 2001
From: yangshu <yangshu2087@gmail.com>
Date: Wed, 8 Apr 2026 08:02:29 -0700
Subject: [PATCH 3/3] docs(design): add workspace design baseline and shortlist

---
 .../skills/frontend-design-review/SKILL.md    |  22 +-
 AGENTS.md                                     |  10 +
 DESIGN.md                                     | 219 ++++++++++++++++++
 docs/design-reference-shortlist.md            | 190 +++++++++++++++
 docs/stitch-ai-studio-codex-workflow.md       |  10 +
 5 files changed, 443 insertions(+), 8 deletions(-)
 create mode 100644 DESIGN.md
 create mode 100644 docs/design-reference-shortlist.md

diff --git a/.agents/skills/frontend-design-review/SKILL.md b/.agents/skills/frontend-design-review/SKILL.md
index 076392b..2e19a03 100644
--- a/.agents/skills/frontend-design-review/SKILL.md
+++ b/.agents/skills/frontend-design-review/SKILL.md
@@ -11,11 +11,13 @@ Use this skill when Codex should behave like a design-aware front-end implemente
 
 Read the highest-signal design inputs available before changing code:
 
-1. Figma links or node IDs
-2. Repository design files under `design/`
-3. Screenshots or reference images
-4. Existing component library and tokens
-5. Product spec or acceptance notes in repo docs, Notion, or Google Drive
+1. Repository `DESIGN.md`
+2. Workspace or repo design shortlist docs when present
+3. Figma links or node IDs
+4. Repository design files under `design/`
+5. Screenshots or reference images
+6. Existing component library and tokens
+7. Product spec or acceptance notes in repo docs, Notion, or Google Drive
 
 If a design source is missing, say so explicitly and continue with the strongest remaining source instead of pretending the design is fully specified.
 
@@ -43,6 +45,7 @@ If a design source is missing, say so explicitly and continue with the strongest
    - visible focus states
    - contrast awareness
 5. When implementing from Figma, preserve intent rather than copying every raw pixel token if that would fight the local design system.
+6. If using an external inspiration reference, state it explicitly and translate it into local rules rather than copying the original brand.
 
 ## Verification loop
 
@@ -68,6 +71,8 @@ Do not stop at “the code compiles.” Run a visual loop when possible:
 
 In repositories that follow the workspace conventions:
 
+- inspect `DESIGN.md` first
+- inspect `docs/design-reference-shortlist.md` when present
 - inspect `design/design-system.md` if present
 - inspect `design/tokens.example.json` or the real token file if present
 - inspect `docs/ui-acceptance-checklist.md`
@@ -78,6 +83,7 @@ In repositories that follow the workspace conventions:
 When summarizing work, include:
 
 1. what design inputs were used
-2. what UI layers changed
-3. what states and breakpoints were checked
-4. what remains visually unverified
+2. what external inspirations were chosen, if any
+3. what UI layers changed
+4. what states and breakpoints were checked
+5. what remains visually unverified
diff --git a/AGENTS.md b/AGENTS.md
index e12e2c8..89ef9a4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,10 +66,13 @@
 
 - For front-end tasks, prefer a design-first loop: design inputs -> implementation -> browser verification -> UI review.
 - Start with the highest-signal design artifact available: Figma, checked-in design docs, screenshots, or reference shots.
+- Read repository `DESIGN.md` before changing UI. In this workspace, `/Users/yangshu/Codex/DESIGN.md` is the team baseline when a repo has not defined a narrower design source of truth yet.
+- Use `/Users/yangshu/Codex/docs/design-reference-shortlist.md` as the approved inspiration map for external visual references. Pick 1-2 references that fit the task and translate them into local tokens and components instead of cloning them.
 - Keep front-end repo guidance close to the code by checking in `design/README.md`, `design/design-system.md`, and `docs/ui-acceptance-checklist.md` where UI work happens.
 - Use the workspace skill `frontend-design-review` for UI implementation and polish work that needs spacing, typography, states, responsive behavior, and visual verification.
 - Prefer tokenized values and reusable components over one-off CSS when refining UI.
 - When Context7 is authenticated, prefer it for current framework and component-library docs during front-end work.
+- Do not treat third-party `DESIGN.md` files as direct brand templates; adapt them into project-approved design rules first.
 
 ## Codex and Cursor shared protocol
 
@@ -90,3 +93,10 @@
 
 - After changing Codex config or skills, verify with `codex --version`, `codex features list`, `codex mcp list`, and `scripts/check-codex-upgrade.sh`.
 - If behavior depends on project instructions, confirm Codex is launched from the intended directory so the nearest `AGENTS.md` wins.
+
+## DESIGN.md workflow
+
+- Keep repository-level `DESIGN.md` as the source of truth for look-and-feel constraints used by AI agents.
+- For front-end tasks, read `DESIGN.md` before implementation and follow its token, component, state, and responsive rules.
+- Use `/Users/yangshu/Codex/docs/design-reference-shortlist.md` only as inspiration calibration, not as permission to clone brand visuals.
+- Before finalizing UI work, run narrow code checks and at least one browser visual verification pass.
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..cdc95e9
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,219 @@
+# Workspace Design Language
+
+This `DESIGN.md` is the team-level design source of truth for Codex work in this workspace.
+
+It is intentionally not a copy of any one brand.  
+It is a synthesis of the approved reference set in [`docs/design-reference-shortlist.md`](/Users/yangshu/Codex/docs/design-reference-shortlist.md), with the strongest influence coming from:
+
+- Vercel
+- Linear
+- Stripe
+- Notion
+- Mintlify
+
+The target default is: **developer-tool SaaS with precise hierarchy, restrained surfaces, strong readability, and reusable component logic**.
+
+## 1. Visual Theme & Atmosphere
+
+The default visual mood should feel:
+
+- calm
+- engineered
+- trustworthy
+- modern
+- readable under long use
+
+Prefer **light-first public surfaces**:
+
+- marketing pages
+- pricing pages
+- docs pages
+- onboarding flows
+
+Use **dark product shells** only when they help dense logged-in workflows:
+
+- dashboards
+- lists and detail panes
+- settings
+- command-heavy product views
+
+Do not mix multiple strong visual worlds on the same page.  
+Choose one dominant mode and keep the rest supportive.
+
+## 2. Color Palette & Roles
+
+### Core neutrals
+
+- **Ink 900** `#171717`: primary headings, strong text, dark iconography
+- **Ink 700** `#4d4d4d`: secondary text, helper copy
+- **Ink 500** `#666666`: tertiary text, muted labels
+- **Ink 300** `#808080`: placeholders, disabled text
+- **Canvas** `#ffffff`: page background, major card surface
+- **Surface 50** `#fafafa`: subtle alternate surface
+- **Border** `#ebebeb`: dividers, input outlines, card edges
+
+### Primary interactive colors
+
+- **Action Blue** `#0a72ef`: primary action, selected state, key links
+- **Focus Blue** `#0072f5`: focus ring, accessibility-visible interaction
+- **Success Green** `#15be53`: success state, positive metric, completion cue
+- **Warning Amber** `#c37d0d`: warning and caution
+- **Danger Rose** `#cf2d56`: error and destructive state
+
+### Reserved accent colors
+
+- **Accent Indigo** `#5e6ad2`: allowed for AI / automation / active-navigation moments
+- **Accent Violet** `#7170ff`: allowed sparingly in dark authenticated product shells
+
+Rule:
+
+- On any one screen, use **one dominant chromatic accent**.
+- Secondary accent colors should appear only as small support signals, not as competing primaries.
+
+## 3. Typography Rules
+
+### Font families
+
+Use the repository-native font stack if one already exists.  
+If no strong existing stack exists, prefer:
+
+- **Sans**: `Geist Sans`, then `Inter`, then system fallback
+- **Mono**: `Geist Mono`, `Berkeley Mono`, or `ui-monospace`
+
+Avoid defaulting to generic Arial/system-only output when a more intentional stack already exists.
+
+### Hierarchy
+
+- **Display / Hero**: `48px-64px`, weight `600`, tight line height, negative tracking only when visually justified
+- **H1 / Section Headings**: `36px-48px`, weight `600`
+- **H2 / Subsections**: `28px-36px`, weight `600`
+- **H3 / Card Titles**: `20px-24px`, weight `600`
+- **Body**: `16px-18px`, line-height `1.5-1.7`
+- **Small UI / Meta**: `12px-14px`, weight `500`
+- **Code / Technical Labels**: monospace, small, high-contrast, sparse use
+
+Typography should feel compressed and intentional in headlines, but relaxed and highly legible in body text.
+
+## 4. Component Stylings
+
+### Buttons
+
+- Default height: `40px-44px`
+- Radius: `10px-12px`
+- Primary button: solid accent fill
+- Secondary button: neutral surface + subtle border
+- Tertiary button: text-first, low visual weight
+
+Use full-pill radius only for:
+
+- badges
+- segmented pills
+- small filter chips
+
+### Cards
+
+- Radius: `12px-16px`
+- Prefer border-first depth over heavy shadow
+- Use generous internal padding
+- Keep card content structured: title, supporting text, actions, status
+
+### Inputs and forms
+
+- Height: `40px-44px`
+- Border: subtle by default, stronger on hover/focus
+- Focus state must be visible and consistent
+- Labels should stay readable, never too faint
+
+### Navigation
+
+- Clear active state
+- Strong hierarchy over decoration
+- Minimal chrome
+- In dark shells, keep contrast high without neon excess
+
+## 5. Layout Principles
+
+- Use an `8px` spacing base
+- Prefer generous whitespace on public pages
+- Prefer tighter but still breathable density in logged-in product areas
+- Keep marketing widths around `1200px-1280px`
+- Keep reading content around `720px-840px`
+- Avoid cramming too many unrelated visual motifs into one section
+
+For public surfaces:
+
+- prioritize rhythm
+- visual grouping
+- scroll clarity
+
+For authenticated product surfaces:
+
+- prioritize scannability
+- alignment
+- fast task execution
+
+## 6. Depth & Elevation
+
+Default rule: **border first, shadow second**.
+
+Preferred depth system:
+
+- subtle border on most surfaces
+- micro-shadow only when a surface genuinely needs lift
+- stronger elevation only for dialogs, popovers, or featured cards
+
+Avoid:
+
+- muddy multi-color shadows
+- oversized glassmorphism
+- large blurred glows as a default pattern
+
+## 7. Do's and Don'ts
+
+### Do
+
+- reuse existing tokens and components
+- keep hierarchy obvious
+- verify hover, focus, loading, empty, error, and disabled states
+- match the repo's real design system before introducing new primitives
+- choose a small number of strong ideas and apply them consistently
+
+### Don't
+
+- clone third-party brand styles verbatim
+- mix Vercel minimalism, Cursor warmth, and Stripe luxury on one page
+- use multiple loud accent colors on the same screen
+- overuse gradients, glow, blur, or oversized animations
+- hide important structure behind stylistic flourishes
+
+## 8. Responsive Behavior
+
+Default verification widths:
+
+- `375`
+- `768`
+- `1024`
+- `1440`
+
+Rules:
+
+- mobile first for public flows
+- no clipped copy
+- no broken CTA alignment
+- no hidden states that exist only on desktop
+- preserve hierarchy rather than pixel identity when adapting across sizes
+
+## 9. Agent Prompt Guide
+
+When Codex works on front-end tasks in this workspace, it should:
+
+1. read this `DESIGN.md` first
+2. read [`docs/design-reference-shortlist.md`](/Users/yangshu/Codex/docs/design-reference-shortlist.md) if external inspiration is useful
+3. explicitly state which 1-2 references are relevant for the current task
+4. translate those references into repo-native tokens, components, and patterns
+5. verify at least one real browser or visual pass before claiming completion
+
+Prompting rule:
+
+- treat external references as **design-language input**
+- never treat them as **brand-cloning instructions**
diff --git a/docs/design-reference-shortlist.md b/docs/design-reference-shortlist.md
new file mode 100644
index 0000000..520f568
--- /dev/null
+++ b/docs/design-reference-shortlist.md
@@ -0,0 +1,190 @@
+# Design Reference Shortlist
+
+Source repo: [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
+
+This shortlist is the workspace-approved reference set for current Codex UI work.  
+Use these references as design-language input, not as a brand-cloning kit.
+
+## Selection criteria
+
+The goal was to pick references that match our current mix of:
+
+- AI / developer-tool products
+- SaaS marketing pages
+- authenticated product shells
+- documentation and knowledge surfaces
+
+We optimized for references that are:
+
+- high-signal for AI agents
+- strong at layout and hierarchy
+- reusable across multiple projects
+- less risky than highly distinctive brand worlds
+
+## Top 5 references
+
+### 1. Vercel
+
+Files:
+
+- [repo folder](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/vercel)
+- [DESIGN.md](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/vercel/DESIGN.md)
+
+Why it made the cut:
+
+- best baseline for developer-tool marketing and infrastructure product surfaces
+- strong light-mode precision
+- excellent border, shadow, and spacing restraint
+- useful for hero sections, feature grids, pricing summaries, and polished docs chrome
+
+Use it for:
+
+- landing pages
+- product marketing sections
+- pricing / trust / feature comparison blocks
+- docs homepages
+
+Do not copy literally:
+
+- exact Geist-heavy brand mimicry
+- Vercel workflow accent colors all at once
+
+### 2. Linear
+
+Files:
+
+- [repo folder](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/linear.app)
+- [DESIGN.md](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/linear.app/DESIGN.md)
+
+Why it made the cut:
+
+- strongest reference for dark, authenticated product shells
+- excellent information-density discipline
+- useful for settings, dashboards, tables, sidebars, and command-heavy flows
+
+Use it for:
+
+- logged-in product areas
+- dashboard pages
+- issue/task/list/detail layouts
+- power-user interaction patterns
+
+Do not copy literally:
+
+- blanket dark mode on all public pages
+- brand-indigo overuse
+
+### 3. Stripe
+
+Files:
+
+- [repo folder](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/stripe)
+- [DESIGN.md](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/stripe/DESIGN.md)
+
+Why it made the cut:
+
+- best trust-and-conversion reference in the set
+- useful for pricing, forms, payment, enterprise reassurance, and polished CTAs
+- strong typography, hierarchy, and commercial clarity
+
+Use it for:
+
+- pricing pages
+- onboarding flows
+- checkout or billing-related UI
+- enterprise trust sections
+
+Do not copy literally:
+
+- premium gradient theatrics everywhere
+- overly luxurious styling on utilitarian product pages
+
+### 4. Notion
+
+Files:
+
+- [repo folder](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/notion)
+- [DESIGN.md](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/notion/DESIGN.md)
+
+Why it made the cut:
+
+- strongest reference for calm content-heavy experiences
+- good for docs, help centers, knowledge bases, and editor-adjacent UIs
+- excellent warm-neutral reading surface
+
+Use it for:
+
+- content pages
+- help / FAQ / education sections
+- editor or note-like surfaces
+- knowledge capture / internal docs
+
+Do not copy literally:
+
+- overly soft information density where task execution matters
+- exact Notion visual warmth as a default for all products
+
+### 5. Mintlify
+
+Files:
+
+- [repo folder](https://github.com/VoltAgent/awesome-design-md/tree/main/design-md/mintlify)
+- [DESIGN.md](https://github.com/VoltAgent/awesome-design-md/blob/main/design-md/mintlify/DESIGN.md)
+
+Why it made the cut:
+
+- best documentation-specific reference
+- strong for API docs, developer onboarding, and information hierarchy
+- useful for lightweight marketing/docs hybrids
+
+Use it for:
+
+- docs portals
+- API reference chrome
+- onboarding/tutorial pages
+- product documentation landing pages
+
+Do not copy literally:
+
+- green branding as a global default
+- excessively soft contrast on dense product UI
+
+## Not selected as default team references
+
+These are useful, but too brand-distinctive for the workspace default layer:
+
+- `cursor`: strong and interesting, but too editorial/warm and too tied to one brand world
+- `claude`: useful for warm editorial AI surfaces, but not broad enough for the default team baseline
+- `raycast`: good for utility/productivity aesthetics, but too dark-utility-specific for the default layer
+
+Use them only when a project intentionally wants that direction.
+
+## Default blend rules
+
+These blend rules help Codex use the references without producing direct copies.
+
+### Public marketing / devtool landing
+
+- 60% `vercel`
+- 20% `stripe`
+- 20% `mintlify`
+
+### Authenticated app shell
+
+- 70% `linear.app`
+- 20% `vercel`
+- 10% `notion`
+
+### Docs / knowledge surfaces
+
+- 50% `mintlify`
+- 30% `notion`
+- 20% `vercel`
+
+## Agent usage rules
+
+- Always read the repository `DESIGN.md` first.
+- Use this shortlist only as inspiration and calibration.
+- Explicitly state which 1-2 references are being used for the current task.
+- Translate reference styles into local design tokens, spacing, and components.
+- Do not clone external brand signatures verbatim.
diff --git a/docs/stitch-ai-studio-codex-workflow.md b/docs/stitch-ai-studio-codex-workflow.md
index 187a0e4..c4492af 100644
--- a/docs/stitch-ai-studio-codex-workflow.md
+++ b/docs/stitch-ai-studio-codex-workflow.md
@@ -8,6 +8,12 @@ This workflow turns Google design and prototype tools into repository-native cod
 
 Use Stitch to explore UI direction, layout, and interaction ideas.
 
+Before prompting Stitch, choose 1-2 approved visual references from the workspace shortlist:
+
+- `/Users/yangshu/Codex/docs/design-reference-shortlist.md`
+
+Translate those references into a project-specific `DESIGN.md` direction first instead of asking Stitch to copy a brand literally.
+
 Check the source artifacts into the target repository under:
 
 - `design/stitch/`
@@ -18,6 +24,7 @@ Recommended contents:
 - screenshots
 - prompt notes
 - short README explaining what the export represents
+- the reference inspirations used (for example `vercel + mintlify`)
 
 ## Stage 2: Google AI Studio
 
@@ -40,6 +47,7 @@ Use Codex to convert the prototype into maintainable repository code.
 
 Codex responsibilities:
 
+- confirm or create the repository `DESIGN.md` before implementation when UI direction matters
 - move generated code into the real project structure
 - replace placeholder logic with repository-native integrations
 - connect configuration, environment variables, and production services
@@ -50,6 +58,7 @@ Codex responsibilities:
 
 When a repository uses this workflow, it should contain:
 
+- `DESIGN.md`
 - `design/stitch/`
 - `prototypes/ai-studio/`
 - `docs/agent-handoff.md`
@@ -60,6 +69,7 @@ Before switching between Stitch, AI Studio, Codex, or Cursor:
 
 - update `docs/agent-handoff.md`
 - record source artifact paths
+- record the `DESIGN.md` reference or shortlist inspirations in use
 - record current branch
 - record changed files
 - record verification