@dreki-gg/pi-code-reviewer 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @dreki-gg/pi-code-reviewer
+
+Multi-lens code review extension for [pi](https://github.com/earendil-works/pi). Reviews working directory changes through configurable criteria lenses — each project defines its own review standards and tooling.
+
+## Install
+
+```bash
+pi install npm:@dreki-gg/pi-code-reviewer
+```
+
+This is a **project-local** extension. Install it per-project so each project can configure its own lenses and tools.
+
+## Setup
+
+After installing, scaffold the review configuration:
+
+```
+/review-init
+```
+
+This creates:
+- `.code-review.json` — config file (lens directory, default lenses)
+- `.code-review/lenses/` — lens definition files
+
+## Usage
+
+```
+/review                          # Review all changes with all lenses
+/review --lens code-quality      # Single lens
+/review --lens quality,ux        # Multiple lenses
+/review --base main              # Diff against a branch
+/review --staged                 # Only staged changes
+/review-lenses                   # List available lenses
+```
+
+The `code_review` tool is also available for programmatic use by the agent.
+
+## Lenses
+
+A lens is a markdown file that defines review criteria, project tools to run, and severity rules:
+
+```md
+# Code Quality
+
+Evaluates changes for correctness and adherence to project standards.
+
+## Criteria
+- Does the diff introduce new type errors?
+- Are there new unused exports?
+- Does the change follow naming conventions?
+
+## Tools
+- `bun run typecheck`
+- `bun run lint`
+
+## Severity
+- blocker: Type errors, unresolved imports
+- warning: New lint violations, unused code
+- note: Style suggestions
+```
+
+### Bundled lenses
+
+The package ships with four example lenses:
+
+| Lens | Focus |
+| --- | --- |
+| `code-quality` | Correctness, lint, types, dead code |
+| `maintainability` | Coupling, complexity, readability |
+| `product-vision` | Alignment with product direction |
+| `ux-design` | Accessibility, responsiveness, interaction quality |
+
+Run `/review-init` to scaffold these (customized for your project's tools) into `.code-review/lenses/`.
+
+## Configuration
+
+`.code-review.json`:
+
+```json
+{
+  "lensDir": ".code-review/lenses",
+  "defaultLenses": ["code-quality", "maintainability"]
+}
+```
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `lensDir` | `.code-review/lenses` | Directory containing lens files |
+| `defaultLenses` | `[]` (all) | Lenses to run when none specified |
+

package/extensions/code-reviewer/commands/review-init.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import { getConfigPath } from '../config';
+
+export function registerReviewInitCommand(pi: ExtensionAPI) {
+  pi.registerCommand('review-init', {
+    description: 'Scaffold a .code-review/ directory with default lenses for this project',
+    handler: async (_args, ctx) => {
+      const configPath = getConfigPath(ctx.cwd);
+      pi.sendUserMessage(
+        [
+          `Initialize a code review configuration for this project.`,
+          ``,
+          `1. Read the project's AGENTS.md, package.json, and any CONTEXT.md to understand the stack and conventions.`,
+          `2. Create a \`.code-review.json\` config file at the project root.`,
+          `3. Create lens files in \`.code-review/lenses/\` — start with: code-quality.md, maintainability.md`,
+          `4. Each lens should reference the project's actual tools (from package.json scripts).`,
+          `5. Tailor the criteria to the project's stack and conventions.`,
+          ``,
+          `Config path: ${configPath}`,
+        ].join('\n'),
+        { deliverAs: 'followUp' },
+      );
+    },
+  });
+}

package/extensions/code-reviewer/commands/review-lenses.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import { loadConfig, getLensDir } from '../config';
+import { discoverLenses } from '../lenses';
+
+export function registerReviewLensesCommand(pi: ExtensionAPI) {
+  pi.registerCommand('review-lenses', {
+    description: 'List available review lenses for this project',
+    handler: async (_args, ctx) => {
+      const config = loadConfig(ctx.cwd);
+      const lensDir = getLensDir(ctx.cwd, config);
+      const available = discoverLenses(lensDir);
+
+      if (available.size === 0) {
+        ctx.ui.notify(
+          `No lenses in ${config.lensDir}. Run /review-init to scaffold defaults.`,
+          'warning',
+        );
+        return;
+      }
+
+      const lines = [`Available lenses (${config.lensDir}):`, ''];
+      for (const [key, lens] of available) {
+        const isDefault = config.defaultLenses.includes(key);
+        const marker = isDefault ? ' ★' : '';
+        const tools = lens.tools.length > 0 ? ` [${lens.tools.length} tool(s)]` : '';
+        lines.push(`  ${key}${marker} — ${lens.description}${tools}`);
+      }
+
+      if (config.defaultLenses.length > 0) {
+        lines.push('');
+        lines.push(`★ = default lens (runs when no --lens specified)`);
+      }
+
+      ctx.ui.notify(lines.join('\n'), 'info');
+    },
+  });
+}

package/extensions/code-reviewer/commands/review-tool.ts

@@ -0,0 +1,135 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+import { loadConfig, getLensDir } from '../config';
+import { collectDiff, getChangedFiles } from '../diff';
+import { discoverLenses, getLensContent } from '../lenses';
+import { reviewWithLens } from '../reviewer';
+import { buildReport } from '../report';
+import type { LensResult, ReviewConfig, ReviewReport } from '../types';
+
+export function registerReviewTool(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: 'code_review',
+    label: 'Code Review',
+    description:
+      'Run a multi-lens code review on the current working directory changes. Returns review findings grouped by lens.',
+    promptSnippet: 'Run a multi-lens code review against working directory changes',
+    promptGuidelines: [
+      'Use code_review when the user asks to review their changes, check code quality, or before committing.',
+      'code_review reads lens definitions from .code-review/lenses/ in the project root.',
+    ],
+    parameters: Type.Object({
+      lenses: Type.Optional(
+        Type.Array(Type.String(), {
+          description:
+            'Specific lenses to apply. If omitted, uses project defaults or all available.',
+        }),
+      ),
+      base: Type.Optional(
+        Type.String({
+          description: 'Git ref to diff against (e.g., "main", "HEAD~3"). Defaults to HEAD.',
+        }),
+      ),
+      staged: Type.Optional(
+        Type.Boolean({
+          description: 'Review only staged changes instead of all working directory changes.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const cwd = ctx.cwd;
+      const config = loadConfig(cwd);
+      const lensDir = getLensDir(cwd, config);
+      const available = discoverLenses(lensDir);
+
+      if (available.size === 0) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `No lenses found in ${config.lensDir}. Run /review-init to scaffold a default config, or create .code-review/lenses/*.md files.`,
+            },
+          ],
+          details: {},
+        };
+      }
+
+      const lensNames = resolveLensNames(params.lenses, config, available);
+
+      const diff = await collectDiff(pi, cwd, {
+        base: params.base,
+        staged: params.staged,
+      });
+
+      if (!diff.diff.trim()) {
+        return {
+          content: [{ type: 'text', text: 'No changes to review.' }],
+          details: {},
+        };
+      }
+
+      const results: LensResult[] = [];
+      for (const name of lensNames) {
+        if (signal?.aborted) break;
+
+        const lens = available.get(name)!;
+        const content = getLensContent(lensDir, name) ?? '';
+        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff, signal);
+        results.push(result);
+      }
+
+      const report: ReviewReport = {
+        diff: diff.diff,
+        diffStat: diff.stat,
+        lenses: results,
+        generatedAt: new Date().toISOString().slice(0, 10),
+      };
+
+      const markdown = buildReport(report);
+      const toolContext = buildToolContext(results);
+
+      return {
+        content: [{ type: 'text', text: markdown + toolContext }],
+        details: {
+          lensCount: lensNames.length,
+          availableLenses: [...available.keys()],
+          changedFiles: await getChangedFiles(pi, cwd, {
+            base: params.base,
+            staged: params.staged,
+          }),
+        },
+      };
+    },
+  });
+}
+
+function resolveLensNames(
+  requested: string[] | undefined,
+  config: ReviewConfig,
+  available: Map<string, unknown>,
+): string[] {
+  if (requested && requested.length > 0) {
+    return requested.filter((l) => available.has(l));
+  }
+  if (config.defaultLenses.length > 0) {
+    return config.defaultLenses.filter((l) => available.has(l));
+  }
+  return [...available.keys()];
+}
+
+function buildToolContext(results: LensResult[]): string {
+  const prompts = results.map((r) => r._prompt).filter(Boolean);
+
+  if (prompts.length === 0) return '';
+
+  return [
+    '',
+    '---',
+    '',
+    'The tool outputs above provide automated analysis. Now evaluate the diff through each lens criteria:',
+    '',
+    ...prompts,
+  ].join('\n');
+}

