oh-my-customcode 0.33.0 → 0.34.0

package/README.md

@@ -21,7 +21,7 @@ Like oh-my-zsh transformed shell customization, oh-my-customcode makes personali
 
 | Feature | Description |
 |---------|-------------|
-| **Batteries Included** | 44 agents, 69 skills, 25 guides, 19 rules, 2 hooks, 4 contexts, ontology graph - ready to use out of the box |
+| **Batteries Included** | 44 agents, 71 skills, 25 guides, 19 rules, 1 hook, 4 contexts, ontology graph - ready to use out of the box |
 | **Sub-Agent Model** | Supports hierarchical agent orchestration with specialized roles |
 | **Dead Simple Customization** | Create a folder + markdown file = new agent or skill |
 | **Mix and Match** | Use built-in components, create your own, or combine both |
@@ -101,7 +101,7 @@ All commands are invoked inside the Claude Code conversation.
 
 | Command | Description |
 |---------|-------------|
-| `/analysis` | Analyze project and auto-configure agents, skills, rules |
+| `/omcustom:analysis` | Analyze project and auto-configure agents, skills, rules |
 | `/research` | 10-team parallel deep analysis with cross-verification |
 
 #### Development
@@ -115,11 +115,11 @@ All commands are invoked inside the Claude Code conversation.
 
 | Command | Description |
 |---------|-------------|
-| `/create-agent` | Create new agent |
-| `/update-docs` | Sync project structure and documentation |
-| `/update-external` | Update agents from external sources |
-| `/audit-agents` | Audit agent dependencies |
-| `/fix-refs` | Fix broken references |
+| `/omcustom:create-agent` | Create new agent |
+| `/omcustom:update-docs` | Sync project structure and documentation |
+| `/omcustom:update-external` | Update agents from external sources |
+| `/omcustom:audit-agents` | Audit agent dependencies |
+| `/omcustom:fix-refs` | Fix broken references |
 
 #### Memory
 
@@ -128,13 +128,13 @@ All commands are invoked inside the Claude Code conversation.
 | `/memory-save` | Save session context to claude-mem |
 | `/memory-recall` | Search and recall memories |
 
-#### DevOps & Publishing
+#### DevOps & Package Management
 
 | Command | Description |
 |---------|-------------|
-| `/npm-publish` | Publish package to npm registry |
-| `/npm-version` | Semantic version management |
-| `/npm-audit` | Dependency security audit |
+| `/omcustom:npm-publish` | Publish package to npm registry |
+| `/omcustom:npm-version` | Semantic version management |
+| `/omcustom:npm-audit` | Dependency security audit |
 
 #### Optimization
 
@@ -148,13 +148,14 @@ All commands are invoked inside the Claude Code conversation.
 
 | Command | Description |
 |---------|-------------|
-| `/sauron-watch` | Full R017 sync verification |
-| `/monitoring-setup` | OTel console monitoring enable/disable |
+| `/omcustom:sauron-watch` | Full R017 sync verification |
+| `/omcustom:monitoring-setup` | OTel console monitoring enable/disable |
 | `/codex-exec` | Execute Codex CLI prompt |
+| `/deep-plan` | Research-validated planning (research → plan → verify) |
 | `/structured-dev-cycle` | 6-phase structured development cycle |
-| `/lists` | Show all available commands |
-| `/status` | System status and health checks |
-| `/help` | Help information |
+| `/omcustom:lists` | Show all available commands |
+| `/omcustom:status` | System status and health checks |
+| `/omcustom:help` | Help information |
 
 ---
 
@@ -178,7 +179,7 @@ All commands are invoked inside the Claude Code conversation.
 | **Security** | 1 | sec-codeql-expert |
 | **Total** | **44** | |
 
-### Skills (69)
+### Skills (71)
 
 | Category | Count | Skills |
 |----------|-------|--------|
@@ -191,7 +192,7 @@ All commands are invoked inside the Claude Code conversation.
 | **Package Management** | 3 | npm-publish, npm-version, npm-audit |
 | **Operations** | 7 | update-docs, update-external, audit-agents, fix-refs, sauron-watch, monitoring-setup, claude-code-bible |
 | **Utilities** | 5 | lists, help, status, result-aggregation, writing-clearly-and-concisely |
