oh-my-codex 0.6.4 → 0.7.0

package/skills/configure-slack/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: configure-slack
+description: Configure Slack webhook notifications via natural language
+triggers:
+  - "configure slack"
+  - "setup slack"
+  - "slack notifications"
+  - "slack webhook"
+---
+
+# Configure Slack Notifications
+
+Set up Slack notifications so OMX can ping you when sessions end, need input, or complete background tasks.
+
+## How This Skill Works
+
+This is an interactive, natural-language configuration skill. Walk the user through setup by asking questions with AskUserQuestion. Write the result to `~/.codex/.omx-config.json`.
+
+## Step 1: Detect Existing Configuration
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+
+if [ -f "$CONFIG_FILE" ]; then
+  HAS_SLACK=$(jq -r '.notifications.slack.enabled // false' "$CONFIG_FILE" 2>/dev/null)
+  WEBHOOK_URL=$(jq -r '.notifications.slack.webhookUrl // empty' "$CONFIG_FILE" 2>/dev/null)
+  CHANNEL=$(jq -r '.notifications.slack.channel // empty' "$CONFIG_FILE" 2>/dev/null)
+  USERNAME=$(jq -r '.notifications.slack.username // empty' "$CONFIG_FILE" 2>/dev/null)
+  MENTION=$(jq -r '.notifications.slack.mention // empty' "$CONFIG_FILE" 2>/dev/null)
+
+  if [ "$HAS_SLACK" = "true" ]; then
+    echo "EXISTING_CONFIG=true"
+    [ -n "$WEBHOOK_URL" ] && echo "WEBHOOK_URL=$WEBHOOK_URL"
+    [ -n "$CHANNEL" ] && echo "CHANNEL=$CHANNEL"
+    [ -n "$USERNAME" ] && echo "USERNAME=$USERNAME"
+    [ -n "$MENTION" ] && echo "MENTION=$MENTION"
+  else
+    echo "EXISTING_CONFIG=false"
+  fi
+else
+  echo "NO_CONFIG_FILE"
+fi
+```
+
+If existing config is found, show the user what's currently configured and ask if they want to update or reconfigure.
+
+## Step 2: Collect Webhook URL
+
+Use AskUserQuestion:
+
+**Question:** "Paste your Slack Incoming Webhook URL. To create one: Go to api.slack.com/apps > Your App > Incoming Webhooks > Add New Webhook to Workspace > Copy URL"
+
+The user will type their webhook URL in the "Other" field.
+
+**Validate** the URL:
+- Must start with `https://hooks.slack.com/services/` or `https://hooks.slack.com/workflows/`
+- If invalid, explain the format and ask again
+
+## Step 3: Configure Channel (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Which Slack channel should receive notifications? (Optional — leave blank to use the webhook's default channel)"
+
+**Options:**
+1. **Use webhook default** - The channel configured in the Slack app integration
+2. **Specify a channel** - Enter a channel name (e.g. `#dev-alerts`) or channel ID
+
+Note: Overriding the channel requires the webhook to have permission for that channel.
+
+## Step 4: Configure Mention (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Would you like notifications to mention (ping) someone?"
+
+**Options:**
+1. **Yes, mention a user** - Tag a user with `<@UXXXXXXXX>`
+2. **Yes, mention a channel** - Tag everyone with `<!channel>` or `<!here>`
+3. **No mentions** - Just post the message without pinging anyone
+
+### If user wants to mention a user:
+
+Ask: "What is the Slack member ID to mention? (Click the user's profile > More > Copy member ID)"
+
+Format: `<@UXXXXXXXX>` (e.g. `<@U012AB3CD>`)
+
+### If user wants a channel mention:
+
+Choose between:
+- `<!channel>` — notifies all channel members regardless of online status
+- `<!here>` — notifies only currently active channel members
+
+## Step 5: Configure Display Name (Optional)
+
+Use AskUserQuestion:
+
+**Question:** "Custom bot display name in Slack? (Shows as the message sender)"
+
+**Options:**
+1. **OMX (default)** - Display as "OMX"
+2. **Codex CLI** - Display as "Codex CLI"
+3. **Custom** - Enter a custom name
+
+## Step 6: Configure Events
+
+Use AskUserQuestion with multiSelect:
+
+**Question:** "Which events should trigger Slack notifications?"
+
+**Options (multiSelect: true):**
+1. **Session end (Recommended)** - When a Codex session finishes
+2. **Input needed** - When Codex is waiting for your response (great for long-running tasks)
+3. **Session start** - When a new session begins
+4. **Session continuing** - When a persistent mode keeps the session alive
+
+Default selection: session-end + ask-user-question.
+
+## Step 7: Write Configuration
+
+Read the existing config, merge the new Slack settings, and write back:
+
+```bash
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+
+if [ -f "$CONFIG_FILE" ]; then
+  EXISTING=$(cat "$CONFIG_FILE")
+else
+  EXISTING='{}'
+fi
+
+# WEBHOOK_URL, CHANNEL, MENTION, USERNAME are collected from user
+echo "$EXISTING" | jq \
+  --arg url "$WEBHOOK_URL" \
+  --arg channel "$CHANNEL" \
+  --arg mention "$MENTION" \
+  --arg username "$USERNAME" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.slack = {
+     enabled: true,
+     webhookUrl: $url,
+     channel: (if $channel == "" then null else $channel end),
+     mention: (if $mention == "" then null else $mention end),
+     username: (if $username == "" then null else $username end)
+   }' > "$CONFIG_FILE"
+```
+
+### Add event-specific config if user didn't select all events:
+
+For each event NOT selected, disable it:
+
+```bash
+# Example: disable session-start if not selected
+echo "$(cat "$CONFIG_FILE")" | jq \
+  '.notifications.events = (.notifications.events // {}) |
+   .notifications.events["session-start"] = {enabled: false}' > "$CONFIG_FILE"
+```
+
+## Step 8: Test the Configuration
+
+After writing config, offer to send a test notification:
+
+Use AskUserQuestion:
+
+**Question:** "Send a test notification to verify the setup?"
+
+**Options:**
+1. **Yes, test now (Recommended)** - Send a test message to your Slack channel
+2. **No, I'll test later** - Skip testing
+
+### If testing:
+
+```bash
+RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  -d "{\"text\": \"${MENTION:+$MENTION\\n}OMX test notification - Slack is configured!\", \"username\": \"${USERNAME:-OMX}\"}" \
+  "$WEBHOOK_URL")
+
+if [ "$RESPONSE" = "200" ]; then
+  echo "Test notification sent successfully!"
+else
+  echo "Failed (HTTP $RESPONSE). Check the webhook URL and channel permissions."
+fi
+```
+
+Report success or failure. Common issues:
+- **400 Bad Request**: Malformed JSON or invalid channel override
+- **403 Forbidden**: Channel override not permitted by the webhook
+- **404 Not Found**: Webhook URL is invalid or revoked — regenerate it in Slack
+
+## Step 9: Confirm
+
+Display the final configuration summary:
+
+```
+Slack Notifications Configured!
+
+  Webhook:  https://hooks.slack.com/services/...
+  Channel:  #dev-alerts (or "webhook default")
+  Mention:  <!channel> (or "none")
+  Username: OMX
+  Events:   session-end, ask-user-question
+
+Config saved to: ~/.codex/.omx-config.json
+
+You can also set these via environment variables:
+  OMX_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+  OMX_SLACK_MENTION=<!channel>
+
+To reconfigure: /configure-slack
+To configure Discord: /configure-discord
+To configure Telegram: /configure-telegram
+```
+
+## Environment Variable Alternative
+
+Users can skip this wizard entirely by setting env vars in their shell profile:
+
+```bash
+export OMX_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
+export OMX_SLACK_MENTION="<!channel>"  # optional
+```
+
+Env vars are auto-detected by the notification system without needing `.omx-config.json`.

