oh-my-customcode 0.33.1 → 0.35.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, 70 skills, 25 guides, 19 rules, 1 hook, 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,14 +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 |
 
 ---
 
@@ -179,7 +179,7 @@ All commands are invoked inside the Claude Code conversation.
 | **Security** | 1 | sec-codeql-expert |
 | **Total** | **44** | |
 
-### Skills (70)
+### Skills (71)
 
 | Category | Count | Skills |
 |----------|-------|--------|
@@ -192,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** | 10 | multi-model-verification, structured-dev-cycle, model-escalation, stuck-recovery, dag-orchestration, task-decomposition, worker-reviewer-pipeline, pr-auto-improve, pipeline-guards, deep-plan |
+| **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 |
@@ -281,7 +281,7 @@ your-project/
 │   │   ├── be-fastapi-expert.md
 │   │   ├── mgr-creator.md
 │   │   └── ...
-│   ├── skills/            # Skill modules (70 directories, each with SKILL.md)
+│   ├── skills/            # Skill modules (71 directories, each with SKILL.md)
 │   │   ├── go-best-practices/
 │   │   ├── react-best-practices/
 │   │   ├── secretary-routing/

package/package.json

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

package/templates/.claude/hooks/hooks.json

@@ -221,6 +221,16 @@
           }
         ],
         "description": "Detect repetitive failure loops and advise recovery strategies"
+      },
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\" || tool == \"Bash\" || tool == \"Task\" || tool == \"Agent\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/cost-cap-advisor.sh"
+          }
+        ],
+        "description": "Advisory cost cap monitoring — warn when session cost approaches configurable limit"
       }
     ],
     "Stop": [

package/templates/.claude/hooks/scripts/cost-cap-advisor.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# cost-cap-advisor.sh — Advisory hook for session cost monitoring
+# Trigger: PostToolUse (Agent/Task)
+# Purpose: Warn when session cost approaches configurable cap
+# Protocol: stdin JSON -> stdout pass-through, exit 0 always (advisory only, R010)
+
+input=$(cat)
+
+# Cost bridge file written by statusline.sh
+COST_FILE="/tmp/.claude-cost-${PPID}"
+ADVISORY_FILE="/tmp/.claude-cost-advisory-${PPID}"
+
+# Configurable cap (default $5.00, override via CLAUDE_COST_CAP env var)
+COST_CAP="${CLAUDE_COST_CAP:-5.00}"
+
+# Check if cost data is available
+if [ ! -f "$COST_FILE" ]; then
+  echo "$input"
+  exit 0
+fi
+
+# Read cost data (TSV: cost_usd, ctx_pct, timestamp)
+IFS=$'\t' read -r cost_usd ctx_pct timestamp < "$COST_FILE" 2>/dev/null || {
+  echo "$input"
+  exit 0
+}
+
+# Validate cost_usd is a number
+if ! printf '%f' "$cost_usd" >/dev/null 2>&1; then
+  echo "$input"
+  exit 0
+fi
+
+# Calculate percentage of cap used
+# Use bc for float arithmetic
+cost_pct=$(echo "scale=0; $cost_usd * 100 / $COST_CAP" | bc 2>/dev/null || echo "0")
+
+# Staleness check — skip if data is older than 60 seconds
+now=$(date +%s)
+age=$((now - ${timestamp:-0}))
+if [ "$age" -gt 60 ]; then
+  echo "$input"
+  exit 0
+fi
+
+# Read last advisory level to avoid repeating the same warning
+last_level=""
+if [ -f "$ADVISORY_FILE" ]; then
+  last_level=$(cat "$ADVISORY_FILE" 2>/dev/null || echo "")
+fi
+
+# Determine advisory level and emit warning (only once per level)
+if [ "$cost_pct" -ge 100 ] && [ "$last_level" != "100" ]; then
+  echo "[Cost Cap] Session cost \$${cost_usd} has reached cap \$${COST_CAP} (${cost_pct}%)" >&2
+  echo "[Cost Cap] Consider wrapping up or increasing CLAUDE_COST_CAP" >&2
+  echo "100" > "$ADVISORY_FILE"
+elif [ "$cost_pct" -ge 90 ] && [ "$last_level" != "90" ] && [ "$last_level" != "100" ]; then
+  echo "[Cost Cap] Session cost \$${cost_usd} at 90% of cap \$${COST_CAP}" >&2
+  echo "[Cost Cap] Ecomode recommended — consider /compact" >&2
+  echo "90" > "$ADVISORY_FILE"
+elif [ "$cost_pct" -ge 75 ] && [ "$last_level" != "75" ] && [ "$last_level" != "90" ] && [ "$last_level" != "100" ]; then
+  echo "[Cost Cap] Session cost \$${cost_usd} at 75% of cap \$${COST_CAP}" >&2
+  echo "75" > "$ADVISORY_FILE"
+elif [ "$cost_pct" -ge 50 ] && [ -z "$last_level" ]; then
+  echo "[Cost Cap] Session cost \$${cost_usd} at 50% of cap \$${COST_CAP}" >&2
+  echo "50" > "$ADVISORY_FILE"
+fi
+
+# Pass through — advisory only
+echo "$input"
+exit 0

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)
 
