@champpaba/claude-agent-kit 3.2.0 → 3.4.0

package/.claude/commands/cdev.md

@@ -40,39 +40,71 @@ Run: /csetup {change-id}
 
 ### Step 2: Read Current Phase
 
-```typescript
-const flags = JSON.parse(Read('openspec/changes/{change-id}/.claude/flags.json'))
-const currentPhase = flags.current_phase
-const phaseData = flags.phases[currentPhase]
-
-if (phaseData.status === 'completed') {
-  // Move to next phase
-  currentPhase = getNextPhase(flags)
-}
+---
+
+#### Step 2.1: Read flags.json
+
+1. Read the file `openspec/changes/{change-id}/.claude/flags.json`
+2. Extract and note these values:
+   - `current_phase` - The current phase name
+   - `phases[current_phase].status` - The phase status
+   - `phases[current_phase].agent` - The assigned agent
+
+---
+
+#### Step 2.2: Check Phase Status
+
+**If status equals "completed":**
+1. Look up the next phase in phases.md
+2. Update current_phase to the next phase name
+
+**If status equals "pending" or "in_progress":**
+1. Keep using the current phase (no change)
+
+---
+
+#### Step 2.3: Report Status
+
+Display this information:
 ```
+📍 Current Phase: {phase_number} - {phase_name}
+   Agent: {agent}
+   Status: {status}
+```
+
+---
 
 ### Step 3: Check Phase Type
 
-```typescript
-const agent = phaseData.agent
-
-if (agent === 'user') {
-  // Manual action required
-  output(`🛑 Phase ${phaseData.phase_number} requires manual action`)
-  output(`Instructions: ${getInstructions(currentPhase)}`)
-  output(`When done: /cdev ${changeId} --continue`)
-  return
-}
-
-if (agent.includes('+')) {
-  // Multiple agents (parallel)
-  agents = agent.split('+').map(a => a.trim())
-  invokeMultipleAgents(agents, changeId, currentPhase)
-} else {
-  // Single agent
-  invokeAgent(agent, changeId, currentPhase)
-}
-```
+---
+
+#### Step 3.1: Check for Manual Action
+
+**If the agent value equals "user":**
+1. Display this message:
+   ```
+   🛑 Phase {phase_number} requires manual action
+
+   Instructions:
+   {instructions from phases.md}
+
+   When done: /cdev {change-id} --continue
+   ```
+2. Stop execution and wait for user to complete the task
+3. Wait for user to run /cdev again
+
+---
+
+#### Step 3.2: Check for Multiple Agents
+
+**If the agent value contains "+" (example: "backend + database"):**
+1. Split the agent string by "+" into a list of individual agents
+2. Invoke all agents in parallel
+3. Wait for all agents to complete before proceeding
+
+**If there is only a single agent:**
+1. Invoke that single agent
+2. Wait for completion then proceed to Step 4
 
 ### Step 4: Invoke Agent with Retry & Validation
 
@@ -84,283 +116,268 @@ See: `.claude/lib/agent-executor.md` for full implementation
 
 1. **Calculate Context Size** (for model selection)
 2. **Select Model** (haiku vs sonnet based on complexity)
-3. **Execute Agent with Retry** (automatic retry on failure)
-4. **Validate Pre-Work** (enforce mandatory checklist)
-5. **Validate Output Quality** (check completeness)
-6. **Handle Errors** (retry or escalate)
+3. **Pre-Flight Design Check** (for visual agents) ← NEW v3.3.0
+4. **Execute Agent with Retry** (automatic retry on failure)
+5. **Validate Pre-Work** (enforce mandatory checklist)
+6. **Validate Output Quality** (check completeness)
+7. **Handle Errors** (retry or escalate)
 
-**Implementation:**
+### Step 4.0: Pre-Flight Design Check (v3.3.0)
 
-```typescript
-// Step 4: Invoke Agent with Retry & Validation
+→ **Full Protocol:** `.claude/lib/design-validator.md` (Part 2)
 
