claudecode-omc 4.8.3 → 4.9.3

package/skills/planning-with-files/scripts/session-catchup.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+Session catchup helper for planning-with-files.
+
+Checks if planning files were updated long ago while the working tree changed,
+and prints a lightweight catchup reminder.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+PLANNING_FILES = ("task_plan.md", "findings.md", "progress.md")
+
+
+def run(cmd: list[str], cwd: Path) -> str:
+    try:
+        out = subprocess.check_output(cmd, cwd=str(cwd), stderr=subprocess.STDOUT, text=True)
+        return out.strip()
+    except Exception:
+        return ""
+
+
+def newest_planning_mtime(root: Path) -> float:
+    mtimes = []
+    for name in PLANNING_FILES:
+        p = root / name
+        if p.exists():
+            mtimes.append(p.stat().st_mtime)
+    return max(mtimes) if mtimes else 0.0
+
+
+def main() -> int:
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
+    if not (root / ".git").exists():
+        return 0
+
+    planning_mtime = newest_planning_mtime(root)
+    if planning_mtime == 0:
+        return 0
+
+    diff_stat = run(["git", "diff", "--stat"], root)
+    if not diff_stat:
+        return 0
+
+    now = datetime.now().timestamp()
+    age_hours = (now - planning_mtime) / 3600
+    if age_hours < 1:
+        return 0
+
+    print("[planning-with-files] Catchup reminder")
+    print("Detected git changes after last planning file update.")
+    print("Recommended next steps:")
+    print("1. Read task_plan.md, findings.md, progress.md")
+    print("2. Run: git diff --stat")
+    print("3. Sync planning files with current code changes")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/skills/planning-with-files/templates/findings.md

@@ -0,0 +1,24 @@
+# Findings and Decisions
+
+## Requirements
+-
+
+## Research Findings
+-
+
+## Technical Decisions
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Issues Encountered
+| Issue | Resolution |
+|-------|------------|
+|       |            |
+
+## Resources
+-
+
+## Visual or Browser Findings
+-
+

package/skills/planning-with-files/templates/progress.md

@@ -0,0 +1,38 @@
+# Progress Log
+
+## Session: [DATE]
+
+### Phase 1: [Title]
+- **Status:** in_progress
+- **Started:** [timestamp]
+- Actions taken:
+  -
+- Files created or modified:
+  -
+
+### Phase 2: [Title]
+- **Status:** pending
+- Actions taken:
+  -
+- Files created or modified:
+  -
+
+## Test Results
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+|      |       |          |        |        |
+
+## Error Log
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+|           |       | 1       |            |
+
+## Reboot Check
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase X |
+| Where am I going? | Remaining phases |
+| What is the goal? | See task_plan.md |
+| What have I learned? | See findings.md |
+| What have I done? | See this file |
+

package/skills/planning-with-files/templates/task_plan.md

@@ -0,0 +1,53 @@
+# Task Plan: [Brief Description]
+
+## Goal
+[One sentence describing the end state]
+
+## Current Phase
+Phase 1
+
+## Phases
+
+### Phase 1: Requirements and Discovery
+- [ ] Understand user intent
+- [ ] Identify constraints and requirements
+- [ ] Document findings in findings.md
+- **Status:** in_progress
+
+### Phase 2: Planning and Structure
+- [ ] Define technical approach
+- [ ] Create project structure if needed
+- [ ] Document major decisions
+- **Status:** pending
+
+### Phase 3: Implementation
+- [ ] Execute plan in small steps
+- [ ] Keep changes reversible
+- [ ] Verify incrementally
+- **Status:** pending
+
+### Phase 4: Testing and Verification
+- [ ] Verify requirements are met
+- [ ] Log test results in progress.md
+- [ ] Fix issues found
+- **Status:** pending
+
+### Phase 5: Delivery
+- [ ] Review output quality
+- [ ] Summarize results and residual risks
+- **Status:** pending
+
+## Key Questions
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+|       | 1       |            |
+

