claudecode-omc 4.4.5 → 4.4.6

package/skills/omc-setup/SKILL.md

@@ -277,8 +277,8 @@ fi
 
 # Strip existing markers from downloaded content (idempotency)
 if grep -q '<!-- OMC:START -->' "$TEMP_OMC"; then
-  # Extract content between markers
-  sed -n '/<!-- OMC:START -->/,/<!-- OMC:END -->/{//!p}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
+  # Extract content between markers (awk is portable across GNU/BSD)
+  awk '/<!-- OMC:END -->/{p=0} p; /<!-- OMC:START -->/{p=1}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
   mv "${TEMP_OMC}.clean" "$TEMP_OMC"
 fi
 
@@ -295,8 +295,9 @@ else
   # Merge: preserve user content outside OMC markers
   if grep -q '<!-- OMC:START -->' "$TARGET_PATH"; then
     # Has markers: replace OMC section, keep user content
-    BEFORE_OMC=$(sed -n '1,/<!-- OMC:START -->/{ /<!-- OMC:START -->/!p }' "$TARGET_PATH")
-    AFTER_OMC=$(sed -n '/<!-- OMC:END -->/,${  /<!-- OMC:END -->/!p }' "$TARGET_PATH")
+    # Use awk instead of sed for cross-platform compatibility (GNU/BSD)
+    BEFORE_OMC=$(awk '/<!-- OMC:START -->/{exit} {print}' "$TARGET_PATH")
+    AFTER_OMC=$(awk 'p; /<!-- OMC:END -->/{p=1}' "$TARGET_PATH")
     {
       [ -n "$BEFORE_OMC" ] && printf '%s\n' "$BEFORE_OMC"
       echo '<!-- OMC:START -->'
@@ -433,8 +434,8 @@ fi
 
 # Strip existing markers from downloaded content (idempotency)
 if grep -q '<!-- OMC:START -->' "$TEMP_OMC"; then
-  # Extract content between markers
-  sed -n '/<!-- OMC:START -->/,/<!-- OMC:END -->/{//!p}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
+  # Extract content between markers (awk is portable across GNU/BSD)
+  awk '/<!-- OMC:END -->/{p=0} p; /<!-- OMC:START -->/{p=1}' "$TEMP_OMC" > "${TEMP_OMC}.clean"
   mv "${TEMP_OMC}.clean" "$TEMP_OMC"
 fi
 
@@ -451,8 +452,9 @@ else
   # Merge: preserve user content outside OMC markers
   if grep -q '<!-- OMC:START -->' "$TARGET_PATH"; then
     # Has markers: replace OMC section, keep user content
-    BEFORE_OMC=$(sed -n '1,/<!-- OMC:START -->/{ /<!-- OMC:START -->/!p }' "$TARGET_PATH")
-    AFTER_OMC=$(sed -n '/<!-- OMC:END -->/,${  /<!-- OMC:END -->/!p }' "$TARGET_PATH")
+    # Use awk instead of sed for cross-platform compatibility (GNU/BSD)
+    BEFORE_OMC=$(awk '/<!-- OMC:START -->/{exit} {print}' "$TARGET_PATH")
+    AFTER_OMC=$(awk 'p; /<!-- OMC:END -->/{p=1}' "$TARGET_PATH")
     {
       [ -n "$BEFORE_OMC" ] && printf '%s\n' "$BEFORE_OMC"
       echo '<!-- OMC:START -->'
@@ -653,25 +655,62 @@ echo "Default execution mode set to: USER_CHOICE"
 **Note**: This preference ONLY affects generic keywords ("fast", "parallel"). Explicit keywords ("ulw") always override this preference.
 
 
-## Step 3.8: Install CLI Analytics Tools (Optional)
+## Step 3.8: Install OMC CLI Tool
 
-The OMC CLI provides standalone token analytics commands (`omc stats`, `omc agents`, `omc tui`).
+The OMC CLI (`omc` command) provides standalone token analytics and management commands (`omc stats`, `omc agents`, `omc tui`).
 
-Ask user: "Would you like to install the OMC CLI for standalone analytics? (Recommended for tracking token usage and costs)"
+First, check if the CLI is already installed:
+
+```bash
+# Check if omc CLI is already available
+if command -v omc &>/dev/null; then
+  OMC_CLI_VERSION=$(omc --version 2>/dev/null | head -1 || echo "installed")
+  echo "OMC CLI already installed: $OMC_CLI_VERSION"
+  OMC_CLI_INSTALLED="true"
+else
+  OMC_CLI_INSTALLED="false"
+fi
+```
+
+If `OMC_CLI_INSTALLED` is `"true"`, skip the rest of this step.
+
+If `OMC_CLI_INSTALLED` is `"false"`, use the AskUserQuestion tool to prompt the user:
+
+**Question:** "Would you like to install the OMC CLI globally for standalone analytics? (`omc stats`, `omc agents`, `omc tui`)"
 
 **Options:**
-1. **Yes (Recommended)** - Install CLI tools globally for `omc stats`, `omc agents`, etc.
-2. **No** - Skip CLI installation, use only plugin skills
+1. **Yes (Recommended)** - Install `oh-my-claude-sisyphus` via `npm install -g`
+2. **No - Skip** - Skip installation (can install manually later with `npm install -g oh-my-claude-sisyphus`)
 
-### CLI Installation Note
+If user chooses **Yes**:
 
-The CLI (`omc` command) is **no longer supported** via npm/bun global install.
+```bash
+# Check if npm is available
+if ! command -v npm &>/dev/null; then
+  echo "WARNING: npm not found. Cannot install OMC CLI automatically."
+  echo "Install Node.js/npm first, then run: npm install -g oh-my-claude-sisyphus"
+else
+  # Install the CLI globally
+  if npm install -g oh-my-claude-sisyphus 2>&1; then
+    echo "OMC CLI installed successfully."
+    # Verify installation
+    if command -v omc &>/dev/null; then
+      OMC_CLI_VERSION=$(omc --version 2>/dev/null | head -1 || echo "installed")
+      echo "Verified: omc $OMC_CLI_VERSION"
+    else
+      echo "Installed but 'omc' not on PATH. You may need to restart your shell."
+    fi
+  else
+    echo "WARNING: Failed to install OMC CLI (permission issue or network error)."
+    echo "You can install manually later: npm install -g oh-my-claude-sisyphus"
+    echo "Or with sudo: sudo npm install -g oh-my-claude-sisyphus"
+  fi
+fi
+```
 
-All functionality is available through the plugin system:
-- Use `/oh-my-claudecode:omc-help` for guidance
-- Use `/oh-my-claudecode:omc-doctor` for diagnostics
+If user chooses **No - Skip**, continue to the next step without installing.
 
-Skip this step - the plugin provides all features.
+**Note**: The CLI is optional. All core functionality is also available through the plugin system (`/oh-my-claudecode:omc-help`, `/oh-my-claudecode:omc-doctor`). The CLI adds standalone terminal commands for analytics outside of Claude Code sessions.
 
 ## Step 3.8.5: Select Task Management Tool
 

package/skills/omc-teams/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: omc-teams
+description: Spawn claude, codex, or gemini CLI workers in tmux panes for parallel task execution
+aliases: []
+---
+
+# OMC Teams Skill
+
+Spawn N CLI worker processes in tmux panes to execute tasks in parallel. Supports `claude`, `codex`, and `gemini` agent types. Unlike `/team` (which uses Claude Code's native `TeamCreate`/`Task` tools), this skill uses the tmux runtime to launch actual CLI processes in visible tmux panes.
+
+## Usage
+
+```
+/oh-my-claudecode:omc-teams N:claude "task description"
+/oh-my-claudecode:omc-teams N:codex "task description"
+/oh-my-claudecode:omc-teams N:gemini "task description"
+```
+
+### Parameters
+
+- **N** - Number of CLI workers (1-10)
+- **agent-type** - `claude` (Claude CLI), `codex` (OpenAI Codex CLI), or `gemini` (Google Gemini CLI)
+- **task** - Task description to distribute across all workers
+
+### Examples
+
+```bash
+/omc-teams 2:claude "implement auth module with tests"
+/omc-teams 2:codex "review the auth module for security issues"
+/omc-teams 3:gemini "redesign UI components for accessibility"
+/omc-teams 1:codex "write comprehensive tests for src/api/"
+```
+
+## Requirements
+
+- **tmux** must be running (`$TMUX` set in the current shell)
+- **claude** CLI: `npm install -g @anthropic-ai/claude-code` (for claude workers)
+- **codex** CLI: `npm install -g @openai/codex` (for codex workers)
+- **gemini** CLI: `npm install -g @google/gemini-cli` (for gemini workers)
+
+## How It Works
+
+1. Claude decomposes the task into N independent subtasks (one per worker)
+2. Calls `mcp__team__omc_run_team_start` then `mcp__team__omc_run_team_wait`
+3. The OMC MCP server spawns `runtime-cli.cjs` (co-located in the same install directory)
+4. The runtime creates tmux split-panes and launches the CLI processes
+5. Each worker reads its task from an inbox file and writes `done.json` on completion
+6. The runtime collects results, shuts down workers, returns structured JSON
+7. Claude parses the result and reports to the user
+
+---
+
+## Workflow
+
+### Phase 1: Parse input
+
+Extract from the user command:
+- `N` — number of workers (integer, 1–10)
+- `agent-type` — must be `claude`, `codex`, or `gemini`; reject anything else with an error
+- `task` — the task description
+
+### Phase 2: Decompose task
+
+Break the task into exactly N subtasks. Each subtask must be:
+- **Independent** — no conflicting writes between workers
+- **Scoped** — operates on a distinct subset of files or concerns
+- **Self-contained** — completable without inter-worker coordination
+
+Choose a `teamName` slug from the task (e.g., `auth-security-review`).
+
+### Phase 3: Activate team state & start the team
+
+**CRITICAL: Activate team state BEFORE calling MCP tools.** This prevents the session from
+stopping prematurely after MCP tool calls return. The persistent-mode Stop hook checks
+`team-state.json` to know whether to block the stop or allow it.
+
+```
+state_write(mode="team", current_phase="team-exec", active=true)
+```
+
+Then call `mcp__team__omc_run_team_start` — it spawns workers in the background and returns a
+`jobId` immediately. No Bash, no path resolution; the MCP server finds `runtime-cli.cjs`
+from its own install directory automatically.
+
+```
+mcp__team__omc_run_team_start({
+  "teamName": "{teamName}",
+  "agentTypes": ["{agentType}", "{agentType}", ...],
+  "tasks": [
+    {"subject": "Subtask 1 title", "description": "Full description..."},
+    {"subject": "Subtask 2 title", "description": "Full description..."}
+  ],
+  "cwd": "{cwd}"
+})
+```
+
+Returns: `{ "jobId": "omc-...", "pid": 12345, "message": "Team started in background..." }`
+
+### Phase 4: Wait for completion, then report
+
+Call `mcp__team__omc_run_team_wait` — a single blocking call that polls internally
+(500ms → 2000ms exponential backoff) and returns only when the job reaches a terminal
+state. No repeated polling needed; one call instead of N.
+
+```
+mcp__team__omc_run_team_wait({
+  "job_id": "{jobId}",
+  "timeout_ms": 60000
+})
+```
+
+> **Timeout guidance:** `timeout_ms` is optional; the default wait timeout is fine.
+> If a wait call times out, **workers are left running** — wait timeout does NOT kill
+> worker processes or panes. You have two options:
+> - Call `omc_run_team_wait` again with the same `job_id` to keep waiting (workers continue)
+> - Call `omc_run_team_cleanup` only when you explicitly want to cancel and stop panes
+>
+> Teams can silently stall due to stuck workers or tmux session issues. Use
+> `mcp__team__omc_run_team_status` to inspect live progress before deciding to cancel.
+
+Returns when done:
+```json
+{
+  "jobId": "omc-...",
+  "status": "completed|failed",
+  "elapsedSeconds": "95.3",
+  "result": {
+    "status": "completed",
+    "teamName": "...",
+    "taskResults": [
+      {"taskId": "1", "status": "completed", "summary": "Done: added 12 tests"},
+      {"taskId": "2", "status": "failed", "summary": "Worker exited early"}
+    ],
+    "duration": 95.1,
+    "workerCount": 2
+  }
+}
+```
+
+> **Why no deadlock?** `omc_run_team_wait` uses `async/await` with `setTimeout`,
+> which yields the Node.js event loop between polls. The `child.on('close', ...)`
+> callback that updates job status fires during those yields. The background
+> `runtime-cli.cjs` child process is completely independent — it never calls back
+> into this MCP server.
+>
+> If you need non-blocking checks (e.g. to do other work while waiting), use
+> `mcp__team__omc_run_team_status` instead.
+
+Report results to the user. For `failed` or wait-timeout errors, explain what happened and suggest next steps (reduce scope, check CLI installation, verify tmux is running).
+
+Update OMC state:
+```
+state_write(mode="team", current_phase="completed", active=false)
+```
+
+---
+
+## Error Reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `not inside tmux` | Shell not running inside a tmux session | Start tmux and rerun |
+| `codex: command not found` | Codex CLI not installed | `npm install -g @openai/codex` |
+| `gemini: command not found` | Gemini CLI not installed | `npm install -g @google/gemini-cli` |
+| wait timeout error | `omc_run_team_wait` hit `timeout_ms` before completion | Call `omc_run_team_wait` again to keep waiting, or call `omc_run_team_cleanup` to explicitly stop worker panes |
+| `status: failed` | All workers exited with work remaining | Check stderr for crash details |
+
+---
+
+## Relationship to `/team`
+
+| Aspect | `/team` | `/omc-teams` |
+|--------|---------|-------------|
+| Worker type | Claude Code agents (`Task(subagent_type=...)`) | claude / codex / gemini CLI processes |
+| Invocation | `TeamCreate` / `SendMessage` / `TeamDelete` | `mcp__team__omc_run_team_start` + `omc_run_team_wait` |
+| Coordination | Native Claude Code team messaging | tmux panes + inbox files + `done.json` sentinels |
+| Communication | Native Claude Code team messaging | File-based (inbox.md → done.json) |
+| Use when | You want Claude agents with full tool access | You want CLI autonomy (codex/gemini) at scale |

package/skills/pipeline/SKILL.md

@@ -43,7 +43,7 @@ Run multiple agents in parallel, merge their outputs.
 ```
 parallel(explore, document-specialist) -> architect -> executor
 ```
-<!-- NOTE: document-specialist is a legacy agent for external lookup. Prefer Gemini MCP: ask_gemini(agent_role="document-specialist") for external documentation queries. -->
+<!-- NOTE: document-specialist spawns a Claude Task agent for external documentation lookup. -->
 
 ## Built-in Pipeline Presets
 
@@ -105,7 +105,7 @@ parallel(explore, document-specialist) -> architect -> executor
 
 **Stages:**
 1. `parallel(document-specialist, explore)` - External docs + internal code
-   <!-- NOTE: document-specialist is a legacy agent for external lookup. Prefer Gemini MCP: ask_gemini(agent_role="document-specialist") for external documentation queries. -->
+   <!-- NOTE: document-specialist spawns a Claude Task agent for external documentation lookup. -->
 2. `architect` - Synthesize findings
 3. `writer` - Document recommendations
 
@@ -181,7 +181,7 @@ parallel(explore, document-specialist) -> architect -> executor
 ```
 /pipeline [explore, document-specialist] -> architect -> executor "implement OAuth"
 ```
-<!-- NOTE: document-specialist is a legacy agent for external lookup. Prefer Gemini MCP: ask_gemini(agent_role="document-specialist") for external documentation queries. -->
+<!-- NOTE: document-specialist spawns a Claude Task agent for external documentation lookup. -->
 
 ## Data Passing Protocol
 
@@ -342,7 +342,7 @@ When parallel agents complete:
 /pipeline research "implement GraphQL subscriptions"
 ```
 → Triggers: parallel(document-specialist, explore) → architect → writer
-<!-- NOTE: document-specialist is a legacy agent for external lookup. Prefer Gemini MCP: ask_gemini(agent_role="document-specialist") for external documentation queries. -->
+<!-- NOTE: document-specialist spawns a Claude Task agent for external documentation lookup. -->
 
 ## Cancellation
 

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>
@@ -32,6 +32,7 @@ Jumping into code without understanding requirements leads to rework, scope cree
 - 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 runs fully automated by default; add `--interactive` to enable user prompts at draft review and final approval steps
+- 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,7 +43,7 @@ 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; add `--interactive` for user prompts 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); add `--interactive` for user prompts at draft and approval steps |
 | Review | `--review`, "review this plan" | Critic evaluation of existing plan |
 
 ### Interview Mode (broad/vague requests)
@@ -62,14 +63,21 @@ Jumping into code without understanding requirements leads to rework, scope cree
 
 ### Consensus Mode (`--consensus` / "ralplan")
 
-1. **Planner** creates initial plan
-2. **User feedback** *(--interactive only)*: If running with `--interactive`, **MUST** use `AskUserQuestion` to present the draft plan with these options:
+**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 and the same `AskUserQuestion` gates.
+
+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 (prefer `ask_codex` with `architect` role). **Wait for this step to complete before proceeding to step 4.** Do NOT run steps 3 and 4 in parallel — parallel `ask_codex` calls can trigger a sibling cascade failure if one receives a 429 rate-limit error. If `ask_codex` fails with a rate-limit or 429 error, wait 5–10 seconds and retry once; if it fails again, fall back to spawning a `Task` with `subagent_type="oh-my-claudecode:architect"`.
-4. **Critic** evaluates against quality criteria (prefer `ask_codex` with `critic` role). Run only after step 3 is complete. Apply the same retry/fallback rule: on rate-limit error, retry once after a short delay; on second failure, fall back to `Task` with `subagent_type="oh-my-claudecode:critic"`.
+3. **Architect** reviews for architectural soundness using `Task(subagent_type="oh-my-claudecode: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 `Task(subagent_type="oh-my-claudecode: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, execute this closed loop:
    a. Collect all rejection feedback from Architect + Critic
    b. Pass feedback to Planner to produce a revised plan
@@ -77,10 +85,10 @@ Jumping into code without understanding requirements leads to rework, scope cree
    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. Specifically:
+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 `.omc/plans/` with the accepted improvements (add missing details, refine steps, strengthen acceptance criteria, etc.)
+   c. Update the plan file in `.omc/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
@@ -98,7 +106,7 @@ Jumping into code without understanding requirements leads to rework, scope cree
 ### Review Mode (`--review`)
 
 1. Read plan file from `.omc/plans/`
-2. Evaluate via Critic (prefer `ask_codex` with `critic` role)
+2. Evaluate via Critic using `Task(subagent_type="oh-my-claudecode:critic", ...)`
 3. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
 
 ### Plan Output Format
@@ -109,21 +117,22 @@ 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 `.omc/plans/`. Drafts go to `.omc/drafts/`.
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, run the 3-step discovery: (1) `ToolSearch("mcp")`, (2) select the full name from results (e.g., `mcp__x__ask_codex`), (3) fall back to the equivalent Claude agent only if step 1 returns empty. Never use `ToolSearch("ask_codex")` as the primary search -- it can return false negatives even when MCP tools are present.
 - Use `AskUserQuestion` for preference questions (scope, priority, timeline, risk tolerance) -- provides clickable UI
 - Use plain text for questions needing specific values (port numbers, names, follow-up clarifications)
 - Use `explore` agent (Haiku, 30s timeout) to gather codebase facts before asking the user
-- Use `ask_codex` with `agent_role: "planner"` for planning validation on large-scope plans
-- 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 Claude agents -- never block on external tools
-- **CRITICAL — Consensus mode `ask_codex` calls MUST be sequential, never parallel.** Claude Code cancels sibling tool calls when one fails ("Sibling tool call errored"), so running Architect and Critic `ask_codex` calls in the same tool-call batch will cause a cascade failure if either hits a 429 rate-limit. Always await the Architect call result before issuing the Critic call.
-- On `ask_codex` rate-limit (429) error: wait 5–10 s and retry once. If the second attempt also fails, fall back to the equivalent Claude agent (`Task` with `subagent_type="oh-my-claudecode:architect"` or `"oh-my-claudecode:critic"`).
+- Use `Task(subagent_type="oh-my-claudecode:planner", ...)` for planning validation on large-scope plans
+- Use `Task(subagent_type="oh-my-claudecode:analyst", ...)` for requirements analysis
+- Use `Task(subagent_type="oh-my-claudecode:critic", ...)` for plan review in consensus and review modes
+- **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect Task result before issuing the Critic Task.
+- 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`, skip both prompts and output the final plan.
 - In consensus mode with `--interactive`, on user approval **MUST** invoke `Skill("oh-my-claudecode:ralph")` for execution (step 9) -- never implement directly in the planning agent
 - When user selects "Clear context and implement" in step 7 (--interactive only): invoke `Skill("compact")` first to compress the accumulated planning context, then immediately invoke `Skill("oh-my-claudecode:ralph")` with the plan path -- the compact step is critical to free up context before the implementation loop begins
@@ -193,6 +202,9 @@ 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 `.omc/plans/`
+- [ ] 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`: plan output only, no auto-execution
 </Final_Checklist>
 

package/skills/ralph/SKILL.md

@@ -60,10 +60,9 @@ Complex tasks often fail silently: partial implementations get declared "done",
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, run the 3-step discovery: (1) `ToolSearch("mcp")`, (2) select the full name from results (e.g., `mcp__x__ask_codex`), (3) fall back to the equivalent Claude agent only if step 1 returns empty. Never use `ToolSearch("ask_codex")` as the primary search -- it can return false negatives even when MCP tools are present.
-- Use `ask_codex` with `agent_role: "architect"` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
-- Skip Codex consultation for simple feature additions, well-tested changes, or time-critical verification
-- If ToolSearch finds no MCP tools or Codex is unavailable, proceed with architect agent verification alone -- never block on external tools
+- Use `Task(subagent_type="oh-my-claudecode:architect", ...)` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
+- Skip architect consultation for simple feature additions, well-tested changes, or time-critical verification
+- Proceed with architect agent verification alone -- never block on unavailable tools
 - Use `state_write` / `state_read` for ralph mode state persistence between iterations
 </Tool_Usage>
 

package/skills/ralph-init/SKILL.md

@@ -22,7 +22,9 @@ Initialize a PRD (Product Requirements Document) for structured ralph-loop execu
    - Acceptance criteria (testable)
    - Technical constraints
    - Implementation phases
-3. **Link to Ralph** so that `/oh-my-claudecode:ralph` can use the PRD as its completion criteria
+3. **Output the PRD path** and instruct the user to run ralph separately
+
+**IMPORTANT: This is a planning-only skill. After creating the PRD, you MUST stop and wait for user input. Do NOT automatically start execution, invoke ralph, or begin implementing the PRD. Simply tell the user the PRD path and how to start ralph with it.**
 
 ## Output
 

package/skills/ralplan/SKILL.md

@@ -5,7 +5,7 @@ description: Alias for /plan --consensus
 
 # Ralplan (Consensus Planning Alias)
 
-Ralplan is a shorthand alias for `/oh-my-claudecode:plan --consensus`. It triggers iterative planning with Planner, Architect, and Critic agents until consensus is reached.
+Ralplan is a shorthand alias for `/oh-my-claudecode: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
 
@@ -16,6 +16,7 @@ Ralplan is a shorthand alias for `/oh-my-claudecode:plan --consensus`. It trigge
 ## Flags
 
 - `--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
 
@@ -32,15 +33,99 @@ This skill invokes the Plan skill in consensus mode:
 ```
 
 The consensus workflow:
-1. **Planner** creates initial plan
-2. **User feedback** *(--interactive only)*: If `--interactive` is set, use `AskUserQuestion` to present the draft plan before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
-3. **Architect** reviews for architectural soundness — **await completion before step 4**
-4. **Critic** evaluates against quality criteria — run only after step 3 completes
-5. If Critic rejects: iterate with feedback (max 5 iterations)
-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 / Clear context and implement / Request changes / Reject). Otherwise, output the final plan and stop.
+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 / Clear context and implement / 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 `Skill("oh-my-claudecode:ralph")` for sequential execution or `Skill("oh-my-claudecode:team")` for parallel team execution -- never implement directly
 
-> **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both `ask_codex` calls in the same parallel batch — if one hits a 429 rate-limit error, Claude Code will cancel the sibling call ("Sibling tool call errored"), causing the entire review to fail. On a rate-limit error, retry once after 5–10 s; on second failure fall back to the equivalent Claude agent.
+> **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent Task calls in the same parallel batch. Always await the Architect result before issuing the Critic Task.
 
 Follow the Plan skill's full documentation for consensus mode details.
+
+## Pre-Execution Gate
+
+### Why the Gate Exists
+
+Execution modes (ralph, autopilot, team, ultrawork, ultrapilot) 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 |