feat: unified Reviewer architecture with self-review framework

CLAUDE.md

@@ -99,18 +99,23 @@ ensure_docs_dir "reviews/$BRANCH_SLUG"
 - `CatchUp` → `.docs/CATCH_UP.md` (overwrite latest)
 - `Debug` → `.docs/debug/debug-{timestamp}.md` + `KNOWLEDGE_BASE.md`
 - `devlog` → `.docs/status/{timestamp}.md` + `compact/` + `INDEX.md`
-- `*Review` (11 specialized + Summary) → `.docs/reviews/{branch-slug}/{type}-report-{timestamp}.md`
+- `Reviewer` → `.docs/reviews/{branch-slug}/{focus}.md` (one file per focus area)
+- `Summary` → `.docs/reviews/{branch-slug}/SUMMARY.md`
 - `Release` → `.docs/releases/RELEASE_NOTES_v{version}.md`
 
-**Orchestration commands** (run in main context, spawn native agents):
-- `/specify` - Spawns 4 Explore + 3 Plan agents (requirements focus), creates GitHub issue
-- `/implement` - Spawns 4 Explore + 3 Plan + 1-N Coder + 5-8 review-* agents
+**Orchestration commands** (run in main context, spawn agents):
+- `/specify` - Spawns Skimmer + 4 Explore + Synthesize + 3 Plan + Synthesize, creates GitHub issue
+- `/implement` - Spawns Skimmer + 4 Explore + Synthesize + 3 Plan + Synthesize + 1-N Coder (with self-review), then calls `/review`
+- `/review` - Spawns 7-11 Reviewer agents (different focus areas) + Comment + TechDebt + Summary
 
 **Native agents used** (built-in Claude Code agents):
 - `Explore` - Fast codebase exploration (patterns, integration, testing)
 - `Plan` - Implementation planning with trade-off analysis
-- `Coder` - Code implementation in isolated worktrees
-- `*Review` (11 specialized + Summary) - Specialized code analysis
+- `Coder` - Code implementation in isolated worktrees + self-review via Stop hook
+
+**Review agents**:
+- `Reviewer` - Universal parameterized reviewer (focus via prompt injection)
+- `Summary` - Aggregates review findings, determines merge recommendation
 
 **Utility agents** (focused tasks, no sub-spawning):
 - `Commit` - Creates git commit only
@@ -310,14 +315,29 @@ DevFlow uses a **tiered skills system** where skills serve as shared knowledge l
 
 | Skill | Purpose | Used By |
 |-------|---------|---------|
-| `devflow-core-patterns` | Engineering patterns (Result types, DI, immutability, pure functions) | Coder, TypescriptReview, ArchitectureReview |
-| `devflow-review-methodology` | 6-step review process, 3-category issue classification | All Review agents (12 total) |
-| `devflow-docs-framework` | Documentation conventions (.docs/ structure, naming, templates) | Devlog, CatchUp, DocumentationReview, Debug |
+| `devflow-core-patterns` | Engineering patterns (Result types, DI, immutability, pure functions) | Coder, Reviewer |
+| `devflow-review-methodology` | 6-step review process, 3-category issue classification | Reviewer |
+| `devflow-self-review` | 9-pillar self-review framework (Design, Functionality, Security, Complexity, Error Handling, Tests, Naming, Consistency, Documentation) | Coder (via Stop hook) |
+| `devflow-docs-framework` | Documentation conventions (.docs/ structure, naming, templates) | Devlog, CatchUp, Debug |
 | `devflow-git-safety` | Git operations, lock handling, commit conventions, sensitive file detection | Commit, Coder, PullRequest, Release |
-| `devflow-security-patterns` | Security vulnerability patterns, OWASP mapping, detection strategies | SecurityReview |
 | `devflow-implementation-patterns` | Common implementation patterns (CRUD, API endpoints, events, config, logging) | Coder |
 | `devflow-codebase-navigation` | Codebase exploration, entry points, data flow tracing, pattern discovery | Coder |
 
+**Tier 1b: Pattern Skills** (domain expertise for Reviewer agent focus areas)
+
+| Skill | Purpose | Reviewer Focus |
+|-------|---------|----------------|
+| `devflow-security-patterns` | Injection, auth, crypto, OWASP vulnerabilities | `security` |
+| `devflow-architecture-patterns` | SOLID violations, coupling, layering, modularity | `architecture` |
+| `devflow-performance-patterns` | Algorithms, N+1, memory, I/O, caching | `performance` |
+| `devflow-complexity-patterns` | Cyclomatic complexity, readability, maintainability | `complexity` |
+| `devflow-consistency-patterns` | Pattern violations, simplification, truncation | `consistency` |
+| `devflow-tests-patterns` | Coverage, quality, brittle tests, mocking | `tests` |
+| `devflow-database-patterns` | Schema, queries, migrations, indexes | `database` |
+| `devflow-documentation-patterns` | Docs quality, alignment, code-comment drift | `documentation` |
+| `devflow-dependencies-patterns` | CVEs, versions, licenses, supply chain | `dependencies` |
+| `devflow-regression-patterns` | Lost functionality, broken behavior, migrations | `regression` |
+
 **Tier 2: Specialized Skills** (user-facing, auto-activate based on context)
 
 | Skill | Purpose | Auto-Triggers When |
