lev-code-review

# 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] ```