Code Review Skill — Principal Engineering Board

A code review skill that simulates a board of principal engineers with 20+ years of production real experience. Primary focus on TypeScript, NestJS, Express, Fastify, and the full Node.js ecosystem.

Compatible with opencode, claude-code, and GitHub Copilot.

Published on npm: https://www.npmjs.com/package/pe-board-review
Install globally: npm install -g pe-board-review

⚡ Quick Start

# Install globally (works with opencode and GitHub Copilot automatically)
npm install -g pe-board-review

# Use with opencode
opencode "/pe-board-review Review this file as a principal engineering board"

# Use with GitHub Copilot in VS Code
# @workspace /pe-board-review Review this code as a principal engineering board

→ See INSTALLATION.md for full setup guide for opencode, GitHub Copilot, and CI/CD

What This Skill Does

When invoked, it simulates 5 principal engineers reviewing your code with:

• Warmth-first reviews — genuine praise before critique
• Level-aware feedback — calibrated for junior / mid / senior patterns
• TypeScript-first analysis — type safety, any detection, utility types
• NestJS architecture — layer responsibility, module design, guards/pipes/interceptors
• Security scanning — injection, auth gaps, mass assignment, secrets
• Performance — N+1 queries, missing pagination, sequential vs parallel async
• Error consistency — error factory adherence, HTTP code correctness
• Naming & consistency — conventions enforcement across the entire codebase
• Constants & enums — magic value detection, enum patterns
• Clean code — SOLID, DRY, YAGNI, Law of Demeter
• Common mistake patterns — 30+ documented mistakes across all seniority levels

Primary Stack

| Priority | Technologies | |----------|-------------| | 🎯 Primary | TypeScript · Node.js · NestJS · Express · Fastify · Hapi | | 🔶 Secondary | TypeORM · Prisma · Mongoose · GraphQL · BullMQ | | 🟡 Tertiary | Python · Ruby — concepts only |

All code examples are TypeScript/JavaScript only.

Features

TypeScript Type Safety

• any type detection
• Unsafe as assertions
• Non-null assertion (!) overuse
• Missing return types on public methods
• Missing utility types (Partial<T>, Omit<T, K>, etc.)

NestJS Architecture

• Layer responsibility enforcement (Controller / Service / Repository)
• Module boundary rules
• Guards, Pipes, Interceptors, Exception Filters
• DTO validation with class-validator
• TypeORM / Prisma patterns

Security

• NoSQL operator injection
• SQL injection via QueryBuilder
• Missing auth guards
• Mass assignment via missing ValidationPipe
• Sensitive data in responses or logs
• Rate limiting gaps
• Hardcoded secrets

Performance

• N+1 query detection (TypeORM / Prisma / Mongoose)
• Missing pagination on list endpoints
• Sequential async instead of Promise.all()
• Missing database transactions
• Missing indexes on queried columns
• Blocking event loop (sync CPU work in request path)

Error Handling

• Raw Error throws in application code
• Wrong HTTP status codes (401 vs 403, 500 for client errors)
• Empty catch blocks
• Missing log context before rethrow
• Inconsistency with codebase error factory

Naming & Consistency

• Mixed verb conventions (get vs fetch vs find)
• Boolean variable prefixes (is/has/can/should)
• Magic numbers and strings
• Inconsistent response shapes
• File/folder naming violations

Common Mistakes by Level

• 10 junior patterns (console.log, no validation, hardcoded secrets...)
• 10 mid-level patterns (N+1, no transactions, race conditions...)
• 10 senior patterns (no idempotency, no retry, breaking API changes...)

📦 Installation & Usage

For detailed setup instructions, see INSTALLATION.md

Quick Install (All Platforms)

npm install -g pe-board-review

Use with opencode

opencode "/pe-board-review Review this PR diff as a principal engineering board"
opencode "/pe-board-review Review src/orders/order.service.ts"

Use with GitHub Copilot (VS Code)

@workspace /pe-board-review Review this code as a principal engineering board.
Output as GitHub PR comment.

Full guide with examples, CI/CD integration, and troubleshooting: INSTALLATION.md

Output Formats

1. GitHub PR Comment (Default)

## 🔍 Code Review

> Reviewed by: Principal Engineering Board | 2026-06-26

### ✅ What's Done Well
[Specific, genuine praise]

### 🔴 Blockers — Must Fix Before Merge
[Issues with location → problem → production consequence → concrete fix]

### 🟠 High Priority — Fix in This PR
[Important but not merge-blocking]

### 🟡 Suggestions — Follow-up PR OK
[Improvements, refactors]

### 📋 Pre-Merge Checklist
- [ ] No `any` types, explicit return types on public methods
- [ ] No hardcoded secrets, input validation present
- [ ] Error handling follows codebase convention
- [ ] No N+1 queries, pagination on list endpoints
- [ ] Naming follows codebase conventions
- [ ] No magic numbers/strings