package/extensions/code-reviewer/commands/review.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import { loadConfig, getLensDir } from '../config';
+import { collectDiff } from '../diff';
+import { discoverLenses, getLensContent } from '../lenses';
+import { reviewWithLens } from '../reviewer';
+import { parseReviewArgs } from '../parse-args';
+
+export function registerReviewCommand(pi: ExtensionAPI) {
+  pi.registerCommand('review', {
+    description:
+      'Run a multi-lens code review on working directory changes. Usage: /review [--lens name,...] [--base ref] [--staged]',
+    handler: async (args, ctx) => {
+      const cwd = ctx.cwd;
+      const config = loadConfig(cwd);
+      const lensDir = getLensDir(cwd, config);
+      const available = discoverLenses(lensDir);
+
+      if (available.size === 0) {
+        ctx.ui.notify(
+          `No lenses found in ${config.lensDir}. Run /review-init to scaffold a default config.`,
+          'warning',
+        );
+        return;
+      }
+
+      const parsed = parseReviewArgs(args ?? '');
+      const lensNames = resolveLensNames(parsed.lenses, config.defaultLenses, available, (msg) =>
+        ctx.ui.notify(msg, 'warning'),
+      );
+
+      if (lensNames.length === 0) {
+        ctx.ui.notify('No lenses selected', 'warning');
+        return;
+      }
+
+      const diff = await collectDiff(pi, cwd, {
+        base: parsed.base,
+        staged: parsed.staged,
+      });
+
+      if (!diff.diff.trim()) {
+        ctx.ui.notify('No changes to review', 'info');
+        return;
+      }
+
+      ctx.ui.notify(`Reviewing ${diff.label} through ${lensNames.length} lens(es)...`, 'info');
+
+      const lensPrompts: string[] = [];
+      for (const name of lensNames) {
+        const lens = available.get(name)!;
+        const content = getLensContent(lensDir, name) ?? '';
+        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff);
+
+        if (result._prompt) {
+          lensPrompts.push(result._prompt);
+        }
+      }
+
+      const combinedPrompt = [
+        `Review the following changes through ${lensNames.length} lens(es): ${lensNames.join(', ')}.`,
+        '',
+        'For each lens, evaluate the diff against its criteria and produce findings.',
+        'Output your review as a structured report with sections per lens.',
+        '',
+        ...lensPrompts,
+      ].join('\n');
+
+      pi.sendUserMessage(combinedPrompt, { deliverAs: 'followUp' });
+    },
+  });
+}
+
+/** Resolve which lens names to run based on explicit selection, defaults, or all available. */
+function resolveLensNames(
+  requested: string[],
+  defaults: string[],
+  available: Map<string, unknown>,
+  warn: (msg: string) => void,
+): string[] {
+  if (requested.length > 0) {
+    const missing = requested.filter((l) => !available.has(l));
+    if (missing.length > 0) warn(`Unknown lenses: ${missing.join(', ')}`);
+    return requested.filter((l) => available.has(l));
+  }
+
+  if (defaults.length > 0) {
+    return defaults.filter((l) => available.has(l));
+  }
+
+  return [...available.keys()];
+}

