claudecode-omc 4.8.3 → 4.9.3

package/skills/ai-slop-cleaner/SKILL.md

@@ -1,130 +1,133 @@
 ---
 name: ai-slop-cleaner
-description: Clean AI-generated code slop with a test-first, deletion-first deslop workflow and optional reviewer-only mode
+description: Clean AI-generated code slop with a regression-safe, deletion-first workflow and optional reviewer-only mode
+level: 3
 ---
 
-<Purpose>
-Use this skill to systematically clean AI-generated code slop without changing intended behavior. It focuses on simplifying existing code by deleting dead code, collapsing duplicates, removing needless abstractions, tightening boundaries, and reinforcing tests before and after cleanup.
-</Purpose>
-
-<Use_When>
-- The user explicitly says "deslop", "anti-slop", or "AI slop"
-- The request is to clean up or refactor code that feels bloated, repetitive, or overly abstract
-- The user wants a reviewer-only anti-slop pass via `--review` after cleanup work is drafted
-- The user calls out duplicate code, dead code, wrapper layers, boundary violations, or weak regression coverage
-- The goal is simplification, deletion, and cleanup rather than adding new features
-</Use_When>
-
-<Do_Not_Use_When>
-- The task is primarily a new feature build -- use `autopilot` or direct implementation instead
-- The user wants a broad architecture redesign rather than an incremental cleanup pass
-- The request is a generic refactor with no cleanup/simplification intent
-- Behavior is unclear and there are no tests or concrete anchors -- clarify scope first
-</Do_Not_Use_When>
-
-<Why_This_Exists>
-AI-generated code often works while still adding avoidable complexity: duplicate helpers, dead branches, wrapper layers, inconsistent naming, boundary leaks, and missing tests. This skill enforces a disciplined cleanup workflow so simplification happens deliberately instead of as vague "refactoring" that might expand scope.
-</Why_This_Exists>
-
-<Review_Mode>
-### Review Mode (`--review`)
-`--review` activates an explicit reviewer pass after the cleanup writer pass.
+# AI Slop Cleaner
+
+Use this skill to clean AI-generated code slop without drifting scope or changing intended behavior. In OMC, this is the bounded cleanup workflow for code that works but feels bloated, repetitive, weakly tested, or over-abstracted.
+
+## When to Use
+
+Use this skill when:
+- the user explicitly says `deslop`, `anti-slop`, or `AI slop`
+- the request is to clean up or refactor code that feels noisy, repetitive, or overly abstract
+- follow-up implementation left duplicate logic, dead code, wrapper layers, boundary leaks, or weak regression coverage
+- the user wants a reviewer-only anti-slop pass via `--review`
+- the goal is simplification and cleanup, not new feature delivery
+
+## When Not to Use
+
+Do not use this skill when:
+- the task is mainly a new feature build or product change
+- the user wants a broad redesign instead of an incremental cleanup pass
+- the request is a generic refactor with no simplification or anti-slop intent
+- behavior is too unclear to protect with tests or a concrete verification plan
+
+## OMC Execution Posture
+
+- Preserve behavior unless the user explicitly asks for behavior changes.
+- Lock behavior with focused regression tests first whenever practical.
+- Write a cleanup plan before editing code.
+- Prefer deletion over addition.
+- Reuse existing utilities and patterns before introducing new ones.
+- Avoid new dependencies unless the user explicitly requests them.
+- Keep diffs small, reversible, and smell-focused.
+- Stay concise and evidence-dense: inspect, edit, verify, and report.
+- Treat new user instructions as local scope updates without dropping earlier non-conflicting constraints.
+
+## Scoped File-List Usage
+
+This skill can be bounded to an explicit file list or changed-file scope when the caller already knows the safe cleanup surface.
+
+- Good fit: `oh-my-claudecode:ai-slop-cleaner skills/ralph/SKILL.md skills/ai-slop-cleaner/SKILL.md`
+- Good fit: a Ralph session handing off only the files changed in that session
+- Preserve the same regression-safe workflow even when the scope is a short file list
+- Do not silently expand a changed-file scope into broader cleanup work unless the user explicitly asks for it
+
+## Ralph Integration
+
+Ralph can invoke this skill as a bounded post-review cleanup pass.
+
+- In that workflow, the cleaner runs in standard mode (not `--review`)
+- The cleanup scope is the Ralph session's changed files only
+- After the cleanup pass, Ralph re-runs regression verification before completion
+- `--review` remains the reviewer-only follow-up mode, not the default Ralph integration path
+
+## Review Mode (`--review`)
+
+`--review` is a reviewer-only pass after cleanup work is drafted. It exists to preserve explicit writer/reviewer separation for anti-slop work.
 
 - **Writer pass**: make the cleanup changes with behavior locked by tests.