package/skills/project-session-manager/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: project-session-manager
-description: Manage isolated dev environments with git worktrees and tmux sessions
+description: Worktree-first dev environment manager for issues, PRs, and features with optional tmux sessions
 aliases: [psm]
+level: 2
 ---
 
 # Project Session Manager (PSM) Skill
 
 `psm` is the compatibility alias for this canonical skill entrypoint.
 
-> **Quick Start:** For simple worktree creation without tmux sessions, use `omc teleport`:
+> **Quick Start (worktree-first):** Start with `omc teleport` when you want an isolated issue/PR/feature worktree before adding any tmux/session orchestration:
 > ```bash
 > omc teleport #123          # Create worktree for issue/PR
 > omc teleport my-feature    # Create worktree for feature

package/skills/ralph/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ralph
 description: Self-referential loop until task completion with configurable verification reviewer
+level: 4
 ---
 
 [RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]
@@ -38,6 +39,8 @@ By default, ralph operates in PRD mode. A scaffold `prd.json` is auto-generated
 
 **Opt-out:** If `{{PROMPT}}` contains `--no-prd`, skip PRD generation and work in legacy mode (no story tracking, generic verification). Use this for trivial quick fixes.
 
+**Deslop opt-out:** If `{{PROMPT}}` contains `--no-deslop`, skip the mandatory post-review deslop pass entirely. Use this only when the cleanup pass is intentionally out of scope for the run.
+
 **Reviewer selection:** Pass `--critic=architect`, `--critic=critic`, or `--critic=codex` in the Ralph prompt to choose the completion reviewer for that run. `architect` remains the default.
 </PRD_Mode>
 
@@ -95,7 +98,18 @@ By default, ralph operates in PRD mode. A scaffold `prd.json` is auto-generated
    - Ralph floor: always at least STANDARD, even for small changes
    - The selected reviewer verifies against the SPECIFIC acceptance criteria from prd.json, not vague "is it done?"
 
-8. **On approval**: Run `/oh-my-claudecode:cancel` to cleanly exit and clean up all state files
+7.5 **Mandatory Deslop Pass**:
+   - Unless `{{PROMPT}}` contains `--no-deslop`, run `oh-my-claudecode:ai-slop-cleaner` in standard mode (not `--review`) on the files changed during the current Ralph session only.
+   - Keep the scope bounded to the Ralph changed-file set; do not broaden the cleanup pass to unrelated files.
+   - If the reviewer approved the implementation but the deslop pass introduces follow-up edits, keep those edits inside the same changed-file scope before proceeding.
+
+7.6 **Regression Re-verification**:
+   - After the deslop pass, re-run all relevant tests, build, and lint checks for the Ralph session.
+   - Read the output and confirm the post-deslop regression run actually passes.
+   - If regression fails, roll back the cleaner changes or fix the regression, then rerun the verification loop until it passes.
+   - Only proceed to completion after the post-deslop regression run passes (or `--no-deslop` was explicitly specified).
+
+8. **On approval**: After Step 7.6 passes (with Step 7.5 completed, or skipped via `--no-deslop`), run `/oh-my-claudecode:cancel` to cleanly exit and clean up all state files
 
 9. **On rejection**: Fix the issues raised, re-verify with the same reviewer, then loop back to check if the story needs to be marked incomplete
 </Steps>
@@ -191,6 +205,8 @@ Why bad: Did not refine scaffold criteria into task-specific ones. This is PRD t
 - [ ] lsp_diagnostics shows 0 errors on affected files
 - [ ] progress.txt records implementation details and learnings
 - [ ] Selected reviewer verification passed against specific acceptance criteria
+- [ ] ai-slop-cleaner pass completed on changed files (or `--no-deslop` specified)
+- [ ] Post-deslop regression tests pass
 - [ ] `/oh-my-claudecode:cancel` run for clean state cleanup
 </Final_Checklist>
 

package/skills/ralplan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ralplan
-description: Alias for /omc-plan --consensus
+description: Consensus planning entrypoint that auto-gates vague ralph/autopilot/team requests before execution
+level: 4
 ---
 
 # Ralplan (Consensus Planning Alias)
@@ -17,6 +18,8 @@ Ralplan is a shorthand alias for `/oh-my-claudecode:omc-plan --consensus`. It tr
 
 - `--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).