package/skills/omx-setup/SKILL.md

@@ -10,14 +10,14 @@ Use this skill when users want to install or refresh oh-my-codex for the **curre
 ## Command
 
 ```bash
-omx setup [--force] [--dry-run] [--verbose] [--scope <user|project-local|project>]
+omx setup [--force] [--dry-run] [--verbose] [--scope <user|project>]
 ```
 
 Supported setup flags (current implementation):
 - `--force`: overwrite/reinstall managed artifacts where applicable
 - `--dry-run`: print actions without mutating files
 - `--verbose`: print per-file/per-step details
-- `--scope`: choose install scope (`user`, `project-local`, `project`)
+- `--scope`: choose install scope (`user`, `project`)
 
 ## What this setup actually does
 
@@ -25,31 +25,26 @@ Supported setup flags (current implementation):
 
 1. Resolve setup scope:
    - `--scope` explicit value
-   - else persisted `./.omx/setup-scope.json`
+   - else persisted `./.omx/setup-scope.json` (with automatic migration of legacy values)
    - else interactive prompt on TTY (default `user`)
    - else default `user` (safe for CI/tests)
-2. Create project OMX directories (`./.omx/state`, `./.omx/plans`, `./.omx/logs`) and persist effective scope
-3. For `user`/`project-local` scope:
-   - install prompts
-   - remove legacy prompt shims
-   - install native agent configs
-   - install skills
-   - merge OMX config.toml
-4. For `project` scope: skip prompt/skill/config/native-agent installs with console messages
-6. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
-7. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
-8. Configure notify hook references and write `./.omx/hud-config.json`
+2. Create directories and persist effective scope
+3. Install prompts, native agent configs, skills, and merge config.toml (scope determines target directories)
+4. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
+5. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
+6. Configure notify hook references and write `./.omx/hud-config.json`
 
 ## Important behavior notes
 
 - `omx setup` only prompts for scope when no scope is provided/persisted and stdin/stdout are TTY.
 - Local project orchestration file is `./AGENTS.md` (project root).
