lev-code-review

name	lev-code-review
description	Code organization and modularity audit with parallel agent inspection. Creates XDG-compatible artifact reports using lev-ref validation patterns. Use when auditing code structure, checking fractal compliance, or reviewing module organization.

lev-code-review

Multi-agent code review orchestrator that dispatches parallel inspection agents, validates against lev-ref patterns, and saves templated artifacts to XDG-compatible scratch folders.

When to Use

Triggers:

• "audit the codebase"
• "check module compliance"
• "run code organization review"
• "inspect core/ structure"
• "fractal compliance check"

Configuration

Scratch Folder (XDG-Compatible)

# Default location
SCRATCH_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/lev/scratch/code-review"

# Session-specific subfolder
SESSION_DIR="$SCRATCH_DIR/$(date +%Y%m%d-%H%M%S)"

Artifacts are saved to ~/.config/lev/scratch/code-review/ by default.

Parallel Agent Inspection Plan

Phase 1: Structure Analysis (Parallel)

Launch 4 agents simultaneously:

agents:
  - name: package-compliance
    focus: "Check package.json presence, @lev-os/* namespace, leviathan field"
    output: "$SESSION_DIR/01-package-compliance.md"

  - name: config-compliance
    focus: "Check config.yaml presence, fractal declarations, poly.sdk"
    output: "$SESSION_DIR/02-config-compliance.md"

  - name: structure-compliance
    focus: "Check src/, tests/, README.md, required directories"
    output: "$SESSION_DIR/03-structure-compliance.md"

  - name: anomaly-detection
    focus: "Find nested duplicates, orphaned node_modules, empty stubs"
    output: "$SESSION_DIR/04-anomalies.md"

Phase 2: Deep Analysis (Parallel)

After Phase 1 completes:

agents:
  - name: import-patterns
    focus: "Validate ES module exports, command patterns, tool exports"
    output: "$SESSION_DIR/05-import-patterns.md"

  - name: test-coverage
    focus: "Check test presence, naming conventions, test structure"
    output: "$SESSION_DIR/06-test-coverage.md"

  - name: dependency-audit
    focus: "Hoisting issues, local vs workspace deps, peer deps"
    output: "$SESSION_DIR/07-dependencies.md"

Phase 3: Synthesis (Sequential)

agents:
  - name: synthesizer
    focus: "Merge all artifacts into compliance matrix and recommendations"
    inputs: "$SESSION_DIR/*.md"
    output: "$SESSION_DIR/REPORT.md"

Artifact Template

Each agent produces a markdown artifact following this template:

# {Agent Name} Report

**Generated:** {ISO timestamp}
**Scope:** {directories analyzed}
**Confidence:** {N%} - {reason}

## Summary

{2-3 sentence overview}

## Findings

### Compliant
| Module | Status | Notes |
|--------|--------|-------|
| ... | ... | ... |

### Non-Compliant
| Module | Issue | Recommendation |
|--------|-------|----------------|
| ... | ... | ... |

### Anomalies
{If any detected}

## Metrics

- Total modules: {N}
- Compliant: {N} ({%})
- Partial: {N} ({%})
- Non-compliant: {N} ({%})

## Next Actions

1. {Action 1}
2. {Action 2}
...

---
*Report generated by lev-code-review agent: {agent-name}*

lev-ref Integration

Apply these patterns from lev-ref throughout:

Confidence Scoring (per finding)

[95% confident] Missing package.json (clear file absence)
[70% confident] Should merge schema/ dirs (multiple valid approaches)
[50% confident] CDO decomposition strategy (needs human input)

Validation Gates (Two-Tier)

Tier 1 - Universal (always check):

universal_gates:
  namespace_compliance:
    check: "All package.json use @lev-os/*"
    type: command
    command: "grep -r '\"name\":' core/*/package.json | grep -v @lev-os"
    pass: "empty output"

  structure_presence:
    check: "Required directories exist"
    type: file_check
    files: ["package.json", "src/", "README.md"]

  no_nested_duplicates:
    check: "No recursive directory structures"
    type: command
    command: "find core -type d -name 'core' | grep -v node_modules"

Tier 2 - Dynamic (per module): Generated based on module type (core vs plugin, fractal owner vs consumer).

Enriched Response Protocol

All outputs follow lev-ref inline conventions:

[92% confident] 5 modules fully compliant (package.json + config.yaml + tests)

💡 Tip: Use `index` and `memory` as reference implementations

→ Next: Fix auth-sniffer/core/ nested duplicate
→ Related: Review CDO monolith decomposition strategy

[Resume: lev-code-review --continue $SESSION_DIR]

Execution

Quick Audit (5 modules)

lev code-review --scope core/{index,memory,polyglot-runners} --quick

Full Audit

lev code-review --scope core/ --full

Resume from Checkpoint

lev code-review --continue ~/.config/lev/scratch/code-review/20260113-165432

Standards Reference

Fractal Compliance (from PACKAGE_SCHEMA.md)

Required for all core/ modules:*

• package.json with @lev-os/* namespace
• package.json.leviathan field for core packages
• config.yaml for fractal owners or consumers

Required structure:

core/{module}/
├── package.json      # @lev-os/{name}, leviathan field
├── config.yaml       # Fractal declarations (if applicable)
├── README.md         # Documentation
├── src/              # Source code
│   └── commands/     # Command handlers (if CLI)
└── tests/            # Test suite

File naming:

• JavaScript/TypeScript: kebab-case.js
• Go: snake_case.go

Command pattern:

export const metadata = { name, namespace, description, args }
export async function handler(args, deps) { /* ... */ }
export default { metadata, handler }

Output Location

Final reports are saved to:

~/.config/lev/scratch/code-review/
└── {session-timestamp}/
    ├── 01-package-compliance.md
    ├── 02-config-compliance.md
    ├── 03-structure-compliance.md
    ├── 04-anomalies.md
    ├── 05-import-patterns.md
    ├── 06-test-coverage.md
    ├── 07-dependencies.md
    └── REPORT.md          # Synthesized final report

Example Invocation

User: run a code review on core/

Agent: [Using lev-code-review skill]

Launching parallel inspection agents...

Phase 1: Structure Analysis
├─ [package-compliance] Scanning 30 modules...
├─ [config-compliance] Checking config.yaml presence...
├─ [structure-compliance] Validating directory layouts...
└─ [anomaly-detection] Searching for issues...

[✓] Phase 1 complete. 4 artifacts saved to ~/.config/lev/scratch/code-review/20260113-170000/

Phase 2: Deep Analysis
├─ [import-patterns] Analyzing exports...
├─ [test-coverage] Checking test structure...
└─ [dependency-audit] Reviewing hoisting...

[✓] Phase 2 complete. 3 artifacts saved.

Phase 3: Synthesis
└─ [synthesizer] Merging findings...

[✓] Final report: ~/.config/lev/scratch/code-review/20260113-170000/REPORT.md

[90% confident] Audit complete

Summary:
- 5 fully compliant (index, memory, validation, triggers, polyglot-runners)
- 12 partially compliant (missing config.yaml or tests)
- 13 non-compliant (no package.json or empty stubs)

💡 Tip: Use `index` as reference for new modules

→ Next: Fix auth-sniffer/core/ nested duplicate
→ Related: Review CDO decomposition (822MB monolith)

[Resume: lev code-review --continue 20260113-170000]