-| **Quality & Workflow** | 9 | multi-model-verification, structured-dev-cycle, model-escalation, stuck-recovery, dag-orchestration, task-decomposition, worker-reviewer-pipeline, pr-auto-improve, pipeline-guards |
+| **Quality & Workflow** | 11 | multi-model-verification, structured-dev-cycle, model-escalation, stuck-recovery, dag-orchestration, task-decomposition, worker-reviewer-pipeline, pr-auto-improve, pipeline-guards, deep-plan, evaluator-optimizer |
 | **Security** | 2 | cve-triage, jinja2-prompts |
 | **Research** | 1 | research |
 | **Deploy** | 2 | vercel-deploy, codex-exec |
@@ -218,7 +219,7 @@ Comprehensive reference documentation covering:
 | **SHOULD** | 6 | Interactions, error handling (recommended) |
 | **MAY** | 1 | Optimization guidelines (optional) |
 
-### Hooks (2)
+### Hooks (1)
 
 Event-driven automation for agent lifecycle events (PreToolUse, PostToolUse, etc.).
 
@@ -280,7 +281,7 @@ your-project/
 │   │   ├── be-fastapi-expert.md
 │   │   ├── mgr-creator.md
 │   │   └── ...
-│   ├── skills/            # Skill modules (69 directories, each with SKILL.md)
+│   ├── skills/            # Skill modules (71 directories, each with SKILL.md)
 │   │   ├── go-best-practices/
 │   │   ├── react-best-practices/
 │   │   ├── secretary-routing/
@@ -292,7 +293,7 @@ your-project/
 │   │   ├── rules.yaml
 │   │   └── graphs/
 │   ├── rules/             # Behavior rules (19 total)
-│   ├── hooks/             # Event hooks (2 total)
+│   ├── hooks/             # Event hooks (1 total)
 │   └── contexts/          # Context files (4 total)
 └── templates/
     └── guides/            # Reference docs (25 total)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/hooks/scripts/stuck-detector.sh

@@ -4,7 +4,12 @@ set -euo pipefail
 # Stuck Detector Hook
 # Trigger: PostToolUse, tool matches "Edit|Write|Bash|Task|Agent"
 # Purpose: Detect repetitive failure loops and advise recovery
-# Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
+# Protocol: stdin JSON -> process -> stdout pass-through
+#   - exit 0: advisory (normal cases, < HARD_BLOCK_THRESHOLD repetitions)
+#   - exit 1: hard block (extreme stuck loops, >= HARD_BLOCK_THRESHOLD repetitions)
+
+# Hard block threshold: consecutive identical operations before blocking
+HARD_BLOCK_THRESHOLD=5
 
 input=$(cat)
 
@@ -120,6 +125,61 @@ if [ "$stuck_detected" = true ]; then
   echo "----------------------------------------" >&2
 fi
 
+# --- Hard Block Detection (extreme stuck loops) ---
+# Check if the same operation has been repeated HARD_BLOCK_THRESHOLD+ times consecutively.
+# This catches cases where advisory warnings are being ignored.
+
+hard_block=false
+hard_block_reason=""
+
+if [ -f "$HISTORY_FILE" ]; then
+  last_n=$(tail -"$HARD_BLOCK_THRESHOLD" "$HISTORY_FILE" 2>/dev/null)
+  last_n_count=$(echo "$last_n" | wc -l | tr -d ' ')
+
+  if [ "$last_n_count" -ge "$HARD_BLOCK_THRESHOLD" ]; then
+    # Check 1: Same file edited HARD_BLOCK_THRESHOLD+ times consecutively
+    if [ -n "$file_path" ]; then
+      escaped_path=$(echo "$file_path" | sed 's/[.[\*^$()+?{|]/\\&/g')
+      consecutive_file=$(echo "$last_n" | grep -c "\"path\":\"${escaped_path}\"" 2>/dev/null || echo "0")
+      if [ "$consecutive_file" -ge "$HARD_BLOCK_THRESHOLD" ]; then
+        hard_block=true
+        hard_block_reason="Same file ($(basename "$file_path")) edited ${consecutive_file} consecutive times"
+      fi
+    fi
+
+    # Check 2: Same error repeated HARD_BLOCK_THRESHOLD+ times consecutively
+    if [ "$hard_block" = false ] && [ "$is_error" = "true" ] && [ -n "$error_hash" ]; then
+      consecutive_error=$(echo "$last_n" | grep -c "\"error_hash\":\"${error_hash}\"" 2>/dev/null || echo "0")
+      if [ "$consecutive_error" -ge "$HARD_BLOCK_THRESHOLD" ]; then
+        hard_block=true
+        hard_block_reason="Same error repeated ${consecutive_error} consecutive times"
+      fi
+    fi
+
+    # Check 3: Same tool+target combination HARD_BLOCK_THRESHOLD+ times consecutively
+    if [ "$hard_block" = false ] && [ -n "$file_path" ]; then
+      escaped_path=$(echo "$file_path" | sed 's/[.[\*^$()+?{|]/\\&/g')
+      consecutive_tool_target=$(echo "$last_n" | grep "\"tool\":\"${tool_name}\"" | grep -c "\"path\":\"${escaped_path}\"" 2>/dev/null || echo "0")
+      if [ "$consecutive_tool_target" -ge "$HARD_BLOCK_THRESHOLD" ]; then
+        hard_block=true
+        hard_block_reason="${tool_name} called on $(basename "$file_path") ${consecutive_tool_target} consecutive times"
+      fi
+    fi
+  fi
+fi
+
+if [ "$hard_block" = true ]; then
+  echo "" >&2
+  echo "=== [Stuck Detection] HARD BLOCK ===" >&2
+  echo "  ${hard_block_reason}" >&2
+  echo "  Threshold: ${HARD_BLOCK_THRESHOLD} consecutive identical operations" >&2
+  echo "  Action: Blocking this tool call to break the stuck loop." >&2
+  echo "  Recovery: Step back, re-read the error, and try a fundamentally different approach." >&2
+  echo "=====================================" >&2
+  echo "$input"
+  exit 1
+fi
+
 # Pass through
 echo "$input"
 exit 0

