claudecode-omc 4.8.3 → 4.9.3

package/skills/multi-model-research/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: multi-model-research
+description: Run structured multi-model research (Claude, Gemini, Codex) and synthesize consensus, disagreements, and final recommendations.
+---
+
+# Multi-Model Research
+
+Use this skill for architecture choices, tradeoff analysis, or high-stakes technical decisions.
+
+## Use When
+
+- The user asks for multi-model research, technology selection, or architecture comparison
+- A decision has competing options and needs cross-model critique
+- You need confidence checks before implementation
+
+## Workflow
+
+1. Define the research question:
+   - Decision to make
+   - Constraints
+   - Evaluation criteria (performance, maintainability, cost, risk)
+2. Query providers with the same prompt template:
+   - `omc ask claude "<question>"`
+   - `omc ask gemini "<question>"`
+   - `omc ask codex "<question>"`
+3. Normalize each answer into:
+   - Proposed approach
+   - Key arguments
+   - Risks and unknowns
+4. Synthesize:
+   - Consensus points
+   - Contradictions
+   - Missing evidence
+   - Final recommendation with rationale
+5. Record artifacts and next validation steps.
+
+## Quality Rules
+
+- Keep prompts equivalent across models to reduce bias.
+- Cite concrete evidence, not authority.
+- Separate facts from inference.
+- If a provider is unavailable, continue and clearly state the reduced confidence.
+
+## Output Format
+
+- Research question and criteria
+- Per-model findings
+- Consensus and disagreements
+- Recommended decision
+- Validation checklist and follow-up experiments
+

package/skills/omc-doctor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: omc-doctor
 description: Diagnose and fix oh-my-claudecode installation issues
+level: 3
 ---
 
 # Doctor Skill
@@ -53,10 +54,10 @@ ls -la ~/.claude/CLAUDE.md 2>/dev/null
 grep -q "<!-- OMC:START -->" ~/.claude/CLAUDE.md 2>/dev/null && echo "Has OMC config" || echo "Missing OMC config in CLAUDE.md"
 
 # Check companion files for file-split pattern (e.g. CLAUDE-omc.md)
-ls ~/.claude/CLAUDE-*.md 2>/dev/null
-for f in ~/.claude/CLAUDE-*.md; do
-  [ -f "$f" ] && grep -q "<!-- OMC:START -->" "$f" 2>/dev/null && echo "Has OMC config in companion: $f"
-done
+find "$HOME/.claude" -maxdepth 1 -type f -name 'CLAUDE-*.md' -print 2>/dev/null
+while IFS= read -r f; do
+  grep -q "<!-- OMC:START -->" "$f" 2>/dev/null && echo "Has OMC config in companion: $f"
+done < <(find "$HOME/.claude" -maxdepth 1 -type f -name 'CLAUDE-*.md' -print 2>/dev/null)
 
 # Check if CLAUDE.md references a companion file
 grep -o "CLAUDE-[^ )]*\.md" ~/.claude/CLAUDE.md 2>/dev/null
@@ -104,7 +105,7 @@ ls -la ~/.claude/skills/ 2>/dev/null
 `architect.md`, `document-specialist.md`, `explore.md`, `executor.md`, `debugger.md`, `planner.md`, `analyst.md`, `critic.md`, `verifier.md`, `test-engineer.md`, `designer.md`, `writer.md`, `qa-tester.md`, `scientist.md`, `security-reviewer.md`, `code-reviewer.md`, `git-master.md`, `code-simplifier.md`
 
 **Known plugin skill names** (check skills/ for these):
