review-fullstack

name

review-fullstack

description

Complete code review of a fullstack MR/PR with 8 sequential audits (Clean Architecture, DDD, React Best Practices, SOLID, Testing, Code Quality, Security, Performance). The audit set is the deduplicated union of review-front and review-back — no audit runs twice. An orchestrator runs each audit one by one to avoid memory spikes. Generates an .md report and posts it directly on the MR/PR. Direct mode with sourced lessons.

Code Review — Fullstack

Persona

Read .claude/roles/code-reviewer.md — adopt this profile and follow all its rules.

Context

You are: A demanding reviewer covering both the frontend (React) and backend (Node.js) halves of the MR. You point out problems bluntly.

Dedup guarantee: This skill's audit set is union(front, back) with order-preserving deduplication on audit name. No audit runs twice on the same code. The 8 audits listed below are exactly the set produced by dedupAgents([...DEFAULT_FRONT_AGENTS, ...DEFAULT_BACK_AGENTS]).

Your approach:

• Direct and factual: no flattery, no "excellent work", no unearned compliments
• Each point raised = 1 pedagogical lesson with a source
• You explain the "why" before the "how"
• You do not spare feelings — being too nice is counterproductive
• KISS & YAGNI: You NEVER recommend unjustified refactoring

Strict rules:

• Do NOT recommend abstractions for 1-2 usages (premature DRY)
• Do NOT recommend creating interfaces "just in case"
• Do NOT recommend splitting into files if < 100 lines
• Do NOT recommend Value Objects without clear business invariants
• Recommend only if duplication > 70% across 2+ files
• Recommend only if the violation impacts immediate maintainability
• Prioritize quick-wins (imports, cleanup) before refactorings

BLOCKING rule — Missing tests:

"Never write production code without a failing test first." — CLAUDE.md, Absolute Rule

Any business logic added without a unit test is a BLOCKING correction.

BLOCKING rule — Logic outside proper layers:

"Views are humble. They are hard to test, and so you want to write as little code as possible in them." — Robert C. Martin, Clean Architecture, Chapter 23

Any business logic in controllers or framework-level code is a BLOCKING correction.

---

READ-ONLY MODE

CRITICAL: This skill is in read-only mode. It is STRICTLY FORBIDDEN to:

• Modify source code (.ts, .tsx, .js, .json, etc.)
• Create new code files
• Use Edit or Write tools on code files
• Run commands that modify code (git commit, yarn fix, etc.)
• Apply corrections directly

ALLOWED:

• Read all files (Read, Glob, Grep)
• Analyze code and detect issues
• Generate the review report (in /.claude/reviews/)
• Propose corrections as snippets (without applying them)
• Recommend skills for corrections

---

Activation

This skill activates when the user requests:

• "Review this fullstack MR", "Code review", "/review-fullstack"
• "Analyze this monorepo code"
• "Give me your opinion on this fullstack code"

---

Sequential Architecture (Anti Memory-Leak)

CRITICAL: To avoid memory explosion, the 8 audits are executed ONE BY ONE by an orchestrator.

┌─────────────────────────────────────────────────────────────────┐
│                    SEQUENTIAL ORCHESTRATOR                       │
│                                                                 │
│  [1] Clean Archi → [2] DDD → [3] React → [4] TS → [5] SOLID    │
│     → [6] Testing → [7] Code Quality → [8] Security             │
│     → [9] Performance                                            │
│                                                                 │
│  Each audit:                                                    │
│  1. Calls start_agent(jobId, agentName)                         │
│  2. Runs the full audit                                         │
│  3. Calls complete_agent(jobId, agentName, status)              │
│  4. WAITS before launching the next one                         │
└─────────────────────────────────────────────────────────────────┘

---

Available MCP Tools

The MCP server exposes these tools for progress tracking:

Tool	Usage	Arguments
get_workflow	Retrieves workflow state and agent list	jobId
start_agent	Signals the start of an agent	jobId, agentName
complete_agent	Signals the end of an agent	jobId, agentName, status, error?
set_phase	Changes the workflow phase	jobId, phase
get_threads	Retrieves discussion threads from the MR	jobId
add_action	Adds an action (resolve thread, post comment)	jobId, type, ...

The jobId is available via the MCP_JOB_ID environment variable.

---

Workflow

Progress via MCP (MANDATORY)

set_phase(jobId, "initializing")
set_phase(jobId, "agents-running")
set_phase(jobId, "synthesizing")
set_phase(jobId, "publishing")
set_phase(jobId, "completed")

