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)

```bash
# 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:

```yaml
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:

```yaml
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)

```yaml
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:

```markdown
# {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):**
```yaml
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)
```bash
lev code-review --scope core/{index,memory,polyglot-runners} --quick
```

### Full Audit
```bash
lev code-review --scope core/ --full
```

### Resume from Checkpoint
```bash
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:**
```javascript
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]
```