+- If `AGENTS.md` exists and `--force` is not used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
 - Scope targets:
   - `user`: user directories (`~/.codex`, `~/.agents/skills`, `~/.omx/agents`)
-  - `project-local`: local directories (`./.codex`, `./.agents/skills`, `./.omx/agents`)
-  - `project`: project-only OMX setup (`./.omx/*`, `AGENTS.md`, HUD)
-- If persisted scope is `project-local`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
+  - `project`: local directories (`./.codex`, `./.agents/skills`, `./.omx/agents`)
+- If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
 - With `--force`, AGENTS overwrite may still be skipped if an active OMX session is detected (safety guard).
+- Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
 
 ## Recommended workflow
 
@@ -70,8 +65,8 @@ omx doctor
 ## Expected verification indicators
 
 From `omx doctor`, expect:
-- Prompts installed (scope-dependent: user or project-local)
-- Skills installed (scope-dependent: user or project-local)
+- Prompts installed (scope-dependent: user or project)
+- Skills installed (scope-dependent: user or project)
 - AGENTS.md found in project root
 - `.omx/state` exists
 - OMX MCP servers configured in scope target `config.toml` (`~/.codex/config.toml` or `./.codex/config.toml`)

package/skills/plan/SKILL.md

@@ -4,7 +4,7 @@ description: Strategic planning with optional interview workflow
 ---
 
 <Purpose>
-Plan creates comprehensive, actionable work plans through intelligent interaction. It auto-detects whether to interview the user (broad requests) or plan directly (detailed requests), and supports consensus mode (iterative Planner/Architect/Critic loop) and review mode (Critic evaluation of existing plans).
+Plan creates comprehensive, actionable work plans through intelligent interaction. It auto-detects whether to interview the user (broad requests) or plan directly (detailed requests), and supports consensus mode (iterative Planner/Architect/Critic loop with RALPLAN-DR structured deliberation) and review mode (Critic evaluation of existing plans).
 </Purpose>
 
 <Use_When>
@@ -31,7 +31,8 @@ Jumping into code without understanding requirements leads to rework, scope cree
 - Ask one question at a time during interviews -- never batch multiple questions
 - Gather codebase facts via `explore` agent before asking the user about them
 - Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
-- Consensus mode auto-proceeds by default; add `--interactive` to require explicit user approval before proceeding to implementation
+- Consensus mode outputs the final plan by default; add `--interactive` to enable execution handoff
+- Consensus mode uses RALPLAN-DR short mode by default; switch to deliberate mode with `--deliberate` or when the request explicitly signals high risk (auth/security, data migration, destructive/irreversible changes, production incident, compliance/PII, public API breakage)
 </Execution_Policy>
 
 <Steps>
@@ -42,8 +43,8 @@ Jumping into code without understanding requirements leads to rework, scope cree
 |------|---------|----------|
 | Interview | Default for broad requests | Interactive requirements gathering |
 | Direct | `--direct`, or detailed request | Skip interview, generate plan directly |