@@ -342,34 +362,58 @@ Agents declare skills in their frontmatter to automatically load shared knowledg
 
 ```yaml
 ---
-name: SecurityReview
-description: Security vulnerability detection
-model: inherit
-skills: devflow-review-methodology, devflow-security-patterns
+name: Reviewer
+description: Universal code review agent with parameterized focus
+model: sonnet
+skills: devflow-review-methodology, devflow-security-patterns, devflow-architecture-patterns, ...
 ---
 ```
 
+The unified `Reviewer` agent loads ALL pattern skills and applies the relevant one based on the focus area specified in its invocation prompt.
+
 ### Iron Laws
 
 Every skill has a single, non-negotiable **Iron Law** - a core principle that must never be violated. Iron Laws are enforced automatically when skills activate.
 
+**Foundation Skills:**
+
 | Skill | Iron Law |
 |-------|----------|
 | `devflow-core-patterns` | NEVER THROW IN BUSINESS LOGIC |
 | `devflow-review-methodology` | NEVER BLOCK FOR PRE-EXISTING ISSUES |
+| `devflow-self-review` | FIX BEFORE RETURNING |
 | `devflow-git-safety` | NEVER RUN GIT COMMANDS IN PARALLEL |
+| `devflow-docs-framework` | ALL ARTIFACTS FOLLOW NAMING CONVENTIONS |
+| `devflow-implementation-patterns` | FOLLOW EXISTING PATTERNS |
+| `devflow-codebase-navigation` | FIND PATTERNS BEFORE IMPLEMENTING |
+
+**Pattern Skills (Reviewer focus areas):**
+
+| Skill | Iron Law |
+|-------|----------|
+| `devflow-security-patterns` | ASSUME ALL INPUT IS MALICIOUS |
+| `devflow-architecture-patterns` | SEPARATION OF CONCERNS IS NON-NEGOTIABLE |
+| `devflow-performance-patterns` | MEASURE BEFORE OPTIMIZING |
+| `devflow-complexity-patterns` | IF YOU CAN'T UNDERSTAND IT IN 5 MINUTES, IT'S TOO COMPLEX |
+| `devflow-consistency-patterns` | MATCH EXISTING PATTERNS OR JUSTIFY DEVIATION |
+| `devflow-tests-patterns` | TESTS VALIDATE BEHAVIOR, NOT IMPLEMENTATION |
+| `devflow-database-patterns` | EVERY QUERY MUST HAVE AN EXECUTION PLAN |
+| `devflow-documentation-patterns` | DOCUMENTATION MUST MATCH REALITY |
+| `devflow-dependencies-patterns` | EVERY DEPENDENCY IS AN ATTACK SURFACE |
+| `devflow-regression-patterns` | WHAT WORKED BEFORE MUST WORK AFTER |
+
+**Specialized & Domain Skills:**
+
+| Skill | Iron Law |
+|-------|----------|
 | `devflow-debug` | NO FIXES WITHOUT ROOT CAUSE INVESTIGATION |
 | `devflow-test-design` | COMPLEX TESTS INDICATE BAD DESIGN |
 | `devflow-code-smell` | NO FAKE SOLUTIONS |
 | `devflow-research` | NO IMPLEMENTATION WITHOUT EXPLORATION |
 | `devflow-input-validation` | ALL EXTERNAL DATA IS HOSTILE |
-| `devflow-docs-framework` | ALL ARTIFACTS FOLLOW NAMING CONVENTIONS |
-| `devflow-security-patterns` | ASSUME ALL INPUT IS MALICIOUS |
-| `devflow-codebase-navigation` | FIND PATTERNS BEFORE IMPLEMENTING |
-| `devflow-implementation-patterns` | FOLLOW EXISTING PATTERNS |
+| `devflow-worktree` | ONE TASK, ONE WORKTREE |
 | `devflow-react` | COMPOSITION OVER PROPS |
 | `devflow-typescript` | UNKNOWN OVER ANY |