package/extensions/code-reviewer/config.ts

@@ -0,0 +1,36 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ReviewConfig } from './types';
+
+const CONFIG_FILE = '.code-review.json';
+const DEFAULT_LENS_DIR = '.code-review/lenses';
+
+export function loadConfig(cwd: string): ReviewConfig {
+  const configPath = resolve(cwd, CONFIG_FILE);
+
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(configPath, 'utf-8');
+      const parsed = JSON.parse(raw) as Partial<ReviewConfig>;
+      return {
+        lensDir: parsed.lensDir ?? DEFAULT_LENS_DIR,
+        defaultLenses: parsed.defaultLenses ?? [],
+      };
+    } catch {
+      // Malformed config — fall back to defaults
+    }
+  }
+
+  return {
+    lensDir: DEFAULT_LENS_DIR,
+    defaultLenses: [],
+  };
+}
+
+export function getLensDir(cwd: string, config: ReviewConfig): string {
+  return resolve(cwd, config.lensDir);
+}
+
+export function getConfigPath(cwd: string): string {
+  return resolve(cwd, CONFIG_FILE);
+}

package/extensions/code-reviewer/diff.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+export type DiffSource = {
+  diff: string;
+  stat: string;
+  label: string;
+};
+
+/** Collect the diff from the working directory or a specific base ref. */
+export async function collectDiff(
+  pi: ExtensionAPI,
+  cwd: string,
+  options: { base?: string; staged?: boolean },
+): Promise<DiffSource> {
+  if (options.staged) {
+    const diff = await pi.exec('git', ['diff', '--staged'], { cwd });
+    const stat = await pi.exec('git', ['diff', '--staged', '--stat'], { cwd });
+    return {
+      diff: diff.stdout,
+      stat: stat.stdout,
+      label: 'staged changes',
+    };
+  }
+
+  if (options.base) {
+    const diff = await pi.exec('git', ['diff', options.base], { cwd });
+    const stat = await pi.exec('git', ['diff', options.base, '--stat'], { cwd });
+    return {
+      diff: diff.stdout,
+      stat: stat.stdout,
+      label: `changes since ${options.base}`,
+    };
+  }
+
+  // Default: working directory changes (unstaged + staged)
+  const diff = await pi.exec('git', ['diff', 'HEAD'], { cwd });
+  const stat = await pi.exec('git', ['diff', 'HEAD', '--stat'], { cwd });
+
+  // If no HEAD diff, fall back to just working directory
+  if (!diff.stdout.trim()) {
+    const wdDiff = await pi.exec('git', ['diff'], { cwd });
+    const wdStat = await pi.exec('git', ['diff', '--stat'], { cwd });
+    return {
+      diff: wdDiff.stdout,
+      stat: wdStat.stdout,
+      label: 'working directory changes',
+    };
+  }
+
+  return {
+    diff: diff.stdout,
+    stat: stat.stdout,
+    label: 'all uncommitted changes',
+  };
+}
+
+/** Get a list of changed file paths from the diff. */
+export async function getChangedFiles(
+  pi: ExtensionAPI,
+  cwd: string,
+  options: { base?: string; staged?: boolean },
+): Promise<string[]> {
+  const args = ['diff', '--name-only'];
+
+  if (options.staged) {
+    args.push('--staged');
+  } else if (options.base) {
+    args.push(options.base);
+  } else {
+    args.push('HEAD');
+  }
+
+  const result = await pi.exec('git', args, { cwd });
+  return result.stdout
+    .split('\n')
+    .map((f) => f.trim())
+    .filter(Boolean);
+}