+- `--architect codex`: Use Codex for the Architect pass when Codex CLI is available. Otherwise, briefly note the fallback and keep the default Claude Architect review.
+- `--critic codex`: Use Codex for the Critic pass when Codex CLI is available. Otherwise, briefly note the fallback and keep the default Claude Critic review.
 
 ## Usage with interactive mode
 

package/skills/release/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: release
 description: Automated release workflow for oh-my-claudecode
+level: 3
 ---
 
 # Release Skill

package/skills/sciomc/SKILL.md

@@ -2,6 +2,7 @@
 name: sciomc
 description: Orchestrate parallel scientist agents for comprehensive analysis with AUTO mode
 argument-hint: <research goal>
+level: 4
 ---
 
 # Research Skill

package/skills/setup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: setup
-description: Unified setup entrypoint for install, diagnostics, and MCP configuration
+description: Use first for install/update routing — sends setup, doctor, or MCP requests to the correct OMC setup flow
+level: 2
 ---
 
 # Setup
@@ -18,18 +19,18 @@ Use `/oh-my-claudecode:setup` as the unified setup/configuration entrypoint.
 
 ## Routing
 
-Route by the first argument:
+Process the request by the **first argument only** so install/setup questions land on the right flow immediately:
 
-- No argument, `wizard`, `local`, `global`, or `--force` -> run `/oh-my-claudecode:omc-setup {{ARGUMENTS}}`
-- `doctor` -> run `/oh-my-claudecode:omc-doctor {{ARGUMENTS_AFTER_DOCTOR}}`
-- `mcp` -> run `/oh-my-claudecode:mcp-setup {{ARGUMENTS_AFTER_MCP}}`
+- No argument, `wizard`, `local`, `global`, or `--force` -> route to `/oh-my-claudecode:omc-setup` with the same remaining args
+- `doctor` -> route to `/oh-my-claudecode:omc-doctor` with everything after the `doctor` token
+- `mcp` -> route to `/oh-my-claudecode:mcp-setup` with everything after the `mcp` token
 
 Examples:
 
 ```bash
-/oh-my-claudecode:omc-setup {{ARGUMENTS}}
-/oh-my-claudecode:omc-doctor {{ARGUMENTS_AFTER_DOCTOR}}
-/oh-my-claudecode:mcp-setup {{ARGUMENTS_AFTER_MCP}}
+/oh-my-claudecode:setup --local          # => /oh-my-claudecode:omc-setup --local
+/oh-my-claudecode:setup doctor --json    # => /oh-my-claudecode:omc-doctor --json
+/oh-my-claudecode:setup mcp github       # => /oh-my-claudecode:mcp-setup github
 ```
 
 ## Notes

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: skill-creator
+description: Create new skills, modify and improve existing skills, and evaluate whether they route and behave correctly in OMC. Use when users want to create a skill from scratch, edit an existing skill, improve skill triggering, or iterate on a skill with prompt-based tests.
+argument-hint: "<skill-goal-or-skill-path>"
+metadata:
+  short-description: Create or upgrade a skill
+---
+
+# Skill Creator
+
+A skill for creating new skills and iteratively improving them.
+
+This local version is based on the vendored Anthropic upstream file at `references/upstream-anthropic-skill-creator.md`, then adapted for OMC conventions and tooling.
+
+## Adaptation Summary
+
+- Upstream baseline: overall skill-creation loop, communication guidance, capture-intent flow, anatomy, progressive disclosure, and writing principles
+- Local OMC adaptation: replaces upstream eval-viewer and benchmark workflow with `skill-quality-analyzer`, `skill-debugger`, and `skill-tester`
+- Local OMC adaptation: keeps Claude Code-oriented metadata examples used in this repo
+- Local OMC adaptation: confines project-specific orchestration fields such as `pipeline`, `next-skill`, and `handoff` to explicit local sections
+- Maintenance rule: when upstream changes, update the vendored file first, then re-apply only the minimal OMC-specific differences
+
+## Upstream Sync Policy
+
+Treat `references/upstream-anthropic-skill-creator.md` as the authoritative upstream baseline for structure and intent.
+
+When updating this local file:
+- compare against the vendored upstream file first
+- preserve the upstream section order unless there is a concrete local reason not to
+- keep OMC-specific behavior in clearly labeled local sections
+- do not silently replace upstream guidance with local conventions
+- if upstream and OMC differ, prefer upstream for general skill-authoring advice and confine OMC differences to explicit adaptation notes
+
+When Anthropic updates the upstream file:
+1. refresh the vendored upstream copy
+2. diff the upstream copy against this local file
+3. pull forward structural and wording improvements that still fit OMC
+4. re-check OMC-specific sections so they remain isolated and justified
+
+At a high level, the process of creating a skill in OMC goes like this:
+
+- Decide what you want the skill to do and roughly how it should do it
+- Write a draft of the skill
+- Create a few realistic test prompts and run prompt-level checks
+- Review the results both qualitatively and structurally
+- Rewrite the skill based on what you learn
+- Repeat until routing and behavior are stable
+- Expand the test set and try again at larger scale if needed
+
+Your job when using this skill is to figure out where the user is in this process and then help them move forward. Sometimes that means interviewing and drafting. Sometimes it means jumping straight to evaluation and revision.
+
+After the draft exists, the normal OMC collaboration loop is:
+
+1. `skill-quality-analyzer` for static review
+2. `skill-debugger` for routing/configuration diagnosis
+3. `skill-tester` for prompt-level verification
+4. revise and repeat
+
+## Communicating with the User
+
+People using this skill may have very different levels of technical familiarity. Phrase things according to the user's level.
+
+In the default case:
+- "evaluation" and "benchmark" are usually acceptable
+- terms like "JSON", "frontmatter", or "assertion" may need a brief explanation
+
+Prefer short explanations over jargon when unsure.
+
+## Creating a Skill
+
+### Capture Intent
+
+Start by understanding the user's intent. The current conversation may already contain the workflow the user wants to capture.
+
+Extract from the conversation first:
+- tools that were used
+- sequence of steps
+- corrections the user made
+- input and output formats
+
+Then fill the gaps:
+1. What should this skill enable Claude to do?
+2. When should this skill trigger?
+3. What should the output or effect look like?
+4. Should we set up prompt tests to verify the skill works?
+
+Skills with objectively checkable outputs benefit from test cases. Purely subjective skills may need lighter evaluation.
+
+### Interview and Research
+
+Ask about:
+- edge cases
+- input and output formats
+- example files
+- success criteria
+- dependencies
+- nearby requests that should go elsewhere
+
+Do not write test prompts until the intended boundaries are clear.
+
+If outside research is useful, use primary sources and repo context first.
+
+### Write the `SKILL.md`
+
+Based on the interview, fill in:
+- `name`
+- `description`
+- optional behavior metadata
+- the actual instructions
+
+The `description` is the primary discovery mechanism. It should say both what the skill does and when to use it.
+
+Because skills tend to under-trigger, descriptions should be a little pushy. Do not make them vague taglines.
+
+## Skill Writing Guide
+
+### Anatomy of a Skill
+
+```text
+skill-name/
+├── SKILL.md
+├── Bundled Resources
+│   ├── scripts/
+│   ├── references/
+│   └── assets/
+└── agents/
+    └── openai.yaml
+```
+
+#### `SKILL.md`
+
+Every `SKILL.md` consists of:
+- frontmatter
+- markdown instructions
+
+The main discovery surface is:
+- `name`
+- `description`
+
+Recommended local frontmatter shape:
+
+```yaml
+---
+name: skill-name
+description: When to use the skill and what it does.
+argument-hint: "<args>"
+disable-model-invocation: false
+user-invocable: true
+allowed-tools:
+  - Read
+  - Grep
+model: sonnet
+---
+```
+
+#### Bundled Resources
+
+##### `scripts/`
+
+Use when the same code keeps getting rewritten or determinism matters.
+
+##### `references/`
+
+Use for documentation Claude should read only when needed.
+
+##### `assets/`
+
+Use for templates, icons, fonts, sample deliverables, and similar output resources.
+
+#### What Not to Include in a Skill
+
+A skill should contain the files needed for another agent to do the work, not extra process documentation.
+
+Avoid adding:
+- `README.md`
+- `INSTALLATION_GUIDE.md`
+- `QUICK_REFERENCE.md`
+- `CHANGELOG.md`
+
+### Progressive Disclosure
+
+Skills use a three-level loading model:
+1. metadata
+2. `SKILL.md` body
+3. bundled resources
+
+Guidelines:
+- keep `SKILL.md` compact
+- split detail into `references/` before the file becomes hard to scan
+- clearly point from `SKILL.md` to any follow-up files
+- avoid deeply nested references
+
+### Principle of Lack of Surprise
+
+Skills must not contain malware, exploit code, or misleading behavior. The contents of the skill should match what the description leads a user to expect.
+
+### Writing Patterns
+
+Prefer imperative instructions.
+
+Defining output formats:
+
+```markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+Examples pattern:
+
+```markdown
+## Commit message format
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+### Writing Style
+
+Explain why important things matter instead of only piling up MUSTs. Prefer a draft-and-revise approach over trying to write the perfect skill in one pass.
+
+## Test Cases
+
+After writing the draft, come up with 2-3 realistic test prompts. Share them with the user or validate them yourself if the intent is already clear.
+
+In OMC, prefer a prompt matrix with:
+- obvious positive cases
+- borderline positive cases
+- obvious negative cases
+
+The best negative cases are near-misses, not completely unrelated requests.
+
+## Running and Evaluating Test Cases in OMC
+
+This local adaptation does not rely on Anthropic's upstream benchmark viewer scripts as the primary workflow. Use the OMC toolchain instead.
+
+### Step 1: Static Review
+
+Run `skill-quality-analyzer` to inspect:
+- discovery surface
+- structure
+- examples and eval coverage
+- execution safety
+- maintainability
+
+### Step 2: Routing and Config Review
+
+Run `skill-debugger` to inspect:
+- under-triggering
+- over-triggering
+- name/description collisions
+- metadata issues such as `disable-model-invocation`, `user-invocable`, and `allowed-tools`
+
+### Step 3: Prompt-Level Verification
+
+Run `skill-tester` with:
+- positive prompts
+- borderline prompts
+- negative prompts
+
+Check both selection and behavior after selection.
+
+### Step 4: Revise
+
+Bias revisions toward:
+- tightening `description`
+- narrowing overlap with neighboring skills
+- fixing metadata that blocks routing
+- bundling deterministic resources where repetition keeps appearing
+
+### Step 5: Repeat Until Stable
+
+Continue until:
+- the skill triggers for clear in-scope prompts
+- the skill stays quiet for clear out-of-scope prompts
+- the body and bundled resources are proportionate to the task
+
+## OMC-Specific Extensions
+
+The upstream Anthropic file is the baseline. The fields below are local OMC extensions and should be treated as project-specific:
+
+```yaml
+pipeline: [skill-a, skill-b]
+next-skill: skill-b
+next-skill-args: --direct
+handoff: .omc/plans/example.md
+```
+
+Use them only when this repository actually consumes them.
+
+## Deliverables
+
+A finished local skill should have:
+- a valid `SKILL.md`
+- a differentiated `description`
+- justified bundled resources
+- positive and negative prompt examples
+- evidence from analyzer/debugger/tester passes
+
+## Success Checklist
+
+- [ ] skill package exists at `skills/<name>/SKILL.md`
+- [ ] `name` matches the folder name
+- [ ] `description` clearly says when to use the skill and what it does
+- [ ] prompt matrix covers positive, borderline, and negative cases
+- [ ] `skill-quality-analyzer` feedback addressed
+- [ ] `skill-debugger` feedback addressed
+- [ ] `skill-tester` feedback addressed