-- **Reviewer pass (`--review`)**: inspect the result for duplication, dead code, boundary violations, missing tests, and unnecessary abstractions.
-- The same pass must not both write and self-approve without a separate review step.
+- **Reviewer pass**: inspect the cleanup plan, changed files, and verification evidence.
+- The same pass must not both write and self-approve high-impact cleanup without a separate review step.
 
 In review mode:
-1. Do **not** make edits first.
-2. Inspect the cleanup plan, changed files, and regression coverage.
+1. Do **not** start by editing files.
+2. Review the cleanup plan, changed files, and regression coverage.
 3. Check specifically for:
    - leftover dead code or unused exports
-   - duplicate logic that was not consolidated
+   - duplicate logic that should have been consolidated
    - needless wrappers or abstractions that still blur boundaries
    - missing tests or weak verification for preserved behavior
-   - risky cleanup that changed behavior without explicit intent
+   - cleanup that appears to have changed behavior without intent
 4. Produce a reviewer verdict with required follow-ups.
-5. If changes are needed, hand them back to a separate writer/executor pass instead of fixing and approving in one pass.
-
-This mode exists to preserve writer/reviewer separation: the authoring pass changes code, the reviewer pass evaluates whether the cleanup actually reduced slop safely.
-</Review_Mode>
-
-<Execution_Policy>
-- Preserve behavior unless the user explicitly asks for behavior changes
-- Lock behavior with regression tests first whenever practical
-- Write a cleanup plan before editing code
-- Prefer deletion over addition
-- Reuse existing utilities and patterns before introducing anything new
-- Avoid new dependencies unless the user explicitly requests them
-- Keep diffs small, reversible, and smell-focused
-- Keep writer/reviewer separation: author in one pass, review in another
-- Verify with lint/typecheck/tests/static analysis relevant to the touched area
-</Execution_Policy>
-
-<Steps>
-1. **Lock behavior first**
-   - Identify the current behavior and add or strengthen regression tests before cleanup when practical
-   - If tests cannot be added first, record the verification plan explicitly before editing
-
-2. **Create a cleanup plan**
-   - Do not start coding immediately
-   - List the targeted smells and the files likely involved
-   - Sequence cleanup passes from lowest-risk deletion to higher-risk consolidation
-
-3. **Categorize the slop**
-   - Duplicate code
-   - Dead or unused code
-   - Needless abstraction / wrapper layers
-   - Boundary violations / misplaced responsibilities
-   - Missing or weak tests
-
-4. **Execute one smell-focused pass at a time**
-   - **Pass 1: Dead code deletion** -- remove unused branches, helpers, exports, and stale comments
-   - **Pass 2: Duplicate removal** -- consolidate repeated logic into existing patterns where possible
-   - **Pass 3: Naming and error-handling cleanup** -- tighten naming, trim noisy plumbing, normalize obvious inconsistencies
-   - **Pass 4: Test reinforcement** -- fill any regression gaps revealed by the cleanup
-
-5. **Run quality gates**
-   - Run the relevant lint, typecheck, unit/integration tests, and any static or security checks already present for the touched area
-   - If a gate fails, fix the underlying issue or revert the risky cleanup instead of forcing it through
-
-6. **Optional `--review` pass**
-   - Run a distinct reviewer pass that checks duplication, dead code, boundary violations, test coverage, and needless abstractions
-   - If the reviewer finds issues, address them in a follow-up cleanup pass before closing the task
-
-7. **Report outcome**
-   - Changed files
-   - Simplifications made
-   - Behavior locked by tests
-   - Remaining risks or slop intentionally left for a later pass
-</Steps>
-
-<Examples>
-<Good>
-User: "deslop this module -- too many wrappers, duplicate helpers, and dead code"
-Why good: Explicit anti-slop intent with concrete cleanup smells.
-</Good>
-
-<Good>
-User: "cleanup the AI slop in src/auth: remove dead code and tighten boundaries"
-Why good: Cleanup/refactor request is clearly about simplification, not feature work.
-</Good>
-
-<Bad>
-User: "refactor auth to support SSO"
-Why bad: This is feature work disguised as refactoring, not anti-slop cleanup.
-</Bad>
-
-<Bad>
-User: "clean up formatting"
-Why bad: Formatting-only work does not need the full anti-slop workflow.
-</Bad>
-</Examples>
-
-<Final_Report>
-Always end with:
-- **Changed files**
-- **Simplifications**
-- **Verification run**
-- **Remaining risks**
-</Final_Report>
+5. Hand needed changes back to a separate writer pass instead of fixing and approving in one step.
+
+## Workflow
+
+1. **Protect current behavior first**
+   - Identify what must stay the same.
+   - Add or run the narrowest regression tests needed before editing.
+   - If tests cannot come first, record the verification plan explicitly before touching code.
+
+2. **Write a cleanup plan before code**
+   - Bound the pass to the requested files or feature area.
+   - List the concrete smells to remove.
+   - Order the work from safest deletion to riskier consolidation.
+
+3. **Classify the slop before editing**
+   - **Duplication** — repeated logic, copy-paste branches, redundant helpers
+   - **Dead code** — unused code, unreachable branches, stale flags, debug leftovers
+   - **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers
+   - **Boundary violations** — hidden coupling, misplaced responsibilities, wrong-layer imports or side effects
+   - **Missing tests** — behavior not locked, weak regression coverage, edge-case gaps
+
+4. **Run one smell-focused pass at a time**
+   - **Pass 1: Dead code deletion**
+   - **Pass 2: Duplicate removal**
+   - **Pass 3: Naming and error-handling cleanup**
+   - **Pass 4: Test reinforcement**
+   - Re-run targeted verification after each pass.
+   - Do not bundle unrelated refactors into the same edit set.
+
+5. **Run the quality gates**
+   - Keep regression tests green.
+   - Run the relevant lint, typecheck, and unit/integration tests for the touched area.
+   - Run existing static or security checks when available.
+   - If a gate fails, fix the issue or back out the risky cleanup instead of forcing it through.
+
+6. **Close with an evidence-dense report**
+   Always report:
+   - **Changed files**
+   - **Simplifications**
+   - **Behavior lock / verification run**
+   - **Remaining risks**
+
+## Usage
+
+- `/oh-my-claudecode:ai-slop-cleaner <target>`
+- `/oh-my-claudecode:ai-slop-cleaner <target> --review`
+- `/oh-my-claudecode:ai-slop-cleaner <file-a> <file-b> <file-c>`
+- From Ralph: run the cleaner on the Ralph session's changed files only, then return to Ralph for post-cleanup regression verification
+
+## Good Fits
+
+**Good:** `deslop this module: too many wrappers, duplicate helpers, and dead code`
+
+**Good:** `cleanup the AI slop in src/auth and tighten boundaries without changing behavior`
+
+**Bad:** `refactor auth to support SSO`
+
+**Bad:** `clean up formatting`