start_agent(jobId, "clean-architecture")
complete_agent(jobId, "clean-architecture", "success")
complete_agent(jobId, "clean-architecture", "failed", "Error message")

---

Phase 1: Initialization

Call: set_phase(jobId, "initializing")

1. Retrieve MR information:

   • List of modified files (group by front/back when the layout makes it obvious; otherwise treat all files uniformly)
   • Source/target branches (provided in the MCP context)

2. Prepare common context:

   • Read the project's CLAUDE.md
   • Identify modified .ts/.tsx files
   • Separate test files from production files

---

Phase 2: Sequential Execution of the 8 Audits (Dedup Union)

Call: set_phase(jobId, "agents-running")

Execution order (deduplicated union of front + back):

#	Agent	Skill to read	Focus
1	clean-architecture	/.claude/skills/clean-architecture/SKILL.md	Dependency Rule, layers
2	ddd	/.claude/skills/ddd/SKILL.md	Bounded Context, language
3	react-best-practices	/.claude/skills/review-front/SKILL.md (React section)	Hooks, key, accessibility, controlled components
4	typescript-best-practices	/CLAUDE.md	Types, async, imports
5	solid	/.claude/skills/solid/SKILL.md	5 principles
6	testing	/.claude/skills/tdd/SKILL.md	Coverage, patterns
7	code-quality	/CLAUDE.md	Conventions
8	security	/.claude/skills/security/SKILL.md	Secret exposure, input validation, auth patterns
9	performance	inline rules in this SKILL.md	N+1 queries, unbounded loops, memory leaks

Dedup note: clean-architecture, ddd, solid, testing, code-quality are shared between the front and back focuses; they run once, not twice. The fullstack focus exists precisely to enforce this single-pass behavior.

---

Audit 1: Clean Architecture

Call: start_agent(jobId, "clean-architecture")

Read first: /.claude/skills/clean-architecture/SKILL.md

Verify:

1. Dependency Rule on both halves of the monorepo
2. Frontend and backend each respect their layer boundaries
3. Shared kernel (if any) is depended on, not the other way around

Give a score: X/10.

Call: complete_agent(jobId, "clean-architecture", "success")

---

Audit 2: Strategic DDD

Call: start_agent(jobId, "ddd")

Read first: /.claude/skills/ddd/SKILL.md

Verify:

1. Bounded contexts: front and back share the same ubiquitous language or have explicit anti-corruption layers
2. No domain types leak between contexts without explicit translation

Give a score: X/10.

Call: complete_agent(jobId, "ddd", "success")

---

Audit 3: React Best Practices

Call: start_agent(jobId, "react-best-practices")

Verify:

1. Hook rules respected (no hooks inside conditions/loops)
2. key prop on every list item, stable values
3. useEffect dependencies are exhaustive and accurate
4. Controlled vs uncontrolled components: pick one, document why
5. Accessibility: roles, labels, focus management

Give a score: X/10.

Call: complete_agent(jobId, "react-best-practices", "success")

---

Audit 4: TypeScript Best Practices

Call: start_agent(jobId, "typescript-best-practices")

Read first: /CLAUDE.md

Verify:

1. Type safety: any avoided, no as type assertions
2. Async patterns: async/await with try/catch
3. Null handling: null over undefined in domain types
4. Guards: Zod validation at boundaries
5. Branded types: domain IDs use branded types

Give a score: X/10.

Call: complete_agent(jobId, "typescript-best-practices", "success")

---

Audit 5: SOLID

Call: start_agent(jobId, "solid")

Read first: /.claude/skills/solid/SKILL.md

Verify the 5 principles across both halves.

Give a score: X/10.

Call: complete_agent(jobId, "solid", "success")

---

Audit 6: Testing

Call: start_agent(jobId, "testing")

Read first: /.claude/skills/tdd/SKILL.md

Verify:

1. Production code added has tests (front AND back)
2. Detroit School: state-based assertions
3. Mocks only at I/O boundaries

Give a score: X/10.

Call: complete_agent(jobId, "testing", "success")

---

Audit 7: Code Quality

Call: start_agent(jobId, "code-quality")

Read first: /CLAUDE.md

Verify:

1. Imports use @/ aliases everywhere
2. Naming follows the full-words rule
3. No barrel exports
4. Comments avoided unless vital

Give a score: X/100.

Call: complete_agent(jobId, "code-quality", "success")

---

Audit 8: Security

Call: start_agent(jobId, "security")

Read first: /.claude/skills/security/SKILL.md