@@ -26,7 +31,7 @@ if [ "$is_error" = "true" ]; then
   error_hash=$(echo "$output_preview" | head -c 50 | md5sum 2>/dev/null | cut -d' ' -f1 || echo "unknown")
 fi
 
-entry=$(jq -n \
+entry=$(jq -cn \
   --arg ts "$timestamp" \
   --arg tool "$tool_name" \
   --arg path "$file_path" \
@@ -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

@@ -2,16 +2,16 @@
 set -euo pipefail
 
 # Task/Agent Outcome Recorder Hook
-# Trigger: PostToolUse, tool == "Task" || tool == "Agent"
+# Trigger: PostToolUse (tool == "Task" || "Agent") and SubagentStop
 # Purpose: Record task outcomes for model escalation decisions
 # Protocol: stdin JSON -> process -> stdout pass-through, exit 0 always
 
 input=$(cat)
 
-# Extract task info
-agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // "unknown"')
-model=$(echo "$input" | jq -r '.tool_input.model // "inherit"')
-description=$(echo "$input" | jq -r '.tool_input.description // ""' | head -c 80)
+# Extract task info — support both PostToolUse (tool_input.*) and SubagentStop (top-level) shapes
+agent_type=$(echo "$input" | jq -r '.tool_input.subagent_type // .agent_type // "unknown"')
+model=$(echo "$input" | jq -r '.tool_input.model // .model // "inherit"')
+description=$(echo "$input" | jq -r '.tool_input.description // .description // ""' | head -c 80)
 
 # Determine outcome
 is_error=$(echo "$input" | jq -r '.tool_output.is_error // false')
@@ -24,8 +24,34 @@ else
   error_summary=""
 fi
 
-# Session-scoped outcome log
+# Session-scoped outcome log and agent count tracker
 OUTCOME_FILE="/tmp/.claude-task-outcomes-${PPID}"
+TASK_COUNT_FILE="/tmp/.claude-task-count-${PPID}"
+
+# --- Pattern Detection ---
+# Priority: skill-specific patterns > parallel > sequential (default)
+pattern="sequential"
+
+# Check description for skill-specific workflow patterns
+desc_lower=$(echo "$description" | tr '[:upper:]' '[:lower:]')
+
+if echo "$desc_lower" | grep -qE '(evaluator.optimizer|evaluator_optimizer)'; then
+  pattern="evaluator-optimizer"
+elif echo "$desc_lower" | grep -qE '(worker.reviewer|worker_reviewer)'; then
+  pattern="worker-reviewer"
+elif echo "$desc_lower" | grep -qE '(dag.orchestrat|dag_orchestrat|multi.phase|orchestrat)'; then
+  pattern="orchestrator"
+elif echo "$desc_lower" | grep -qE '(parallel|\[1\]|\[2\]|\[3\]|\[4\])'; then
+  pattern="parallel"
+else
+  # Infer parallel from agent count: if 2+ agents spawned this session, mark as parallel
+  if [ -f "$TASK_COUNT_FILE" ]; then
+    session_agent_count=$(cat "$TASK_COUNT_FILE" 2>/dev/null || echo "0")
+    if [ "$session_agent_count" -ge 2 ] 2>/dev/null; then
+      pattern="parallel"
+    fi
+  fi
+fi
 
 # Append JSON line entry
 timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
@@ -34,9 +60,10 @@ entry=$(jq -n \
   --arg agent "$agent_type" \
   --arg model "$model" \
   --arg outcome "$outcome" \
+  --arg pattern "$pattern" \
   --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/dev-refactor/SKILL.md

@@ -9,6 +9,81 @@ 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.
+
+## Pre-flight Guards
+
+Before executing the refactoring workflow, the agent MUST run these checks:
+
+### Guard 1: Test Coverage Check
+**Level**: WARN
+**Check**: Verify test files exist for the refactoring target
+```bash
+# For target file src/module/foo.ts, check for:
+# - src/module/foo.test.ts
+# - src/module/foo.spec.ts
+# - tests/module/foo.test.ts
+# - test/module/foo.test.ts
+# - __tests__/module/foo.test.ts
+# For Go: foo_test.go in same package
+# For Python: test_foo.py or foo_test.py
+```
+**Action**: `[Pre-flight] WARN: No test file found for {target}. Refactoring without tests risks silent regressions. Consider writing tests first (/structured-dev-cycle).`
+
+### Guard 2: Rename-Only Detection
+**Level**: INFO
+**Check**: If the user request is purely about renaming (no structural change)
+```
+# Keyword detection in user request
+keywords: rename, 이름 변경, 이름 바꿔, rename variable, rename function
+# AND no structural keywords
+structural_keywords: extract, split, merge, restructure, reorganize, decompose
+```
+**Action**: `[Pre-flight] INFO: For rename-only refactoring, IDE rename (F2) or sed is faster and safer (handles all references). Proceeding with full refactoring.`
+
+### Guard 3: Formatting-Only Request Detection
+**Level**: INFO
+**Check**: If the request is about formatting or style cleanup
+```
+# Keyword detection
+keywords: format, formatting, indent, indentation, 포맷, 스타일, whitespace, spacing
+```
+**Action**: `[Pre-flight] INFO: For formatting cleanup, run the appropriate formatter (prettier, gofmt, black, rustfmt). Proceeding with full refactoring.`
+
+### Guard 4: File Move Detection
+**Level**: INFO
+**Check**: If the request is about moving files between directories
+```
+# Keyword detection
+keywords: move file, move to, 파일 이동, 옮겨, relocate, reorganize files
+# AND no code-level changes mentioned
+```
+**Action**: `[Pre-flight] INFO: For file moves without code changes, use git mv via mgr-gitnerd to preserve git history.`
+
+### Display Format
+
+```
+[Pre-flight] dev-refactor
+├── Test coverage: WARN — no test file for src/utils.ts
+├── Rename-only: PASS
+├── Formatting-only: PASS
+└── File move: PASS
+Result: PROCEED WITH CAUTION (0 GATE, 1 WARN, 0 INFO)
+```
+
+If any GATE: block and suggest prerequisite.
+If any WARN: show warning, ask user to confirm.
+If only PASS/INFO: proceed automatically.
+
 ## Parameters
 
 | Name | Type | Required | Description |
@@ -28,6 +103,7 @@ Refactor code for better structure, naming, and patterns using language-specific
 ## Workflow
 
 ```
+0. Run pre-flight guards (MUST complete before proceeding)
 1. Detect language (or use --lang)
 2. Select appropriate expert agent
 3. Load language-specific skill

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

@@ -9,6 +9,81 @@ 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.
+
+## Pre-flight Guards
+
+Before executing the review workflow, the agent MUST run these checks:
+
+### Guard 1: Auto-generated Code Detection
+**Level**: WARN
+**Check**: Scan target files for auto-generation markers
+```bash
+# Detection patterns (any match = WARN)
+grep -rl "DO NOT EDIT" {target} 2>/dev/null
+grep -rl "auto-generated" {target} 2>/dev/null
+grep -rl "@generated" {target} 2>/dev/null
+# File pattern detection
+# *.gen.*, *.pb.go, */generated/*, */proto/*, *_generated.*, *.g.dart
+```
+**Action**: `[Pre-flight] WARN: Auto-generated code detected in {file}. Generated code follows its own conventions — review may produce false positives. Continue? [Y/n]`
+
+### Guard 2: Formatting-Only Changes Detection
+**Level**: INFO
+**Check**: If reviewing changed files (not full codebase), check if changes are formatting-only
+```bash
+# If git diff is available for the target
+git diff --stat {target} | grep -E '^\s+\d+ files? changed'
+# Compare with whitespace-ignored diff
+git diff -w {target}
+# If -w diff is empty but regular diff has changes → formatting only
+```
+**Action**: `[Pre-flight] INFO: Changes in {file} appear to be formatting-only. Consider running the appropriate formatter instead (prettier, gofmt, black).`
+
+### Guard 3: Single Syntax Error Detection
+**Level**: INFO
+**Check**: If target is a single file and the request mentions "error", "syntax", or "broken"
+```
+# Keyword detection in user request
+keywords: error, syntax, broken, doesn't compile, won't build
+# Single file check
+target is exactly 1 file (not a directory)
+```
+**Action**: `[Pre-flight] INFO: For single syntax errors, IDE/LSP diagnostics are faster. Proceeding with full review.`
+
+### Guard 4: Linter/Formatter Available Detection
+**Level**: INFO
+**Check**: Detect if a project-appropriate linter exists
+```bash
+# Check for linter configs in project root
+ls .eslintrc* .prettierrc* biome.json .golangci.yml pyproject.toml .rubocop.yml 2>/dev/null
+```
+**Action**: `[Pre-flight] INFO: Linter config found ({config}). For style-only issues, run the linter directly.`
+
+### Display Format
+
+```
+[Pre-flight] dev-review
+├── Auto-generated code: PASS
+├── Formatting-only changes: INFO — whitespace changes in src/util.ts
+├── Single syntax error: PASS
+└── Linter available: INFO — .eslintrc.json found
+Result: PROCEED (0 GATE, 0 WARN, 2 INFO)
+```
+
+If any GATE: block and suggest alternative.
+If any WARN: show warning, ask user to confirm.
+If only PASS/INFO: proceed automatically.
+
 ## Parameters
 
 | Name | Type | Required | Description |
@@ -27,6 +102,7 @@ Review code for best practices using language-specific expert agents.
 ## Workflow
 
 ```
+0. Run pre-flight guards (see ## Pre-flight Guards)
 1. Detect language (or use --lang)
 2. Select appropriate expert agent
 3. Load language-specific skill