-`ai-slop-cleaner`, `ask`, `autopilot`, `cancel`, `ccg`, `configure-notifications`, `deep-interview`, `deepinit`, `external-context`, `hud`, `learner`, `mcp-setup`, `omc-doctor`, `omc-setup`, `omc-teams`, `plan`, `project-session-manager`, `ralph`, `ralplan`, `release`, `sciomc`, `setup`, `skill`, `team`, `ultraqa`, `ultrawork`, `writer-memory`
+`ai-slop-cleaner`, `ask`, `autopilot`, `cancel`, `ccg`, `configure-notifications`, `deep-interview`, `deepinit`, `external-context`, `hud`, `learner`, `mcp-setup`, `omc-doctor`, `omc-setup`, `omc-teams`, `plan`, `project-session-manager`, `ralph`, `ralplan`, `release`, `sciomc`, `setup`, `skill`, `team`, `ultraqa`, `ultrawork`, `visual-verdict`, `writer-memory`
 
 **Known plugin command names** (check commands/ for these):
 `ultrawork.md`, `deepsearch.md`

package/skills/omc-reference/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: omc-reference
+description: OMC agent catalog, available tools, team pipeline routing, commit protocol, and skills registry. Auto-loads when delegating to agents, using OMC tools, orchestrating teams, making commits, or invoking skills.
+user-invocable: false
+---
+
+# OMC Reference
+
+Use this built-in reference when you need detailed OMC catalog information that does not need to live in every `CLAUDE.md` session.
+
+## Agent Catalog
+
+Prefix: `oh-my-claudecode:`. See `agents/*.md` for full prompts.
+
+- `explore` (haiku) — fast codebase search and mapping
+- `analyst` (opus) — requirements clarity and hidden constraints
+- `planner` (opus) — sequencing and execution plans
+- `architect` (opus) — system design, boundaries, and long-horizon tradeoffs
+- `debugger` (sonnet) — root-cause analysis and failure diagnosis
+- `executor` (sonnet) — implementation and refactoring
+- `verifier` (sonnet) — completion evidence and validation
+- `tracer` (sonnet) — trace gathering and evidence capture
+- `security-reviewer` (sonnet) — trust boundaries and vulnerabilities
+- `code-reviewer` (opus) — comprehensive code review
+- `test-engineer` (sonnet) — testing strategy and regression coverage
+- `designer` (sonnet) — UX and interaction design
+- `writer` (haiku) — documentation and concise content work
+- `qa-tester` (sonnet) — runtime/manual validation
+- `scientist` (sonnet) — data analysis and statistical reasoning
+- `document-specialist` (sonnet) — SDK/API/framework documentation lookup
+- `git-master` (sonnet) — commit strategy and history hygiene
+- `code-simplifier` (opus) — behavior-preserving simplification
+- `critic` (opus) — plan/design challenge and review
+
+## Model Routing
+
+- `haiku` — quick lookups, lightweight inspection, narrow docs work
+- `sonnet` — standard implementation, debugging, and review
+- `opus` — architecture, deep analysis, consensus planning, and high-risk review
+
+## Tools Reference
+
+### External AI / orchestration
+- `/team N:executor "task"`
+- `omc team N:codex|gemini "..."`
+- `omc ask <claude|codex|gemini>`
+- `/ccg`
+
+### OMC state
+- `state_read`, `state_write`, `state_clear`, `state_list_active`, `state_get_status`
+
+### Team runtime
+- `TeamCreate`, `TeamDelete`, `SendMessage`, `TaskCreate`, `TaskList`, `TaskGet`, `TaskUpdate`
+
+### Notepad
+- `notepad_read`, `notepad_write_priority`, `notepad_write_working`, `notepad_write_manual`
+
+### Project memory
+- `project_memory_read`, `project_memory_write`, `project_memory_add_note`, `project_memory_add_directive`
+
+### Code intelligence
+- LSP: `lsp_hover`, `lsp_goto_definition`, `lsp_find_references`, `lsp_diagnostics`, and related helpers
+- AST: `ast_grep_search`, `ast_grep_replace`
+- Utility: `python_repl`
+
+## Skills Registry
+
+Invoke built-in workflows via `/oh-my-claudecode:<name>`.
+
+### Workflow skills
+- `autopilot` — full autonomous execution from idea to working code
+- `ralph` — persistence loop until completion with verification
+- `ultrawork` — high-throughput parallel execution
+- `visual-verdict` — structured visual QA verdicts
+- `team` — coordinated team orchestration
+- `ccg` — Codex + Gemini + Claude synthesis lane
+- `ultraqa` — QA cycle: test, verify, fix, repeat
+- `omc-plan` — planning workflow and `/plan`-safe alias
+- `ralplan` — consensus planning workflow
+- `sciomc` — science/research workflow
+- `external-context` — external docs/research workflow
+- `deepinit` — hierarchical AGENTS.md generation
+- `deep-interview` — Socratic ambiguity-gated requirements workflow
+- `ai-slop-cleaner` — regression-safe cleanup workflow
+
+### Utility skills
+- `ask`, `cancel`, `note`, `learner`, `omc-setup`, `mcp-setup`, `hud`, `omc-doctor`, `trace`, `release`, `project-session-manager`, `skill`, `writer-memory`, `configure-notifications`
+
+### Keyword triggers kept compact in CLAUDE.md
+- `"autopilot"→autopilot`
+- `"ralph"→ralph`
+- `"ulw"→ultrawork`
+- `"ccg"→ccg`
+- `"ralplan"→ralplan`
+- `"deep interview"→deep-interview`
+- `"deslop" / "anti-slop"→ai-slop-cleaner`
+- `"deep-analyze"→analysis mode`
+- `"tdd"→TDD mode`
+- `"deepsearch"→codebase search`
+- `"ultrathink"→deep reasoning`
+- `"cancelomc"→cancel`
+- Team orchestration is explicit via `/team`.
+
+## Team Pipeline
+
+Stages: `team-plan` → `team-prd` → `team-exec` → `team-verify` → `team-fix` (loop).
+
+- Use `team-fix` for bounded remediation loops.
+- `team ralph` links the team pipeline with Ralph-style sequential verification.
+- Prefer team mode when independent parallel lanes justify the coordination overhead.
+
+## Commit Protocol
+
+Use git trailers to preserve decision context in every commit message.
+
+### Format
+- Intent line first: why the change was made
+- Optional body with context and rationale
+- Structured trailers when applicable
+
+### Common trailers
+- `Constraint:` active constraint shaping the decision
+- `Rejected:` alternative considered | reason for rejection
+- `Directive:` forward-looking warning or instruction
+- `Confidence:` `high` | `medium` | `low`
+- `Scope-risk:` `narrow` | `moderate` | `broad`
+- `Not-tested:` known verification gap
+
+### Example
+```text
+feat(docs): reduce always-loaded OMC instruction footprint
+
+Move reference-only orchestration content into a native Claude skill so
+session-start guidance stays small while detailed OMC reference remains available.
+
+Constraint: Preserve CLAUDE.md marker-based installation flow
+Rejected: Sync all built-in skills in legacy install | broader behavior change than issue requires
+Confidence: high
+Scope-risk: narrow
+Not-tested: End-to-end plugin marketplace install in a fresh Claude profile
+```