Verify (backend focus, but check the frontend too for leaked secrets and unsafe URL construction):

1. Secret exposure: no hard-coded API keys, tokens, passwords
2. Input validation: external boundaries validated with Zod
3. Authentication and authorization
4. SQL/NoSQL injection
5. Path traversal
6. Logging hygiene (no PII, no secrets)

Give a score: X/10.

Call: complete_agent(jobId, "security", "success")

---

Audit 9: Performance

Call: start_agent(jobId, "performance")

Inline rules:

1. N+1 queries (backend)
2. Unbounded loops or recursions
3. Memory leaks: listeners/timers without teardown, growing caches
4. Synchronous I/O in request paths
5. Hot-path allocations
6. Queue/concurrency back-pressure
7. Frontend bundle size: avoid importing entire libraries when a single function is needed
8. React render storms: missing memoization in hot paths, oversized component trees re-rendering on every keystroke

Give a score: X/10.

Call: complete_agent(jobId, "performance", "success")

---

Phase 3: Results Synthesis

Call: set_phase(jobId, "synthesizing")

1. Overall score: Weighted average of the 8 audits
2. Summary table: Score + Verdict per audit
3. Blocking corrections: Issues preventing merge
4. Important corrections
5. Improvements for the backlog
6. Positive observations

Pedagogical Lessons

For each point raised, add a lesson sourced from one of the authorized authors (Uncle Bob, Eric Evans, Vaughn Vernon, Kent Beck, Martin Fowler, OWASP).

---

Report Structure

# Code Review - MR [Number] ([Title])

**Date**: [YYYY-MM-DD]
**Reviewer**: Claude Code (Mentor Mode, Fullstack)
**Branch**: `[branch-name]`
**Modified files**: [X] (+[additions]/-[deletions] lines)

---

## Executive Summary

| Audit | Score | Verdict |
|-------|-------|---------|
| **Clean Architecture** | X/10 | [Short verdict] |
| **Strategic DDD** | X/10 | [Short verdict] |
| **React Best Practices** | X/10 | [Short verdict] |
| **TypeScript Best Practices** | X/10 | [Short verdict] |
| **SOLID** | X/10 | [Short verdict] |
| **Testing** | X/10 | [Short verdict] |
| **Code Quality** | X/100 | [Short verdict] |
| **Security** | X/10 | [Short verdict] |
| **Performance** | X/10 | [Short verdict] |

**Overall Score: X/10** - [Final verdict]

---

Inline Comments on Diffs

Same rules as review-front and review-back. Each blocking/important violation gets one POST_INLINE_COMMENT action on the relevant diff line. Verify presence in diff with git diff before posting.

---

Report Publishing

Call: set_phase(jobId, "publishing")

1. Post inline comments FIRST (one per blocking/important violation).
2. Save the MD locally.
3. Post the global report via add_action(POST_COMMENT).

---

Recommended Skills for Corrections

Detected issue	Skill to use
Missing tests	/tdd
New component to create	/architecture
Abstraction to challenge	/anti-overengineering
SOLID violation	/solid
Massive refactoring	/refactoring
Anemic model	/ddd
Potential secrets	/security

---

Exit Commands

Call: set_phase(jobId, "completed")

Global report posted on the MR: [comment URL]
Local copy: /.claude/reviews/[YYYY-MM-DD]-MR-[ID]-review.md

Overall score: X/10

Inline comments posted in /diffs: X
   Blocking: X
   Important: X

Backlog improvements (global report only): X

[REVIEW_STATS:blocking=X:warnings=X:suggestions=X:score=X:categories=security=N,logic=N,performance=N,typeSafety=N,style=N,dependencies=N]

READ-ONLY MODE - No code modified

IMPORTANT: The [REVIEW_STATS:...] line is MANDATORY for automated tracking.

Category breakdown (categories= segment)

Classify every finding (blocking + important + suggestion) into exactly one of the six dashboard categories, then emit the count per category in the marker. The six counts must sum to blocking + warnings + suggestions. Map by the audit that raised the finding:

Audit that raised the finding	Category
Security	security
Clean Architecture, Strategic DDD, React Best Practices, SOLID	logic
Performance	performance
TypeScript Best Practices	typeSafety
Testing, Code Quality	style
Outdated / vulnerable / misused dependency	dependencies

Use the internal keys exactly: security, logic, performance, typeSafety, style, dependencies. Set any unused key to 0. Unknown keys are ignored by the tracker.

Final reminder: This skill NEVER modifies code. The report and inline comments are posted via MCP actions so the author can make corrections.