/design-review-gate

name: design-review-gate
description: Automatic review gate that runs after brainstorming completes - spawns PM, Architect, Designer, Security, and CTO agents in parallel, iterates until all approve
auto_activate: true
triggers:
  - "design document created"
  - "docs/plans/*-design.md committed"
  - after:superpowers:brainstorming

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:

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

All five must approve before proceeding to implementation.

---

Coordination Mode Note

This skill supports both coordination modes:

• **Task Mode** (default): Spawn 5 parallel `Task()` subagents for each review round. Fresh instances per round.
• **Team Mode**: `TeamCreate("review-{design-doc-name}")`, spawn 5 reviewers as named teammates (`pm`, `architect`, `designer`, `security`, `cto`). Reviewers retain context through revision cycles — saves 5 cold starts per re-review round. After approval, send `shutdown_request` to all, then `TeamDelete`.

In either mode, the review criteria, iteration protocol, and escalation rules are identical. See `./guides/agent-coordination.md` for mode detection.

---

Activation Triggers

This skill auto-activates when:

1. A design document is committed to `docs/plans/*-design.md` 2. The `superpowers:brainstorming` skill completes 3. User explicitly requests: `/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 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:

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

---

Agent Prompts

Product Manager Agent Prompt

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:

```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

```markdown
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
- [ ] Service placement is correct
- [ ] Dependencies flow correctly (no circular deps)
- [ ] Naming conventions followed

### 2. Technical Correctness
- [ ] API contracts well-defined
- [ ] Database