-| `devflow-worktree` | ONE TASK, ONE WORKTREE |
 
 **Iron Law Format** in SKILL.md files:
 ```markdown

README.md

@@ -75,6 +75,16 @@ Every skill has a single, non-negotiable **Iron Law** - a core principle that mu
 | `devflow-security-patterns` | ASSUME ALL INPUT IS MALICIOUS |
 | `devflow-typescript` | UNKNOWN OVER ANY |
 | `devflow-react` | COMPOSITION OVER PROPS |
+| `devflow-self-review` | FIX BEFORE RETURNING |
+| `devflow-architecture-patterns` | VIOLATIONS IN YOUR CHANGES ARE BLOCKING |
+| `devflow-performance-patterns` | MEASURE BEFORE OPTIMIZING |
+| `devflow-complexity-patterns` | COMPLEXITY IS THE ENEMY OF RELIABILITY |
+| `devflow-consistency-patterns` | FOLLOW EXISTING PATTERNS |
+| `devflow-tests-patterns` | TESTS MUST VALIDATE BEHAVIOR NOT IMPLEMENTATION |
+| `devflow-database-patterns` | MIGRATIONS MUST BE REVERSIBLE |
+| `devflow-documentation-patterns` | DOCS MUST MATCH CODE |
+| `devflow-dependencies-patterns` | NO VULNERABLE DEPENDENCIES IN PRODUCTION |
+| `devflow-regression-patterns` | PRESERVE EXISTING FUNCTIONALITY |
 
 Iron Laws are enforced automatically when skills activate.
 
@@ -94,14 +104,29 @@ DevFlow uses a **tiered skills system** where skills serve as shared knowledge l
 
 | Skill | Purpose | Used By |
 |-------|---------|---------|
-| `devflow-core-patterns` | Result types, DI, immutability, pure functions | Coder, TypescriptReview, ArchitectureReview |
-| `devflow-review-methodology` | 6-step review process, 3-category classification | All Review agents |
-| `devflow-docs-framework` | .docs/ structure, naming, templates | Devlog, CatchUp, DocumentationReview |
+| `devflow-core-patterns` | Result types, DI, immutability, pure functions | Coder, Reviewer |
+| `devflow-review-methodology` | 6-step review process, 3-category classification | Reviewer |
+| `devflow-self-review` | 9-pillar self-review framework | Coder (via Stop hook) |
+| `devflow-docs-framework` | .docs/ structure, naming, templates | Devlog, CatchUp |
 | `devflow-git-safety` | Git operations, lock handling, commit conventions | Commit, Coder, PullRequest, Release |
-| `devflow-security-patterns` | OWASP mapping, vulnerability patterns | SecurityReview |
 | `devflow-implementation-patterns` | CRUD, API, events, config, logging | Coder |
 | `devflow-codebase-navigation` | Exploration, pattern discovery, data flow | Coder |
 
+**Pattern Skills** (domain expertise for Reviewer focus areas)
+
+| Skill | Reviewer Focus | Purpose |
+|-------|----------------|---------|
+| `devflow-security-patterns` | `security` | Injection, auth, crypto vulnerabilities |
+| `devflow-architecture-patterns` | `architecture` | SOLID, coupling, layering, modularity |
+| `devflow-performance-patterns` | `performance` | Algorithms, N+1, memory, I/O, caching |
+| `devflow-complexity-patterns` | `complexity` | Cyclomatic complexity, readability |
+| `devflow-consistency-patterns` | `consistency` | Pattern violations, simplification |
+| `devflow-tests-patterns` | `tests` | Coverage, quality, brittleness |
+| `devflow-database-patterns` | `database` | Schema, queries, migrations |
+| `devflow-documentation-patterns` | `documentation` | Docs quality, alignment |
+| `devflow-dependencies-patterns` | `dependencies` | CVEs, versions, licenses |
+| `devflow-regression-patterns` | `regression` | Lost functionality, broken behavior |
+
 **Tier 2: Specialized Skills** (user-facing, auto-activate based on context)
 
 | Skill | Purpose | Auto-Triggers When |
@@ -122,20 +147,24 @@ DevFlow uses a **tiered skills system** where skills serve as shared knowledge l
 
 **How Agents Use Skills:**
 
-Agents declare skills in their frontmatter to automatically load shared knowledge:
+The unified `Reviewer` agent loads ALL pattern skills and applies the relevant one based on the focus area specified in its invocation prompt:
 ```yaml
 ---