package/templates/.claude/hooks/scripts/task-outcome-recorder.sh

@@ -34,9 +34,10 @@ entry=$(jq -n \
   --arg agent "$agent_type" \
   --arg model "$model" \
   --arg outcome "$outcome" \
+  --arg pattern "unknown" \
   --arg desc "$description" \
   --arg err "$error_summary" \
-  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, description: $desc, error_summary: $err}')
+  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, pattern_used: $pattern, description: $desc, error_summary: $err}')
 
 echo "$entry" >> "$OUTCOME_FILE"
 

package/templates/.claude/rules/MUST-agent-design.md

@@ -165,10 +165,10 @@ Use `context: fork` for skills that orchestrate multi-agent workflows. Cap at **
 | Multi-agent coordination patterns | Single-agent reference skills |
 | Task decomposition/planning | External tool integrations |
 
-Current skills with `context: fork` (8/10 cap):
+Current skills with `context: fork` (9/10 cap):
 - secretary-routing, dev-lead-routing, de-lead-routing, qa-lead-routing
 - dag-orchestration, task-decomposition, worker-reviewer-pipeline
-- pipeline-guards
+- pipeline-guards, deep-plan
 
 ## Naming
 

package/templates/.claude/skills/analysis/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: analysis
+name: omcustom:analysis
 description: Analyze project and auto-configure agents, skills, rules, and guides
-scope: core
+scope: harness
 argument-hint: "[--dry-run] [--verbose]"
 ---
 

package/templates/.claude/skills/audit-agents/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: audit-agents
+name: omcustom:audit-agents
 description: Audit agent dependencies and references
 scope: harness
 argument-hint: "[agent-name] [--all] [--fix]"

package/templates/.claude/skills/create-agent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: create-agent
+name: omcustom:create-agent
 description: Create a new agent with complete structure
 scope: harness
 argument-hint: "<name> --type <type>"