-| Consensus | `--consensus`, "ralplan" | Planner -> Architect -> Critic loop until agreement; auto-proceeds by default |
-| Consensus Interactive | `--consensus --interactive` | Same as Consensus but pauses for user feedback at draft and approval steps |
+| Consensus | `--consensus`, "ralplan" | Planner -> Architect -> Critic loop until agreement with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk); outputs plan by default |
+| Consensus Interactive | `--consensus --interactive` | Same as Consensus but pauses for user feedback at draft and approval steps, then hands off to execution |
 | Review | `--review`, "review this plan" | Critic evaluation of existing plan |
 
 ### Interview Mode (broad/vague requests)
@@ -63,31 +64,48 @@ Jumping into code without understanding requirements leads to rework, scope cree
 
 ### Consensus Mode (`--consensus` / "ralplan")
 
-Default behavior is **non-interactive**: the workflow auto-proceeds through all steps without pausing for user input. Add `--interactive` to enable confirmation prompts at the draft and approval steps.
-
-1. **Planner** creates initial plan
-2. **User feedback** (only in `--interactive` mode):
-   - Use `AskUserQuestion` to present the draft plan with these options:
-     - **Proceed to review** — send to Architect and Critic for evaluation
-     - **Request changes** — return to step 1 with user feedback incorporated
-     - **Skip review** — go directly to final approval (step 6)
-   - Without `--interactive`: automatically proceed to Architect review (step 3)
-3. **Architect** reviews for architectural soundness (prefer `ask_codex` with `architect` role)
-4. **Critic** evaluates against quality criteria (prefer `ask_codex` with `critic` role)
-5. If Critic rejects: iterate with feedback (max 5 iterations)
-6. On Critic approval:
-   - **`--interactive` mode**: use `AskUserQuestion` to present the plan with these options:
-     - **Approve and execute** — proceed to implementation via ralph+ultrawork
-     - **Request changes** — return to step 1 with user feedback
-     - **Reject** — discard the plan entirely
-   - **Default (non-interactive)**: automatically approve and proceed to execution
-7. (`--interactive` only) User chooses via the structured `AskUserQuestion` UI (never ask for approval in plain text)
-8. On approval: **MUST** invoke `/ralph` with the approved plan path from `.omx/plans/` as context. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
+**RALPLAN-DR modes**: **Short** (default, bounded structure) and **Deliberate** (for `--deliberate` or explicit high-risk requests). Both modes keep the same Planner -> Architect -> Critic sequence. The workflow auto-proceeds through planning steps (Planner/Architect/Critic) but outputs the final plan without executing.
+
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before any Architect review. The summary **MUST** include:
+   - **Principles** (3-5)
+   - **Decision Drivers** (top 3)
+   - **Viable Options** (>=2) with bounded pros/cons for each option
+   - If only one viable option remains, an explicit **invalidation rationale** for the alternatives that were rejected
+   - In **deliberate mode**: a **pre-mortem** (3 failure scenarios) and an **expanded test plan** covering **unit / integration / e2e / observability**
+2. **User feedback** *(--interactive only)*: If running with `--interactive`, **MUST** use `AskUserQuestion` to present the draft plan **plus the RALPLAN-DR Principles / Decision Drivers / Options summary for early direction alignment** with these options:
+   - **Proceed to review** — send to Architect and Critic for evaluation
+   - **Request changes** — return to step 1 with user feedback incorporated
+   - **Skip review** — go directly to final approval (step 7)
+   If NOT running with `--interactive`, automatically proceed to review (step 3).
+3. **Architect** reviews for architectural soundness using `ask_codex` with `agent_role: "architect"`. Architect review **MUST** include: strongest steelman counterargument (antithesis) against the favored option, at least one meaningful tradeoff tension, and (when possible) a synthesis path. In deliberate mode, Architect should explicitly flag principle violations. **Wait for this step to complete before proceeding to step 4.** Do NOT run steps 3 and 4 in parallel.
+4. **Critic** evaluates against quality criteria using `ask_codex` with `agent_role: "critic"`. Critic **MUST** verify principle-option consistency, fair alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. Critic **MUST** explicitly reject shallow alternatives, driver contradictions, vague risks, or weak verification. In deliberate mode, Critic **MUST** reject missing/weak pre-mortem or missing/weak expanded test plan. Run only after step 3 is complete.
+5. **Re-review loop** (max 5 iterations): If Critic rejects or iterates, execute this closed loop:
+   a. Collect all feedback from Architect + Critic
+   b. Pass feedback to Planner to produce a revised plan
+   c. **Return to Step 3** — Architect reviews the revised plan
+   d. **Return to Step 4** — Critic evaluates the revised plan
+   e. Repeat until Critic approves OR max 5 iterations reached
+   f. If max iterations reached without approval, present the best version to user via `AskUserQuestion` with note that expert consensus was not reached
+6. **Apply improvements**: When reviewers approve with improvement suggestions, merge all accepted improvements into the plan file before proceeding. Final consensus output **MUST** include an **ADR** section with: **Decision**, **Drivers**, **Alternatives considered**, **Why chosen**, **Consequences**, **Follow-ups**. Specifically:
+   a. Collect all improvement suggestions from Architect and Critic responses
+   b. Deduplicate and categorize the suggestions
+   c. Update the plan file in `.omx/plans/` with the accepted improvements (add missing details, refine steps, strengthen acceptance criteria, ADR updates, etc.)
+   d. Note which improvements were applied in a brief changelog section at the end of the plan
+7. On Critic approval (with improvements applied): *(--interactive only)* If running with `--interactive`, use `AskUserQuestion` to present the plan with these options:
+   - **Approve and execute** — proceed to implementation via ralph+ultrawork
+   - **Approve and implement via team** — proceed to implementation via coordinated parallel team agents
+   - **Request changes** — return to step 1 with user feedback
+   - **Reject** — discard the plan entirely
+   If NOT running with `--interactive`, output the final approved plan and stop. Do NOT auto-execute.
+8. *(--interactive only)* User chooses via the structured `AskUserQuestion` UI (never ask for approval in plain text)
+9. On user approval (--interactive only):
+   - **Approve and execute**: **MUST** invoke `$ralph` with the approved plan path from `.omx/plans/` as context. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
+   - **Approve and implement via team**: **MUST** invoke `$team` with the approved plan path from `.omx/plans/` as context. Do NOT implement directly. The team skill coordinates parallel agents across the staged pipeline for faster execution on large tasks.
 
 ### Review Mode (`--review`)
 
 1. Read plan file from `.omx/plans/`