package/extensions/code-reviewer/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import { registerReviewCommand } from './commands/review';
+import { registerReviewInitCommand } from './commands/review-init';
+import { registerReviewLensesCommand } from './commands/review-lenses';
+import { registerReviewTool } from './commands/review-tool';
+
+export default function codeReviewerExtension(pi: ExtensionAPI) {
+  registerReviewCommand(pi);
+  registerReviewInitCommand(pi);
+  registerReviewLensesCommand(pi);
+  registerReviewTool(pi);
+}

package/extensions/code-reviewer/lenses.ts

@@ -0,0 +1,117 @@
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import type { LensConfig, LensSeverity } from './types';
+
+type SectionKind = 'top' | 'criteria' | 'tools' | 'severity';
+
+const SECTION_MAP: Record<string, SectionKind> = {
+  '## criteria': 'criteria',
+  '## tools': 'tools',
+  '## severity': 'severity',
+};
+
+type ParseState = {
+  name: string;
+  description: string;
+  criteriaLines: string[];
+  tools: string[];
+  severityRules: Record<LensSeverity, string>;
+};
+
+type LineHandler = (trimmed: string, state: ParseState) => void;
+
+const SECTION_HANDLERS: Record<SectionKind, LineHandler> = {
+  top: (trimmed, state) => {
+    if (!state.description) state.description = trimmed;
+  },
+  criteria: (trimmed, state) => state.criteriaLines.push(trimmed),
+  tools: (trimmed, state) => parseTool(trimmed, state.tools),
+  severity: (trimmed, state) => parseSeverityRule(trimmed, state.severityRules),
+};
+
+/** Parse a lens markdown file into a structured LensConfig. */
+function parseLensFile(content: string, filename: string): LensConfig {
+  const state: ParseState = {
+    name: basename(filename, '.md'),
+    description: '',
+    criteriaLines: [],
+    tools: [],
+    severityRules: { blocker: '', warning: '', note: '' },
+  };
+
+  let section: SectionKind = 'top';
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('# ') && !trimmed.startsWith('## ')) {
+      state.name = trimmed.slice(2).trim();
+      continue;
+    }
+
+    const nextSection = detectSection(trimmed);
+    if (nextSection !== undefined) {
+      section = nextSection;
+      continue;
+    }
+
+    if (trimmed) SECTION_HANDLERS[section](trimmed, state);
+  }
+
+  return {
+    name: state.name,
+    description: state.description,
+    criteria: state.criteriaLines.join('\n'),
+    tools: state.tools,
+    severityRules: state.severityRules,
+  };
+}
+
+/** Detect which section a heading line introduces, or undefined if not a section heading. */
+function detectSection(trimmed: string): SectionKind | undefined {
+  if (!trimmed.startsWith('## ')) return undefined;
+  return SECTION_MAP[trimmed.toLowerCase()] ?? 'top';
+}
+
+/** Extract a tool command from a list item line. */
+function parseTool(trimmed: string, tools: string[]): void {
+  const backtickMatch = trimmed.match(/^-\s*`(.+)`$/);
+  if (backtickMatch) {
+    tools.push(backtickMatch[1]);
+  } else if (trimmed.startsWith('- ') && trimmed.length > 2) {
+    tools.push(trimmed.slice(2));
+  }
+}
+
+/** Extract a severity rule from a list item line. */
+function parseSeverityRule(trimmed: string, rules: Record<LensSeverity, string>): void {
+  const match = trimmed.match(/^-\s*(blocker|warning|note):\s*(.+)$/i);
+  if (match) {
+    rules[match[1].toLowerCase() as LensSeverity] = match[2];
+  }
+}
+
+/** Discover all lens files in a directory. */
+export function discoverLenses(lensDir: string): Map<string, LensConfig> {
+  const lenses = new Map<string, LensConfig>();
+
+  if (!existsSync(lensDir)) return lenses;
+
+  const files = readdirSync(lensDir).filter((f) => f.endsWith('.md'));
+
+  for (const file of files) {
+    const content = readFileSync(resolve(lensDir, file), 'utf-8');
+    const config = parseLensFile(content, file);
+    const key = basename(file, '.md');
+    lenses.set(key, config);
+  }
+
+  return lenses;
+}
+
+/** Get raw markdown content for a lens to pass to the reviewer agent. */
+export function getLensContent(lensDir: string, lensName: string): string | null {
+  const filePath = resolve(lensDir, `${lensName}.md`);
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, 'utf-8');
+}

