feat: Architecture v3 - Unified Reviewer, Self-Review Framework, Agent Hooks

[dean0x]

Summary

Leverage new Claude Code features (agent hooks, context: fork, skill agent field) to simplify our architecture:

1. Consolidate 11 review agents → 1 parameterized Reviewer
2. Add self-review framework to Coder with fix-before-returning behavior
3. Use agent hooks for lifecycle control and file persistence
4. DRY review orchestration - /implement calls /review

New Claude Code Features We're Leveraging

Feature	How We Use It
context: fork	Run Coder and Reviewer in isolated sub-agent contexts
agent field in skills	Skills can specify which agent executes them
Agent hooks.Stop	Self-review in Coder, file persistence in Reviewer
type: prompt hooks	Intelligent self-review decisions

Design Decisions

Decision	Choice	Rationale
Orchestrator context	Main (visible)	User sees progress, can intervene at gates
Review gating	Report only	Show findings, user decides
Coder → Review transition	Orchestrator spawns	/implement calls /review command
Review consolidation	Parameterized Reviewer	Pattern skills exist, methodology shared
Self-review behavior	Fix, not just report	Catch issues before external review
Review output format	Markdown (.md)	Human readable
Migration strategy	Big bang + coexistence	Keep old agents for rollback

Architecture

Current (11 Review Agents)

/implement
  ├─→ Coder
  └─→ SecurityReview    ─┐
      ArchitectureReview ├─→ Summary
      PerformanceReview  │
      ComplexityReview   │
      ConsistencyReview  │
      TypescriptReview   │
      TestsReview        │
      DocumentationReview│
      DependenciesReview │
      RegressionReview   │
      DatabaseReview    ─┘

Problem: 11 agents with duplicated methodology

Proposed (1 Parameterized Reviewer)

/implement (main context, visible)
  │
  ▼
┌─────────────────────────────────────────────────────────────┐
│                 Coder (context: fork)                        │
│  hooks:                                                      │
│    Stop:                                                     │
│      - type: prompt                                          │
│        prompt: "Self-review using devflow-self-review.       │
│                 Fix all P0/P1 issues. Return when PASS."     │
│                                                              │
│  Output: implementation + self-review report                 │
└─────────────────────────────────────────────────────────────┘
  │
  ▼ (orchestrator calls /review command)