-2. Evaluate via Critic (prefer `ask_codex` with `critic` role)
+2. Evaluate via Critic using `ask_codex` with `agent_role: "critic"`
 3. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
 
 ### Plan Output Format
@@ -98,6 +116,9 @@ Every plan includes:
 - Implementation Steps (with file references)
 - Risks and Mitigations
 - Verification Steps
+- For consensus/ralplan: **RALPLAN-DR summary** (Principles, Decision Drivers, Options)
+- For consensus/ralplan final output: **ADR** (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups)
+- For deliberate consensus mode: **Pre-mortem (3 scenarios)** and **Expanded Test Plan** (unit/integration/e2e/observability)
 
 Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 </Steps>
@@ -111,9 +132,10 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 - Use `ask_codex` with `agent_role: "analyst"` for requirements analysis
 - Use `ask_codex` with `agent_role: "critic"` for plan review in consensus and review modes
 - If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent OMX prompt agents -- never block on external tools
-- In consensus mode with `--interactive`, **MUST** use `AskUserQuestion` for the user feedback step (step 2) and the final approval step (step 6) -- never ask for approval in plain text
-- In consensus mode **without** `--interactive`, auto-proceed through all steps without pausing for user input
-- In consensus mode, on approval **MUST** invoke `/ralph` for execution (step 8) -- never implement directly in the planning agent
+- **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect result before issuing the Critic call.
+- In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on `--deliberate` or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
+- In consensus mode with `--interactive`: use `AskUserQuestion` for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text. Without `--interactive`, auto-proceed through planning steps without pausing. Output the final plan without execution.
+- In consensus mode with `--interactive`, on user approval **MUST** invoke `$ralph` for execution (step 9) -- never implement directly in the planning agent
 </Tool_Usage>
 
 <Examples>
@@ -169,8 +191,8 @@ Why bad: Decision fatigue. Present one option with trade-offs, get reaction, the
 <Escalation_And_Stop_Conditions>
 - Stop interviewing when requirements are clear enough to plan -- do not over-interview
 - In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
-- Consensus mode auto-proceeds to implementation by default; with `--interactive`, requires explicit user approval before implementation begins
-- If the user says "just do it" or "skip planning", **MUST** invoke `/ralph` to transition to execution mode. Do NOT implement directly in the planning agent.
+- Consensus mode outputs the plan by default; with `--interactive`, user can approve and hand off to ralph/team
+- If the user says "just do it" or "skip planning", **MUST** invoke `$ralph` to transition to execution mode. Do NOT implement directly in the planning agent.
 - Escalate to the user when there are irreconcilable trade-offs that require a business decision
 </Escalation_And_Stop_Conditions>
 