package/extensions/code-reviewer/parse-args.ts

@@ -0,0 +1,25 @@
+/** Parse /review command arguments into structured options. */
+export function parseReviewArgs(args: string): {
+  lenses: string[];
+  base?: string;
+  staged: boolean;
+} {
+  const lenses: string[] = [];
+  let base: string | undefined;
+  let staged = false;
+
+  const parts = args.split(/\s+/).filter(Boolean);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part === '--lens' && i + 1 < parts.length) {
+      lenses.push(...parts[++i].split(','));
+    } else if (part === '--base' && i + 1 < parts.length) {
+      base = parts[++i];
+    } else if (part === '--staged') {
+      staged = true;
+    }
+  }
+
+  return { lenses, base, staged };
+}

package/extensions/code-reviewer/report.ts

@@ -0,0 +1,109 @@
+import type { LensFinding, LensResult, LensSeverity, ReviewReport } from './types';
+
+/** Build a markdown report from lens results. */
+export function buildReport(report: ReviewReport): string {
+  const sections = [
+    `# Code Review — ${report.generatedAt}`,
+    '',
+    buildChangesSection(report.diffStat),
+    buildScoreboard(report.lenses),
+    ...report.lenses.map(buildLensSection),
+  ];
+
+  return sections.join('\n');
+}
+
+function buildChangesSection(diffStat: string): string {
+  return ['## Changes', '', '```', diffStat, '```', ''].join('\n');
+}
+
+function buildScoreboard(lenses: LensResult[]): string {
+  const counts = countFindings(lenses);
+  return [
+    '## Scoreboard',
+    '',
+    '| Metric | Count |',
+    '| --- | --- |',
+    `| **Total findings** | **${counts.total}** |`,
+    `| 🔴 Blockers | ${counts.blocker} |`,
+    `| 🟡 Warnings | ${counts.warning} |`,
+    `| 🔵 Notes | ${counts.note} |`,
+    `| Lenses applied | ${lenses.length} |`,
+    '',
+  ].join('\n');
+}
+
+function countFindings(lenses: LensResult[]): Record<LensSeverity | 'total', number> {
+  const counts = { blocker: 0, warning: 0, note: 0, total: 0 };
+  for (const lens of lenses) {
+    for (const f of lens.findings) {
+      counts[f.severity]++;
+      counts.total++;
+    }
+  }
+  return counts;
+}
+
+function buildLensSection(lens: LensResult): string {
+  const lines: string[] = [`## ${lens.lens}`, ''];
+
+  if (lens.findings.length === 0) {
+    lines.push('No findings. ✓', '');
+    if (lens.summary) lines.push(lens.summary, '');
+    return lines.join('\n');
+  }
+
+  lines.push(buildFindingsByGroup(lens.findings));
+
+  if (lens.summary) {
+    lines.push(`**Summary:** ${lens.summary}`, '');
+  }
+
+  if (lens.toolOutputs && Object.keys(lens.toolOutputs).length > 0) {
+    lines.push(buildToolOutputDetails(lens.toolOutputs));
+  }
+
+  return lines.join('\n');
+}
+
+const SEVERITY_ICONS: Record<LensSeverity, string> = {
+  blocker: '🔴',
+  warning: '🟡',
+  note: '🔵',
+};
+
+function buildFindingsByGroup(findings: LensFinding[]): string {
+  const lines: string[] = [];
+  const severities: LensSeverity[] = ['blocker', 'warning', 'note'];
+
+  for (const severity of severities) {
+    const group = findings.filter((f) => f.severity === severity);
+    if (group.length === 0) continue;
+
+    const label = severity.charAt(0).toUpperCase() + severity.slice(1);
+    lines.push(`### ${SEVERITY_ICONS[severity]} ${label}s (${group.length})`, '');
+
+    for (const f of group) {
+      const loc = f.line ? `${f.file}:${f.line}` : f.file;
+      lines.push(`- \`${loc}\` — ${f.message}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function buildToolOutputDetails(toolOutputs: Record<string, string>): string {
+  const lines = [
+    '<details>',
+    `<summary>Tool outputs (${Object.keys(toolOutputs).length})</summary>`,
+    '',
+  ];
+
+  for (const [cmd, output] of Object.entries(toolOutputs)) {
+    lines.push(`**\`${cmd}\`**`, '```', output.slice(0, 5000), '```');
+  }
+
+  lines.push('</details>', '');
+  return lines.join('\n');
+}

package/extensions/code-reviewer/reviewer.ts

@@ -0,0 +1,130 @@
+import { platform } from 'node:os';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { DiffSource } from './diff';
+import type { LensConfig, LensResult } from './types';
+
+const isWindows = platform() === 'win32';
+
+/** Run project tools specified by a lens and collect their output. */
+async function runLensTools(
+  pi: ExtensionAPI,
+  cwd: string,
+  tools: string[],
+  signal?: AbortSignal,
+): Promise<Record<string, string>> {
+  const outputs: Record<string, string> = {};
+
+  for (const tool of tools) {
+    if (signal?.aborted) break;
+
+    try {
+      const [shell, shellArgs] = isWindows ? ['cmd', ['/c', tool]] : ['sh', ['-c', tool]];
+      const result = await pi.exec(shell, shellArgs, {
+        cwd,
+        timeout: 60_000,
+        signal,
+      });
+      outputs[tool] = result.stdout || result.stderr || '(no output)';
+    } catch {
+      outputs[tool] = `(tool failed or timed out: ${tool})`;
+    }
+  }
+
+  return outputs;
+}
+
+/** Build the review prompt for a single lens. */
+function buildReviewPrompt(
+  lens: LensConfig,
+  lensContent: string,
+  diff: DiffSource,
+  toolOutputs: Record<string, string>,
+): string {
+  const parts: string[] = [];
+
+  parts.push(`You are reviewing code changes through the "${lens.name}" lens.`);
+  parts.push('');
+  parts.push('## Lens Definition');
+  parts.push(lensContent);
+  parts.push('');
+  parts.push(`## Diff (${diff.label})`);
+  const maxDiffLen = 50_000;
+  const diffTruncated = diff.diff.length > maxDiffLen;
+  parts.push('```diff');
+  parts.push(diff.diff.slice(0, maxDiffLen));
+  parts.push('```');
+  if (diffTruncated) {
+    parts.push(
+      `> ⚠️ Diff truncated (${diff.diff.length} chars → ${maxDiffLen}). Some files may not appear above.`,
+    );
+  }
+  parts.push('');
+  parts.push('## Diff Stats');
+  parts.push('```');
+  parts.push(diff.stat);
+  parts.push('```');
+
+  if (Object.keys(toolOutputs).length > 0) {
+    parts.push('');
+    parts.push('## Tool Outputs');
+    for (const [cmd, output] of Object.entries(toolOutputs)) {
+      parts.push(`### \`${cmd}\``);
+      parts.push('```');
+      parts.push(output.slice(0, 20_000));
+      parts.push('```');
+    }
+  }
+
+  parts.push('');
+  parts.push('## Instructions');
+  parts.push('');
+  parts.push('Review the diff through this lens. For each finding, output a JSON array:');
+  parts.push('');
+  parts.push('```json');
+  parts.push('[');
+  parts.push(
+    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
+  );
+  parts.push(']');
+  parts.push('```');
+  parts.push('');
+  parts.push('Severity levels:');
+  if (lens.severityRules.blocker) parts.push(`- **blocker**: ${lens.severityRules.blocker}`);
+  if (lens.severityRules.warning) parts.push(`- **warning**: ${lens.severityRules.warning}`);
+  if (lens.severityRules.note) parts.push(`- **note**: ${lens.severityRules.note}`);
+  parts.push('');
+  parts.push(
+    'After the JSON array, write a 2-3 sentence summary of your review through this lens.',
+  );
+  parts.push('If there are no findings, return an empty array `[]` and note the code looks good.');
+
+  return parts.join('\n');
+}
+
+/** Execute a review for a single lens using the subagent tool. */
+export async function reviewWithLens(
+  pi: ExtensionAPI,
+  _ctx: unknown,
+  cwd: string,
+  lens: LensConfig,
+  lensContent: string,
+  diff: DiffSource,
+  signal?: AbortSignal,
+): Promise<LensResult> {
+  // Run lens tools first
+  const toolOutputs = await runLensTools(pi, cwd, lens.tools, signal);
+
+  // Build the prompt
+  const prompt = buildReviewPrompt(lens, lensContent, diff, toolOutputs);
+
+  // Use sendMessage to delegate to the agent for review
+  // For now, we return the prompt and let the command handler
+  // pass it to a subagent via the subagent tool
+  return {
+    lens: lens.name,
+    findings: [],
+    summary: '',
+    toolOutputs,
+    _prompt: prompt,
+  };
+}

package/extensions/code-reviewer/types.ts

@@ -0,0 +1,37 @@
+export type LensSeverity = 'blocker' | 'warning' | 'note';
+
+export type LensFinding = {
+  file: string;
+  line?: number;
+  severity: LensSeverity;
+  message: string;
+};
+
+export type LensConfig = {
+  name: string;
+  description: string;
+  criteria: string;
+  tools: string[];
+  severityRules: Record<LensSeverity, string>;
+};
+
+export type LensResult = {
+  lens: string;
+  findings: LensFinding[];
+  summary: string;
+  toolOutputs?: Record<string, string>;
+  /** Review prompt built for this lens, used internally to delegate to the agent. */
+  _prompt?: string;
+};
+
+export type ReviewConfig = {
+  lensDir: string;
+  defaultLenses: string[];
+};
+
+export type ReviewReport = {
+  diff: string;
+  diffStat: string;
+  lenses: LensResult[];
+  generatedAt: string;
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@dreki-gg/pi-code-reviewer",
+  "version": "0.1.0",
+  "description": "Multi-lens code review extension for pi — configurable review criteria per project",
+  "keywords": [
+    "pi-package"
+  ],
+  "author": "Juan Albarran <jalbarrandev@gmail.com>",
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreki-gg/pi-extensions",
+    "directory": "packages/code-reviewer"
+  },
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint extensions",
+    "format": "oxfmt --write extensions",
+    "format:check": "oxfmt --check extensions"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/code-reviewer"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "24",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: code-review
+description: Multi-lens code review against working directory changes. Evaluates diffs through configurable criteria like code-quality, maintainability, product-vision, and ux-design. Use when user says "review my changes", "review this code", "check before committing", or "code review".
+---
+
+# Code Review
+
+Review working directory changes through configurable lenses — each lens evaluates the diff against specific criteria and project tools.
+
+## Quick start
+
+```
+/review                          # All lenses, working dir diff
+/review --lens code-quality      # Single lens
+/review --lens quality,ux        # Multiple lenses
+/review --base main              # Diff against a branch
+/review --staged                 # Only staged changes
+/review-lenses                   # List available lenses
+/review-init                     # Scaffold lenses for this project
+```
+
+Or use the `code_review` tool directly for programmatic access.
+
+
+## Lens format
+
+Each lens is a markdown file in `.code-review/lenses/`:
+
+```md
+# Lens Name
+
+Description of what this lens evaluates.
+
+## Criteria
+- Evaluation point 1
+- Evaluation point 2
+
+## Tools
+- `bun run typecheck`
+- `bun run codeql:fallow -- --changed-since HEAD`
+
+## Severity
+- blocker: What constitutes a blocking issue
+- warning: What constitutes a warning
+- note: What constitutes a note
+```
+
+## Configuration
+
+Optional `.code-review.json` at project root:
+
+```json
+{
+  "lensDir": ".code-review/lenses",
+  "defaultLenses": ["code-quality", "maintainability"]
+}
+```

package/skills/code-review/lenses/README.md

@@ -0,0 +1,8 @@
+# Example Lenses
+
+These are reference lenses that ship with the `@dreki-gg/pi-code-reviewer` package.
+
+To use them in your project, run `/review-init` which will scaffold a `.code-review/lenses/` directory
+tailored to your project's tools and conventions.
+
+You can also copy these files directly into your project's `.code-review/lenses/` directory and customize them.

package/skills/code-review/lenses/code-quality.md

@@ -0,0 +1,20 @@
+# Code Quality
+
+Evaluates changes for correctness, dead code introduction, and adherence to project lint/type standards.
+
+## Criteria
+- Does the diff introduce new lint violations or type errors?
+- Are there new unused exports, imports, or variables?
+- Does the change follow existing naming conventions?
+- Are error cases handled properly?
+- Are there any obvious bugs or logic errors?
+- Does the code avoid known anti-patterns for the project's framework?
+
+## Tools
+- `bun run typecheck`
+- `bun run lint`
+
+## Severity
+- blocker: Type errors, unresolved imports, obvious bugs, unhandled error paths
+- warning: New lint violations, unused code, inconsistent naming
+- note: Style suggestions, minor improvements

package/skills/code-review/lenses/maintainability.md

@@ -0,0 +1,20 @@
+# Maintainability
+
+Evaluates whether changes will be easy to understand, modify, and extend in the future.
+
+## Criteria
+- Is the code well-organized with clear separation of concerns?
+- Are functions and components reasonably sized (not giant)?
+- Are there clear abstractions or is logic tangled?
+- Does the change increase coupling between modules?
+- Would a new team member understand this code without extensive context?
+- Are there magic numbers, hardcoded values, or unclear abbreviations?
+- Is there adequate documentation for complex logic?
+- Does the change duplicate existing patterns instead of reusing them?
+
+## Tools
+
+## Severity
+- blocker: Introduces tight coupling across module boundaries, creates circular dependencies
+- warning: Large functions (>100 lines), duplicated logic, unclear naming, missing docs on complex code
+- note: Opportunities to simplify, extract, or clarify

package/skills/code-review/lenses/product-vision.md

@@ -0,0 +1,19 @@
+# Product Vision
+
+Evaluates whether changes align with the product direction and serve real user needs.
+
+## Criteria
+- Does this change serve existing users or is it speculative?
+- Does it introduce UI concepts or flows that don't exist elsewhere in the app?
+- Does it add unnecessary complexity to user-facing functionality?
+- Does it respect the established information architecture?
+- Is the feature discoverable and intuitive?
+- Does it follow the project's domain language (check CONTEXT.md if it exists)?
+- Are there simpler alternatives that would achieve the same user goal?
+
+## Tools
+
+## Severity
+- blocker: Changes that contradict the product direction or break existing user workflows
+- warning: Speculative features, unnecessary complexity, inconsistent UX patterns
+- note: Opportunities to better align with product vision

package/skills/code-review/lenses/ux-design.md

@@ -0,0 +1,20 @@
+# UX Design
+
+Evaluates the user experience quality of UI changes — accessibility, responsiveness, and interaction design.
+
+## Criteria
+- Are interactive elements accessible (keyboard navigation, ARIA labels, focus management)?
+- Are loading and error states handled visually?
+- Is the layout responsive or does it break at common viewport sizes?
+- Are animations purposeful and not distracting (100-200ms, no bouncy effects)?
+- Is text readable (minimum 12px body, sufficient contrast)?
+- Are form inputs properly labeled with clear validation feedback?
+- Does the change follow the project's existing component patterns?
+- Are click targets large enough for touch (minimum 44px)?
+
+## Tools
+
+## Severity
+- blocker: Missing keyboard accessibility on interactive elements, broken layout, no error states on data-fetching UI
+- warning: Missing ARIA labels, tiny text (<12px), missing loading states, non-responsive layout
+- note: Animation polish, spacing consistency, component reuse opportunities