-// 4.1: Build agent prompt (with design reference + best practices - v2.1.2)
-function buildAgentPrompt(phase, changeContext) {
-  let prompt = `
-# Phase ${phase.phase_number}: ${phase.name}
+**When to execute:** Before invoking uxui-frontend or frontend agent
+
+---
 
-## Change Context
-${changeContext.proposal}
+#### Step 4.0.1: Check if Visual Agent
 
-## Tasks
-${changeContext.tasks}
+1. Look at the phase.agent value
+2. Check if it equals `uxui-frontend` or `frontend`
 
-## Design Decisions (from design.md)
-${changeContext.design || '(no design.md found)'}
+**If NOT a visual agent:**
+- Skip Step 4.0 entirely and proceed to Step 4.1
 
-${phase.instructions}
+**If it IS a visual agent:**
+- Proceed to next step
 
 ---
 
-## 📦 Library Requirements
+#### Step 4.0.2: Check for Design System
 
-**Scan for required libraries before implementation:**
+1. Attempt to read the file `design-system/data.yaml`
 
-1. **Review tasks.md above** for these patterns:
-   - "Install X and dependencies" → Use library X
-   - "Configure X with Y adapter" → Use X with adapter Y
-   - Backtick packages like \`better-auth\` → Required dependency
+**If the file exists:**
+1. Display this message:
+   ```
+   ✅ Design system found: design-system/data.yaml
+   ```
+2. Proceed to Step 4.0.3
 
-2. **Review "Design Decisions" section above** for:
-   - "### D1: Use X Library" → Decision to use X
-   - "**Decision:** Use X" → Chosen library
-   - Specific configurations (e.g., "JWT 15min", "Redis refresh token 30d")
-   - Architecture decisions (e.g., "Hybrid Session Strategy")
+**If the file does NOT exist:**
+1. Display this warning:
+   ```
+   ⚠️ WARNING: No design system found!
+      Path: design-system/data.yaml (not found)
 
-3. **Use the specified libraries**
-   - WHY: The team chose these for compatibility, features, or constraints
-   - Custom implementations duplicate effort and miss edge cases the library handles
+      Options:
+      1. Run /designsetup first (recommended)
+      2. Continue with fallback design principles
 
-4. **Implement according to Design Spec (not library defaults)**
-   - If design.md specifies "JWT 15min + Redis refresh 30d" → Configure library with these values
-   - If design.md specifies custom endpoints → Implement those endpoints
-   - Library defaults are starting points, not final implementation
-   - WHY: Design decisions were made for specific project requirements
+      Proceeding with fallback...
+   ```
+2. Skip to Step 4.1 without injecting design system instructions
 
-**Example:**
-\`\`\`
-design.md says:
-  "Hybrid Session Strategy: JWT 15min + Redis refresh 30d"
+---
 
-→ Use better-auth library (from tasks.md)
-→ Configure JWT plugin with 15min expiry
-→ Configure refresh token with 30d in Redis
-→ Implement /api/auth/refresh endpoint
+#### Step 4.0.3: Inject Design System Instructions
 
-WHY not defaults? Design spec has project-specific security requirements
-that differ from library defaults.
-\`\`\`
+When building the agent prompt, include this text:
 
-**Report in validation:**
-\`\`\`
-Libraries: better-auth, @better-auth/drizzle, ioredis
-Design Spec Implementation:
-- [x] JWT access token: 15min (design.md D1)
-- [x] Redis refresh token: 30d (design.md D2)
-- [x] /api/auth/refresh endpoint (design.md D3)
-\`\`\`
+```
+MANDATORY: Read design-system/data.yaml before writing any CSS/Tailwind.
+Report the tokens you loaded before starting implementation.
+
+You must report:
+- Colors: primary=#xxx, secondary=#xxx, etc.
+- Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
+- Animation durations: 150ms, 300ms, 500ms ONLY
+
+DO NOT use:
+- Hardcoded colors (#3b82f6, rgb())
+- Arbitrary spacing (p-5, gap-7)
+- Random durations (duration-200, duration-250)
+```
 
 ---
-`
 
-  // v3.1.0: Add Level 1 Universal Patterns (development-principles.md) for ALL agents
-  // Source: context-loading-protocol.md - Level 1 patterns apply to ALL agents
-  const devPrinciplesPath = '.claude/contexts/patterns/development-principles.md'
-  if (fileExists(devPrinciplesPath)) {
-    prompt += `
+#### Step 4.0.4: Verify Agent Compliance
 
----
+After the agent responds, check the output for this report:
 
-## 🏛️ Development Principles (Level 1 - ALL Agents)
+```
+✅ Design System Loaded (STEP 0.5)
+   - Source: design-system/data.yaml
+   - Colors: [list]
+   - Spacing: [list]
+   - Animation: [list]
+```
 
-**REQUIRED READING:** @${devPrinciplesPath}
+**If the report is present:**
+- Validation passed, proceed
 
-These principles apply to ALL code written by ALL agents:
+**If the report is missing:**
+- Ask the agent whether they read the design system
 
-**Quick Reference:**
-| Principle | Summary |
-|-----------|---------|
-| **KISS** | Choose simple solutions over complex ones |
-| **YAGNI** | Build only what you need now |
-| **SRP** | One responsibility per module |
-| **DRY** | Single source of truth for all knowledge |
-| **Fail Fast** | Detect and raise errors immediately |
-| **Observability** | Log everything that matters |
+---
 
-**Report format:**
-\`\`\`
-✅ Development Principles Applied
-   - KISS ✓ (simple implementation)
-   - DRY ✓ (no duplication)
-   - Separation of Concerns ✓
-\`\`\`
+### Step 4.1: Build Agent Prompt
 
----
-`
-  }
+Build the agent prompt by assembling these sections:
 
-  // Add best-practices reference for ALL agents
-  const bpDir = '.claude/contexts/domain/project/best-practices/'
-  if (fileExists(bpDir)) {
-    const bpFiles = listFiles(bpDir).filter(f => f.endsWith('.md') && f !== 'index.md')
+---
 
-    // Map agent type to relevant best-practices
-    const agentBpMapping = {
-      'uxui-frontend': ['react', 'nextjs', 'vue', 'tailwind'],
-      'frontend': ['react', 'nextjs', 'vue', 'typescript'],
-      'backend': ['express', 'fastapi', 'django', 'prisma', 'drizzle'],
-      'database': ['prisma', 'drizzle', 'postgres', 'mongodb'],
-      'test-debug': ['vitest', 'jest', 'playwright'],
-      'integration': ['typescript'], // minimal
-      'ux-tester': [] // No best practices needed - uses Chrome DevTools
-    }
+#### Section 1: Change Context
 
-    const relevantTechs = agentBpMapping[phase.agent] || []
-    const relevantFiles = bpFiles.filter(f =>
-      relevantTechs.some(tech => f.toLowerCase().includes(tech))
-    )
+Include information from these files:
+1. Read `proposal.md` - What we're building and why
+2. Read `tasks.md` - Tasks for this phase
+3. Read `design.md` - Design decisions (if the file exists)
+4. Read `phases.md` - Phase instructions
 
-    if (relevantFiles.length > 0) {
-      prompt += `
+Combine this information into the prompt context.
 
 ---
 
-## 📚 Best Practices (STEP 0)
+#### Section 2: Library Requirements (v2.1.2)
 
-Read these files before implementation for quality output:
+Add these instructions to the agent prompt:
+1. Scan tasks.md for patterns like: "Install X", "Configure X"
+2. Scan design.md for: "D1: Use X Library", "Decision: Use X"
+3. Use the specified libraries, not custom implementations
+4. Implement according to design spec, not library defaults
 
-${relevantFiles.map(f => `- Read: ${bpDir}${f}`).join('\n')}
+---
 
-**Report format:**
-\`\`\`
-✅ Best Practices Loaded
-   ${relevantFiles.map(f => `- ${f.replace('.md', '')} ✓`).join('\n   ')}
-\`\`\`
+#### Section 3: Development Principles (v3.1.0 - ALL agents)
 
-WHY: Best practices ensure consistency with project patterns.
+**If the file `.claude/contexts/patterns/development-principles.md` exists:**
 
----
-`
-    }
-  }
+Add this section to the prompt:
+```
+## 🏛️ Development Principles (Level 1 - ALL Agents)
 
-  // Add design reference for uxui-frontend agent (not full content!)
-  if (phase.agent === 'uxui-frontend') {
-    const tokensPath = 'design-system/data.yaml'
-    const dataYamlPath = 'design-system/data.yaml'
-    const hasTokens = fileExists(tokensPath)
+REQUIRED READING: @.claude/contexts/patterns/development-principles.md
 
-    if (hasTokens) {
-      prompt += `
+Quick Reference:
+| Principle | Summary |
+|-----------|---------|
+| KISS | Choose simple solutions |
+| YAGNI | Build only what you need now |
+| SRP | One responsibility per module |
+| DRY | Single source of truth |
+| Fail Fast | Detect errors immediately |
+```
 
 ---
 
-## 🎨 Design System (STEP 0.5)
-
-**Files to read:**
+#### Section 4: Best Practices (agent-specific)
 
-${hasTokens ? `- design-system/data.yaml (~500 tokens) - Colors, spacing, typography, psychology` : ''}
+**If the directory `.claude/contexts/domain/project/best-practices/` exists:**
 
-**Style Guidelines:**
+1. Determine which best-practices files match the current agent:
 
-| Instead of | Use | WHY |
-|------------|-----|-----|
-| text-gray-500, #64748b | text-foreground/70, bg-muted | Theme-aware |
-| p-5, gap-7 | p-4, p-6, gap-8 | Spacing scale |
-| mixing shadow-sm/lg | consistent shadow-md | Visual consistency |
+   | Agent | Relevant Topics |
+   |-------|-----------------|
+   | uxui-frontend | react, nextjs, vue, tailwind |
+   | frontend | react, nextjs, vue, typescript |
+   | backend | express, fastapi, django, prisma, drizzle |
+   | database | prisma, drizzle, postgres, mongodb |
+   | test-debug | vitest, jest, playwright |
+   | integration | typescript |
+   | ux-tester | (none) |
 
-**Report format:**
-\`\`\`
-✅ Design System Loaded
-   - data.yaml ✓
-   - Design Tokens Extracted: [list key tokens]
-\`\`\`
+2. Add this section to the prompt with the relevant file names:
+   ```
+   ## 📚 Best Practices (STEP 0)
 
-WHY: Design tokens ensure visual consistency across components.
+   Read these files before implementation:
+   - Read: .claude/contexts/domain/project/best-practices/{relevant-file}.md
+   ```
 
 ---
-`
-    } else {
-      prompt += `
 
----
+#### Section 5: Design System (uxui-frontend only)
 
-⚠️ **WARNING:** No design system found!
-Using fallback: .claude/contexts/design/*.md (universal principles)
+**If the agent equals uxui-frontend:**
 
-Run \`/designsetup\` to generate project-specific design system.
+1. Check if `design-system/data.yaml` exists
 
----
-`
-    }
-  }
+   **If the file exists:**
+   Add this section to the prompt:
+   ```
+   ## 🎨 Design System (STEP 0.5)
 
-  return prompt
-}
+   Files to read:
+   - design-system/data.yaml
 
-const prompt = buildAgentPrompt(phase, changeContext)
+   Style Guidelines:
+   | Instead of | Use |
+   |------------|-----|
+   | text-gray-500, #64748b | text-foreground, bg-muted |
+   | p-5, gap-7 | p-4, p-6, gap-8 |
+   | mixing shadow-sm/lg | consistent shadow-md |
+   ```
 
