Code Review Orchestrator

READ-ONLY CONSTRAINT

npm install

pip install

1. Command Routing

/codeprobe [subcommand] [path]

Routing Table

/codeprobe audit <path>

file_stats.py

/codeprobe solid <path>

codeprobe-solid

/codeprobe security <path>

codeprobe-security

/codeprobe smells <path>

codeprobe-code-smells

/codeprobe architecture <path>

codeprobe-architecture

/codeprobe patterns <path>

codeprobe-patterns

/codeprobe performance <path>

codeprobe-performance

/codeprobe errors <path>

codeprobe-error-handling

/codeprobe tests <path>

codeprobe-testing

/codeprobe framework <path>

codeprobe-framework

/codeprobe quick <path>

/codeprobe diff [branch]

main

/codeprobe report

scripts/generate_report.py

Default Behaviors

• No subcommand given: Ask the user what they want. Present the available commands.
• No path given: Use the current working directory.
• Phase 3 stubs: If the user invokes

  diff

  or

  report

  , respond: "This feature is coming in Phase 3. Available now: audit, solid, security, smells, architecture, patterns, performance, errors, tests, framework, quick."

2. Stack Auto-Detection

Detection Procedure

1. Use Glob to scan file extensions at the target path (recursive, reasonable depth).
2. Apply the following detection rules — multiple stacks can match simultaneously:

.php

references/php-laravel.md

.js

.ts

.jsx

.tsx

references/javascript-typescript.md

.py

references/python.md

.jsx

.tsx

next.config.*

references/react-nextjs.md

.sql

migrations/

references/sql-database.md

routes/

references/api-design.md

1. For each detected stack, attempt to load the corresponding reference file using Read. If the file does not exist yet (Phase 2+), skip silently.
2. Collect all loaded references into a context bundle to pass to sub-skills.

Reference Loading

references/

references/{reference-file}.md

references/

3. Config Loading

.codeprobe-config.json

Config Schema

{
  "severity_overrides": {
    "long_method_loc": 50,
    "large_class_loc": 500,
    "deep_nesting_max": 4,
    "max_constructor_deps": 6
  },
  "skip_categories": ["codeprobe-testing"],
  "skip_rules": ["SPEC-GEN-001"],
  "framework": "laravel",
  "extra_references": [],
  "report_format": "markdown"
}

Config Behavior

• If absent: All defaults apply. No error.

• severity_overrides

  : Pass to sub-skills so they adjust thresholds accordingly.

• skip_categories

  : Do not invoke the listed sub-skills, even in

  audit

  or

  quick

  mode.

• skip_rules

  : Pass to sub-skills so they suppress findings with matching IDs.

• framework

  : If set, skip auto-detection for that framework and force-load the corresponding reference. Other auto-detection still proceeds.

• extra_references

  : Additional reference file paths to load and pass to sub-skills.

• report_format

  : Output format preference (default:

  markdown

  ).

4. Sub-Skill Execution

Pre-Loading Phase (runs once before any sub-skill)

