oh-my-codex 0.20.3 → 0.21.0

package/skills/configure-notifications/SKILL.md

@@ -24,264 +24,78 @@ triggers:
 
 # Configure OMX Notifications
 
-Unified and only entry point for notification setup.
+Use this card for Discord, Telegram, Slack, generic command aliases, or OpenClaw. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in `templates/AGENTS.md`.
 
-- **Native integrations (first-class):** Discord, Telegram, Slack
-- **Generic extensibility integrations:** `custom_webhook_command`, `custom_cli_command`
-
-> Standalone configure skills (`configure-discord`, `configure-telegram`, `configure-slack`, `configure-openclaw`) are removed.
-
-## Step 1: Inspect Current State
+## 1. Inspect and choose a path
 
 ```bash
 CONFIG_FILE="$HOME/.codex/.omx-config.json"
-
 if [ -f "$CONFIG_FILE" ]; then
-  jq -r '
-    {
-      notifications_enabled: (.notifications.enabled // false),
-      discord: (.notifications.discord.enabled // false),
-      discord_bot: (.notifications["discord-bot"].enabled // false),
-      telegram: (.notifications.telegram.enabled // false),
-      slack: (.notifications.slack.enabled // false),
-      openclaw: (.notifications.openclaw.enabled // false),
-      custom_webhook_command: (.notifications.custom_webhook_command.enabled // false),
-      custom_cli_command: (.notifications.custom_cli_command.enabled // false),
-      verbosity: (.notifications.verbosity // "session"),
-      idleCooldownSeconds: (.notifications.idleCooldownSeconds // 60),
-      reply_enabled: (.notifications.reply.enabled // false)
-    }
-  ' "$CONFIG_FILE"
+  jq -r '{notifications_enabled:(.notifications.enabled // false), discord:(.notifications.discord.enabled // false), discord_bot:(.notifications["discord-bot"].enabled // false), telegram:(.notifications.telegram.enabled // false), slack:(.notifications.slack.enabled // false), openclaw:(.notifications.openclaw.enabled // false), custom_webhook_command:(.notifications.custom_webhook_command.enabled // false), custom_cli_command:(.notifications.custom_cli_command.enabled // false), verbosity:(.notifications.verbosity // "session"), idleCooldownSeconds:(.notifications.idleCooldownSeconds // 60), reply_enabled:(.notifications.reply.enabled // false)}' "$CONFIG_FILE"
 else
   echo "NO_CONFIG_FILE"
 fi
 ```
 
-## Step 2: Main Menu
-
-Use AskUserQuestion:
-
-**Question:** "What would you like to configure?"
-
-**Options:**
-1. **Discord (native)** - webhook or bot
-2. **Telegram (native)** - bot token + chat id
-3. **Slack (native)** - incoming webhook
-4. **Generic webhook command** - `custom_webhook_command`
-5. **Generic CLI command** - `custom_cli_command`
-6. **Cross-cutting settings** - verbosity, idle cooldown, profiles, reply listener
-7. **Disable all notifications** - set `notifications.enabled = false`
-
-## Step 3: Configure Native Platforms (Discord / Telegram / Slack)
-
-Collect and validate platform-specific values, then write directly under native keys:
+Use AskUserQuestion to choose: Discord native (webhook or bot), Telegram native (bot token + chat id), Slack native (incoming webhook), `custom_webhook_command`, `custom_cli_command`, cross-cutting settings, or disable all notifications.
 
-- Discord webhook: `notifications.discord`
-- Discord bot: `notifications["discord-bot"]`
-- Telegram: `notifications.telegram`
-- Slack: `notifications.slack`
+## 2. Native providers
 
-Do not write these as generic command/webhook aliases.
+Collect and validate provider values, then write only these native keys: `notifications.discord`, `notifications["discord-bot"]`, `notifications.telegram`, or `notifications.slack`. Do not represent native providers with generic aliases.
 
-## Step 4: Configure Generic Extensibility
+## 3. Generic aliases
 