-// 4.2: Execute agent with retry & validation
-output(`\n🚀 Invoking ${phase.agent} agent (model: opus)...`)
+   **If the file does NOT exist:**
+   Add this warning to the prompt:
+   ```
+   ⚠️ WARNING: No design system found!
+   Using fallback: .claude/contexts/design/*.md
+   ```
+
+---
 
-const result = await executeAgentWithRetry(
-  phase.agent,
-  phase,
-  changeContext,
-  {
-    max_retries: 2,
-    retry_delay: 5000,
-    timeout: 600000,  // 10 minutes
-    validate_output: true
-  }
-)
+### Step 4.2: Execute Agent with Retry
 
-// 4.3: Handle result
-if (result.success) {
-  output(`\n✅ Phase ${phase.phase_number} completed successfully!`)
-  output(`⏱️ Execution time: ${(result.execution_time / 1000).toFixed(1)}s`)
-  output(`🔄 Retries used: ${result.retries_used}`)
-  output(`✅ Validation: ${result.validation_passed ? 'PASSED' : 'SKIPPED'}`)
+---
 
-  // Continue to Step 5: Post-Execution
-} else {
-  output(`\n❌ Phase ${phase.phase_number} failed`)
-  output(`Error: ${result.error}`)
-  output(`Retries used: ${result.retries_used}`)
+#### Step 4.2.1: Invoke the Agent
 
-  // Escalate to user
-  const action = await escalateToUser(phase.agent, phase, result)
+1. Display this message before invoking:
+   ```
+   🚀 Invoking {agent} agent (model: opus)...
+   ```
 
-  switch (action) {
-    case 'retry':
-      output(`Retrying Phase ${phase.phase_number}...`)
-      // Restart Step 4
-      return executePhaseAgain(changeId, phase)
+2. Invoke the agent with these settings:
+   - Model: opus (fixed)
+   - Timeout: 10 minutes
+   - Max retries: 2 attempts
 
-    case 'skip':
-      output(`⚠️ Skipping Phase ${phase.phase_number}`)
-      await markPhaseAsSkipped(changeId, phase, result.error)
-      // Continue to next phase
-      break
+---
 
-    case 'abort':
-      output(`🛑 Workflow aborted`)
-      output(`Resume with: /cdev ${changeId}`)
-      return
-  }
-}
-```
+#### Step 4.2.2: Handle Result
+
+**If execution succeeded:**
+1. Display this success message:
+   ```
+   ✅ Phase {phase_number} completed successfully!
+   ⏱️ Execution time: {time}s
+   🔄 Retries used: {retries}
+   ✅ Validation: PASSED
+   ```
+2. Proceed to Step 5
+
+**If execution failed:**
+1. Display this error message:
+   ```
+   ❌ Phase {phase_number} failed
+   Error: {error}
+   Retries used: {retries}
+   ```
+
+2. Ask the user for their choice:
+   ```
+   Options:
+   [retry] - Try again
+   [skip]  - Skip this phase
+   [abort] - Stop execution
+   ```
+
+3. Wait for user response and act accordingly
 
-**Helper Functions Used:**
+---
 
-1. **buildAgentPrompt()**: See `.claude/lib/agent-executor.md`
-2. **executeAgentWithRetry()**: See `.claude/lib/agent-executor.md`
-3. **escalateToUser()**: See `.claude/lib/agent-executor.md`
+**Helper Functions:**
+
+See `.claude/lib/agent-executor.md` for:
+- buildAgentPrompt()
+- executeAgentWithRetry()
+- escalateToUser()
 
 **Model Strategy:**
 - All agents use `model: opus` (fixed)
 - Opus 4.5 is the latest Claude model with best performance
-- Quality maintained through comprehensive validation framework
 
 ---
 
@@ -389,309 +406,302 @@ See `.claude/contexts/patterns/validation-framework.md` for complete checklist p
 
 ### Step 4.6: Approval Gate Handling (v2.7.0)
 
-**NEW:** Handle phases with `requires_approval: true` (e.g., ux-tester Phase 1.5)
+**For phases with** `requires_approval: true` (example: ux-tester Phase 1.5)
+
+---
+
+#### Step 4.6.1: Check if Approval Required
+
+1. Look in phases.md at the current phase
+2. Check if it has:
+   - `requires_approval: true`
+   - OR metadata contains the word `approval-gate`
+
+**If approval is NOT required:**
+- Skip Step 4.6 entirely
+
+**If approval IS required:**
+- Proceed to next step
 
-```typescript
-// Check if this phase requires user approval
-const isApprovalGate = phase.requires_approval === true ||
-                       phase.metadata?.includes('approval-gate')
+---
 
