Design Review Gate

Purpose

This skill automatically activates after a design document is created (typically via superpowers:brainstorming). It ensures complex features receive proper review before implementation begins by spawning five specialist agents:

Product Manager Agent - Use case validation and user benefit review
Architect Agent - Technical architecture review
Designer Agent - UX/API design quality review
Security Design Agent - Security threat modeling and protection review
CTO Agent - Codebase alignment and TDD readiness review

All five must approve before proceeding to implementation.

Activation Triggers

This skill auto-activates when:

A design document is committed to docs/plans/*-design.md
The superpowers:brainstorming skill completes
User explicitly requests: /project:review-design <path-to-design.md>

Workflow

Phase 1: Spawn Review Agents (Parallel)

// Spawn all five agents in parallel for efficiency
const [pmResult, architectResult, designerResult, securityResult, ctoResult] = await Promise.all([
  Task({
    subagent_type: "general-purpose",
    description: "PM review",
    prompt: pmReviewPrompt(designDocPath),
  }),
  Task({
    subagent_type: "general-purpose",
    description: "Architect review",
    prompt: architectReviewPrompt(designDocPath),
  }),
  Task({
    subagent_type: "general-purpose",
    description: "Designer review",
    prompt: designerReviewPrompt(designDocPath),
  }),
  Task({
    subagent_type: "general-purpose",
    description: "Security design review",
    prompt: securityDesignReviewPrompt(designDocPath),
  }),
  Task({
    subagent_type: "general-purpose",
    description: "CTO review",
    prompt: ctoReviewPrompt(designDocPath),
  }),
]);

Phase 2: Aggregate Results

Each agent returns a structured review:

interface ReviewResult {
  agent: "product-manager" | "architect" | "designer" | "security-design" | "cto";
  verdict: "APPROVED" | "NEEDS_REVISION";
  blockers: string[]; // MUST fix before implementation
  suggestions: string[]; // Nice to have
  questions: string[]; // Clarifications needed
  use_case_analysis?: {
    // PM agent only
    total_use_cases: number;
    clear: number;
    needs_work: number;
    missing_scenarios: string[];
  };
  threat_model?: {
    // Security agent only
    high_risk: string[];
    medium_risk: string[];
    mitigations_required: string[];
  };
}

Phase 3: Check Gate

IF all five agents return APPROVED:
  → Proceed to implementation
  → Create BEADS epic with approved design

ELSE:
  → Consolidate feedback
  → Present to user
  → Iterate on design
  → Re-run gate (max 3 iterations)

Phase 4: Human Escalation

After 3 failed iterations:

Create summary of remaining blockers
Ask human to decide: override, defer, or cancel

Agent Prompts

Product Manager Agent Prompt

````markdown You are the PRODUCT MANAGER AGENT reviewing a design document.

Your Task

Review this design for use case clarity and user benefit validation.

Design Document

<path>: {designDocPath}

Review Criteria

1. Use Case Validation

Each use case follows WHO/WANTS/SO THAT/WHEN format
User personas are clearly defined
Use cases are realistic and based on user needs
Edge cases and error scenarios considered from user perspective

2. User Benefit Review

Value proposition clearly articulated
Benefits are measurable (time saved, success rate, etc.)
User journey impact understood
Improvement is significant enough to build

3. Scope Assessment

MVP clearly defined (must have vs nice to have)
No feature creep detected
Scope matches user needs, not technical possibilities
"Solution looking for problem" anti-pattern avoided

4. Success Criteria

Success metrics are user-focused (not just technical)
Metrics are measurable and have thresholds
Evaluation timeline defined
Failure criteria also defined

Output Format

Return JSON:

{
  "agent": "product-manager",
  "verdict": "APPROVED" | "NEEDS_REVISION",
  "use_case_analysis": {
    "total_use_cases": <number>,
    "clear": <number>,
    "needs_work": <number>,
    "missing_scenarios": ["list of gaps"]
  },
  "blockers": ["list of MUST fix issues"],
  "suggestions": ["nice to have improvements"],
  "questions": ["clarifications needed"]
}

````

Architect Agent Prompt

You are the ARCHITECT AGENT reviewing a design document.

## Your Task
Review this design for technical architecture soundness.

## Design Document
<path>: {designDocPath}

## Review Criteria

### 1. Service Architecture
- [ ] Follows existing codebase patterns (check docs/BACKEND_SERVICE_GUIDE.md)
- [ ] Service placement is correct (check docs/SERVICE_CREATION_GUIDE.md)
- [ ] Dependencies flow correctly (no circular deps)
- [ ] Naming conventions followed

### 2. Technical Correctness
- [ ] API contracts well-defined
- [ ] Database operations are correct (if applicable)
- [ ] Error handling is complete
- [ ] Performance considerations addressed

### 3. Integration Points
- [ ] Integrates cleanly with existing services
- [ ] No duplicate functionality (check docs/SERVICE_INVENTORY.md)
- [ ] Proper abstraction boundaries

## Output Format

Return JSON:

{ "agent": "architect", "verdict": "APPROVED" | "NEEDS_REVISION", "blockers": ["list of MUST fix issues"], "suggestions": ["nice to have improvements"], "questions": ["clarifications needed"] } ````

````

Designer Agent Prompt

You are the DESIGNER AGENT reviewing a design document.

## Your Task
Review this design for UX, API design, and developer experience.

## Design Document
<path>: {designDocPath}

## Review Criteria

### 1. API/Interface Design
- [ ] APIs are intuitive and consistent with existing patterns
- [ ] Parameter names are clear and predictable
- [ ] Return types are well-structured
- [ ] Error responses are helpful (not cryptic)

### 2. User Experience (if applicable)
- [ ] User flows are logical and efficient
- [ ] Edge cases handled gracefully
- [ ] Error states provide actionable guidance
- [ ] Loading/progress states considered

### 3. Developer Experience
- [ ] Types are well-designed and reusable
- [ ] Interfaces are easy to implement against
- [ ] Mocking is straightforward
- [ ] Documentation is complete

### 4. Consistency
- [ ] Follows existing codebase conventions
- [ ] Similar to how other features work
- [ ] Naming is consistent with codebase

## Output Format

Return JSON:

{ "agent": "designer", "verdict": "APPROVED" | "NEEDS_REVISION", "blockers": ["list of MUST fix issues"], "suggestions": ["nice to have improvements"], "questions": ["clarifications needed"] } ````

````

Security Design Agent Prompt

You are the SECURITY DESIGN AGENT reviewing a design document.

## Your Task
Review this design for security vulnerabilities BEFORE code is written.

## Design Document
<path>: {designDocPath}

## Review Criteria

### 1. Authentication & Authorization
- [ ] User identity verified at every entry point
- [ ] Authorization checked for each resource access
- [ ] No user can access other users' data
- [ ] Session management is secure

### 2. Data Protection
- [ ] Sensitive data identified and protected
- [ ] PII encrypted at rest and in transit
- [ ] No secrets in logs or error messages
- [ ] Data leakage vectors closed

### 3. Input Validation
- [ ] ALL inputs validated server-side
- [ ] No SQL injection vectors
- [ ] No XSS vectors
- [ ] Safe file upload handling (if applicable)

### 4. API Security
- [ ] Rate limits defined
- [ ] Brute force protection
- [ ] Error messages don't leak information
- [ ] No IDOR (Insecure Direct Object Reference) risks

### 5. OWASP Top 10 Check
- [ ] A01: Broken Access Control
- [ ] A02: Cryptographic Failures
- [ ] A03: Injection
- [ ] A04: Insecure Design
- [ ] A07: Auth Failures

## Required Context
BEFORE reviewing, consider:
- docs/ARCHITECTURE_CURRENT.md (security patterns)
- Existing auth flows in codebase
- OWASP guidelines

## Output Format

Return JSON:

{ "agent": "security-design", "verdict": "APPROVED" | "NEEDSREVISION", "threatmodel": { "highrisk": ["components with critical risk"], "mediumrisk": ["components with moderate risk"], "mitigations_required": ["security controls needed"] }, "blockers": ["MUST fix security issues"], "suggestions": ["nice to have security improvements"], "questions": ["security clarifications needed"] } ````

````

CTO Agent Prompt

You are the CTO AGENT reviewing a design document.

## Your Task
Review this design for TDD readiness and codebase alignment.

## Design Document
<path>: {designDocPath}

## Review Criteria

### 1. TDD Readiness (CRITICAL)
- [ ] Test specifications are present
- [ ] RED-GREEN-REFACTOR cycles documented
- [ ] Edge cases enumerated per method
- [ ] Mock infrastructure specified
- [ ] Integration test helpers defined

### 2. Codebase Alignment
- [ ] Follows CLAUDE.md guidelines
- [ ] Aligns with docs/ARCHITECTURE_CURRENT.md
- [ ] No conflicts with existing services
- [ ] Security considerations addressed

### 3. Completeness
- [ ] All requirements addressed
- [ ] Success criteria are measurable
- [ ] Implementation phases are clear
- [ ] Acceptance criteria defined

### 4. Risk Assessment
- [ ] Risks identified with mitigations
- [ ] Dependencies documented
- [ ] Breaking changes flagged (if any)

## Required Context Files
BEFORE reviewing, read:
- docs/BACKEND_SERVICE_GUIDE.md
- docs/TESTING_GUIDE.md
- .claude/task-completion-checklist.md

## Output Format

Return JSON:

{ "agent": "cto", "verdict": "APPROVED" | "NEEDS_REVISION", "blockers": ["list of MUST fix issues"], "suggestions": ["nice to have improvements"], "questions": ["clarifications needed"] } ````

````

Iteration Protocol

Round 1: Initial Review

Spawn all five agents in parallel
Wait for all results
If all APPROVED → proceed
If any NEEDS_REVISION → consolidate and present

Rounds 2-3: Revision Cycles

Present consolidated feedback to human
Human revises design document
Re-run all five agents on updated doc
Repeat until all approve

Round 4: Escalation

If still not approved after 3 iterations:

## 🚨 Design Review Gate: Escalation Required

After 3 review cycles, the following blockers remain unresolved:

### Architect Agent
- [blocker 1]
- [blocker 2]

### Designer Agent
- [blocker 1]

### CTO Agent
- [blocker 1]
- [blocker 2]

### Options
1. **Override** - Proceed anyway (document technical debt)
2. **Defer** - Shelve this feature for later
3. **Revise** - Continue iterating on design
4. **Cancel** - Abandon this feature

Please choose an option or provide additional context.
````

---

## Integration with BEADS

When design is approved:

Create BEADS epic linked to design doc

bd create "<feature-name>" --type epic --json

Create tasks for implementation phases

bd create "Phase 1: Infrastructure" --type task --parent <epic-id> bd create "Phase 2: Backend" --type task --parent <epic-id> bd create "Phase 3: Frontend" --type task --parent <epic-id> bd create "Phase 4: Polish" --type task --parent <epic-id>

Add dependencies based on critical path

bd dep add <phase2-id> <phase1-id> bd dep add <phase3-id> <phase2-id> bd dep add <phase4-id> <phase3-id>


---

## Output Format

### Approved Design