package/skills/omc-setup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: omc-setup
-description: Setup and configure oh-my-claudecode (the ONLY command you need to learn)
+description: Install or refresh oh-my-claudecode for plugin, npm, and local-dev setups from the canonical setup flow
+level: 2
 ---
 
 # OMC Setup
@@ -11,6 +12,14 @@ This is the **only command you need to learn**. After running this, everything e
 
 Note: All `~/.claude/...` paths in this guide respect `CLAUDE_CONFIG_DIR` when that environment variable is set.
 
+## Best-Fit Use
+
+Choose this setup flow when the user wants to **install, refresh, or repair OMC itself**.
+
+- Marketplace/plugin install users should land here after `/plugin install oh-my-claudecode`
+- npm users should land here after `npm i -g oh-my-claude-sisyphus@latest`
+- local-dev and worktree users should land here after updating the checked-out repo and rerunning setup
+
 ## Flag Parsing
 
 Check for flags in the user's invocation:
@@ -153,7 +162,7 @@ Execute phases sequentially. For each phase, read the corresponding file and fol
 
 1. **Phase 1 - Install CLAUDE.md**: Read `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/01-install-claude-md.md` and follow its instructions.
 
-2. **Phase 2 - Environment Configuration**: Read `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/02-configure.md` and follow its instructions.
+2. **Phase 2 - Environment Configuration**: Read `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/02-configure.md` and follow its instructions. Phase 2 must delegate HUD/statusLine setup to the `hud` skill; do not generate or patch `statusLine` paths inline here.
 
 3. **Phase 3 - Integration Setup**: Read `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/03-integrations.md` and follow its instructions.
 