┌─────────────────────────────────────────────────────────────┐
│                      /review                                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Reviewer × N (parallel, context: fork)                  │ │
│  │ focus: security | architecture | performance | ...      │ │
│  │ Loads: devflow-review-methodology + devflow-{focus}-*   │ │
│  │                                                         │ │
│  │ hooks:                                                  │ │
│  │   Stop:                                                 │ │
│  │     - type: command                                     │ │
│  │       command: "# findings already saved to file"       │ │
│  │                                                         │ │
│  │ Output: .docs/reviews/{branch}/{focus}.md               │ │
│  └────────────────────────────────────────────────────────┘ │
│                            │                                 │
│                            ▼                                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Summary (context: fork)                                 │ │
│  │ Reads: .docs/reviews/{branch}/*.md                      │ │
│  │ Output: .docs/reviews/{branch}/SUMMARY.md               │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────────────────────────────┐
│                      USER GATE                               │
│  Shows: Summary + recommendation                             │
│  Options: Create PR / Request fixes / Abort                  │
└─────────────────────────────────────────────────────────────┘

Component Specifications

1. New Skill: devflow-self-review

Iron Law: FIX BEFORE RETURNING

8 Pillars (prioritized):

Priority	Pillar	Key Checks
P0	Design	Fits architecture, interaction logic sound, not over-solving
P0	Functionality	Works as intended, edge cases handled, no race conditions
P0	Security	Input validation, no injection risks, no secrets exposed
P1	Complexity	Understandable in <5 min, single responsibility, no over-abstraction
P1	Error Handling	Explicit handling, Result types where appropriate, no silent failures
P1	Tests	Cover new functionality, would fail if code breaks, edge cases tested
P2	Naming	Descriptive names, comments explain "why" not "what"
P2	Consistency	Follows style guide, matches surrounding patterns

Behavior:

• Evaluate P0 → fix immediately → evaluate P1 → fix → evaluate P2 → fix if time
• If P0 issue unfixable → STOP and report blocker
• Only return when all P0 and P1 PASS

Based on: Google Engineering Practices, Microsoft Engineering Playbook

2. New Agent: Reviewer

---
name: Reviewer
description: Universal code review agent with parameterized focus
model: sonnet
skills: devflow-review-methodology, devflow-security-patterns,
        devflow-architecture-patterns, devflow-performance-patterns, ...
tools: Read, Grep, Glob, LSP
---

Parameterization: Invoked with focus parameter that determines which pattern skill to apply:

• focus: security → applies devflow-security-patterns
• focus: architecture → applies devflow-architecture-patterns
• etc.

Output: Writes findings to .docs/reviews/{branch}/{focus}.md

3. Updated Agent: Coder

Add to frontmatter:

skills: devflow-core-patterns, devflow-implementation-patterns,
        devflow-git-safety, devflow-self-review
hooks:
  Stop:
    - hooks:
        - type: prompt
          prompt: |
            Before completing, run self-review using devflow-self-review.
            Evaluate each pillar in order. FIX any issues found.
            Only return when all P0 and P1 pillars PASS.
            Output: fixes made + final status.

4. Updated Command: /implement

Change Phase 8-9 (review phases) to:

## Phase 8: Code Review

Invoke the /review command to run comprehensive review.

This ensures review orchestration logic is not duplicated.

5. Updated Command: /review

Replace individual review agent spawns with parameterized Reviewer:

## Phase 3: Parallel Reviews

Spawn Reviewer agent for each focus area in parallel:

| Focus | Condition |
|-------|-----------|
| security | Always |
| architecture | Always |
| performance | Always |
| complexity | Always |
| consistency | Always |
| tests | Always |
| regression | Always |
| typescript | If .ts/.tsx files changed |
| database | If migration/schema files changed |
| documentation | If docs changed |
| dependencies | If package.json/lock files changed |

Each invocation:
- Agent: Reviewer
- Parameter: focus={focus}
- Output: .docs/reviews/{branch}/{focus}.md

Self-Review vs External Review

Aspect	Self-Review (Coder)	External Review (Reviewer)
Purpose	Catch obvious issues before submitting	Fresh eyes, specialized expertise
Action	Fix immediately	Report findings
Scope	8 pillars, general quality	Domain-specific deep dives
When	Before returning from Coder	After Coder completes
Output	Fixed code + report	Findings in .md files

Migration Strategy

1. Create new components (Reviewer, devflow-self-review)
2. Update existing (Coder hooks, /review, /implement)
3. Keep old review agents (deprecate but don't delete)
4. Test end-to-end
5. Remove old agents in next release (after validation)

Implementation Tasks

Phase 1: Pattern Skills Extraction

• Extract patterns from review-architecture.md → devflow-architecture-patterns
• Extract patterns from review-performance.md → devflow-performance-patterns
• Extract patterns from review-complexity.md → devflow-complexity-patterns
• Extract patterns from review-consistency.md → devflow-consistency-patterns
• Extract patterns from review-tests.md → devflow-tests-patterns
• Extract patterns from review-database.md → devflow-database-patterns
• Extract patterns from review-documentation.md → devflow-documentation-patterns
• Extract patterns from review-dependencies.md → devflow-dependencies-patterns
• Extract patterns from review-regression.md → devflow-regression-patterns

Phase 2: Self-Review Framework

• Create skills/devflow-self-review/SKILL.md with 8 pillars
• Update agents/coder.md with Stop hook

Phase 3: Unified Reviewer

• Create agents/reviewer.md with parameterized focus
• Update commands/review.md to use Reviewer
• Update agents/review-summary.md to read .md files

Phase 4: Pipeline Integration

• Update commands/implement.md to call /review
• Test end-to-end flow

Phase 5: Cleanup

• Add deprecation notice to old review agents
• Update CLAUDE.md documentation
• Update README.md if needed

Pattern Skills Gap Analysis

Existing pattern skills:

• devflow-security-patterns - EXISTS

Missing pattern skills needed for Reviewer:

• devflow-architecture-patterns - MISSING
• devflow-performance-patterns - MISSING
• devflow-complexity-patterns - MISSING
• devflow-consistency-patterns - MISSING
• devflow-tests-patterns - MISSING
• devflow-database-patterns - MISSING
• devflow-documentation-patterns - MISSING
• devflow-dependencies-patterns - MISSING
• devflow-regression-patterns - MISSING

Decision: Extract ALL patterns from existing review agents into skills upfront. Each current review-{type}.md agent contains specialized knowledge that becomes devflow-{type}-patterns skill.

This adds ~9 new skill files but:

1. Makes patterns reusable (Coder can use them too)
2. Single source of truth for each domain
3. Cleaner separation of concerns

References

• Claude Code hooks documentation
• Google Engineering Practices
• Microsoft Engineering Playbook
• Issue feat: Shepherd hooks for subagent orchestration #27 (Shepherd hooks design - related but different scope)

[dean0x]

Design Clarifications (2026-01-11)

Following review of Issue #28 against Claude Code documentation and industry references (Google Engineering Practices, Microsoft Engineering Playbook), these decisions were made:

1. Focus Parameterization: Prompt Injection ✅

Decision: Single Reviewer agent receives focus via prompt text.

Mechanism:

Reviewer prompt: "Review this code focusing exclusively on SECURITY. 
Apply patterns from devflow-security-patterns skill.
Output findings to .docs/reviews/{branch}/security.md"

Rationale:

• No new infrastructure needed
• Claude Code Task tool doesn't support custom parameters
• Prompt injection is flexible and explicit

2. Documentation Added to P2 Pillars ✅

Decision: Add Documentation as 9th pillar at P2 priority.

Updated 8→9 Pillars:

Priority	Pillar
P0	Design, Functionality, Security
P1	Complexity, Error Handling, Tests
P2	Naming, Consistency, Documentation

Rationale: Aligns with Google Engineering Practices (#8) and Microsoft's Design Pass.

3. Feature Availability Verified ✅

All Claude Code features confirmed stable and documented:

• context: fork - skills.md
• agent field in frontmatter - skills.md
• hooks.Stop - hooks.md
• type: prompt hooks - hooks.md

4. Proceeding with Phase 1

Starting pattern skill extraction immediately (9 skills from existing review agents).

---

Resolved Concerns:

• Feature availability uncertainty → All features verified
• Parameterization mechanism unclear → Prompt injection
• Documentation pillar missing → Added to P2