Agent skill

code-review

Comprehensive parallel code review using 5 specialized subagents: general, architectural, TypeScript, product/vision, and TDD/beads compliance

View SKILL.md on GitHub Repository
Stars 4
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/dot-do/workers/tree/main/skills/code-review

SKILL.md

Parallel Code Review

Overview

Conduct a comprehensive code review by dispatching 5 parallel subagents, each with a specialized focus. Results are synthesized into a unified review.

When to Use

  • Before merging significant changes
  • After completing feature implementation
  • When reviewing PRs from others
  • Before deployment of major features

The Process

Step 1: Gather Context

First, collect the changes to review:

  • For PRs: gh pr diff
  • For local changes: git diff main...HEAD or git diff --staged
  • Identify modified files and their purposes

Step 2: Launch Parallel Subagents

Launch 5 parallel Sonnet agents using the Task tool, each with a specialized review focus:

Use the Task tool to launch 5 agents IN PARALLEL (single message, multiple tool calls):

Agent 1: General Code Review

Review these changes for:
- Obvious bugs and logic errors
- Error handling gaps
- Edge cases not covered
- Code clarity and readability
- Test coverage for new code
- Security vulnerabilities (injection, auth, data exposure)

Focus on issues that would cause runtime failures or incorrect behavior.
Ignore style/formatting issues caught by linters.

Return a list of issues with:
- Severity (critical/high/medium/low)
- File and line reference
- Description and suggested fix

Agent 2: Architectural Review

Review these changes for architectural concerns:
- Does this follow existing patterns in the codebase?
- Are dependencies appropriate (no circular deps, correct layer boundaries)?
- Is the abstraction level correct (not too abstract, not too concrete)?
- Does this scale appropriately?
- Are there better existing utilities/helpers that should be used?
- Does this introduce technical debt?

Check consistency with CLAUDE.md and ARCHITECTURE.md if present.

Return architectural concerns with:
- Impact level (breaking/significant/minor)
- Description of the concern
- Recommended approach

Agent 3: TypeScript Review

Review these TypeScript changes for:
- Type safety issues (any abuse, unsafe casts, missing null checks)
- Generic usage (correct constraints, inference issues)
- Interface/type design (appropriate use of interfaces vs types)
- Import organization and module boundaries
- Async/await correctness (missing awaits, unhandled promises)
- Potential runtime type mismatches

Assume the code compiles - focus on semantic type issues.

Return TypeScript issues with:
- File and line reference
- The problematic pattern
- Type-safe alternative

Agent 4: Product/Vision/Roadmap Review

Review these changes against the project's vision and direction:
- Read README.md, CLAUDE.md, and any docs/ for project context
- Check recent git history to understand where the project is heading
- Does this change align with the project's goals?
- Does it conflict with planned features or recent direction changes?
- Are there naming/API inconsistencies with the broader product?
- Does this maintain the project's design philosophy?

Return alignment concerns with:
- What aspect of vision/roadmap it affects
- How the change diverges
- Suggestion to realign (or note if intentional evolution)

Agent 5: TDD & Beads Compliance Review

Review these changes for TDD discipline and beads issue tracking:

**TDD Compliance:**
- Are there corresponding test files for new code?
- Do tests follow RED-GREEN-REFACTOR pattern?
- Were tests written BEFORE implementation? (check git history/commits)
- Are test names clear and behavior-focused?
- Is test coverage adequate for the changes?
- Are there any implementation files without corresponding tests?

**Beads Issue Tracking:**
- Check `bd list` for related issues
- Are changes linked to beads issues?
- Do beads issues follow TDD labeling convention?
  - `tdd-red` labels for failing test issues
  - `tdd-green` labels for implementation issues
  - `tdd-refactor` labels for refactoring issues
- Are there orphaned changes not tracked in beads?
- Should new beads issues be created for discovered work?

**Workflow Compliance:**
- Is work being done in the right order? (red → green → refactor)
- Are dependencies between issues correct?
- Are issues being closed as work completes?

Return TDD/beads compliance issues with:
- Type (missing-test / wrong-order / untracked-work / missing-issue)
- File or feature affected
- Recommended action (create issue, add test, update labels)

Step 3: Synthesize Results

After all agents complete:

  1. Deduplicate: Remove issues flagged by multiple agents
  2. Prioritize: Sort by severity/impact
  3. Filter: Remove likely false positives:
    • Pre-existing issues not introduced by this change
    • Issues that linters/compilers would catch
    • Purely stylistic concerns not in CLAUDE.md
  4. Verify: For critical issues, spot-check the code yourself

Step 4: Present Findings

Format the review as:

markdown
## Code Review Summary

**Files reviewed**: [list]
**Overall assessment**: [APPROVE / REQUEST CHANGES / COMMENT]

### Critical Issues (must fix)
1. [Issue] - [File:Line] - [Which review found it]

### Recommended Changes
1. [Issue] - [File:Line] - [Which review found it]

### Minor Suggestions
1. [Suggestion] - [File:Line]

### Positive Observations
- [What was done well]

Key Principles

  • Parallel execution: All 5 agents run simultaneously for speed
  • Specialized focus: Each agent has deep expertise in their domain
  • Synthesis over duplication: Consolidate overlapping findings
  • Signal over noise: Filter aggressively to surface real issues
  • Actionable feedback: Every issue should have a clear resolution path

Agent Configuration

When launching agents:

  • Use model: "sonnet" for thorough analysis
  • Include the full diff/changes in each agent's prompt
  • Include relevant context files (CLAUDE.md, README.md, package.json)
  • Set clear expectations for output format

Example Invocation

I need to review the changes in this PR. Let me launch 5 parallel review agents.

[Launch Task tool 5 times in a SINGLE message with the specialized prompts above]

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

dot-do/workers

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

4 1
Explore
dot-do/workers

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

4 1
Explore
dot-do/workers

development-loop

Complete development lifecycle: brainstorm → TDD planning → ralph implementation → review → feedback loop until approved

4 1
Explore
dot-do/workers

beads

Track work with beads issue tracker using TDD workflow. Create issues for RED (failing tests), GREEN (implementation), and REFACTOR phases.

4 1
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results