oh-my-design-cli 0.1.3 → 1.0.0

package/.claude/hooks/post-edit-watch.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// PostToolUse hook — runs after Edit/Write on .tsx/.jsx/.css/.scss files.
+// Detects if the change introduced a hex/spacing value that's NOT in
+// DESIGN.md tokens, and surfaces a one-line suggestion to capture as preference.
+//
+// Hook input shape (Claude Code hook contract):
+//   stdin = JSON with toolName / args / etc.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const designMd = path.join(projectDir, 'DESIGN.md');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => (input += c));
+process.stdin.on('end', () => {
+  let payload = {};
+  try {
+    payload = JSON.parse(input || '{}');
+  } catch {
+    process.exit(0);
+  }
+  const toolName = payload.toolName || payload.tool_name || '';
+  if (!['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
+    process.exit(0);
+  }
+  const filePath = payload.toolInput?.file_path || payload.toolInput?.filePath || '';
+  if (!/\.(tsx|jsx|ts|js|css|scss)$/i.test(filePath)) {
+    process.exit(0);
+  }
+
+  const newText =
+    payload.toolInput?.content ||
+    payload.toolInput?.new_string ||
+    '';
+  if (!newText) process.exit(0);
+
+  // Normalize a hex to canonical 6-char lowercase form (#abc → #aabbcc)
+  function normHex(h) {
+    let s = h.toLowerCase();
+    if (s.length === 4) {
+      // #abc → #aabbcc
+      s = '#' + s[1] + s[1] + s[2] + s[2] + s[3] + s[3];
+    } else if (s.length === 9) {
+      // #aarrggbb (8-char includes alpha) — strip alpha for comparison
+      s = s.slice(0, 7);
+    }
+    return s;
+  }
+
+  // Extract hexes from new content
+  const rawHexes = newText.match(/#[0-9a-f]{3,8}\b/gi) || [];
+  const hexes = [...new Set(rawHexes.map(normHex))];
+  if (hexes.length === 0) process.exit(0);
+
+  // Read DESIGN.md hexes — also handle CSS vars and oklch (Tailwind v4) by
+  // signaling N/A when DESIGN.md is purely token-driven (no inline hex).
+  let designHexes = new Set();
+  let designUsesTokenSystem = false;
+  if (fs.existsSync(designMd)) {
+    try {
+      const text = fs.readFileSync(designMd, 'utf8');
+      const lower = text.toLowerCase();
+      for (const h of (lower.match(/#[0-9a-f]{3,8}\b/g) || [])) {
+        designHexes.add(normHex(h));
+      }
+      // If DESIGN.md mostly uses oklch() / CSS vars / token names, hex-only
+      // comparison is unreliable — skip warning to avoid noise.
+      const hexCount = designHexes.size;
+      const oklchCount = (lower.match(/oklch\(/g) || []).length;
+      const cssVarCount = (lower.match(/var\(--/g) || []).length;
+      if ((oklchCount + cssVarCount) > hexCount * 2) {
+        designUsesTokenSystem = true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  if (designUsesTokenSystem) process.exit(0); // skip — too noisy
+  const introduced = hexes.filter((h) => !designHexes.has(h));
+  if (introduced.length === 0) process.exit(0);
+
+  const lines = [
+    '',
+    'OMD WATCH:',
+    `방금 ${path.basename(filePath)} 에 DESIGN.md에 없는 색이 들어갔어요: ${introduced.slice(0, 3).join(', ')}`,
+    '의도된 거면 \`omd remember "<설명>" --context "' + filePath + '"\` 으로 preference 캡처 추천.',
+    '',
+  ];
+
+  // Hook contract: write to additionalContext via JSON stdout
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+});
+

package/.claude/hooks/session-end-foldin.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Stop hook — at session end, run fold-in algorithm on .omd/preferences.md.
+// If proposals exceed threshold, append a note to .omd/timeline.md so the
+// next SessionStart hook surfaces it as "fold-in proposals ready: N".
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const preferencesMd = path.join(projectDir, '.omd', 'preferences.md');
+const timelineMd = path.join(projectDir, '.omd', 'timeline.md');
+const configJson = path.join(projectDir, '.omd', 'config.json');
+
+if (!fs.existsSync(preferencesMd)) process.exit(0);
+
+let config = {
+  fold_in_score_threshold: 60,
+  recurrence_window_days: 7,
+};
+try {
+  if (fs.existsSync(configJson)) {
+    config = { ...config, ...JSON.parse(fs.readFileSync(configJson, 'utf8')) };
+  }
+} catch {
+  // ignore
+}
+
+let prefText;
+try {
+  prefText = fs.readFileSync(preferencesMd, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+// Parse pending entries (very rough)
+const blocks = prefText.split(/^### /m).slice(1);
+const now = Date.now();
+const windowMs = config.recurrence_window_days * 24 * 3600 * 1000;
+const byScope = new Map();
+
+for (const block of blocks) {
+  const tsMatch = /^- ts:\s*(.+)$/m.exec(block);
+  const scopeMatch = /^- scope:\s*(.+)$/m.exec(block);
+  const statusMatch = /^- status:\s*(\w+)$/m.exec(block);
+  const importanceMatch = /^- importance:\s*([1-5])$/m.exec(block);
+  if ((statusMatch?.[1] || 'pending') !== 'pending') continue;
+  if (!tsMatch || !scopeMatch) continue;
+  const ts = new Date(tsMatch[1]).getTime();
+  if (Number.isNaN(ts) || now - ts > windowMs) continue;
+  const scope = scopeMatch[1];
+  const importance = parseInt(importanceMatch?.[1] || '3', 10);
+  const list = byScope.get(scope) || [];
+  list.push({ ts, importance });
+  byScope.set(scope, list);
+}
+
+const proposals = [];
+for (const [scope, entries] of byScope.entries()) {
+  if (entries.length < 3) continue;
+  const importanceAvg = entries.reduce((s, e) => s + e.importance, 0) / entries.length;
+  // Hard floor matches src/core/memory.ts — keep these in sync.
+  if (importanceAvg < 2.5) continue;
+  const lastTs = entries.reduce((m, e) => Math.max(m, e.ts), 0);
+  const daysSince = (now - lastTs) / (24 * 3600 * 1000);
+  const recency = Math.exp(-daysSince / 7);
+  const score = entries.length * importanceAvg * recency * 10;
+  if (score >= config.fold_in_score_threshold) {
+    proposals.push({ scope, count: entries.length, score: Math.round(score) });
+  }
+}
+
+if (proposals.length === 0) process.exit(0);
+
+// Append to timeline.md
+const ts = new Date().toISOString();
+const block =
+  `## ${ts} — fold_in_proposal\n\n` +
+  `${proposals.length} fold-in proposals ready (top: ${proposals[0].scope}, score ${proposals[0].score}).\n\n` +
+  '```json\n' +
+  JSON.stringify(proposals.slice(0, 5), null, 2) +
+  '\n```\n\n';
+
+if (!fs.existsSync(path.dirname(timelineMd))) {
+  fs.mkdirSync(path.dirname(timelineMd), { recursive: true });
+}
+if (!fs.existsSync(timelineMd)) {
+  fs.writeFileSync(timelineMd, '# OMD TIMELINE — per-session journal\n\n' + block);
+} else {
+  fs.appendFileSync(timelineMd, block);
+}
+
+// Optional: print one-line confirmation to stdout
+process.stdout.write(JSON.stringify({}) || '');
+

package/.claude/hooks/session-state-loader.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// SessionStart hook — load .omd/state.md (and a recent timeline tail) into the
+// session as additionalContext. If state.md is missing or stale, recompute
+// best-effort from preferences.md + timeline.md.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const stateMd = path.join(projectDir, '.omd', 'state.md');
+const timelineMd = path.join(projectDir, '.omd', 'timeline.md');
+const preferencesMd = path.join(projectDir, '.omd', 'preferences.md');
+
+function safeRead(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+const lines = [];
+
+if (fs.existsSync(stateMd)) {
+  const content = safeRead(stateMd);
+  if (content) {
+    lines.push('## OMD ENVIRONMENT STATE');
+    lines.push('');
+    lines.push(content.split('\n').slice(0, 60).join('\n')); // cap injection size
+    lines.push('');
+  }
+} else if (fs.existsSync(preferencesMd)) {
+  // Best-effort fallback — count pending entries
+  const text = safeRead(preferencesMd) || '';
+  const pendingCount = (text.match(/^- status:\s*pending\b/gm) || []).length;
+  if (pendingCount > 0) {
+    lines.push('## OMD ENVIRONMENT STATE');
+    lines.push('');
+    lines.push(`Pending preferences: ${pendingCount}${pendingCount >= 7 ? ' — consider /omd-learn review' : ''}`);
+    lines.push('');
+  }
+}
+
+if (fs.existsSync(timelineMd)) {
+  const text = safeRead(timelineMd) || '';
+  const blocks = text.split(/^## /m).slice(1).slice(-3);
+  if (blocks.length > 0) {
+    lines.push('## RECENT TIMELINE (last 3)');
+    lines.push('');
+    for (const b of blocks) {
+      const firstLine = b.split('\n')[0];
+      const summary = (b.split('\n').slice(2).find((l) => l.trim()) || '').trim();
+      lines.push(`- ${firstLine.trim()} — ${summary}`);
+    }
+    lines.push('');
+  }
+}
+
+if (lines.length > 0) {
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+}
+

package/.claude/hooks/skill-activation.cjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook — forced-eval skill activation (~84% reliability).
+// Reads .claude/skills/skill-rules.json + the user's prompt, finds matching
+// rules, appends a structured "SKILL ACTIVATION CHECK" block via the
+// `additionalContext` channel.
+//
+// Plain CommonJS so it works on any Node ≥18 without build deps.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const rulesPath = path.join(projectDir, '.claude', 'skills', 'skill-rules.json');
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (prompt += chunk));
+process.stdin.on('end', () => {
+  if (!fs.existsSync(rulesPath)) {
+    process.exit(0);
+  }
+  let rules;
+  try {
+    rules = JSON.parse(fs.readFileSync(rulesPath, 'utf8'));
+  } catch (e) {
+    process.exit(0);
+  }
+  const matches = [];
+  const lower = prompt.toLowerCase();
+  for (const [skill, def] of Object.entries(rules.skills || {})) {
+    const t = def.promptTriggers || {};
+    const all = [...(t.keywordsKr || []), ...(t.keywordsEn || [])];
+    const kwHit = all.some((k) => lower.includes(k.toLowerCase()) || prompt.includes(k));
+    let ipHit = false;
+    for (const p of t.intentPatterns || []) {
+      try {
+        if (new RegExp(p, 'i').test(prompt)) {
+          ipHit = true;
+          break;
+        }
+      } catch {
+        // bad regex — skip
+      }
+    }
+    if (kwHit || ipHit) matches.push({ skill, def });
+  }
+  if (matches.length === 0) {
+    process.exit(0);
+  }
+
+  const required = matches.filter((m) => m.def.enforcement === 'required');
+  const suggested = matches.filter((m) => m.def.enforcement === 'suggest');
+
+  const lines = [
+    '',
+    'OMD SKILL ACTIVATION CHECK',
+  ];
+  if (required.length > 0) {
+    lines.push('REQUIRED skills (use Skill tool BEFORE responding):');
+    for (const m of required) lines.push(`  → ${m.skill}`);
+  }
+  if (suggested.length > 0) {
+    lines.push('SUGGESTED skills (consider invoking):');
+    for (const m of suggested) lines.push(`  → ${m.skill}`);
+  }
+  lines.push('Reasoning: state YES/NO with brief reason for each rule before doing the work.');
+  lines.push('');
+
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+});
+

package/.claude/settings.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_doc": "OmD project hooks — auto-installed by `omd install-skills`. Re-run with --force to refresh.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-activation.cjs",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/session-state-loader.cjs",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/post-edit-watch.cjs",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/session-end-foldin.cjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+

package/.claude/skills/skill-rules.json

@@ -0,0 +1,87 @@
+{
+  "version": 1,
+  "_doc": "OmD skill activation rules — read by .claude/hooks/skill-activation.cjs (UserPromptSubmit hook). Forced-eval pattern (~84% reliability vs ~50% naked description matching). 1.0.0: omd-add-reference removed (no SKILL.md), omd-apply triggers tightened to push complex work into subagent dispatch.",
+  "skills": {
+    "omd-apply": {
+      "enforcement": "required",
+      "priority": "critical",
+      "promptTriggers": {
+        "keywordsKr": ["스타일", "색", "버튼", "카드", "여백", "폰트", "라운드", "그림자", "톤", "카피", "에러 메시지", "empty state", "loading", "컴포넌트", "아이콘", "차트", "그래프", "SVG", "일러스트", "에셋"],
+        "keywordsEn": ["style", "color", "button", "card", "spacing", "font", "rounded", "shadow", "tone", "copy", "error message", "empty state", "loading", "component", "icon", "chart", "graph", "svg", "illustration", "asset"],
+        "intentPatterns": [
+          "(this|these|이|그|저).*?(warmer|cooler|rounder|tighter|softer|더|좀|덜)",
+          "edit.*\\.(tsx|jsx|css|scss|vue|svelte)",
+          "(만들|make|create|generate).*?(아이콘|icon|차트|chart|일러스트|illustration|svg)"
+        ]
+      }
+    },
+    "omd-remember": {
+      "enforcement": "suggest",
+      "priority": "medium",
+      "promptTriggers": {
+        "keywordsKr": ["기억해", "앞으로", "우리는"],
+        "keywordsEn": ["remember", "going forward", "we never", "we always"],
+        "intentPatterns": [
+          "(원래|never|항상|absolutely).*?(쓰지|don't|do not)",
+          "rule of thumb"
+        ]
+      }
+    },
+    "omd-learn": {
+      "enforcement": "suggest",
+      "priority": "medium",
+      "promptTriggers": {
+        "keywordsKr": ["preference 정리", "프리퍼런스", "교정 반영", "DESIGN.md 업데이트", "fold"],
+        "keywordsEn": ["fold preferences", "apply preferences", "fold in", "learn from corrections"],
+        "intentPatterns": ["preference.*?(정리|반영|fold|apply)"]
+      }
+    },
+    "omd-sync": {
+      "enforcement": "required",
+      "priority": "high",
+      "promptTriggers": {
+        "keywordsKr": ["배포", "퍼블리시", "릴리즈", "동기화", "shim", "sync", "shim 갱신", "drift 확인"],
+        "keywordsEn": ["ship", "deploy", "publish", "release", "sync", "shim", "drift check"],
+        "intentPatterns": ["^/?(ship|deploy|publish|sync)\\b"]
+      }
+    },
+    "omd-3d-blender": {
+      "enforcement": "required",
+      "priority": "medium",
+      "promptTriggers": {
+        "keywordsKr": ["블렌더", "Blender", "3D", "렌더", "렌더링", "GLB", "모델링", "3차원"],
+        "keywordsEn": ["blender", "3d render", "3d mockup", "glb export", "isometric", "product render", "3d model"],
+        "intentPatterns": [
+          "(blender|블렌더).*?(설치|install|사용|연결|쓰)",
+          "(3d|3D|3차원).*?(mockup|목업|render|렌더|모델|model)",
+          "(hero|메인).*?(render|렌더|3d|3차원)"
+        ]
+      }
+    },
+    "omd-init": {
+      "enforcement": "suggest",
+      "priority": "low",
+      "promptTriggers": {
+        "keywordsKr": ["DESIGN.md", "디자인 시스템", "초기화", "세팅", "레퍼런스", "참고"],
+        "keywordsEn": ["design system", "init", "bootstrap", "reference"],
+        "intentPatterns": ["DESIGN\\.md.*?(create|만들|초기화|generate|emit)"]
+      }
+    },
+    "omd-harness": {
+      "enforcement": "required",
+      "priority": "high",
+      "promptTriggers": {
+        "keywordsKr": ["하네스", "알아서", "전체", "처음부터", "메인 화면", "랜딩", "랜딩페이지", "와이어프레임", "디자인 시작", "디자인 짜줘", "화면 디자인", "전반", "다듬", "정비", "톤 정비", "개선", "프로덕션화", "프로덕션", "실제로 만들", "실배포", "프로젝트화"],
+        "keywordsEn": ["harness", "from scratch", "full design", "design the entire", "wireframe", "design from", "landing", "landing page", "polish", "improve", "tone", "productionize", "production-ready", "ship it"],
+        "intentPatterns": [
+          "design.*?(from scratch|처음부터|전체)",
+          "(full|전체).*?(design|디자인)",
+          "(메인|main|first|landing|home|랜딩).*?(화면|screen|page|페이지|디자인|design|만들|build|개선|improve|다듬|정비|polish)",
+          "(프로덕션|production).*?(화|ize|만들|시키|구조|준비|진행)",
+          "(실제로|properly|production-ready).*?(만들|ship|구조)",
+          "(개선|improve|다듬|정비|polish|brush).*?(page|페이지|랜딩|landing|화면|screen|전반|전체|whole)"
+        ]
+      }
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md — oh-my-design
+
+This is the agent-instruction shim for OpenAI Codex / generic AGENTS.md-aware CLIs working inside this repository.
+
+oh-my-design itself uses Claude Code skills + subagents for its design harness. This file is the parity layer for Codex users.
+
+## Repository quick map
+
+- `src/` — TypeScript source for the `omd` CLI (`bin/oh-my-design.ts` is the entrypoint).
+- `references/` — 67 real-company DESIGN.md files used as bundled references.
+- `skills/omd-*` — Claude Code / Codex / OpenCode skill files (installed into target projects via `omd install-skills`).
+- `.claude/agents/` — Subagent definitions for the design harness (Claude Code).
+- `.codex/agents/` — Mirror TOML definitions for the design harness (Codex).
+- `spec/omd-v0.1.md` — OmD spec (15-section DESIGN.md format).
+- `research/harness-design/` — Design harness research + integration design.
+- `skills/omd-lab-02-design-harness/` — Lab #02 versioned harness experiments.
+
+## Build / test / lint
+
+- Build: `npm run build` (tsup → `dist/`)
+- Type-check: `npm run lint` (`tsc --noEmit`)
+- Unit tests: `npm test` (vitest)
+- The CLI runs via `node dist/bin/oh-my-design.js …` after build.
+
+## Design harness mode
+
+User-facing entry: **`/omd-harness <task>`** in Claude Code or Codex CLI.
+
+The harness runs entirely inside the host CLI session — no external API keys, no separate process. The skill at `.codex/skills/omd-harness/` (or `.claude/skills/omd-harness/` for Claude Code) handles bootstrapping and orchestration handoff.
+
+### Entrypoint
+
+```
+/omd-harness <도메인 + 톤/스타일 + 핵심 화면>
+```
+
+Examples:
+- `/omd-harness 토스 스타일로 가족용 식단 공유 앱 메인 화면`
+- `/omd-harness Linear-clone B2B SaaS dashboard — 6 widgets, dark first`
+- `/omd-harness 결제 완료 화면 — 성공/실패/부분성공 3 states`
+
+For Lab #02 versioned runs, append `--lab v1` (or v2, v3 …) inside the slash command.
+
+The skill internally bootstraps the run dir via a hidden `omd harness` helper (slug consistency, standardized subdirs, INDEX.md append). This helper is NOT a user surface — always use `/omd-harness`.
+
+### Codex-specific harness flow
+
+When this AGENTS.md is loaded and a fresh `.omd/runs/run-<latest>/` exists:
+
+1. **Activate the orchestrator persona.** Read `.codex/agents/omd-master.toml` and adopt that role. The full behavioral spec lives at `.claude/agents/omd-master.md` — follow it verbatim regardless of channel.
+
+2. **Run the 10 phases in order** (see `.claude/agents/omd-master.md` for full details):
+   - Phase 1 — Discovery (5-8 questions, one batch)
+   - Phase 1.5 — Asset Brief (spawn omd-asset-curator)
+   - Phase 2 — UX Research (parallel × 2-3 omd-ux-researcher)
+   - Phase 3 — IA / Journey (master itself) → **user checkpoint #1**
+   - Phase 4 — Wireframe (spawn omd-ui-junior)
+   - Phase 5 — System / DESIGN.md.patch (master + omd init prepare) → **user checkpoint #2**
+   - Phase 6 — Components (spawn omd-ui-junior)
+   - Phase 6.5 — Asset Sourcing (spawn omd-asset-curator)
+   - Phase 7 — Microcopy (spawn omd-microcopy)
+   - Phase 8 — Validation (spawn omd-a11y-auditor → cross-family jury → spawn omd-persona-tester × 4) → **user checkpoint #3**
+   - Iteration loop (cap 3) — spawn omd-critic between iterations
+   - Phase 9 — Handoff (zip packaging for v0/Cursor/Subframe)
+
+3. **Spawn sub-agents** via Codex's spawn-agent mechanism with names matching `.codex/agents/<name>.toml`:
+   - `omd-ux-researcher`
+   - `omd-asset-curator`
+   - `omd-ui-junior`
+   - `omd-microcopy`
+   - `omd-a11y-auditor`
+   - `omd-persona-tester` (×4 in parallel for Phase 8)
+   - `omd-critic` (iteration > 1)
+
+4. **All artifacts go inside the run dir.** Never write outside it except for `DESIGN.md` (Phase 5, with user checkpoint approval) and `.omd/preferences.md` (via `omd remember`).
+
+### User checkpoints (mandatory, do not auto-skip)
+
+- Checkpoint #1 (Phase 3 end) — show `journey.mmd`, halt for user reply.
+- Checkpoint #2 (Phase 5 end) — show `DESIGN.md.patch`, halt.
+- Checkpoint #3 (Phase 8 end) — show validation summary, halt.
+
+A non-mandatory informational checkpoint #0 follows Phase 1.5 (asset self/fallback/skip choice). All four are gated; do not bypass.
+
+## OmD apply (UI work outside the harness)
+
+For ad-hoc UI work (component changes, microcopy edits, color tweaks) not running through the full harness:
+
+1. Read project-root `DESIGN.md` in full at the start of the turn.
+2. Read `.omd/preferences.md` `pending` entries — these override DESIGN.md until folded in.
+3. Apply changes citing only DESIGN.md tokens (never invent).
+4. If the user corrects your design choice, run `omd remember "<one-sentence summary>" --context "<file>"` before ending the turn.
+
+This mirrors the `omd:apply` Claude Code skill behavior.
+
+## Hard rules (apply across channels)
+
+- Never fabricate DESIGN.md §11-13 (Brand Narrative / Principles / Personas) facts. Use `[FILL IN]` placeholders if user-provided facts are absent.
+- Never introduce a token absent from DESIGN.md without going through Phase 5 (system extension with checkpoint #2 approval).
+- Never download from Pinterest. Pinterest URLs are listed for the user to download manually.
+- Never emit SUS / NPS / "satisfaction score" from synthetic personas. Use task_success / steps_vs_optimal / friction_count / heuristic_violations / abandonment instead.
+- Never auto-skip user checkpoints.
+- Never delete a run directory. They are permanent learning artifacts.
+
+## Pre-existing OmD shims (managed by `omd sync`)
+
+Below this line, `omd sync` may add a managed block with shim content for Claude Code / Cursor compat. Do not edit between the markers.
+
+<!-- omd:start version=1 -->
+<!-- omd:end -->
+