-name: SecurityReview
-description: Security vulnerability detection
-model: inherit
-skills: devflow-review-methodology, devflow-security-patterns
+name: Reviewer
+description: Universal code review agent with parameterized focus
+model: sonnet
+skills: devflow-review-methodology, devflow-security-patterns, devflow-architecture-patterns, ...
 ---
 ```
 
-This creates a **shared library pattern** where:
-- Common methodology is defined once (in foundation skills)
-- Agents inherit and extend with their specialization
-- No duplication of review process or core patterns across agents
+The `Coder` agent uses a Stop hook to run self-review before returning:
+```yaml
+hooks:
+  Stop:
+    - hooks:
+        - type: prompt
+          prompt: "Run self-review using devflow-self-review. Fix all P0/P1 issues..."
+```
 
 **Dual-Mode Pattern**: The `debug` skill also exists as a slash command (`/debug`) for manual control:
 - **Skill mode** (auto): Activates when Claude detects errors or failures
@@ -172,19 +201,13 @@ This gives you the best of both worlds: automatic assistance when needed, manual
 | `Plan` | Implementation Planning | 1-3 spawned in parallel per task for architecture, testing, parallelization |
 | `Coder` | Implementation | 1-N spawned per task (parallel when work is parallelizable) |
 
-**Review Agents** (specialized code analysis):
+**Review Agent** (unified, parameterized):
 
-| Agent | Specialty | Purpose |
-|-------|-----------|---------|
-| `SecurityReview` | Security | Vulnerability detection and security code review |
-| `PerformanceReview` | Performance | Optimization and bottleneck detection |
-| `ArchitectureReview` | Architecture | Design pattern analysis and code structure review |
-| `TestsReview` | Testing | Test quality, coverage, and effectiveness analysis |
-| `ComplexityReview` | Complexity | Code complexity and maintainability assessment |
-| `DependenciesReview` | Dependencies | Dependency management and security analysis |
-| `DatabaseReview` | Database | Database design and optimization review |
-| `DocumentationReview` | Documentation | Docs-code alignment, API accuracy, comment quality |
-| `TypescriptReview` | TypeScript | Type safety enforcement and TypeScript code quality |
+| Agent | Purpose | Focus Areas |
+|-------|---------|-------------|
+| `Reviewer` | Universal code review with parameterized focus | security, architecture, performance, complexity, consistency, regression, tests, dependencies, documentation, typescript, database |
+
+The Reviewer agent is spawned multiple times in parallel, each with a different focus area specified in the prompt. This replaces the previous 11 individual review agents while maintaining the same specialized analysis.
 
 **Utility Agents** (focused tasks):
 
@@ -200,10 +223,13 @@ This gives you the best of both worlds: automatic assistance when needed, manual
 | `Debug` | Debugging | Systematic debugging with hypothesis testing |
 | `Comment` | PR Comments | Create summary comments for non-diff issues |
 | `TechDebt` | Tech Debt | Manage tech debt backlog GitHub issue |
+| `Summary` | Review Synthesis | Aggregate review findings with merge recommendation |
+| `Synthesize` | Output Synthesis | Combine outputs from parallel agents into actionable summaries |
 
 **How Commands Orchestrate Agents:**
-- `/specify` → Skimmer + 4 Explore + 3 Plan agents (requirements focus) → GitHub issue
-- `/implement` → Skimmer + 4 Explore + 3 Plan + 1-N Coder + 5-8 Review agents → PR
+- `/specify` → Skimmer + 4 Explore + Synthesize + 3 Plan + Synthesize → GitHub issue
+- `/implement` → Skimmer + 4 Explore + Synthesize + 3 Plan + Synthesize + 1-N Coder (with self-review) → `/review` → PR
+- `/review` → 7-11 Reviewer agents (parallel, different focus areas) + Comment + TechDebt + Summary
 
 **Skimmer Integration:**
 
@@ -216,8 +242,8 @@ Requires `skim` tool: `npm install -g rskim` or `cargo install rskim`
 
 **Invoking Sub-Agents:**
 ```bash
-# Explicit invocation
-"Use the SecurityReview sub-agent to analyze this authentication code"
+# Explicit invocation with focus
+"Use the Reviewer agent with security focus to analyze this authentication code"
 
 # Automatic delegation (Claude Code decides which sub-agent to use)
 "Review this code for security issues"
@@ -319,7 +345,7 @@ DevFlow agents automatically create and maintain project documentation in the `.
 - **`/devlog`** → `.docs/status/{timestamp}.md` + compact version + INDEX
 - **`/debug`** → `.docs/debug/debug-{timestamp}.md` + KNOWLEDGE_BASE
 - **`/implement`** → `.docs/design/{topic}-{timestamp}.md` (via Design agent)
-- **`/review`** → `.docs/reviews/{branch}/` (up to 11 review reports + summary)
+- **`/review`** → `.docs/reviews/{branch}/` (7-11 focus area reports + summary)
 - **`/release`** → `.docs/releases/RELEASE_NOTES_v{version}.md`
 
 ### Version Control
@@ -434,8 +460,8 @@ devflow init
 
 ### Custom Audit Rules
 ```bash
-# Extend sub-agents for project-specific patterns
-echo "Check for exposed API keys in config files" >> ~/.claude/agents/devflow/review-security.md
+# Extend pattern skills for project-specific checks
+echo "Check for exposed API keys in config files" >> ~/.claude/skills/devflow-security-patterns/SKILL.md
 ```
 
 ### Team Usage