@@ -180,8 +202,10 @@ Why bad: Decision fatigue. Present one option with trade-offs, get reaction, the
 - [ ] All risks have mitigations identified
 - [ ] No vague terms without metrics ("fast" -> "p99 < 200ms")
 - [ ] Plan saved to `.omx/plans/`
-- [ ] In consensus mode with `--interactive`: user explicitly approved before any execution
-- [ ] In consensus mode without `--interactive`: auto-proceeded to execution after Critic approval
+- [ ] In consensus mode: RALPLAN-DR summary includes 3-5 principles, top 3 drivers, and >=2 viable options (or explicit invalidation rationale)
+- [ ] In consensus mode final output: ADR section included (Decision / Drivers / Alternatives considered / Why chosen / Consequences / Follow-ups)
+- [ ] In deliberate consensus mode: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability) included
+- [ ] In consensus mode with `--interactive`: user explicitly approved before any execution; without `--interactive`: output final plan after Critic approval (no auto-execution)
 </Final_Checklist>
 
 <Advanced>
@@ -228,5 +252,5 @@ Before asking any interview question, classify it:
 
 ## Deprecation Notice
 
-The separate `/planner`, `/ralplan`, and `/review` skills have been merged into `/plan`. All workflows (interview, direct, consensus, review) are available through `/plan`.
+The separate `/planner`, `/ralplan`, and `/review` skills have been merged into `$plan`. All workflows (interview, direct, consensus, review) are available through `$plan`.
 </Advanced>

package/skills/ralplan/SKILL.md

@@ -1,46 +1,132 @@
 ---
 name: ralplan
-description: Alias for /plan --consensus
+description: Alias for $plan --consensus
 ---
 
 # Ralplan (Consensus Planning Alias)
 
-Ralplan is a shorthand alias for `/plan --consensus`. It triggers iterative planning with Planner, Architect, and Critic agents until consensus is reached.
+Ralplan is a shorthand alias for `$plan --consensus`. It triggers iterative planning with Planner, Architect, and Critic agents until consensus is reached, with **RALPLAN-DR structured deliberation** (short mode by default, deliberate mode for high-risk work).
 
 ## Usage
 
 ```
-/ralplan "task description"
-/ralplan --interactive "task description"
+$ralplan "task description"
 ```
 
 ## Flags
 
-| Flag | Description |
-|------|-------------|
-| *(none)* | Default non-interactive mode: auto-proceeds through all steps without pausing |
-| `--interactive` | Pauses at draft feedback (step 2) and final approval (step 6) to prompt the user |
+- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — and outputs the final plan without asking for confirmation.
+- `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
+
+## Usage with interactive mode
+
+```
+$ralplan --interactive "task description"
+```
 
 ## Behavior
 
 This skill invokes the Plan skill in consensus mode:
 
 ```