package/skills/analyze/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: analyze
+description: Deep analysis and investigation for bugs, architecture issues, and risk hotspots. Use when the user asks to analyze, investigate, debug, or explain why something is failing.
+agent: debugger
+---
+
+# Analyze
+
+Use this skill for evidence-driven investigation before implementation.
+
+## Use When
+
+- The user asks to analyze, investigate, debug, root-cause, or explain failures
+- A fix has failed repeatedly and the team needs diagnosis first
+- You need architecture or dependency impact analysis before making changes
+
+## Workflow
+
+1. Scope the target precisely.
+2. Gather evidence:
+   - Read relevant files and tests
+   - Reproduce the issue when possible
+   - Capture exact errors and stack traces
+3. Build and test hypotheses:
+   - Compare broken path vs working path
+   - Trace control/data flow
+   - Validate assumptions with commands
+4. Conclude with ranked findings and concrete next actions.
+
+## Debug Protocol
+
+- Root-cause first. Do not jump to fixes.
+- After 3 failed hypotheses, expand scope and challenge the initial assumption.
+- Prefer user-observable behavior and reproducible evidence over speculation.
+
+## Output Format
+
+- Summary (2-3 sentences)
+- Key findings (ranked by impact)
+- Evidence (file references, command output, repro notes)
+- Recommended next actions (minimal-risk order)
+

package/skills/ask/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ask
-description: Ask Claude, Codex, or Gemini via local CLI and capture a reusable artifact
+description: Process-first advisor routing for Claude, Codex, or Gemini via `omc ask`, with artifact capture and no raw CLI assembly
 ---
 
 # Ask