-### 4a) `custom_webhook_command`
-
-Use AskUserQuestion to collect:
-- URL
-- Optional headers
-- Optional method (`POST` default, or `PUT`)
-- Optional event list (`session-end`, `ask-user-question`, `session-start`, `session-idle`, `stop`)
-- Optional instruction template
-
-Write:
+For `custom_webhook_command`, collect URL, optional headers, method (`POST` default or `PUT`), events (`session-end`, `ask-user-question`, `session-start`, `session-idle`, `stop`), and an instruction template:
 
 ```bash
-jq \
-  --arg url "$URL" \
-  --arg method "${METHOD:-POST}" \
-  --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" \
-  '.notifications = (.notifications // {enabled: true}) |
-   .notifications.enabled = true |
-   .notifications.custom_webhook_command = {
-     enabled: true,
-     url: $url,
-     method: $method,
-     instruction: $instruction,
-     events: ["session-end", "ask-user-question"]
-   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+jq --arg url "$URL" --arg method "${METHOD:-POST}" --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" --argjson headers "${HEADERS_JSON:-{}}" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.custom_webhook_command={enabled:true,url:$url,headers:$headers,method:$method,instruction:$instruction,events:["session-end","ask-user-question"]}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-### 4b) `custom_cli_command`
-
-Use AskUserQuestion to collect:
-- Command template (supports `{{event}}`, `{{instruction}}`, `{{sessionId}}`, `{{projectPath}}`)
-- Optional event list
-- Optional instruction template
-
-Write:
+For `custom_cli_command`, collect a command template (`{{event}}`, `{{instruction}}`, `{{sessionId}}`, `{{projectPath}}`), optional events, and an instruction template:
 
 ```bash