### 💬 Closing
[Brief, encouraging]

2. JSON Report

{
  "review_metadata": {
    "timestamp": "2026-06-26T10:30:00Z",
    "reviewer": "Principal Engineering Board",
    "files_reviewed": 3,
    "total_issues": 8
  },
  "praise": ["..."],
  "blockers": [...],
  "high_priority": [...],
  "suggestions": [...],
  "checklist": { "passed": 6, "failed": 2 }
}

3. Inline Comments

// 🔴 [BLOCKER] NoSQL injection: req.body.email could be { "$gt": "" }
// Fix: const email = String(req.body.email);
const user = await userModel.findOne({ email: req.body.email });

Reference Files

| File | What It Covers | |------|---------------| | SKILL.md | Core skill instructions — the principal engineer persona | | references/typescript-nestjs-patterns.md | TypeScript type safety, NestJS patterns, Guards/Pipes/Interceptors, TypeORM, Mongoose + NestJS (Part 9) | | references/naming-conventions-consistency.md | Full naming rules, folder structure, consistency enforcement | | references/error-handling-factory.md | Error factory pattern, custom exceptions, HTTP code guide | | references/common-mistakes-by-level.md | 30+ common mistakes: junior / mid / senior with TypeScript examples | | references/database-n1-queries.md | N+1 detection, TypeORM/Prisma/Mongoose batching strategies | | references/security-checklist.md | Full security checklist · NestJS patterns · Mongoose-specific security (SEC-M1 to SEC-M7) | | references/performance-guide.md | Performance patterns, caching, queues, Node.js-specific optimizations | | references/solid-dry-architecture.md | SOLID, DRY, YAGNI, Law of Demeter — all in TypeScript |

Severity Guide

| Label | Meaning | Required Action | |-------|---------|----------------| | 🔴 Blocker | Security hole, data loss, crash, critical arch violation | Must fix before merge | | 🟠 High | Performance regression, inconsistency, missing validation | Fix in this PR | | 🟡 Medium | Code quality, maintainability | Fix in follow-up | | 🟢 Low | Style, informational | Author's discretion |

Version: 1.1.3
Updated: 2026-06-27
Primary Focus: TypeScript · Node.js · NestJS · Express · Fastify
License: MIT } ] };

## Security Checklist

The skill checks against these security items:

- ✅ Input validation & sanitization
- ✅ SQL/NoSQL injection prevention
- ✅ XSS protection
- ✅ CSRF protection
- ✅ Authentication/authorization
- ✅ Sensitive data handling
- ✅ Environment variable management
- ✅ Error message exposure
- ✅ Rate limiting
- ✅ API security headers

See [security-checklist.md](references/security-checklist.md) for full details.

## Performance Guidelines

The skill provides guidance on:

- Database query optimization
- Caching strategies
- Async/await best practices
- Memory management
- Stream processing
- Algorithm complexity
- Bundle size optimization
- Connection pooling

See [performance-guide.md](references/performance-guide.md) for full details.

## Helper Scripts

The `scripts/` directory contains utility functions:

### Format JSON
```bash
node scripts/format-json.js

Converts review to structured JSON format

Format Markdown

node scripts/format-markdown.js

Generates readable Markdown report

Format GitHub PR

node scripts/format-github-pr.js

Creates GitHub PR comment format

Tips for Best Results

1. Provide Context

   • Include imports and dependencies
   • Specify the framework (Express, Next.js, etc.)
   • Mention Node.js version

2. Be Specific

   • Ask about specific concerns
   • Provide function or module scope
   • Include related files

3. Use Appropriate Format

   • Markdown for documentation
   • JSON for CI/CD pipelines
   • GitHub PR for pull request reviews

4. Follow Up

   • Ask for specific solutions
   • Request refactoring suggestions
   • Query explanations for complex issues

CI/CD Integration

GitHub Actions

name: Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Code Review
        run: |
          opencode --skill code-review-skill \
            "Review changes for security and performance" \
            --output json > review.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
opencode --skill code-review-skill \
  "Quick security check before commit" \
  --strict

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new review rules
4. Submit a pull request

Issues & Feature Requests

Found a bug or have a feature idea? Open an issue

Support

• 📖 Full Documentation
• 💬 Discussions
• 🐛 Bug Reports

License

MIT License - see LICENSE for details

Changelog

Version 1.0.0 (Current)

• Initial release
• Support for JavaScript/Node.js
• Three review dimensions: security, best practices, performance
• Multiple output formats
• Helper scripts included

Built for: opencode
Requires: Node.js 16+ (for opencode integration)
Author: Mohamed Mamdouh

Roadmap

• [ ] TypeScript support
• [ ] Python code review (Flask, Django)
• [ ] Go code review
• [ ] Rust code review
• [ ] Real-time feedback in editors (VSCode extension)
• [ ] Integration with SonarQube
• [ ] Custom rule builder UI
• [ ] Team collaboration features

Made with ❤️ for the Node.js community