-/plan --consensus <arguments>
-/plan --consensus --interactive <arguments>
+$plan --consensus <arguments>
+$plan --consensus --interactive <arguments>
 ```
 
-The consensus workflow (default — non-interactive):
-1. **Planner** creates initial plan
-2. *(skipped in default mode)* Auto-proceeds to Architect review
-3. **Architect** reviews for architectural soundness
-4. **Critic** evaluates against quality criteria
-5. If Critic rejects: iterate with feedback (max 5 iterations)
-6. *(skipped in default mode)* Auto-approves on Critic approval
-7. **MUST** invoke `/ralph` for execution -- never implement directly
+The consensus workflow:
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before review:
+   - Principles (3-5)
+   - Decision Drivers (top 3)
+   - Viable Options (>=2) with bounded pros/cons
+   - If only one viable option remains, explicit invalidation rationale for alternatives
+   - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
+2. **User feedback** *(--interactive only)*: If `--interactive` is set, use `AskUserQuestion` to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
+3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. In deliberate mode, Architect should explicitly flag principle violations.
+4. **Critic** evaluates against quality criteria — run only after step 3 completes. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
+5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   a. Collect Architect + Critic feedback
+   b. Revise the plan with Planner
+   c. Return to Architect review
+   d. Return to Critic evaluation
+   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
+   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
+6. On Critic approval *(--interactive only)*: If `--interactive` is set, use `AskUserQuestion` to present the plan with approval options (Approve and execute via ralph / Approve and implement via team / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups). Otherwise, output the final plan and stop.
+7. *(--interactive only)* User chooses: Approve (ralph or team), Request changes, or Reject
+8. *(--interactive only)* On approval: invoke `$ralph` for sequential execution or `$team` for parallel team execution -- never implement directly
 
-With `--interactive` flag, steps 2 and 6 pause to ask the user via `AskUserQuestion`:
-- Step 2 options: Proceed to review / Request changes / Skip review
-- Step 6 options: Approve and execute / Request changes / Reject
+> **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent calls in the same parallel batch. Always await the Architect result before invoking Critic.
 
 Follow the Plan skill's full documentation for consensus mode details.
+
+## Pre-Execution Gate
+
+### Why the Gate Exists
+
+Execution modes (ralph, autopilot, team, ultrawork) spin up heavy multi-agent orchestration. When launched on a vague request like "ralph improve the app", agents have no clear target — they waste cycles on scope discovery that should happen during planning, often delivering partial or misaligned work that requires rework.
+
+The ralplan-first gate intercepts underspecified execution requests and redirects them through the ralplan consensus planning workflow. This ensures:
+- **Explicit scope**: A PRD defines exactly what will be built
+- **Test specification**: Acceptance criteria are testable before code is written
+- **Consensus**: Planner, Architect, and Critic agree on the approach
+- **No wasted execution**: Agents start with a clear, bounded task
+
+### Good vs Bad Prompts
+
+**Passes the gate** (specific enough for direct execution):
+- `ralph fix the null check in src/hooks/bridge.ts:326`
+- `autopilot implement issue #42`
+- `team add validation to function processKeywordDetector`
+- `ralph do:\n1. Add input validation\n2. Write tests\n3. Update README`
+- `ultrawork add the user model in src/models/user.ts`
+
+**Gated — redirected to ralplan** (needs scoping first):
+- `ralph fix this`
+- `autopilot build the app`
+- `team improve performance`
+- `ralph add authentication`
+- `ultrawork make it better`
+
+**Bypass the gate** (when you know what you want):
+- `force: ralph refactor the auth module`
+- `! autopilot optimize everything`
+
+### When the Gate Does NOT Trigger
+
+The gate auto-passes when it detects **any** concrete signal. You do not need all of them — one is enough:
+
+| Signal Type | Example prompt | Why it passes |
+|---|---|---|
+| File path | `ralph fix src/hooks/bridge.ts` | References a specific file |
+| Issue/PR number | `ralph implement #42` | Has a concrete work item |
+| camelCase symbol | `ralph fix processKeywordDetector` | Names a specific function |
+| PascalCase symbol | `ralph update UserModel` | Names a specific class |
+| snake_case symbol | `team fix user_model` | Names a specific identifier |
+| Test runner | `ralph npm test && fix failures` | Has an explicit test target |
+| Numbered steps | `ralph do:\n1. Add X\n2. Test Y` | Structured deliverables |
+| Acceptance criteria | `ralph add login - acceptance criteria: ...` | Explicit success definition |
+| Error reference | `ralph fix TypeError in auth` | Specific error to address |
+| Code block | `ralph add: \`\`\`ts ... \`\`\`` | Concrete code provided |
+| Escape prefix | `force: ralph do it` or `! ralph do it` | Explicit user override |
+
+### End-to-End Flow Example
+
+1. User types: `ralph add user authentication`
+2. Gate detects: execution keyword (`ralph`) + underspecified prompt (no files, functions, or test spec)
+3. Gate redirects to **ralplan** with message explaining the redirect
+4. Ralplan consensus runs:
+   - **Planner** creates initial plan (which files, what auth method, what tests)
+   - **Architect** reviews for soundness
+   - **Critic** validates quality and testability
+5. On consensus approval, user chooses execution path:
+   - **ralph**: sequential execution with verification
+   - **team**: parallel coordinated agents
+6. Execution begins with a clear, bounded plan
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Gate fires on a well-specified prompt | Add a file reference, function name, or issue number to anchor the request |
+| Want to bypass the gate | Prefix with `force:` or `!` (e.g., `force: ralph fix it`) |
+| Gate does not fire on a vague prompt | The gate only catches prompts with <=15 effective words and no concrete anchors; add more detail or use `$ralplan` explicitly |
+| Redirected to ralplan but want to skip planning | In the ralplan workflow, say "just do it" or "skip planning" to transition directly to execution |