-if (isApprovalGate && result.success) {
-  // Read all phases for loop back logic
-  const phasesPath = `openspec/changes/${changeId}/.claude/phases.md`
-  const allPhases = parsePhasesFromMd(Read(phasesPath))
+#### Step 4.6.2: Display Results and Wait for Decision
 
-  output(`
+Display this message:
+```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🧪 ${phase.name} Complete - Awaiting Approval
+🧪 {phase_name} Complete - Awaiting Approval
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-${result.summary || 'Report generated successfully'}
+{result_summary}
 
-📄 Full report: ${result.reportPath || `openspec/changes/${changeId}/ux-test-report.md`}
+📄 Full report: openspec/changes/{change-id}/ux-test-report.md
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-กรุณาตัดสินใจ:
+Please decide:
 
-✅ "approve" → ไป Phase ถัดไป
-❌ "reject [feedback]" → กลับแก้ไข Phase ก่อนหน้า
+✅ "approve" → Continue to next phase
+❌ "reject [feedback]" → Go back and fix previous phase
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  `)
-
-  // PAUSE - Main Claude waits for user's next message
-  // User responds with "approve" or "reject [feedback]"
-  return { status: 'awaiting_approval', phase, changeId }
-}
-
-// When user responds (in next message):
-function handleUserApprovalResponse(userResponse: string, phase: Phase, changeId: string, allPhases: Phase[]) {
-  const normalized = userResponse.trim().toLowerCase()
-
-  // Handle APPROVE
-  if (normalized.match(/^(approve|approved|ok|yes|ใช่|อนุมัติ|ผ่าน|ลุย|ได้|ดี)$/)) {
-    output(`✅ ${phase.name} approved! Continuing to next phase...`)
-    updateFlags(changeId, {
-      [`phase_${phase.phase_number}`]: {
-        status: 'approved',
-        approved_at: new Date().toISOString()
-      }
-    })
-    // Continue to Step 5
-    return { action: 'continue' }
-  }
-
-  // Handle REJECT
-  if (normalized.startsWith('reject') || normalized.startsWith('ไม่') ||
-      normalized.startsWith('แก้') || normalized.startsWith('no')) {
-
-    const feedback = userResponse.replace(/^(reject|ไม่อนุมัติ|แก้ไข|no)\s*/i, '').trim()
-
-    // Find the phase to loop back to
-    const loopBackPhase = allPhases.find(p => p.agent === 'uxui-frontend') || allPhases[0]
-
-    output(`
-🔄 ${phase.name} rejected
-
-📝 Feedback: ${feedback || 'None provided'}
-🔙 Looping back to: Phase ${loopBackPhase.phase_number} - ${loopBackPhase.name}
-
-${loopBackPhase.agent} agent จะได้รับ feedback นี้เพื่อแก้ไข
-    `)
-
-    // Update flags for rejection
-    updateFlags(changeId, {
-      [`phase_${phase.phase_number}`]: {
-        status: 'rejected',
-        rejected_at: new Date().toISOString(),
-        rejection_feedback: feedback
-      },
-      [`phase_${loopBackPhase.phase_number}`]: {
-        status: 'pending',
-        rerun_reason: `Rejected from UX Testing: ${feedback}`
-      }
-    })
-
-    // Loop back to uxui-frontend phase
-    output(`\n🔄 Restarting Phase ${loopBackPhase.phase_number}: ${loopBackPhase.name}`)
-    return {
-      action: 'loop_back',
-      loopBackPhase,
-      feedback
-    }
-  }
-
-  // Unknown response - ask again
-  output(`⚠️ ไม่เข้าใจคำตอบ กรุณาตอบ "approve" หรือ "reject [feedback]"`)
-  return { action: 'ask_again' }
-}
 ```
 
+Wait for user response.
+
+---
+
+#### Step 4.6.3: Handle User Response
+
+**If user approves:**
+1. Recognize these words as approval: approve, approved, ok, yes, ใช่, อนุมัติ, ผ่าน, ลุย, ได้, ดี
+2. Display: `✅ {phase_name} approved! Continuing to next phase...`
+3. Update flags.json: set status = "approved"
+4. Proceed to Step 5
+
+**If user rejects:**
+1. Recognize these words as rejection: reject, ไม่, แก้, no (followed by feedback)
+2. Extract the feedback text from the user's message
+3. Identify which phase needs to be fixed (uxui-frontend)
+4. Display:
+   ```
+   🔄 {phase_name} rejected
+
+   📝 Feedback: {feedback}
+   🔙 Looping back to: Phase {X} - {phase_name}
+
+   {agent} agent will receive this feedback for fixes
+   ```
+5. Update flags.json: set status = "rejected"
+6. Return to run the phase that needs fixing
+
+**If response is unclear:**
+1. Display:
+   ```
+   ⚠️ Response unclear. Please answer "approve" or "reject [feedback]"
+   ```
+2. Ask the user again
+
+---
+
 **See:** `.claude/lib/agent-executor.md` → "Approval Gate Execution" section for complete flow
 
 ---
 
 ### Step 4.7: Validate Page Plan Compliance (uxui-frontend only)
 
-**Only runs for uxui-frontend agent when page-plan.md exists:**
-
-**Purpose:** Verify agent implemented ALL sections from page-plan.md, not a subset.
-
-```typescript
-// Check if page-plan.md exists
-const pagePlanPath = `openspec/changes/${changeId}/page-plan.md`
-const hasPagePlan = fileExists(pagePlanPath)
-
-if (phase.agent === 'uxui-frontend' && hasPagePlan) {
-  output(`\n🔍 Validating page-plan.md compliance...`)
-
-  // Extract sections from page-plan.md Section 2 (Page Structure)
-  const pagePlan = Read(pagePlanPath)
-  const section2Match = pagePlan.match(/## 2\. Page Structure[\s\S]*?(?=## 3\.|## 2\.5|## 2\.6|$)/)
-
-  if (section2Match) {
-    // Count expected sections (extract component names from JSX)
-    const componentMatches = section2Match[0].match(/<([A-Z]\w+)/g) || []
-    const expectedComponents = componentMatches
-      .map(m => m.replace('<', ''))
-      .filter(name => name !== 'Layout' && name !== 'div') // Exclude wrappers
-
-    const uniqueComponents = [...new Set(expectedComponents)] // Remove duplicates
-
-    output(`\n📋 Page Plan Analysis:`)
-    output(`   Expected sections: ${uniqueComponents.length}`)
-    output(`   Components: ${uniqueComponents.join(', ')}`)
-
-    // Prompt user to verify agent compliance
-    output(`\n⚠️ VALIDATION REQUIRED:`)
-    output(`\nDid the agent implement ALL ${uniqueComponents.length} sections?`)
-    output(`\nPlease verify the implementation includes:`)
-    uniqueComponents.forEach(c => output(`   - ${c}`))
-
-    output(`\nOptions:`)
-    output(`  [yes]   - All sections implemented ✓`)
-    output(`  [retry] - Agent skipped sections, retry with strict enforcement`)
-    output(`  [skip]  - Skip validation (not recommended)`)
-
-    const answer = await askUser(`\nConfirm all sections implemented?`)
-
-    if (answer === 'retry') {
-      output(`\n🔄 Retrying phase with enhanced enforcement...`)
-      output(`Agent will be explicitly instructed to implement all ${uniqueComponents.length} sections`)
-
-      // Restart phase with enhanced prompt
-      return executePhaseAgain(changeId, phase, {
-        enforce_page_plan: true,
-        required_sections: uniqueComponents
-      })
-    } else if (answer === 'skip') {
-      warn(`\n⚠️ Skipping validation - proceed with caution`)
-      warn(`   This may result in incomplete implementation`)
-    } else {
-      output(`\n✅ Page plan compliance confirmed`)
-      output(`   All ${uniqueComponents.length} sections implemented`)
-    }
-  } else {
-    warn(`\n⚠️ Could not parse page-plan.md Section 2`)
-    warn(`   Skipping compliance validation`)
-  }
-} else {
-  // Not uxui-frontend or no page-plan.md - skip validation
-  output(`\nℹ️ Page plan validation: N/A (agent: ${phase.agent}, has plan: ${hasPagePlan})`)
-}
+**Only for uxui-frontend agent when page-plan.md exists**
+
+**Purpose:** Verify that agent implemented all sections from page-plan.md
+
+---
+
+#### Step 4.7.1: Check Prerequisites
+
+**If agent is NOT uxui-frontend OR page-plan.md does NOT exist:**
+1. Display:
+   ```
+   ℹ️ Page plan validation: N/A (agent: {agent}, has plan: {true/false})
+   ```
+2. Skip Step 4.7 entirely
+
+**If agent equals uxui-frontend AND page-plan.md exists:**
+- Proceed to next step
+
+---
+
+#### Step 4.7.2: Analyze page-plan.md
+
+1. Read `openspec/changes/{change-id}/page-plan.md`
+2. Find Section 2 (Page Structure)
+3. Count the components:
+   - Look for JSX elements starting with uppercase (example: `<HeroSection>`, `<PricingTable>`)
+   - Do NOT count Layout, div (wrapper elements)
+   - Remove duplicates
+
+4. Display:
+   ```
+   📋 Page Plan Analysis:
+      Expected sections: {count}
+      Components: {list}
+   ```
+
+---
+
+#### Step 4.7.3: Ask User for Confirmation
+
+Display this prompt:
+```
+⚠️ VALIDATION REQUIRED:
+
+Did the agent implement ALL {count} sections?
+
+Please verify the implementation includes:
+   - {Component1}
+   - {Component2}
+   - ...
+
+Options:
+  [yes]   - All sections implemented ✓
+  [retry] - Agent skipped sections, retry with strict enforcement
+  [skip]  - Skip validation (not recommended)
 ```
 
+Wait for user response.
+
+---
+
+#### Step 4.7.4: Handle User Response
+
+**If user answers yes:**
+1. Display:
+   ```
+   ✅ Page plan compliance confirmed
+      All {count} sections implemented
+   ```
+2. Proceed to Step 5
+
+**If user answers retry:**
+1. Display:
+   ```
+   🔄 Retrying phase with enhanced enforcement...
+   Agent will be explicitly instructed to implement all {count} sections
+   ```
+2. Return to run the phase again with enhanced prompt
+
+**If user answers skip:**
+1. Display:
+   ```
+   ⚠️ Skipping validation - proceed with caution
+      This may result in incomplete implementation
+   ```
+2. Proceed to Step 5
+
+---
+
 **When to use:**
-- ✅ Agent: uxui-frontend
-- ✅ page-plan.md exists
-- ✅ Phase completed successfully
+- Agent: uxui-frontend
+- page-plan.md exists
+- Phase completed successfully
 
 **Common issues caught:**
 - Agent implemented 5/10 sections (missing ProblemSection, ComparisonTable, etc.)
 - Agent followed tasks.md ("4-5 components") instead of page-plan.md (10 sections)
 - Agent skipped sections they thought were "optional"
 
-**Remediation:**
-- If validation fails → Retry with `enforce_page_plan: true`
-- Agent will receive enhanced prompt with explicit section list
-- Validation runs again after retry
-
 ---
 
 ### Step 5: Post-Execution (Flags Update)
 
-**Main Claude updates flags.json after each phase completion.**
+**Main Claude updates flags.json after each phase**
 
 → See: `.claude/lib/flags-updater.md` for complete protocol
 
 WHY: Immediate updates ensure /cstatus shows accurate progress.
 
-**Execution Order:**
-
-```typescript
-// 1. Update flags.json
-output(`\n🔄 Updating progress tracking...`)
-
-// See flags-updater.md for updateFlagsAfterPhase() implementation
-updateFlagsAfterPhase(changeId, currentPhase, agentResponse)
-
-// This function:
-// - Marks phase as completed
-// - Records actual duration
-// - Extracts files created/modified
-// - Updates meta statistics (progress %, time remaining)
-// - Moves current_phase to next phase
-// - Writes back to flags.json
-// - Reports progress to user
-
-// 2. Read updated flags
-const flagsPath = `openspec/changes/${changeId}/.claude/flags.json`
-const flags = JSON.parse(Read(flagsPath))
-
-// 3. Report progress to user
-output(`\n📊 Progress Update:`)
-output(`   ✅ ${flags.meta.completed_phases}/${flags.meta.total_phases} phases complete`)
-output(`   📈 ${flags.meta.progress_percentage}% progress`)
-output(`   ⏱️  ${formatDuration(flags.meta.total_actual_minutes)} spent`)
-output(`   ⏱️  ${formatDuration(flags.meta.time_remaining_estimate)} remaining`)
-
-// 4. Check next phase
-if (flags.ready_to_archive) {
-  // 🆕 v1.2.0: Verbose Summary Output (replaces documentation/report phases)
-  output(`\n`)
-  output(`╔════════════════════════════════════════════════════════════╗`)
-  output(`║           ✅ CHANGE COMPLETED SUCCESSFULLY                 ║`)
-  output(`╚════════════════════════════════════════════════════════════╝`)
-  output(``)
-  output(`📦 Change: ${changeId}`)
-  output(`📋 Template: ${flags.template} (${flags.meta.total_phases} phases)`)
-  output(``)
-  output(`═══════════════════════════════════════════════════════════════`)
-  output(`📊 EXECUTION SUMMARY`)
-  output(`═══════════════════════════════════════════════════════════════`)
-  output(``)
-  output(`⏱️  Time:`)
-  output(`   • Estimated: ${formatDuration(flags.meta.total_estimated_minutes)}`)
-  output(`   • Actual:    ${formatDuration(flags.meta.total_actual_minutes)}`)
-  output(`   • Variance:  ${calculateVariance(flags.meta)}`)
-  output(``)
-  output(`📈 Phases Completed: ${flags.meta.completed_phases}/${flags.meta.total_phases}`)
-
-  // List all phases with status
-  Object.entries(flags.phases).forEach(([phaseId, phase]) => {
-    const status = phase.status === 'completed' ? '✅' :
-                   phase.status === 'skipped' ? '⏭️' : '❌'
-    const time = phase.actual_minutes ? `(${phase.actual_minutes}m)` : ''
-    output(`   ${status} ${phase.phase_number}. ${phaseId} ${time}`)
-  })
-
-  output(``)
-  output(`═══════════════════════════════════════════════════════════════`)
-  output(`📁 FILES CREATED/MODIFIED`)
-  output(`═══════════════════════════════════════════════════════════════`)
-
-  // Collect all files from phase outputs
-  const allFiles = collectFilesFromPhases(flags.phases)
-  if (allFiles.created.length > 0) {
-    output(``)
-    output(`✨ Created (${allFiles.created.length}):`)
-    allFiles.created.forEach(f => output(`   • ${f}`))
-  }
-  if (allFiles.modified.length > 0) {
-    output(``)
-    output(`📝 Modified (${allFiles.modified.length}):`)
-    allFiles.modified.forEach(f => output(`   • ${f}`))
-  }
-
-  output(``)
-  output(`═══════════════════════════════════════════════════════════════`)
-  output(`🚀 NEXT STEPS`)
-  output(`═══════════════════════════════════════════════════════════════`)
-  output(``)
-  output(`1. Review changes:  /cview ${changeId}`)
-  output(`2. Test manually:   Verify the implementation works`)
-  output(`3. Mark complete:   Update tasks.md (mark all [x])`)
-  output(`4. Archive:         openspec archive ${changeId}`)
-  output(``)
-  output(`💡 Note: flags.json contains full execution history`)
-  output(`   Path: openspec/changes/${changeId}/.claude/flags.json`)
-  output(``)
-} else {
-  const nextPhase = flags.phases[flags.current_phase]
-
-  output(`\n📍 Next: Phase ${nextPhase.phase_number}: ${flags.current_phase}`)
-  output(`   Agent: ${nextPhase.agent}`)
-  output(`   Estimated: ${nextPhase.estimated_minutes} min`)
-
-  if (nextPhase.agent === 'user') {
-    output('\n🛑 Next phase requires your action')
-    output(`When done: /cdev ${changeId} --continue`)
-  } else {
-    output('\nContinue? (yes/no)')
-  }
-}
+---
+
+#### Step 5.1: Update flags.json
+
+1. Display:
+   ```
+   🔄 Updating progress tracking...
+   ```
+
+2. Update these fields in flags.json:
+   - Mark the phase as completed
+   - Record actual duration
+   - Extract files created/modified
+   - Update meta statistics (progress %, time remaining)
+   - Move current_phase to next phase
+
+---
+
+#### Step 5.2: Report Progress
+
+Display this progress summary:
 ```
+📊 Progress Update:
+   ✅ {completed}/{total} phases complete
+   📈 {percentage}% progress
+   ⏱️  {time_spent} spent
+   ⏱️  {time_remaining} remaining
+```
+
+---
+
+#### Step 5.3: Check Next Phase
+
+**If all phases are complete (ready_to_archive equals true):**
+
+Display this completion report:
+```
+╔════════════════════════════════════════════════════════════╗
+║           ✅ CHANGE COMPLETED SUCCESSFULLY                 ║
+╚════════════════════════════════════════════════════════════╝
+
+📦 Change: {change-id}
+📋 Template: {template} ({total_phases} phases)
+
+═══════════════════════════════════════════════════════════════
+📊 EXECUTION SUMMARY
+═══════════════════════════════════════════════════════════════
+
+⏱️  Time:
+   • Estimated: {estimated}
+   • Actual:    {actual}
+   • Variance:  {variance}
+
+📈 Phases Completed: {completed}/{total}
+   ✅ 1. phase-name (Xm)
+   ✅ 2. phase-name (Xm)
+   ...
+
+═══════════════════════════════════════════════════════════════
+📁 FILES CREATED/MODIFIED
+═══════════════════════════════════════════════════════════════
+
+✨ Created ({count}):
+   • {file1}
+   • {file2}
+
+📝 Modified ({count}):
+   • {file1}
+   • {file2}
+
+═══════════════════════════════════════════════════════════════
+🚀 NEXT STEPS
+═══════════════════════════════════════════════════════════════
+
+1. Review changes:  /cview {change-id}
+2. Test manually:   Verify the implementation works
+3. Mark complete:   Update tasks.md (mark all [x])
+4. Archive:         openspec archive {change-id}
+```
+
+**If there are still incomplete phases:**
+
+Display the next phase information:
+```
+📍 Next: Phase {X}: {phase_name}
+   Agent: {agent}
+   Estimated: {X} min
+```
+
+**If the next phase requires manual action:**
+Display:
+```
+🛑 Next phase requires your action
+When done: /cdev {change-id} --continue
+```
+
+**If the next phase is an agent:**
+Ask the user:
+```
+Continue? (yes/no)
+```
+
+---
 
 **Key points:**
 - Main Claude updates flags.json (sub-agents don't have access)