@@ -23,12 +23,14 @@ Examples:
 
 ## Routing
 
-Preferred path:
+**Required execution path — always use this command:**
 
 ```bash
 omc ask {{ARGUMENTS}}
 ```
 
+**Do NOT manually construct raw provider CLI commands.** Never run `codex`, `claude`, or `gemini` directly to fulfill this skill. The `omc ask` wrapper handles correct flag selection, artifact persistence, and provider-version compatibility automatically. Manually assembling provider CLI flags will produce incorrect or outdated invocations.
+
 ## Requirements
 
 - The selected local CLI must be installed and authenticated.

package/skills/autopilot/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: autopilot
 description: Full autonomous execution from idea to working code
+level: 4
 ---
 
 <Purpose>

package/skills/bdd-generator/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: bdd-generator
+description: Generate and maintain BDD scenarios and step definitions using Gherkin plus playwright-bdd with a one-scenario-at-a-time TDD loop.
+---
+
+# BDD Generator
+
+Use this skill to translate business requirements into executable BDD scenarios.
+
+## Use When
+
+- The user asks for BDD, Gherkin, feature files, or scenario-based tests
+- You need business-readable acceptance tests tied to Playwright execution
+
+## Setup
+
+```bash
+pnpm add -D @playwright/test playwright-bdd
+npx playwright install
+```
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import { defineBddConfig } from 'playwright-bdd';
+
+const testDir = defineBddConfig({
+  features: 'features/**/*.feature',
+  steps: 'features/steps/**/*.ts',
+});
+
+export default defineConfig({ testDir });
+```
+
+## Workflow
+
+1. Write one feature and one scenario first (RED).
+2. Run `bddgen` to generate missing step stubs.
+3. Implement only the first failing step.
+4. Re-run tests; repeat until scenario passes.
+5. Add next scenario only after green.
+
+## Gherkin Best Practices
+
+- Use business language, not technical implementation details.
+- `Given` sets context, `When` describes action, `Then` verifies user-visible outcome.
+- Use `Background` for repeated context.
+- Use `Scenario Outline` for data variants.
+
+## Output
+
+- `*.feature` file with clear business behavior
+- Step definitions in `features/steps/*.ts`
+- Command list to run and debug tests
+
+## References
+
+- Cucumber Gherkin reference: https://cucumber.io/docs/gherkin/reference
+- playwright-bdd: https://github.com/vitalets/playwright-bdd
+

package/skills/cancel/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: cancel
 description: Cancel any active OMC mode (autopilot, ralph, ultrawork, ultraqa, swarm, ultrapilot, pipeline, team)
+level: 2
 ---
 
 # Cancel Skill
@@ -34,6 +35,67 @@ Automatically detects which mode is active and cancels it:
 
 Or say: "cancelomc", "stopomc"
 
+## Critical: Deferred Tool Handling
+
+The state management tools (`state_clear`, `state_read`, `state_write`, `state_list_active`,
+`state_get_status`) may be registered as **deferred tools** by Claude Code. Before calling
+any state tool, you MUST first load all of them via `ToolSearch`:
+
+```
+ToolSearch(query="select:mcp__plugin_oh-my-claudecode_t__state_clear,mcp__plugin_oh-my-claudecode_t__state_read,mcp__plugin_oh-my-claudecode_t__state_write,mcp__plugin_oh-my-claudecode_t__state_list_active,mcp__plugin_oh-my-claudecode_t__state_get_status")
+```
+
+If `state_clear` is unavailable or fails, use this **bash fallback** as an **emergency
+escape from the stop hook loop**. This is NOT a full replacement for the cancel flow —
+it only removes state files to unblock the session. Linked modes (e.g. ralph→ultrawork,
+autopilot→ralph/ultraqa) must be cleared separately by running the fallback once per mode.
+
+Replace `MODE` with the specific mode (e.g. `ralplan`, `ralph`, `ultrawork`, `ultraqa`).
+
+**WARNING:** Do NOT use this fallback for `autopilot` or `omc-teams`. Autopilot requires
+`state_write(active=false)` to preserve resume data. omc-teams requires tmux session
+cleanup that cannot be done via file deletion alone.
+
+```bash
+# Fallback: direct file removal when state_clear MCP tool is unavailable
+SESSION_ID="${CLAUDE_SESSION_ID:-${CLAUDECODE_SESSION_ID:-}}"
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || { d="$PWD"; while [ "$d" != "/" ] && [ ! -d "$d/.omc" ]; do d="$(dirname "$d")"; done; echo "$d"; })"
+
+# Cross-platform SHA-256 (macOS: shasum, Linux: sha256sum)
+sha256portable() { printf '%s' "$1" | (sha256sum 2>/dev/null || shasum -a 256) | cut -c1-16; }
+
+# Resolve state directory (supports OMC_STATE_DIR centralized storage)
+if [ -n "${OMC_STATE_DIR:-}" ]; then
+  # Mirror getProjectIdentifier() from worktree-paths.ts
+  SOURCE="$(git remote get-url origin 2>/dev/null || echo "$REPO_ROOT")"
+  HASH="$(sha256portable "$SOURCE")"
+  DIR_NAME="$(basename "$REPO_ROOT" | sed 's/[^a-zA-Z0-9_-]/_/g')"
+  OMC_STATE="$OMC_STATE_DIR/${DIR_NAME}-${HASH}/state"
+  [ ! -d "$OMC_STATE" ] && { echo "ERROR: State dir not found at $OMC_STATE" >&2; exit 1; }
+elif [ "$REPO_ROOT" != "/" ] && [ -d "$REPO_ROOT/.omc" ]; then
+  OMC_STATE="$REPO_ROOT/.omc/state"
+else
+  echo "ERROR: Could not locate .omc state directory" >&2
+  exit 1
+fi
+MODE="ralplan"  # <-- replace with the target mode
+
+# Clear session-scoped state for the specific mode
+if [ -n "$SESSION_ID" ] && [ -d "$OMC_STATE/sessions/$SESSION_ID" ]; then
+  rm -f "$OMC_STATE/sessions/$SESSION_ID/${MODE}-state.json"
+  rm -f "$OMC_STATE/sessions/$SESSION_ID/${MODE}-stop-breaker.json"
+  # Write cancel signal so stop hook detects cancellation in progress
+  NOW_ISO="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  printf '{"active":true,"requested_at":"%s","mode":"%s","source":"bash_fallback"}' \
+    "$NOW_ISO" "$MODE" > "$OMC_STATE/sessions/$SESSION_ID/cancel-signal-state.json"
+fi
+
+# Clear legacy state only if no session ID (avoid clearing another session's state)
+if [ -z "$SESSION_ID" ]; then
+  rm -f "$OMC_STATE/${MODE}-state.json"
+fi
+```
+
 ## Auto-Detection
 
 `/oh-my-claudecode:cancel` follows the session-aware state contract:

package/skills/ccg/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ccg
 description: Claude-Codex-Gemini tri-model orchestration via /ask codex + /ask gemini, then Claude synthesizes results
+level: 5
 ---
 
 # CCG - Claude-Codex-Gemini Tri-Model Orchestration
@@ -30,11 +31,9 @@ Use this when you want parallel external perspectives without launching tmux tea
    - Codex prompt (analysis/architecture/backend)
    - Gemini prompt (UX/design/docs/alternatives)
 
-2. Claude runs:
-   - /oh-my-claudecode:ask codex "<codex prompt>"
-   - /oh-my-claudecode:ask gemini "<gemini prompt>"
-
-   (equivalent CLI path: `omc ask codex ...` + `omc ask gemini ...`)
+2. Claude runs via CLI (skill nesting not supported):
+   - `omc ask codex "<codex prompt>"`
+   - `omc ask gemini "<gemini prompt>"`
 
 3. Artifacts are written under `.omc/artifacts/ask/`
 
@@ -52,16 +51,11 @@ Split the user request into:
 - **Gemini prompt:** UX/content clarity, alternatives, edge-case usability, docs polish
 - **Synthesis plan:** how to reconcile conflicts
 
-### 2. Invoke ask skills
-
-Use skill routing first:
+### 2. Invoke advisors via CLI
 
-```bash
-/oh-my-claudecode:ask codex <codex prompt>
-/oh-my-claudecode:ask gemini <gemini prompt>
-```
+> **Note:** Skill nesting (invoking a skill from within an active skill) is not supported in Claude Code. Always use the direct CLI path via Bash tool.
 
-Equivalent direct CLI:
+Run both advisors:
 
 ```bash
 omc ask codex "<codex prompt>"

package/skills/configure-notifications/SKILL.md

@@ -13,6 +13,7 @@ triggers:
   - "configure slack"
   - "setup slack"
   - "slack webhook"
+level: 2
 ---
 
 # Configure Notifications