package/skills/omc-setup/phases/01-install-claude-md.md

@@ -17,7 +17,7 @@ Set `CONFIG_TARGET` to `local` or `global` based on user's choice.
 
 ## Download and Install CLAUDE.md
 
-**MANDATORY**: Always run this command. Do NOT skip. Do NOT use the Write tool. Use bash curl exclusively.
+**MANDATORY**: Always run this command. Do NOT skip. Do NOT use the Write tool. Let the setup script choose the safest canonical source (bundled `docs/CLAUDE.md` first, GitHub fallback only if needed).
 
 ```bash
 bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-claude-md.sh" <CONFIG_TARGET>
@@ -25,6 +25,15 @@ bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-claude-md.sh" <CONFIG_TARGET>
 
 Replace `<CONFIG_TARGET>` with `local` or `global`.
 
+The script must install the canonical `docs/CLAUDE.md` content and preserve the required
+`<!-- OMC:START -->` / `<!-- OMC:END -->` markers. Do **not** hand-write, summarize, or
+partially reconstruct CLAUDE.md.
+
+After running the script, verify the target file contains both markers. If marker validation
+fails, stop and report the failure instead of writing CLAUDE.md manually.
+
+For `local` installs inside a git repository, the script also seeds `.git/info/exclude` with an OMC block that ignores local `.omc/*` artifacts by default while preserving `.omc/skills/` for version-controlled project skills.
+
 **FALLBACK** if curl fails:
 Tell user to manually download from:
 https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md
@@ -39,6 +48,7 @@ If `CONFIG_TARGET` is `local`:
 ```
 OMC Project Configuration Complete
 - CLAUDE.md: Updated with latest configuration from GitHub at ./.claude/CLAUDE.md
+- Git excludes: Added local `.omc/*` ignore rules to `.git/info/exclude` (keeps `.omc/skills/` trackable)
 - Backup: Previous CLAUDE.md backed up (if existed)
 - Scope: PROJECT - applies only to this project
 - Hooks: Provided by plugin (no manual installation needed)

package/skills/omc-setup/phases/02-configure.md

@@ -6,10 +6,12 @@
 
 **Note**: If resuming and `lastCompletedStep >= 3`, skip to Step 2.2.
 
-The HUD shows real-time status in Claude Code's status bar. Invoke the hud skill to set up and configure:
+The HUD shows real-time status in Claude Code's status bar. Delegate all HUD/statusLine setup to the `hud` skill:
 
 Use the Skill tool to invoke: `hud` with args: `setup`
 
+Do not generate, normalize, or patch `statusLine` paths inline in this phase. This is especially important on Windows, where backslash path handling must stay inside the `hud` skill.
+
 This will:
 1. Install the HUD wrapper script to `~/.claude/hud/omc-hud.mjs`
 2. Configure `statusLine` in `~/.claude/settings.json`

package/skills/omc-teams/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: omc-teams
-description: Spawn claude, codex, or gemini CLI workers in tmux panes for parallel task execution
+description: CLI-team runtime for claude, codex, or gemini workers in tmux panes when you need process-based parallel execution
 aliases: []
+level: 4
 ---
 
 # OMC Teams Skill
@@ -35,7 +36,7 @@ Spawn N CLI worker processes in tmux panes to execute tasks in parallel. Support
 ## Requirements
 
 - **tmux binary** must be installed and discoverable (`command -v tmux`)
-- **Active tmux session** required to launch worker panes (`$TMUX` set, or start/attach tmux first)
+- **Classic tmux session optional** for in-place pane splitting (`$TMUX` set). Inside cmux or a plain terminal, `omc team` falls back to a detached tmux session instead of splitting the current surface.
 - **claude** CLI: `npm install -g @anthropic-ai/claude-code`
 - **codex** CLI: `npm install -g @openai/codex`
 - **gemini** CLI: `npm install -g @google/gemini-cli`
@@ -51,8 +52,10 @@ command -v tmux >/dev/null 2>&1
 ```
 
 - If this fails, report that **tmux is not installed** and stop.
-- If `tmux` exists but `$TMUX` is empty, report that the user is **not currently inside an active tmux session**. Do **not** say tmux is missing; tell them to start or attach tmux, then rerun.
-- If you need to confirm the active session, use:
+- If `$TMUX` is set, `omc team` can reuse the current tmux window/panes directly.
+- If `$TMUX` is empty but `CMUX_SURFACE_ID` is set, report that the user is running inside **cmux**. Do **not** say tmux is missing or that they are "not inside tmux"; `omc team` will launch a **detached tmux session** for workers instead of splitting the cmux surface.
+- If neither `$TMUX` nor `CMUX_SURFACE_ID` is set, report that the user is in a **plain terminal**. `omc team` can still launch a **detached tmux session**, but if they specifically want in-place pane/window topology they should start from a classic tmux session first.
+- If you need to confirm the active tmux session, use:
 
 ```bash
 tmux display-message -p '#S'
@@ -142,7 +145,8 @@ If encountered, switch to `omc team ...` CLI commands.
 
 | Error                        | Cause                               | Fix                                                                                 |
 | ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
-| `not inside tmux`            | Shell not running inside tmux       | Start tmux and rerun                                                                |
+| `not inside tmux`            | Requested in-place pane topology from a non-tmux surface | Start tmux and rerun, or let `omc team` use its detached-session fallback           |
+| `cmux surface detected`      | Running inside cmux without `$TMUX` | Use the normal `omc team ...` flow; OMC will launch a detached tmux session         |
 | `Unsupported agent type`     | Requested agent is not claude/codex/gemini | Use `claude`, `codex`, or `gemini`; for native Claude Code agents use `/oh-my-claudecode:team` |
 | `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`                                                 |

package/skills/plan/SKILL.md

@@ -4,6 +4,7 @@ description: Strategic planning with optional interview workflow
 pipeline: [deep-interview, omc-plan, autopilot]
 next-skill: autopilot
 handoff: .omc/plans/ralplan-*.md
+level: 4
 ---
 
 <Purpose>
@@ -68,6 +69,19 @@ Jumping into code without understanding requirements leads to rework, scope cree
 
 **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.
 
+**Provider overrides (supported when the provider CLI is installed):**
+- `--architect codex` — replace the Claude Architect pass with `omc ask codex --agent-prompt architect "..."` for implementation-heavy architecture review
+- `--critic codex` — replace the Claude Critic pass with `omc ask codex --agent-prompt critic "..."` for an external review pass before execution
+- If the requested provider is unavailable, briefly note that and continue with the default Claude Architect/Critic step for that stage
+
+**State lifecycle**: The persistent-mode stop hook uses `ralplan-state.json` to enforce continuation during the consensus loop. The skill **MUST** manage this state:
+- **On entry**: Call `state_write(mode="ralplan", active=true, session_id=<current_session_id>)` before step 1
+- **On handoff to execution** (approval → ralph/team): Call `state_write(mode="ralplan", active=false, session_id=<current_session_id>)`. Do NOT use `state_clear` here — `state_clear` writes a 30-second cancel signal that disables stop-hook enforcement for ALL modes, leaving the newly launched execution mode unprotected.
+- **On true terminal exit** (rejection, non-interactive plan output, error/abort): Call `state_clear(mode="ralplan", session_id=<current_session_id>)` — no execution mode follows, so the cancel signal window is harmless.
+- Do NOT clear during intermediate steps like Critic approval or max-iteration presentation, as the user may still select "Request changes".
+
+Without cleanup, the stop hook blocks all subsequent stops with `[RALPLAN - CONSENSUS PLANNING]` reinforcement messages even after the consensus workflow has finished. Always pass `session_id` to avoid clearing other concurrent sessions' state.
+
 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)
@@ -99,9 +113,9 @@ Jumping into code without understanding requirements leads to rework, scope cree
    - **Clear context and implement** — compact the context window first (recommended when context is large after planning), then start fresh implementation via ralph with the saved plan file
    - **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):
+   If NOT running with `--interactive`, output the final approved plan, call `state_clear(mode="ralplan", session_id=<current_session_id>)`, and stop. Do NOT auto-execute.
+8. *(--interactive only)* User chooses via the structured `AskUserQuestion` UI (never ask for approval in plain text). If user selects **Reject**, call `state_clear(mode="ralplan", session_id=<current_session_id>)` and stop.
+9. On user approval (--interactive only): Call `state_write(mode="ralplan", active=false, session_id=<current_session_id>)` **before** invoking the execution skill (ralph/team), so the stop hook does not interfere with the execution mode's own enforcement. Do NOT use `state_clear` here — it writes a cancel signal that disables enforcement for the newly launched mode.
    - **Approve and implement via team**: **MUST** invoke `Skill("oh-my-claudecode:team")` with the approved plan path from `.omc/plans/` as context. Do NOT implement directly. The team skill coordinates parallel agents across the staged pipeline for faster execution on large tasks. This is the recommended default execution path.
    - **Approve and execute via ralph**: **MUST** invoke `Skill("oh-my-claudecode:ralph")` with the approved plan path from `.omc/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.
    - **Clear context and implement**: First invoke `Skill("compact")` to compress the context window (reduces token usage accumulated during planning), then invoke `Skill("oh-my-claudecode:ralph")` with the approved plan path from `.omc/plans/`. This path is recommended when the context window is 50%+ full after the planning session.
@@ -138,7 +152,8 @@ Plans are saved to `.omc/plans/`. Drafts go to `.omc/drafts/`.
 - 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
+- When user selects "Clear context and implement" in step 7 (--interactive only): call `state_write(mode="ralplan", active=false, session_id=<current_session_id>)` first, then invoke `Skill("compact")` 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
+- **CRITICAL — Consensus mode state lifecycle**: Always deactivate ralplan state before stopping or handing off to execution. Use `state_write(active=false)` for handoff paths (approval → ralph/team) and `state_clear` for true terminal exits (rejection, error). Never use `state_clear` before launching an execution mode — its cancel signal disables stop-hook enforcement for 30 seconds.
 </Tool_Usage>
 
 <Examples>
@@ -193,9 +208,9 @@ 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 without `--interactive` outputs the final plan and stops; with `--interactive`, requires explicit user approval before any implementation begins
-- If the user says "just do it" or "skip planning", **MUST** invoke `Skill("oh-my-claudecode:ralph")` to transition to execution mode. Do NOT implement directly in the planning agent.
+- In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version. Do NOT clear ralplan state here — the user may still select "Request changes" in the subsequent step. State is cleared only on the user's final choice (approval/rejection) or when outputting the plan in non-interactive mode.
+- Consensus mode without `--interactive` outputs the final plan and stops; with `--interactive`, requires explicit user approval before any implementation begins. **Always** call `state_clear(mode="ralplan", session_id=<current_session_id>)` before stopping.
+- If the user says "just do it" or "skip planning", call `state_write(mode="ralplan", active=false, session_id=<current_session_id>)` then **MUST** invoke `Skill("oh-my-claudecode: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>
 
@@ -209,6 +224,7 @@ Why bad: Decision fatigue. Present one option with trade-offs, get reaction, the
 - [ ] 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
+- [ ] In consensus mode: ralplan state deactivated on every exit path — `state_write(active=false)` for handoff to execution, `state_clear` for terminal exits (rejection, error, non-interactive stop)
 </Final_Checklist>
 
 <Advanced>

package/skills/planning-with-files/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: planning-with-files
+description: File-based planning workflow for complex tasks. Create and maintain task_plan.md, findings.md, and progress.md as persistent working memory.
+---
+
+# Planning With Files
+
+Use this skill when the task is complex, long-running, or likely to exceed context continuity.
+
+## Use When
+
+- Multi-step tasks (typically 3+ phases)
+- Investigations requiring many reads/searches
+- Work that spans planning, implementation, and verification
+
+## Core Pattern
+
+Context window is volatile; files are durable.
+Write key decisions and discoveries to disk early.
+
+## Standard Files
+
+- `task_plan.md`: goals, phases, decisions, errors
+- `findings.md`: research notes, references, technical findings
+- `progress.md`: chronological execution and test log
+
+## Workflow
+
+1. Initialize files in project root:
+   - `bash skills/planning-with-files/scripts/init-session.sh`
+2. Before major decisions, re-read `task_plan.md`.
+3. After every 2 search/view operations, update `findings.md`.
+4. After each phase, update status and `progress.md`.
+5. Before handoff, validate completeness:
+   - `bash skills/planning-with-files/scripts/check-complete.sh`
+
+## Rules
+
+- Do not start complex implementation without `task_plan.md`.
+- Record all meaningful errors and attempted fixes.
+- Do not repeat identical failed actions.
+- Keep plans minimal and reversible.
+
+## Templates
+
+- `skills/planning-with-files/templates/task_plan.md`
+- `skills/planning-with-files/templates/findings.md`
+- `skills/planning-with-files/templates/progress.md`
+

package/skills/planning-with-files/examples.md

@@ -0,0 +1,17 @@
+# Planning With Files Examples
+
+## Example: feature delivery
+
+1. Run `bash skills/planning-with-files/scripts/init-session.sh`
+2. Set goal and phases in `task_plan.md`
+3. Log findings during discovery in `findings.md`
+4. Implement phase by phase and append test results to `progress.md`
+5. Run `bash skills/planning-with-files/scripts/check-complete.sh`
+
+## Example: bug investigation
+
+1. Capture repro steps and hypotheses in `task_plan.md`
+2. Store command outputs and traces in `findings.md`
+3. Log each failed attempt and changed hypothesis in `progress.md`
+4. Only implement once root cause is validated
+

package/skills/planning-with-files/reference.md

@@ -0,0 +1,21 @@
+# Planning With Files Reference
+
+## Why this exists
+
+Long tasks lose context. Persisting decisions and findings in project files
+keeps implementation aligned with goals and reduces repeated failures.
+
+## Core principles
+
+1. Plan before implementing.
+2. Re-read the plan before major decisions.
+3. Externalize discoveries to `findings.md`.
+4. Track execution and verification in `progress.md`.
+5. Keep failed attempts visible to avoid repeating them.
+
+## Recommended cadence
+
+- Every phase transition: update `task_plan.md`
+- Every 2 search/view actions: update `findings.md`
+- Every test run or fix cycle: update `progress.md`
+

package/skills/planning-with-files/scripts/check-complete.ps1

@@ -0,0 +1,28 @@
+param(
+    [string]$PlanFile = "task_plan.md"
+)
+
+if (-not (Test-Path $PlanFile)) {
+    Write-Host "ERROR: $PlanFile not found"
+    exit 1
+}
+
+$content = Get-Content $PlanFile -Raw
+$total = ([regex]::Matches($content, "### Phase")).Count
+$complete = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
+$inProgress = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
+$pending = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
+
+Write-Host "Total phases: $total"
+Write-Host "Complete: $complete"
+Write-Host "In progress: $inProgress"
+Write-Host "Pending: $pending"
+
+if ($total -gt 0 -and $complete -eq $total) {
+    Write-Host "ALL PHASES COMPLETE"
+    exit 0
+}
+
+Write-Host "TASK NOT COMPLETE"
+exit 1
+

package/skills/planning-with-files/scripts/check-complete.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Verify all phases in task_plan.md are complete.
+# Usage: bash skills/planning-with-files/scripts/check-complete.sh [task_plan_path]
+
+set -euo pipefail
+
+PLAN_FILE="${1:-task_plan.md}"
+
+if [[ ! -f "${PLAN_FILE}" ]]; then
+  echo "ERROR: ${PLAN_FILE} not found"
+  exit 1
+fi
+
+TOTAL="$(grep -c "### Phase" "${PLAN_FILE}" || true)"
+COMPLETE="$(grep -cF "**Status:** complete" "${PLAN_FILE}" || true)"
+IN_PROGRESS="$(grep -cF "**Status:** in_progress" "${PLAN_FILE}" || true)"
+PENDING="$(grep -cF "**Status:** pending" "${PLAN_FILE}" || true)"
+
+echo "Total phases: ${TOTAL}"
+echo "Complete: ${COMPLETE}"
+echo "In progress: ${IN_PROGRESS}"
+echo "Pending: ${PENDING}"
+
+if [[ "${TOTAL}" -gt 0 && "${COMPLETE}" -eq "${TOTAL}" ]]; then
+  echo "ALL PHASES COMPLETE"
+  exit 0
+fi
+
+echo "TASK NOT COMPLETE"
+exit 1
+

package/skills/planning-with-files/scripts/init-session.ps1

@@ -0,0 +1,31 @@
+param(
+    [string]$ProjectName = "project"
+)
+
+$date = Get-Date -Format "yyyy-MM-dd"
+Write-Host "Initializing planning files for: $ProjectName"
+
+if (-not (Test-Path "task_plan.md")) {
+    Copy-Item "skills/planning-with-files/templates/task_plan.md" "task_plan.md"
+    Write-Host "Created task_plan.md"
+} else {
+    Write-Host "task_plan.md already exists, skipping"
+}
+
+if (-not (Test-Path "findings.md")) {
+    Copy-Item "skills/planning-with-files/templates/findings.md" "findings.md"
+    Write-Host "Created findings.md"
+} else {
+    Write-Host "findings.md already exists, skipping"
+}
+
+if (-not (Test-Path "progress.md")) {
+    Copy-Item "skills/planning-with-files/templates/progress.md" "progress.md"
+    (Get-Content "progress.md") -replace "\[DATE\]", $date | Set-Content "progress.md"
+    Write-Host "Created progress.md"
+} else {
+    Write-Host "progress.md already exists, skipping"
+}
+
+Write-Host "Planning files initialized."
+

package/skills/planning-with-files/scripts/init-session.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Initialize planning files in the current project root.
+# Usage: bash skills/planning-with-files/scripts/init-session.sh [project-name]
+
+set -euo pipefail
+
+PROJECT_NAME="${1:-project}"
+DATE="$(date +%Y-%m-%d)"
+
+echo "Initializing planning files for: ${PROJECT_NAME}"
+
+if [[ ! -f task_plan.md ]]; then
+  cp skills/planning-with-files/templates/task_plan.md task_plan.md
+  echo "Created task_plan.md"
+else
+  echo "task_plan.md already exists, skipping"
+fi
+
+if [[ ! -f findings.md ]]; then
+  cp skills/planning-with-files/templates/findings.md findings.md
+  echo "Created findings.md"
+else
+  echo "findings.md already exists, skipping"
+fi
+
+if [[ ! -f progress.md ]]; then
+  cp skills/planning-with-files/templates/progress.md progress.md
+  # Replace session token with current date for convenience.
+  sed -i.bak "s/\\[DATE\\]/${DATE}/g" progress.md && rm -f progress.md.bak
+  echo "Created progress.md"
+else
+  echo "progress.md already exists, skipping"
+fi
+
+echo "Planning files initialized."
+