package/templates/.claude/skills/deep-plan/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: deep-plan
+description: Research-validated planning — research → plan → verify cycle for high-confidence implementation plans
+scope: core
+version: 1.0.0
+user-invocable: true
+argument-hint: "<topic-or-issue>"
+context: fork
+---
+
+# Deep Plan Skill
+
+Research-validated planning that eliminates the gap between research assumptions and actual code. Orchestrates a 3-phase cycle: Discovery Research → Reality-Check Planning → Plan Verification.
+
+**Orchestrator-only** — only the main conversation uses this skill (R010). All phases execute as subagents.
+
+## Usage
+
+```
+/deep-plan <topic-or-issue>
+/deep-plan "implement caching layer for API responses"
+/deep-plan #325 new authentication system
+/deep-plan Rust async runtime migration
+```
+
+## Problem Solved
+
+Research-only analysis (like `/research`) produces findings based on assumptions about the codebase. These assumptions often diverge from reality:
+
+| Assumption | Reality | Impact |
+|------------|---------|--------|
+| "Feature X is missing" | Already implemented | Wasted effort on duplicate work |
+| "Pattern Y is needed" | Partially exists | Over-engineering existing code |
+| "Library Z is required" | Already a dependency | Unnecessary integration effort |
+
+`/deep-plan` solves this by cross-referencing research findings against actual code before committing to a plan.
+
+## Architecture — 3 Phases
+
+### Phase 1: Discovery Research
+
+Invoke the `/research` skill internally for comprehensive topic analysis.
+
+```
+Phase 1: Discovery Research
+├── Skill(research, args="<topic>")
+├── 10-team parallel analysis (3 batches × 4/4/2)
+├── Cross-verification loop (opus + codex)
+├── ADOPT / ADAPT / AVOID taxonomy
+└── Output: research report (artifact)
+```
+
+**Execution**: Delegates to `/research` skill via `Skill(research, args="<topic>")`. The orchestrator waits for completion before proceeding to Phase 2.
+
+**Output**: Full research report with ADOPT/ADAPT/AVOID taxonomy.
+
+### Phase 2: Reality-Check Planning
+
+Ground-truth the research findings against the actual codebase.
+
+```
+Phase 2: Reality-Check Planning
+├── EnterPlanMode
+├── Explore agents (up to 3 parallel)
+│   ├── Explore 1: Verify ADOPT items exist/don't exist
+│   ├── Explore 2: Check ADAPT items for current state
+│   └── Explore 3: Validate AVOID alternatives
+├── Gap analysis table
+├── Refined plan (real gaps only)
+└── ExitPlanMode → user approval
+```
+
+**Steps**:
+
+1. **Enter Plan Mode**: `EnterPlanMode` to activate planning context
+2. **Codebase Exploration**: Spawn up to 3 Explore agents in parallel to verify research assumptions:
+   - Each ADOPT item: Does it already exist? Partially implemented?
+   - Each ADAPT item: What is the current state to adapt from?
+   - Each AVOID item: Are the alternatives already available?
+3. **Gap Analysis**: Build a reconciliation table:
+
+   ```
+   | Research Finding | Actual Code State | Gap Type | Action |
+   |-----------------|-------------------|----------|--------|
+   | "No caching"    | Redis client exists | Overestimate | Remove from plan |
+   | "Need auth middleware" | No auth layer | Real gap | Keep in plan |
+   | "Migrate to v3" | Already on v3.1 | Overestimate | Remove from plan |
+   | "Add rate limiting" | Basic limiter exists | Partial gap | Adapt existing |
+   ```
+
+4. **Refined Plan**: Write implementation plan containing ONLY real gaps:
+   - Remove overestimates (already implemented)
+   - Adjust partial gaps (adapt, don't rebuild)
+   - Prioritize real gaps by impact
+5. **User Approval**: `ExitPlanMode` presents the refined plan for user review
+
+### Phase 3: Plan Verification Research
+
+Validate the refined plan with focused research before implementation begins.
+
+```
+Phase 3: Plan Verification Research
+├── 3-team focused verification
+│   ├── T1: Technical feasibility
+│   ├── T2: Conflict/duplication check
+│   └── T3: Test strategy & risk
+├── Verdict: PASS or REVISE
+├── PASS → implementation advisory
+└── REVISE → return to Phase 2
+```
+
+**Teams** (3 parallel, NOT full 10-team):
+
+| Team | Focus | Verifies |
+|------|-------|----------|
+| T1 | Technical feasibility | Can the plan be implemented with current stack/deps? |
+| T2 | Conflict & duplication | Does the plan conflict with in-flight work or duplicate existing code? |
+| T3 | Test strategy & risk | Is the plan testable? What are the failure modes? |
+
+**Invocation**: Phase 3 teams are spawned directly as parallel agents (NOT via `Skill(research)`). The orchestrator creates 3 focused agents, each with a specific verification mandate derived from the Phase 2 plan.
+
+**Model selection**: sonnet for teams, opus for synthesis.
+
+**Verdict**:
+- **PASS**: Plan is verified. Display implementation advisory.
+- **REVISE**: Issues found. Return to Phase 2 with feedback for plan refinement.
+- **REVISE limit**: After 2 REVISE cycles, escalate to user for manual judgment.
+
+## Workflow Diagram
+
+```
+User: /deep-plan "topic"
+  │
+  ├─ Phase 1: Discovery Research
+  │   ├─ Skill(research, args="topic")
+  │   ├─ 10-team analysis → ADOPT/ADAPT/AVOID
+  │   └─ Output: research artifact
+  │
+  ├─ Phase 2: Reality-Check Planning
+  │   ├─ EnterPlanMode
+  │   ├─ Explore agents (up to 3 parallel)
+  │   ├─ Gap analysis: research vs actual code
+  │   ├─ Refined plan (real gaps only)
+  │   └─ ExitPlanMode → user approval
+  │
+  └─ Phase 3: Plan Verification
+      ├─ 3-team focused research
+      ├─ Verdict: PASS or REVISE
+      ├─ PASS → implementation advisory
+      └─ REVISE → loop back to Phase 2 (max 2 cycles)
+```
+
+## Differentiation
+
+| Skill | Scope | Code Verification | Phases |
+|-------|-------|-------------------|--------|
+| `/research` | Analysis only | None — assumption-based | 1 |
+| Plan mode | Planning only | Yes — code exploration | 1 |
+| `/structured-dev-cycle` | Full implementation | Yes — stage-by-stage | 6 |
+| **`/deep-plan`** | **Analysis + Planning + Verification** | **3-pass cross-verification** | **3** |
+
+`/deep-plan` fills the gap between research (which lacks code grounding) and implementation (which lacks upfront analysis). It produces a **verified plan** ready for execution.
+
+## Display Format
+
+Before execution:
+```
+[Deep Plan] {topic}
+├── Phase 1: Discovery Research (10 teams, 3 batches)
+├── Phase 2: Reality-Check Planning (up to 3 Explore agents)
+└── Phase 3: Plan Verification (3 focused teams)
+
+Estimated phases: 3 | Models: sonnet → opus
+Execute? [Y/n]
+```
+
+Phase transitions:
+```
+[Deep Plan] Phase 1/3 — Discovery Research
+├── Research skill active...
+└── Awaiting 10-team results
+
+[Deep Plan] Phase 2/3 — Reality-Check Planning
+├── Gap analysis: 6 ADOPT items → 2 real gaps, 4 overestimates
+└── Refined plan: 5 action items (down from 12)
+
+[Deep Plan] Phase 3/3 — Plan Verification
+├── T1 (feasibility): ✓ PASS
+├── T2 (conflicts): ✓ PASS
+├── T3 (test/risk): ✓ PASS
+└── Verdict: PASS — ready for implementation
+```
+
+## Post-Completion Advisory
+
+After PASS verdict:
+```
+[Advisory] Verified plan ready for implementation.
+├── For complex implementations (10+ files): /structured-dev-cycle
+├── For parallel task execution: superpowers:subagent-driven-development
+└── For simple tasks (< 3 files): proceed directly
+```
+
+## Execution Rules
+
+| Rule | Detail |
+|------|--------|
+| Phase 1 | Full `/research` skill invocation (10 teams) |
+| Phase 2 | Max 3 parallel Explore agents (R009) |
+| Phase 3 | Max 3 parallel verification teams (R009) |
+| Orchestrator only | Main conversation manages all phases (R010) |
+| Intent display | Show phase plan before execution (R015) |
+| Ecomode | Auto-activate for team result aggregation (R013) |
+| REVISE limit | Max 2 cycles before user escalation |
+
+## Agent Teams (R018)
+
+When Agent Teams is enabled, Phase 1 and Phase 3 parallel teams SHOULD use Agent Teams instead of individual Agent tool calls:
+
+| Phase | Without Agent Teams | With Agent Teams |
+|-------|--------------------|--------------------|
+| Phase 1 | Delegates to `/research` (handles internally) | Delegates to `/research` (handles internally) |
+| Phase 2 | Up to 3 Explore agents via Agent tool | Up to 3 Explore agents via Agent tool (below threshold) |
+| Phase 3 | 3 agents via Agent tool | 3 agents — at threshold, prefer Agent Teams for coordination |
+
+Phase 1 delegation to `/research` means Agent Teams decisions are handled by the research skill itself. Phase 3's 3-team verification is at the Agent Teams threshold (3+ agents) and benefits from peer messaging for cross-verification.
+
+## Model Selection
+
+| Phase | Component | Model | Rationale |
+|-------|-----------|-------|-----------|
+| Phase 1 | Research teams | sonnet | Delegated to /research skill |
+| Phase 1 | Verification | opus | Delegated to /research skill |
+| Phase 2 | Explore agents | haiku | Fast codebase search |
+| Phase 2 | Gap analysis | opus | Complex reconciliation reasoning |
+| Phase 3 | Verification teams | sonnet | Balanced analysis |
+| Phase 3 | Synthesis/verdict | opus | Final judgment |
+
+## Cost Estimate
+
+| Phase | Approximate Cost | Driver |
+|-------|-----------------|--------|
+| Phase 1 | High | Full 10-team `/research` invocation |
+| Phase 2 | Low-Medium | Up to 3 Explore agents (haiku) + 1 opus synthesis |
+| Phase 3 | Medium | 3 sonnet verification teams + 1 opus synthesis |
+| **Total** | **High** | Dominated by Phase 1 research cost |
+
+`/deep-plan` is designed for high-stakes decisions where plan quality justifies the cost. For quick planning, use `EnterPlanMode` directly.
+
+## Integration
+
+| Component | Integration |
+|-----------|-------------|
+| `/research` | Phase 1 full invocation + Phase 3 reduced invocation pattern |
+| EnterPlanMode/ExitPlanMode | Phase 2 plan creation and user approval |
+| Explore agents | Phase 2 codebase verification (up to 3 parallel) |
+| R009 | Phase 1 (10 teams batched), Phase 2 (3 Explore), Phase 3 (3 teams) |
+| R010 | Orchestrator manages all 3 phases; teams are subagents |
+| R013 | Ecomode for team result aggregation |
+| R015 | Phase transition intent display |
+| result-aggregation | Phase 1 and 3 result formatting |
+| superpowers:subagent-driven-development | Post-PASS implementation advisory (external plugin) |
+
+## Fallback Behavior
+
+| Scenario | Fallback |
+|----------|----------|
+| Phase 1 `/research` fails | Manual analysis, then proceed to Phase 2 |
+| Phase 2 EnterPlanMode unavailable | Perform analysis without plan mode context |
+| Phase 3 REVISE ≥ 2 times | Escalate to user for manual judgment |
+| Explore agent failure | Reduce parallel count, retry with remaining |
+| Partial team failure | Synthesize from available results, note gaps |
+
+## Artifact Persistence
+
+Phase 1 research artifact is persisted by the `/research` skill.
+
+Phase 3 verification report is persisted by the final synthesis agent:
+```
+.claude/outputs/sessions/{YYYY-MM-DD}/deep-plan-{HHmmss}.md
+```
+
+With metadata header:
+```markdown
+---
+skill: deep-plan
+date: {ISO-8601 with timezone}
+query: "{original user query}"
+phases_completed: 3
+verdict: PASS|REVISE
+---
+```

package/templates/.claude/skills/dev-refactor/SKILL.md

@@ -9,6 +9,17 @@ argument-hint: "<file-or-directory> [--lang <language>]"
 
 Refactor code for better structure, naming, and patterns using language-specific expert agents.
 
+## When NOT to Use
+
+| Scenario | Better Alternative |
+|----------|--------------------|
+| Renaming only (no structural change) | IDE rename refactoring or `sed` |
+| Formatting cleanup | Run formatter (`prettier`, `gofmt`, `black`) |
+| No test coverage for target code | Write tests first (`/structured-dev-cycle`) |
+| Moving files between directories | `git mv` via mgr-gitnerd |
+
+**Pre-execution check**: Verify test coverage exists for the refactoring target. Refactoring without tests risks silent regressions.
+
 ## Parameters
 
 | Name | Type | Required | Description |

package/templates/.claude/skills/dev-review/SKILL.md

@@ -9,6 +9,17 @@ argument-hint: "<file-or-directory> [--lang <language>]"
 
 Review code for best practices using language-specific expert agents.
 
+## When NOT to Use
+
+| Scenario | Better Alternative |
+|----------|--------------------|
+| Formatting/style issues only | Run linter or formatter directly (`prettier`, `gofmt`, `black`) |
+| Single syntax error | IDE/LSP diagnostics |
+| Auto-generated code | Skip — generated code follows its own conventions |
+| Pre-commit quick check | Git hooks with linter integration |
+
+**Pre-execution check**: If the issue is purely formatting, run the appropriate formatter first.
+
 ## Parameters
 
 | Name | Type | Required | Description |