1. Read the shared preamble from

   shared-preamble.md

   (in this skill's directory). This contains the output contract, execution modes, and constraints shared by all sub-skills.
2. Read all source files at the target path:
   • Use Glob to find all source files (

     .ts

     ,

     .tsx

     ,

     .js

     ,

     .jsx

     ,

     .py

     ,

     .php

     ,

     .vue

     ,

     .sql

     ,

     .css

     ,

     .scss

     and config files like

     next.config.*

     ,

     package.json

     ,

     composer.json

     ,

     requirements.txt

     ,

     .env.example

     ).
   • Read each file using Read.
   • Size cap: If the codebase has more than 50 source files or total LOC exceeds 10,000 lines, do NOT pre-load all files. Instead, pass only the file listing (paths + line counts) and let sub-agents read files they need. Note this in the agent prompt: "Large codebase — file listing provided, use Read for files you need to inspect."
   • Store all file contents as a map:

     {filepath: content}

     .
3. Read all applicable reference files (already loaded during stack detection in Section 2). Store the content.

Invocation Protocol

1. The shared preamble (from

   shared-preamble.md

   ) — output contract, modes, constraints.
2. The sub-skill name to invoke (e.g.,

   codeprobe-security

   ).
3. The mode — one of

   full

   or

   scan

   .
4. Pre-loaded source files — the full content of every source file, formatted as:

   === FILE: {filepath} ===
   {content}
   === END FILE ===

5. Pre-loaded references — the content of all applicable reference files.
6. Config overrides — severity overrides and skip rules from

   .codeprobe-config.json

   .
7. Target path — so the sub-skill knows the project root for any targeted lookups.

Execution Modes

full

/codeprobe audit

/codeprobe solid

scan

/codeprobe quick

Execution Order

• /codeprobe audit

  : Run sub-skills sequentially in this order:

  codeprobe-security

  ,

  codeprobe-error-handling

  ,

  codeprobe-solid

  ,

  codeprobe-architecture

  ,

  codeprobe-patterns

  ,

  codeprobe-performance

  ,

  codeprobe-code-smells

  ,

  codeprobe-testing

  ,

  codeprobe-framework

  — all in

  full

  mode. Collect all findings. Apply deduplication (Section 7A). Derive category scores from severity counts. Compute hot spots by aggregating findings per file and ranking by distinct-categories-flagged. Also run

  scripts/file_stats.py

  for codebase stats (skip gracefully if Python 3 unavailable).

• /codeprobe quick

  : Run all 9 sub-skills in

  scan

  mode. Collect candidate issues from all. Rank by severity (critical > major > minor > suggestion), then select top 5. Re-run relevant sub-skills in

  full

  mode for just those 5 findings to get complete detail.

Available Sub-Skills

1. codeprobe-security

   — Security vulnerability detection

2. codeprobe-error-handling

   — Error handling & resilience

3. codeprobe-solid

   — SOLID principles analysis

4. codeprobe-architecture

   — Architecture analysis

5. codeprobe-patterns

   — Design patterns advisor

6. codeprobe-performance

   — Performance & scalability

7. codeprobe-code-smells

   — Code smell detection

8. codeprobe-testing

   — Test quality & coverage

9. codeprobe-framework

   — Framework-specific best practices

5. Output Contract

id

{PREFIX}-{NNN}

SRP-001

SEC-003

severity

critical

major

minor

suggestion

location

src/UserService.php:45-67

problem

evidence

suggestion

fix_prompt

refactored_sketch

Finding Format Example

### SRP-001 | Major | `src/UserService.php:45-67`

**Problem:** UserService violates Single Responsibility — handles authentication, email sending, and database queries in one class.

**Evidence:**
> Lines 45-50: `public function authenticate($credentials) { ... }`
> Lines 52-60: `public function sendWelcomeEmail($user) { ... }`
> Lines 62-67: `public function findByUsername($name) { ... }`

**Suggestion:** Extract email logic into a dedicated `UserMailer` service and database queries into a `UserRepository`.

**Fix prompt:**
> Refactor `src/UserService.php` to follow Single Responsibility Principle: extract `sendWelcomeEmail()` into a new `UserMailer` class and `findByUsername()` into a `UserRepository` class. Keep `authenticate()` in `UserService` and inject the new dependencies.

6. Severity Levels

Severity Guardrails

• Missing tests (even for critical business logic)
• Code duplication or large classes/files
• Code smells of any kind
• Framework convention violations
• Missing documentation, comments, or type annotations

• Confirmed bugs (code that produces wrong results or crashes)
• Exploitable security vulnerabilities (injection, auth bypass, IDOR with proof)
• Data loss or corruption risks (missing transactions, race conditions on writes)
• Sensitive data exposure (secrets in code, credentials in logs)

7. Scoring

Category Score Formula

crit_penalty  = min(50, critical_count * 15)
major_penalty = min(30, major_count * 6)
minor_penalty = min(10, minor_count * 2)

category_score = max(0, 100 - crit_penalty - major_penalty - minor_penalty)

Category Weights

Overall Score

overall = sum(category_score_i * weight_i for each active category)

skip_categories

.codeprobe-config.json

overall = sum(category_score_i * weight_i for each active category) / sum(weight_i for each active category)

Score Interpretation

7A. Cross-Category Deduplication

Deduplication Procedure

1. Group findings by location. Normalize each finding's

   location

   to

   {file}:{start_line}

   . Two findings overlap if they share the same file AND their line ranges overlap (i.e., start_line_A <= end_line_B AND start_line_B <= end_line_A).
2. For each group of overlapping findings from different categories: a. Select a primary finding. Use this priority order:
   • Security findings (SEC) take priority for anything involving auth, injection, or data exposure
   • Error Handling findings (ERR) take priority for exception/validation issues
   • Performance findings (PERF) take priority for query/caching issues
   • SOLID findings (SRP/OCP/LSP/ISP/DIP) take priority for structural violations
   • Architecture findings (ARCH) take priority for layer/boundary violations
   • If still ambiguous, the category with the higher weight (Section 7) wins b. Mark duplicates. For each non-primary finding in the group, append to its

     problem

     field:

     [Duplicate of {primary_id} — counted there]

     and change its severity to

     suggestion

     so it does not affect the score of its own category. c. Cross-reference the primary. Append to the primary finding's

     suggestion

     field:

     Also flagged by: {list of duplicate category:id pairs}

3. Recount severity totals per category after deduplication, then proceed to scoring.

Examples

• "Refresh bypasses quota" found as SEC-007, ERR-011, FW-001 at same location: keep SEC-007, mark ERR-011 and FW-001 as duplicates (severity → suggestion).
• "God component" found as SRP-001, SMELL-001, ARCH-005 at same file: keep SRP-001 (SOLID priority for structural), mark others as duplicates.
• Same SRP violation found as SRP-001 and SMELL-001: keep SRP-001, mark SMELL-001 as duplicate.

8. Report Rendering

/codeprobe audit

— Full Audit Report

templates/full-audit-report.md

1. Dashboard header:

   Code Health Report — {project}

   title line and

   Overall Health: {score}/100 {status_emoji}

   where status is derived from the thresholds in the "Status thresholds" block below.
2. Category score bars: a 10-character block-character bar proportional to the score for each of the 9 categories (Architecture, Security, Framework, Performance, SOLID, Design Patterns, Code Smells, Test Quality, Error Handling), followed by

   {score}/100 {status}

   .
3. Codebase Stats: output of

   scripts/file_stats.py

   (total files, LOC, backend/frontend split, largest file, test file ratio, comment ratio). If Python 3 is unavailable, omit this block and note: "Install Python 3 for codebase statistics."
4. Hot Spots: top 3 files by distinct-categories-flagged (computed from the same findings that feed the scores).
5. Horizontal rule.
6. Executive Summary: 2-3 sentences covering the most important findings.
7. Critical findings — Full detail: Each critical finding rendered with evidence, suggestion, and fix prompt. These are the most important and justify the token cost.
8. Major findings — Summary table: One row per major finding with ID, file, problem, and fix prompt. No evidence block (saves ~200 tokens per finding).
9. Minor findings — Counts only: Aggregated count per category. No individual findings listed.
10. Suggestions — Counts only: Aggregated count per category. No individual findings listed.
11. Prioritized Fix Order: Ordered list of all critical and major fix prompts, ranked by impact.

• 80-100 = "Healthy"
• 60-79 = "Needs Attention"
• 0-59 = "Critical"

/codeprobe security .

/codeprobe quick

— Quick Review Summary

templates/quick-review-summary.md

1. Header: Project name, "Quick Review — Top 5 Issues".
2. Top 5 Findings: Full detail for the 5 most impactful issues, each with fix prompt.
3. Summary Counts: Total issues found by severity across all categories.
4. Next Step: Suggest running

   /codeprobe audit

   for the complete picture.

9. Claude.ai Degraded Mode

1. Switch to degraded mode: Analyze only the in-context code provided.
2. Execute sub-skills sequentially on the pasted code (no parallel agents).
3. Skip

   file_stats.py

   and all script-dependent steps.
4. Skip

   /codeprobe diff

   ,

   /codeprobe report

   , and the Codebase Stats row of the audit dashboard (still render scores, hot spots, and findings).
5. Inform the user: "Running in Claude.ai mode — some features like codebase statistics, diff review, and multi-file analysis are unavailable. Analyzing the provided code directly."
6. Still produce findings in the standard output contract format.
7. Still compute scores based on findings from available sub-skills.

10. Phase 3 Stubs

Not yet available. This feature is coming in Phase 3. Currently available commands:

• /codeprobe audit <path>

  — Full code audit

• /codeprobe solid <path>

  — SOLID principles check

• /codeprobe security <path>

  — Security audit

• /codeprobe smells <path>

  — Code smells detection

• /codeprobe architecture <path>

  — Architecture analysis

• /codeprobe patterns <path>

  — Design patterns analysis

• /codeprobe performance <path>

  — Performance audit

• /codeprobe errors <path>

  — Error handling audit

• /codeprobe tests <path>

  — Test quality audit

• /codeprobe framework <path>

  — Framework best practices

• /codeprobe quick <path>

  — Top 5 issues

diff

report

11. Execution Flow Summary

/codeprobe

1. Parse command: Extract subcommand and target path from user input.
2. Validate command: Check routing table. If Phase 3 stub, respond with stub message.
3. Resolve target path: Use provided path or default to current working directory.
4. Load config: Check for

   .codeprobe-config.json

   at project root. Apply defaults if absent.
5. Auto-detect stack: Scan target path for technology signals. Load matching references.
6. Apply config overrides: If

   framework

   is set in config, adjust detection. Apply

   skip_categories

   and

   skip_rules

   .
7. Execute sub-skills: Route to appropriate sub-skills based on command and mode.
8. Collect findings: Aggregate all findings in the output contract format.
9. Deduplicate findings: Apply the cross-category deduplication procedure (Section 7A). Adjust severity of duplicates to

   suggestion

   . Recount severity totals per category.
10. Compute scores: Calculate per-category and overall scores using the post-deduplication severity counts and the formulas in Section 7.
11. Render report: Format output using the appropriate template or inline format. Use the tiered output format for

    /codeprobe audit

    .
12. Present to user: Display the final report.