-jq \
-  --arg command "$COMMAND_TEMPLATE" \
-  --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" \
-  '.notifications = (.notifications // {enabled: true}) |
-   .notifications.enabled = true |
-   .notifications.custom_cli_command = {
-     enabled: true,
-     command: $command,
-     instruction: $instruction,
-     events: ["session-end", "ask-user-question"]
-   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+jq --arg command "$COMMAND_TEMPLATE" --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.custom_cli_command={enabled:true,command:$command,instruction:$instruction,events:["session-end","ask-user-question"]}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-> Activation gate: OpenClaw-backed dispatch is active only when `OMX_OPENCLAW=1`.
-> For command gateways, also require `OMX_OPENCLAW_COMMAND=1`.
-> Optional timeout env override: `OMX_OPENCLAW_COMMAND_TIMEOUT_MS` (ms).
+OpenClaw dispatch requires `OMX_OPENCLAW=1`; command gateways additionally require `OMX_OPENCLAW_COMMAND=1`; timeout precedence is `gateways.<name>.timeout` > `OMX_OPENCLAW_COMMAND_TIMEOUT_MS` > `5000` ms.
 
-### 4b-1) OpenClaw + Clawdbot Agent Workflow (recommended for dev)
+## 4. OpenClaw + Clawdbot agent mode
 
-If the user explicitly asks to route hook notifications through **clawdbot agent turns**
-(not direct message/webhook forwarding), use a command gateway that invokes
-`clawdbot agent` and delivers back to Discord.
-
-Notes:
-- Hook name mapping is intentional: notifications `session-stop` -> OpenClaw hook `stop`.
-- OMX shell-escapes template substitutions for command gateways (including `{{instruction}}`).
-- Keep `instruction` templates concise and avoid untrusted shell metacharacters.
-- During troubleshooting, avoid swallowing command output; route it to a log file.
-- Timeout precedence: `gateways.<name>.timeout` > `OMX_OPENCLAW_COMMAND_TIMEOUT_MS` > `5000`.
-- For clawdbot agent workflows, set `gateways.<name>.timeout` to `120000` (recommended).
-- For dev operations, enforce Korean output in all hook instructions.
-- Include both `session={{sessionId}}` and `tmux={{tmuxSession}}` in hook text for traceability.
-- If follow-up is needed, explicitly instruct clawdbot to consult `SOUL.md` and continue in `#omc-dev`.
-- **Error handling**: Append `|| true` to prevent OMX hook failures from blocking the session.
-- **JSONL logging**: Use `.jsonl` extension and append (`>>`) for structured log aggregation.
-- **Reply target format**: Use `--reply-to 'channel:CHANNEL_ID'` for reliability (preferred over channel aliases).
-
-Example (targeting `#omc-dev` with production-tested settings):
+Use this only when the requested route is a `clawdbot agent` turn delivered to Discord. The `session-stop` notification intentionally maps to the OpenClaw `stop` hook. OMX shell-escapes substitutions; keep instructions short, avoid untrusted shell metacharacters, append `|| true`, and append JSONL logs with `>>`.
 
 ```bash
-jq \
-  --arg command "(clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to 'channel:1468539002985644084' --timeout 120 --json >>/tmp/omx-openclaw-agent.jsonl 2>&1 || true)" \
-  '.notifications = (.notifications // {enabled: true}) |
-   .notifications.enabled = true |
-   .notifications.verbosity = "verbose" |
-   .notifications.events = (.notifications.events // {}) |
-   .notifications.events["session-start"] = {enabled: true} |
-   .notifications.events["session-idle"] = {enabled: true} |
-   .notifications.events["ask-user-question"] = {enabled: true} |
-   .notifications.events["session-stop"] = {enabled: true} |
-   .notifications.events["session-end"] = {enabled: true} |
-   .notifications.openclaw = (.notifications.openclaw // {}) |
-   .notifications.openclaw.enabled = true |
-   .notifications.openclaw.gateways = (.notifications.openclaw.gateways // {}) |
-   .notifications.openclaw.gateways["local"] = {
-     type: "command",
-     command: $command,
-     timeout: 120000
-   } |
-   .notifications.openclaw.hooks = (.notifications.openclaw.hooks // {}) |
-   .notifications.openclaw.hooks["session-start"] = {
-     enabled: true,
-     gateway: "local",
-     instruction: "OMX hook=session-start project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 상태를 공유하고 SOUL.md를 참고해 필요한 후속 조치를 #omc-dev에 안내하세요."
-   } |
-   .notifications.openclaw.hooks["session-idle"] = {
-     enabled: true,
-     gateway: "local",
-     instruction: "OMX hook=session-idle project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 idle 상황을 간단히 공유하고 진행중인 작업 팔로업을 안내하세요."
-   } |
-   .notifications.openclaw.hooks["ask-user-question"] = {
-     enabled: true,
-     gateway: "local",
-     instruction: "OMX hook=ask-user-question session={{sessionId}} tmux={{tmuxSession}} question={{question}}. 한국어로 사용자 응답 필요를 #omc-dev에 알리고 즉시 액션 아이템을 제시하세요."
-   } |
-   .notifications.openclaw.hooks["stop"] = {
-     enabled: true,
-     gateway: "local",
-     instruction: "OMX hook=session-stop project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 중단 상태와 정리 액션을 SOUL.md 기준으로 전달하세요."
-   } |
-   .notifications.openclaw.hooks["session-end"] = {
-     enabled: true,
-     gateway: "local",
-     instruction: "OMX hook=session-end project={{projectName}} session={{sessionId}} tmux={{tmuxSession}} reason={{reason}}. 한국어로 완료 요약을 1줄로 남기고 필요한 후속 조치를 안내하세요."
-   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+jq --arg command "(clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to 'channel:CHANNEL_ID' --timeout 120 --json >>/tmp/omx-openclaw-agent.jsonl 2>&1 || true)" '.notifications=(.notifications//{enabled:true})|.notifications.enabled=true|.notifications.verbosity="verbose"|.notifications.openclaw={enabled:true,gateways:{local:{type:"command",command:$command,timeout:120000}},hooks:{"session-start":{enabled:true,gateway:"local",instruction:"OMX hook=session-start project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 상태를 #omc-dev에 공유하고 SOUL.md를 참고하세요."},"session-idle":{enabled:true,gateway:"local",instruction:"OMX hook=session-idle session={{sessionId}} tmux={{tmuxSession}}. 한국어로 팔로업을 #omc-dev에 안내하세요."},"ask-user-question":{enabled:true,gateway:"local",instruction:"OMX hook=ask-user-question session={{sessionId}} tmux={{tmuxSession}} question={{question}}. 한국어로 응답 필요를 #omc-dev에 알리세요."},"stop":{enabled:true,gateway:"local",instruction:"OMX hook=session-stop session={{sessionId}} tmux={{tmuxSession}}. 한국어로 중단 상태를 전달하세요."},"session-end":{enabled:true,gateway:"local",instruction:"OMX hook=session-end session={{sessionId}} tmux={{tmuxSession}} reason={{reason}}. 한국어로 완료 요약을 #omc-dev에 남기세요."}}}' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-Verification for this mode:
+### Compatibility + precedence contract
 
-```bash
-clawdbot agent --session-id omx-hooks --message "OMX hook test via clawdbot agent path" \
-  --thinking minimal --deliver --reply-channel discord --reply-to 'channel:1468539002985644084' --timeout 120 --json
-```
+Explicit `notifications.openclaw` wins when valid; generic aliases are ignored with a warning.
 
-Dev runbook (Korean + tmux follow-up):
+Verify this mode and inspect evidence without hiding output:
 
 ```bash
-# 1) identify active OMX tmux sessions
+clawdbot agent --session-id omx-hooks --message "OMX hook test via clawdbot agent path" --thinking minimal --deliver --reply-channel discord --reply-to 'channel:CHANNEL_ID' --timeout 120 --json
 tmux list-sessions -F '#{session_name}' | rg '^omx-' || true
-
-# 2) confirm hook templates include session/tmux context
 jq '.notifications.openclaw.hooks' "$CONFIG_FILE"
-
-# 3) inspect agent JSONL logs when delivery looks broken
-tail -n 120 /tmp/omx-openclaw-agent.jsonl | jq -s '.[] | {timestamp: (.timestamp // .time), status: (.status // .error // "ok")}'
-
-# 4) check for recent errors in logs
+tail -n 120 /tmp/omx-openclaw-agent.jsonl | jq -s '.[] | {timestamp:(.timestamp // .time),status:(.status // .error // "ok")}'
 rg '"error"|"failed"|"timeout"' /tmp/omx-openclaw-agent.jsonl | tail -20
 ```
 
-### 4c) Compatibility + precedence contract
-
-OMX accepts both:
-- explicit `notifications.openclaw` schema (legacy/runtime shape)
-- generic aliases (`custom_webhook_command`, `custom_cli_command`)
-
-Deterministic precedence:
-1. `notifications.openclaw` **wins** when present and valid.
-2. Generic aliases are ignored in that case (with warning).
-
-## Step 5: Cross-Cutting Settings
-
-### Verbosity
-- minimal / session (recommended) / agent / verbose
+For HTTP integrations, run both a `/hooks/wake` smoke test and `/hooks/agent` delivery verification.
 
-### Idle cooldown
-- `notifications.idleCooldownSeconds`
+## 5. Cross-cutting settings and disable
 
-### Profiles
-- `notifications.profiles`
-- `notifications.defaultProfile`
+- Verbosity: `minimal`, `session` (recommended), `agent`, or `verbose`.
+- Idle cooldown: `notifications.idleCooldownSeconds` (environment override: `OMX_IDLE_COOLDOWN_SECONDS`).
+- Profiles: `notifications.profiles` and `notifications.defaultProfile`.
+- Reply listener: `notifications.reply.enabled`; gates are `OMX_REPLY_ENABLED=true` and, for Discord, `OMX_REPLY_DISCORD_USER_IDS=...`. An authorized Discord bot operator may exact-match `status` on a tracked notification for a bounded read-only session summary.
 
-### Reply listener
-- `notifications.reply.enabled`
-- env gates: `OMX_REPLY_ENABLED=true`, and for Discord `OMX_REPLY_DISCORD_USER_IDS=...`
-- For Discord bot replies, an authorized operator can reply with exact-match `status` to a tracked OMX notification to receive a bounded read-only session summary. This is a reply-thread-scoped status probe, not a general remote control surface.
-
-## Step 6: Disable All Notifications
+Disable all notifications:
 
 ```bash
-jq '.notifications.enabled = false' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+jq '.notifications.enabled=false' "$CONFIG_FILE" >"$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-## Step 7: Verification Guidance
-
-After writing config, run a smoke check:
-
-```bash
-npm run build
-```
-
-For OpenClaw-like HTTP integrations, verify both:
-- `/hooks/wake` smoke test
-- `/hooks/agent` delivery verification
-
-## Final Summary Template
+## Exit evidence
 
-Show:
-- Native platforms enabled
-- Generic aliases enabled (`custom_webhook_command`, `custom_cli_command`)
-- Whether explicit `notifications.openclaw` exists (and therefore overrides aliases)
-- Verbosity + idle cooldown + reply listener state
-- Config path (`~/.codex/.omx-config.json`)
+Run `jq empty "$CONFIG_FILE"` after edits. Report the config path, enabled native providers, enabled aliases, whether valid `notifications.openclaw` overrides aliases, verbosity, idle cooldown, reply-listener state, and smoke-test results. Stop when the JSON parses and the selected path has its required evidence; do not claim delivery from configuration alone.

package/skills/deep-interview/SKILL.md

@@ -82,7 +82,7 @@ If no flag is provided, use **Standard**.
 - Do not hand off to execution while ambiguity remains above threshold unless user explicitly opts to proceed with warning
 - Do not crystallize or hand off while `Non-goals` or `Decision Boundaries` remain unresolved, even if the weighted ambiguity threshold is met
 - Treat early exit as a safety valve, not the default success path
-- Persist mode state for resume safety with CLI-first state commands (`omx state write/read --input '<json>' --json`); use `state_write` / `state_read` only when explicit MCP compatibility is enabled
+- Persist mode state for resume safety only through the CLI/programmatic single-writer authority (`omx state write/read --input '<json>' --json`, backed by `src/state/operations.ts`). The MCP state server is a read-only projection and must never become a second writer.
 </Execution_Policy>
 
 <Steps>
@@ -314,7 +314,7 @@ Readiness gate:
 Show weighted breakdown table, readiness-gate status (`Non-goals`, `Decision Boundaries`), and the next focus dimension.
 
 ### 2e) Persist state
-Append round result and updated scores via `omx state write --input '<json>' --json`; use `state_write` only when explicit MCP compatibility is enabled.
+Append round result and updated scores via `omx state write --input '<json>' --json`. Do not write `{mode}-state.json` directly and do not use the read-only MCP state projection as a writer.
 
 ### 2f) Round controls
 - Do not offer early exit before the first explicit assumption probe and one persistent follow-up have happened
@@ -339,7 +339,7 @@ Track used modes in state to prevent repetition.
 When threshold is met (or user exits with warning / hard cap):
 
 1. Write interview transcript summary to:
-   - `.omx/interviews/{slug}-{timestamp}.md`  
+   - `.omx/interviews/{slug}-{timestamp}.md`
      (kept for ralph PRD compatibility)
 2. Write execution-ready spec to:
    - `.omx/specs/deep-interview-{slug}.md`
@@ -448,7 +448,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 
 ### 2. **`$ralplan` (Recommended when architecture/test-shape review is still needed)**
 - **Input Artifact:** `.omx/specs/deep-interview-{slug}.md` (optionally accompanied by the transcript/context snapshot for traceability)
-- **Invocation:** `$plan --consensus --direct <spec-path>`
+- **Invocation:** `$ralplan <spec-path>`
 - **Consumer Behavior:** Treat the deep-interview spec as the requirements source of truth. Do not repeat the interview by default; refine architecture/feasibility around the clarified intent and boundaries instead.
 - **Skipped / Already-Satisfied Stages:** Requirements discovery, ambiguity clarification, and early intent-boundary elicitation
 - **Expected Output:** Canonical planning artifacts under `.omx/plans/`, especially `prd-*.md` and `test-spec-*.md`
@@ -503,7 +503,7 @@ Recommend `$ultragoal` as the default durable goal-mode follow-up because it sup
 - From attached-tmux Bash/tool paths, call it as `OMX_QUESTION_RETURN_PANE=$TMUX_PANE omx question ...` unless an explicit `%pane` return target is already known
 - If the current runtime is outside tmux and cannot render `omx question`, use native structured input when available; otherwise ask exactly one concise plain-text question and wait for the answer
 - After `omx question` returns JSON, prefer `answers[0].answer` / `answers[]`; use legacy `answer` only as a fallback for older records
-- Use `omx state write/read --input '<json>' --json` for resumable mode state; `state_write` / `state_read` are explicit MCP compatibility fallbacks only
+- Use `omx state write/read --input '<json>' --json` for resumable mode state through the sole-writer state operations path; the MCP state server is read-only and is not a fallback writer
 - If the interview cannot ask a required `omx question` round, persist the blocker as terminal state with `active: false` and `current_phase: "blocked"`; do not write a terminal blocked phase with `active: true`
 - Read/write context snapshots under `.omx/context/`
 - Read applicable repo docs/rules/context during preflight; write durable docs, glossary, ADR, or memory updates only when the user explicitly opts in and the content is public-safe
@@ -567,13 +567,14 @@ enableChallengeModes = true
 
 If interrupted, rerun `$deep-interview`. Resume from persisted mode state via `omx state read --input '{"mode":"deep-interview"}' --json`.
 
-## Recommended 3-Stage Pipeline
+## Canonical Autopilot Entry Pipeline
 
 ```
-deep-interview -> ralplan -> autopilot
+autopilot -> deep-interview -> ralplan -> ultragoal
 ```
 
-- Stage 1 (deep-interview): clarity gate
-- Stage 2 (ralplan): feasibility + architecture gate
-- Stage 3 (autopilot): execution + QA + validation gate
+- Autopilot begins with this independent deep-interview clarity gate; it must not substitute `$plan --interview`.
+- Stage 1 (deep-interview): ambiguity clearance and execution-ready requirements artifact
+- Stage 2 (ralplan): feasibility, architecture, and consensus gate
+- Stage 3 (ultragoal): durable execution, verification, and completion receipts
 </Advanced>

package/skills/design/SKILL.md

@@ -5,176 +5,76 @@ description: Canonical repo-local DESIGN.md workflow for product, UI/UX, and fro
 
 # Design Skill
 
-Use `$design` when product, UI/UX, frontend, or design-system decisions need a durable source of truth in the repository. This skill discovers existing design context, interviews for missing product/design information, and creates or refreshes repo-local `DESIGN.md` so future UI/UX/frontend work is grounded instead of improvised.
+Use `$design` to discover product and UI evidence, close only design-critical context gaps, and create or refresh the repository’s durable `DESIGN.md` contract. It is a maintained design brief, not a pixel-matching loop or one-off critique.
 
-## Purpose
-
-Make repo-local `DESIGN.md` source of truth and canonical design contract for the current repository:
-
-`existing repo evidence -> missing-context interview -> create/refresh DESIGN.md -> use DESIGN.md for UI/UX/frontend decisions`.
-
-The output is not a pixel-matching loop and not a one-off visual critique. It is the maintained design brief/checklist that implementation, review, and future visual work should cite.
+Shared operating, delegation, state, hook, team, cancellation, and verification invariants live in [`templates/AGENTS.md`](../../templates/AGENTS.md). Follow that source instead of duplicating its rules here.
 
 ## Use when
 
-- The user asks for design direction, UX guidance, frontend planning, or design-system alignment.
-- A repo needs a design brief before UI/frontend implementation begins.
-- Existing UI/components/assets/screenshots need to be summarized into a reusable design source of truth.
-- UI/UX/frontend decisions are ambiguous and should be resolved through product context, constraints, and documented principles.
-- A feature needs `DESIGN.md` created or refreshed before `$ralph`, a designer lane, or implementation work proceeds.
-
-## Do not use when
+- Product, UX, frontend, or design-system decisions need a repo-local source of truth.
+- A feature needs a design brief before `$ralph`, a designer lane, or implementation.
+- Existing UI, assets, screenshots, or constraints need an actionable design summary.
 
-- The user provides or requests a visual reference/image/live URL and wants measured implementation until screenshots match. Use `$visual-ralph` for that visual-reference implementation loop.
-- The task is pure backend/API/infrastructure work with no user-facing design consequence.
-- The user only asks to compare screenshots or score visual fidelity. Use `$visual-ralph` and its built-in visual verdict flow.
+Do not use it for visual-reference implementation matching (use `$visual-ralph`), screenshot comparison alone, or backend/infrastructure work without user-facing design impact.
 
 ## Relationship to `$visual-ralph`
 
-`$design` owns the durable repo design source of truth: product goals, users, IA, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`.
-
-`$visual-ralph` owns implementation against an approved generated/static/live-URL visual reference, with screenshot capture, Visual Ralph verdict scoring, and pixel-diff evidence. `$visual-ralph` may read `DESIGN.md`, and it may leave design-system artifacts behind, but it does not replace the `DESIGN.md` discovery/interview/refresh workflow.
-
-If both are needed, run `$design` first to establish the design contract, then run `$visual-ralph` only after the visual reference/baseline is approved.
+`$design` owns product goals, users, information architecture, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`. `$visual-ralph` owns implementation against an approved visual reference or live-URL baseline, measured verdicts, and pixel-diff evidence. Run `$design` first when both are needed; `DESIGN.md` supports but does not replace the visual verdict target.
 
 ## Workflow
 
-### 1. Discover local design evidence
-
-Inspect the repository before writing guidance. Look for:
+### 1. Discover local evidence
 
-- `DESIGN.md`, `docs/design*`, `docs/ux*`, `docs/frontend*`, `README.md`, product specs, PRDs, and issue notes.
-- Existing UI source: routes, pages, layouts, components, stories, examples, demos, theme files, CSS variables, Tailwind/theme config, tokens, icons, and assets.
-- Screenshots, mockups, brand files, logos, Figma/export notes, Storybook snapshots, Playwright screenshots, visual-regression baselines, or `.omx/artifacts/visual-ralph/*` references.
-- Accessibility, responsive, i18n, content, and platform constraints already encoded in code or docs.
+Inspect and cite existing `DESIGN.md`, design/UX/frontend docs, README/specs/issues, routes/pages/layouts/components/stories, theme and token files, assets, screenshots/mockups, Storybook or Playwright baselines, and accessibility/responsive/i18n/platform constraints. Separate observations from inferences; note absent evidence.
 
-Record evidence with file paths. Distinguish observed facts from design inferences.
+### 2. Interview only missing context
 
-### 2. Interview only for missing context
-
-Ask concise questions only when repo evidence cannot answer design-critical context. Prefer one focused round that closes the biggest gaps, such as:
-
-- target users/personas and jobs to be done,
-- product/business goals and non-goals,
-- brand personality or forbidden aesthetics,
-- primary flows and information architecture,
-- accessibility level, device/browser support, and implementation constraints,
-- existing design assets or references the repo does not contain.
-
-If the user wants autonomous progress or cannot answer, create `DESIGN.md` with explicit assumptions and open questions instead of blocking.
+Ask concise questions only for gaps the repository cannot resolve: users/jobs, goals/non-goals, brand personality and forbidden aesthetics, primary flows, accessibility/device/browser targets, or unavailable assets/references. If answers are unavailable, record explicit assumptions and open questions rather than blocking.
 
 ### 3. Create or refresh `DESIGN.md`
 
-Use the structure below. Preserve useful existing content, remove contradictions, and mark unknowns as open questions. Keep it actionable for implementers and reviewers.
-
-#### Required `DESIGN.md` structure/checklist
+Preserve useful content, remove contradictions, mark unknowns, and keep decisions actionable. The root file must contain these sections:
 
-```markdown
 # Design
-
 ## Source of truth
-- Status: Draft | Active | Needs refresh
-- Last refreshed: YYYY-MM-DD
-- Primary product surfaces:
-- Evidence reviewed:
-
+Status (Draft | Active | Needs refresh), date, product surfaces, evidence reviewed.
 ## Brand
-- Personality:
-- Trust signals:
-- Avoid:
-
+Personality, trust signals, avoid.
 ## Product goals
-- Goals:
-- Non-goals:
-- Success signals:
-
+Goals, non-goals, success signals.
 ## Personas and jobs
-- Primary personas:
-- User jobs:
-- Key contexts of use:
-
+Primary personas, user jobs, contexts of use.
 ## Information architecture
-- Primary navigation:
-- Core routes/screens:
-- Content hierarchy:
-
+Navigation, routes/screens, content hierarchy.
 ## Design principles
-- Principle 1:
-- Principle 2:
-- Tradeoffs:
-
+Principles and tradeoffs.
 ## Visual language
-- Color:
-- Typography:
-- Spacing/layout rhythm:
-- Shape/radius/elevation:
-- Motion:
-- Imagery/iconography:
-
+Color, typography, spacing, shape/elevation, motion, imagery/iconography.
 ## Components
-- Existing components to reuse:
-- New/changed components:
-- Variants and states:
-- Token/component ownership:
-
+Existing/new components, variants/states, token ownership.
 ## Accessibility
-- Target standard:
-- Keyboard/focus behavior:
-- Contrast/readability:
-- Screen-reader semantics:
-- Reduced motion and sensory considerations:
-
+Target standard, keyboard/focus, contrast, semantics, reduced motion/sensory concerns.
 ## Responsive behavior
-- Supported breakpoints/devices:
-- Layout adaptations:
-- Touch/hover differences:
-
+Breakpoints/devices, layout adaptations, touch/hover differences.
 ## Interaction states
-- Loading:
-- Empty:
-- Error:
-- Success:
-- Disabled:
-- Offline/slow network, if applicable:
-
+Loading, empty, error, success, disabled, offline/slow network where applicable.
 ## Content voice
-- Tone:
-- Terminology:
-- Microcopy rules:
-
+Tone, terminology, microcopy rules.
 ## Implementation constraints
-- Framework/styling system:
-- Design-token constraints:
-- Performance constraints:
-- Compatibility constraints:
-- Test/screenshot expectations:
-
+Framework/styling, tokens, performance, compatibility, test/screenshot expectations.
 ## Open questions
-- [ ] Question / owner / impact
-```
-
-### 4. Use `DESIGN.md` as the decision contract
-
-For UI/UX/frontend work after the refresh:
+`[ ]` question, owner, and impact.
 
-- Cite the relevant `DESIGN.md` sections before making design choices.
-- Prefer existing components, tokens, and documented constraints.
-- If implementation reveals a design contradiction, update `DESIGN.md` or add an open question before proceeding.
-- Do not introduce a new design-system layer when existing repo-native patterns can be extended.
+### 4. Apply the contract
 
-### 5. Handoff to implementation or Visual Ralph when appropriate
+Before UI decisions, cite relevant `DESIGN.md` sections, reuse documented components/tokens, and update the file or add an open question when implementation exposes a contradiction. Do not invent a parallel design-system layer.
 
-- For normal frontend implementation, hand off with the relevant `DESIGN.md` sections, repo evidence, and acceptance criteria.
-- For visual-reference/image/live-URL matching, hand off to `$visual-ralph` with the approved reference/baseline and note that `DESIGN.md` is supporting context, not the visual verdict target.
+### 5. Handoff
 
-## Completion checklist
+For normal frontend work, provide the relevant sections, repo evidence, and acceptance criteria. For visual-reference, image, or live-URL matching, hand off to `$visual-ralph` with the approved baseline and identify `DESIGN.md` as supporting context only.
 
-Do not declare the design workflow complete until:
+## Evidence and completion
 
-- Existing design docs/assets/components/screenshots have been inspected or explicitly noted as absent.
-- Missing product/design context has been answered, assumed, or listed in `DESIGN.md` open questions.
-- `DESIGN.md` exists at the repo root and contains all required checklist sections.
-- UI/UX/frontend recommendations cite `DESIGN.md` rather than relying on unstated preferences.
-- Any `$visual-ralph` handoff is clearly separated as visual implementation matching, not DESIGN.md governance.
+Complete only when design docs/assets/components/screenshots were inspected or noted absent; missing context is answered, assumed, or listed; root `DESIGN.md` contains every required section; recommendations cite it; and any Visual Ralph handoff is clearly separated from design governance.
 
 Task: {{ARGUMENTS}}