@champpaba/claude-agent-kit 2.6.0 → 2.7.0

package/.claude/contexts/patterns/ui-component-consistency.md

@@ -91,7 +91,7 @@ const ANIMATION_TOKENS = {
   hover: {
     properties: ['transform', 'box-shadow'],  // GPU-accelerated only
     values: ['scale(1.05)', 'shadow-lg'],
-    duration: '150ms',                         // From STYLE_TOKENS.json
+    duration: '150ms',                         // From data.yaml
     easing: 'ease-in-out',
     classes: 'hover:scale-105 hover:shadow-lg transition-all duration-150'
   },
@@ -121,7 +121,7 @@ const ANIMATION_TOKENS = {
 
 **Critical Rules:**
 1. ✅ Extract animation from reference component (same as colors, spacing)
-2. ✅ Use durations from STYLE_TOKENS.json (150ms, 300ms, 500ms)
+2. ✅ Use durations from data.yaml (150ms, 300ms, 500ms)
 3. ✅ Use GPU-accelerated properties (transform, opacity) - NOT width, height, top, left
 4. ✅ Same component type = same animation pattern (buttons scale, cards elevate shadow)
 5. ❌ NO random durations (200ms, 250ms) - only 150/300/500ms
@@ -308,7 +308,7 @@ transition: 'transition-colors'
 - [ ] Found similar reference component in codebase
 - [ ] Extracted all design tokens (icon, spacing, colors, states, **animations**)
 - [ ] Extracted animation tokens (hover, focus, active, durations)
-- [ ] Verified durations match STYLE_TOKENS.json (150/300/500ms)
+- [ ] Verified durations match data.yaml (150/300/500ms)
 - [ ] Verified animation properties are GPU-accelerated (transform, opacity)
 - [ ] Applied tokens exactly (no guessing, no random values)
 - [ ] Tested visual appearance in browser

package/.claude/lib/README.md

@@ -39,7 +39,7 @@ Standardized handoff formats for agent-to-agent communication. Includes all 15 h
 Complete TDD implementation examples (Stripe integration, user auth). Used by frontend, backend, database agents.
 
 **`document-loader.md`** - Token-efficient document loading
-Unified pattern for loading design system files. 3-tier strategy: STYLE_TOKENS.json → design-context.md → STYLE_GUIDE.md.
+Unified pattern for loading design system files. 3-tier strategy: data.yaml → design-context.md → README.md (fallback).
 
 ---
 

package/.claude/lib/agent-executor.md

@@ -154,6 +154,7 @@ WHY: Pre-work validation ensures agents loaded context before implementing. This
 | backend | Patterns Loaded ✓, Existing Endpoints Search ✓, TDD Workflow (if required) |
 | database | Schema Analysis ✓ |
 | test-debug | Test Infrastructure ✓ |
+| ux-tester | Personas Generated ✓, Dev Server Found ✓, Chrome DevTools Connected ✓ |
 
 **Validation Logic:**
 ```typescript
@@ -978,4 +979,226 @@ async function executePhase(phase: Phase, changeId: string) {
 
 ---
 
+## 🛑 Approval Gate Execution (v2.7.0)
+
+> **NEW:** Handle phases with `requires_approval: true` (e.g., ux-tester)
+
+### Detection
+
+```typescript
+function isApprovalGatePhase(phase: Phase): boolean {
+  return phase.requires_approval === true ||
+         phase.metadata?.includes('approval-gate')
+}
+```
+
+### Execution Flow
+
+```typescript
+async function executeApprovalGatePhase(phase: Phase, changeId: string): Promise<ApprovalResult> {
+  // Step 1: Execute the agent (e.g., ux-tester)
+  const agentResult = await executeAgent(phase.agent, buildPrompt(phase))
+
+  // Step 2: Validate agent output
+  if (!agentResult.success) {
+    return { status: 'failed', error: agentResult.error }
+  }
+
+  // Step 3: Update flags to "awaiting_approval"
+  updateFlags(changeId, {
+    [`phase_${phase.number}`]: {
+      status: 'awaiting_approval',
+      report_path: agentResult.reportPath
+    }
+  })
+
+  // Step 4: Display report summary to user
+  output(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧪 ${phase.name} Complete - Awaiting Approval
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${agentResult.summary}
+
+📄 Full report: ${agentResult.reportPath}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+กรุณาตัดสินใจ:
+
+✅ "approve" → ไป Phase ${getNextPhase(phase).number}
+❌ "reject [feedback]" → กลับ Phase ${getPreviousPhase(phase).number} แก้ไข
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `)
+
+  // Step 5: PAUSE and wait for user response
+  const userResponse = await waitForUserInput()
+
+  // Step 6: Handle response
+  return handleApprovalResponse(userResponse, phase, changeId)
+}
+```
+
+### Response Handling
+
+```typescript
+function handleApprovalResponse(
+  response: string,
+  phase: Phase,
+  changeId: string,
+  allPhases: Phase[]  // Added: need all phases for loop back
+): ApprovalResult {
+  const normalized = response.trim().toLowerCase()
+
+  // Approve patterns
+  if (normalized.match(/^(approve|approved|ok|yes|ใช่|อนุมัติ|ผ่าน|ลุย)$/)) {
+    updateFlags(changeId, {
+      [`phase_${phase.number}`]: {
+        status: 'approved',
+        approved_at: new Date().toISOString()
+      }
+    })
+
+    output(`✅ ${phase.name} approved! Continuing to next phase...`)
+
+    return {
+      status: 'approved',
+      nextAction: 'continue'
+    }
+  }
+
+  // Reject patterns
+  if (normalized.startsWith('reject') || normalized.startsWith('ไม่') ||
+      normalized.startsWith('แก้') || normalized.startsWith('no')) {
+
+    // Extract feedback from rejection
+    const feedback = response.replace(/^(reject|ไม่อนุมัติ|แก้ไข|no)\s*/i, '').trim()
+
+    updateFlags(changeId, {
+      [`phase_${phase.number}`]: {
+        status: 'rejected',
+        rejected_at: new Date().toISOString(),
+        rejection_feedback: feedback || 'No specific feedback provided'
+      }
+    })
+
+    // Find the phase to loop back to
+    const loopBackPhase = findLoopBackPhase(phase, allPhases)
+
+    updateFlags(changeId, {
+      [`phase_${loopBackPhase.number}`]: {
+        status: 'pending',
+        rerun_reason: `Rejected from ${phase.name}: ${feedback}`
+      }
+    })
+
+    output(`
+🔄 ${phase.name} rejected
+
+📝 Feedback: ${feedback || 'None provided'}
+🔙 Looping back to: Phase ${loopBackPhase.number} - ${loopBackPhase.name}
+
+${loopBackPhase.agent} agent จะได้รับ feedback นี้เพื่อแก้ไข
+    `)
+
+    return {
+      status: 'rejected',
+      feedback,
+      nextAction: 'loop_back',
+      loopBackTo: loopBackPhase
+    }
+  }
+
+  // Unknown response - ask again
+  output(`
+⚠️ ไม่เข้าใจคำตอบ
+
+กรุณาตอบ:
+- "approve" เพื่อดำเนินการต่อ
+- "reject [feedback]" เพื่อกลับไปแก้ไข
+  `)
+
+  return {
+    status: 'pending',
+    nextAction: 'ask_again'
+  }
+}
+```
+
+### Loop Back Logic
+
+```typescript
+function findLoopBackPhase(currentPhase: Phase, allPhases: Phase[]): Phase {
+  // For ux-tester (Phase 1.5), loop back to uxui-frontend (Phase 1)
+  if (currentPhase.agent === 'ux-tester') {
+    const uxuiFrontendPhase = allPhases.find(p => p.agent === 'uxui-frontend')
+    if (uxuiFrontendPhase) {
+      return uxuiFrontendPhase
+    }
+  }
+
+  // Default: loop back to previous phase
+  const currentIndex = allPhases.findIndex(p => p.number === currentPhase.number)
+  if (currentIndex > 0) {
+    return allPhases[currentIndex - 1]
+  }
+
+  // Fallback: first phase
+  return allPhases[0]
+}
+
+// Helper: Read phases from phases.md file
+function getPhasesFromFile(changeId: string): Phase[] {
+  const phasesPath = `openspec/changes/${changeId}/.claude/phases.md`
+  const content = Read(phasesPath)
+  return parsePhasesFromMd(content)
+}
+```
+
+### Rejection Loop Cycle
+
+```
+Cycle 1:
+  Phase 1 (uxui-frontend) → Phase 1.5 (ux-tester) → [REJECT]
+  → Back to Phase 1 with feedback
+
+Cycle 2:
+  Phase 1 (uxui-frontend) [with feedback] → Phase 1.5 (ux-tester) → [APPROVE]
+  → Continue to Phase 2
+
+No limit on cycles - user decides when to stop
+```
+
+### Feedback Injection
+
+When looping back, inject rejection feedback into agent prompt:
+
+```typescript
+function buildPromptWithFeedback(phase: Phase, changeId: string): string {
+  const flags = readFlags(changeId)
+  const feedback = flags[`phase_${phase.number}`]?.rerun_reason
+
+  let prompt = buildBasePrompt(phase)
+
+  if (feedback) {
+    prompt += `
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ REJECTION FEEDBACK FROM UX TESTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${feedback}
+
+Please address this feedback in your implementation.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`
+  }
+
+  return prompt
+}
+```
+
+---
+
 **This incremental execution framework transforms high-risk tasks into manageable, validated steps! 🚀**

package/.claude/lib/context-loading-protocol.md

@@ -250,15 +250,14 @@ Each agent loads additional contexts based on their role.
 - `@.claude/contexts/patterns/frontend-component-strategy.md` (when to create vs reuse)
 
 **Project-specific (if exists):**
-- `design-system/STYLE_GUIDE.md` (17 sections, ~5K tokens)
-- `design-system/STYLE_TOKENS.json` (lightweight, ~500 tokens)
+- `design-system/data.yaml` (tokens + psychology, ~500 tokens)
+- `design-system/README.md` (human-readable summary, ~100 tokens)
 - `openspec/changes/{change-id}/page-plan.md` (from /pageplan command)
 
 **Loading strategy:**
 ```
-1. Try STYLE_TOKENS.json first (lightweight)
-2. Load STYLE_GUIDE.md sections selectively
-3. Fall back to design/*.md if no style guide
+1. Load data.yaml (contains all design tokens)
+2. Fall back to design/*.md if no data.yaml
 ```
 
 ### backend Agent:
@@ -333,7 +332,7 @@ Each agent loads additional contexts based on their role.
 🎨 Level 3: Agent-Specific (uxui-frontend)
    → Loading: design/*.md ✓
    → Loading: patterns/ui-component-consistency.md ✓
-   → Loading: design-system/STYLE_TOKENS.json ✓
+   → Loading: design-system/data.yaml ✓
    → Loading: openspec/changes/landing-page/page-plan.md ✓
    ✅ Design contexts loaded
 

package/.claude/lib/detailed-guides/agent-system.md

@@ -102,13 +102,13 @@ WHY routing matters: Specialist agents have domain-specific validation (design t
 ### STEP 0.5: Design Context (uxui-frontend only)
 
 ```
-6. Check: design-system/STYLE_GUIDE.md exists?
-   - If YES → Read STYLE_GUIDE.md (project-specific)
+6. Check: design-system/data.yaml exists?
+   - If YES → Read data.yaml (project-specific tokens + psychology)
    - If NO → Read .claude/contexts/design/*.md (fallback)
-7. Report: "✅ Style Guide Loaded"
+7. Report: "✅ Design Tokens Loaded"
 ```
 
-WHY: STYLE_GUIDE.md has project-specific tokens. design/*.md has universal principles.
+WHY: data.yaml has project-specific tokens. design/*.md has universal principles.
 
 **Fallback:** If discovery fails, suggest `/csetup` or `/designsetup`
 

package/.claude/lib/detailed-guides/best-practices-system.md

@@ -85,11 +85,12 @@
    - Asks: Application type (SaaS, Marketing, E-commerce, etc.)
    - Output: Modern, best-practice style guide
 
-### Generated File
+### Generated Files
 
 ```
 design-system/
-└── STYLE_GUIDE.md    ← Comprehensive 17-section guide
+├── data.yaml    ← Design tokens + psychology (agent reads this)
+└── README.md    ← Human-readable summary
 ```
 
 **All 17 Sections (Complete):**
@@ -122,14 +123,14 @@ design-system/
 # 2. Setup change and project (discovers style guide, auto-detects tech stack)
 /csetup feature-login
 
-# 3. Start development (agents use STYLE_GUIDE.md)
+# 3. Start development (agents use data.yaml)
 /cdev feature-login
 ```
 
 ### Agent Discovery
 
 **uxui-frontend agent automatically reads:**
-1. `design-system/STYLE_GUIDE.md` (if exists) ← **Priority #1**
+1. `design-system/data.yaml` (if exists) ← **Priority #1**
 2. `.claude/contexts/design/*.md` (general principles) ← Fallback
 
 **Why this matters:**

package/.claude/lib/detailed-guides/context-optimization.md

@@ -10,21 +10,21 @@
 
 **Before v1.2.0:**
 ```
-/pageplan     → reads STYLE_GUIDE.md (~5K tokens)
-/csetup       → reads STYLE_GUIDE.md (~5K tokens)
-/cdev         → sends STYLE_GUIDE.md (~5K tokens)
-uxui-frontend → reads STYLE_GUIDE.md (~5K tokens)
+/pageplan     → reads data.yaml (~800 tokens)
+/csetup       → reads data.yaml (~800 tokens)
+/cdev         → sends data.yaml (~800 tokens)
+uxui-frontend → reads data.yaml (~800 tokens)
 ────────────────────────────────────────────────
 Total: ~20K tokens (same content read 4 times!)
 ```
 
 **After v1.2.0:**
 ```
-/designsetup  → generates STYLE_TOKENS.json (~500 tokens) ✅
-/pageplan     → reads STYLE_TOKENS.json (~500 tokens) ✅
+/designsetup  → generates data.yaml (~500 tokens) ✅
+/pageplan     → reads data.yaml (~500 tokens) ✅
 /csetup       → validates files exist (0 tokens) ✅
 /cdev         → sends reference only (~200 tokens) ✅
-uxui-frontend → reads STYLE_TOKENS.json + selective STYLE_GUIDE (~3.5K) ✅
+uxui-frontend → reads data.yaml (~800 tokens) ✅
 ────────────────────────────────────────────────
 Total: ~4.7K tokens (70% reduction!) ✨
 ```
@@ -33,7 +33,7 @@ Total: ~4.7K tokens (70% reduction!) ✨
 
 ## The Solution: 3-Tier Loading
 
-### Tier 1: STYLE_TOKENS.json (500 tokens)
+### Tier 1: data.yaml (500 tokens)
 
 - Lightweight design tokens only
 - Used by: /pageplan, /csetup, agents
@@ -49,13 +49,13 @@ Total: ~4.7K tokens (70% reduction!) ✨
 
 **Purpose:** Agent orientation and file discovery
 
-### Tier 3: STYLE_GUIDE.md (5K tokens)
+### Tier 3: README.md (100 tokens)
 
-- Full reference with examples
-- Loaded selectively (specific sections only)
-- Used by: agents (when needed)
+- Human-readable summary
+- NOT for agents (use data.yaml instead)
+- Used by: humans reviewing design
 
-**Purpose:** Complete design system documentation
+**Purpose:** Quick human reference
 
 ---
 
@@ -66,8 +66,8 @@ Total: ~4.7K tokens (70% reduction!) ✨
 ### Pattern A: Planning (/pageplan, /csetup)
 
 ```typescript
-Read: STYLE_TOKENS.json (~500 tokens)
-Validate: STYLE_GUIDE.md exists (0 tokens)
+Read: data.yaml (~500 tokens)
+Validate: data.yaml exists (0 tokens)
 Total: ~500 tokens
 ```
 
@@ -75,16 +75,15 @@ Total: ~500 tokens
 
 ```typescript
 Send: Design reference (~200 tokens)
-Agent reads: STYLE_TOKENS.json (~500 tokens)
+Agent reads: data.yaml (~500 tokens)
 Total: ~700 tokens
 ```
 
 ### Pattern C: Agent (uxui-frontend)
 
 ```typescript
-Read: STYLE_TOKENS.json (~500 tokens)
-Read: STYLE_GUIDE sections (~2K tokens, selective)
-Total: ~2.5K tokens
+Read: data.yaml (~800 tokens)
+Total: ~800 tokens
 ```
 
 ---
@@ -103,10 +102,10 @@ Total: ~2.5K tokens
 ## Generated Files
 
 **/designsetup now creates:**
-1. `design-system/STYLE_GUIDE.md` (full guide, 17 sections)
-2. `design-system/STYLE_TOKENS.json` (tokens only) **NEW!**
+1. `design-system/data.yaml` (tokens + psychology, ~800 lines) **FOR AGENTS**
+2. `design-system/README.md` (human-readable summary, ~100 lines) **FOR HUMANS**
 
-**Agents automatically use both!**
+**Agents read data.yaml only!**
 
 ---
 

package/.claude/lib/detailed-guides/design-system.md

@@ -30,11 +30,12 @@
 
 ---
 
-## Generated File
+## Generated Files
 
 ```
 design-system/
-└── STYLE_GUIDE.md    ← Comprehensive 17-section guide
+├── data.yaml    ← Design tokens + psychology (agent reads this)
+└── README.md    ← Human-readable summary
 ```
 
 **All 17 Sections (Complete):**
@@ -69,7 +70,7 @@ design-system/
 # 2. Setup change and project (discovers style guide, auto-detects tech stack)
 /csetup feature-login
 
-# 3. Start development (agents use STYLE_GUIDE.md)
+# 3. Start development (agents use data.yaml)
 /cdev feature-login
 ```
 
@@ -78,7 +79,7 @@ design-system/
 ## Agent Discovery
 
 **uxui-frontend agent automatically reads:**
-1. `design-system/STYLE_GUIDE.md` (if exists) ← **Priority #1**
+1. `design-system/data.yaml` (if exists) ← **Priority #1**
 2. `.claude/contexts/design/*.md` (general principles) ← Fallback
 
 **Why this matters:**
@@ -92,6 +93,6 @@ design-system/
 ## 🔗 See Also
 
 - `../../commands/designsetup.md` - /designsetup command (generates style guide)
-- `context-optimization.md` - 3-tier loading strategy (STYLE_TOKENS.json)
+- `context-optimization.md` - 3-tier loading strategy (data.yaml)
 - `../../contexts/design/index.md` - General design principles (fallback)
 - `../../contexts/patterns/ui-component-consistency.md` - Component reuse patterns

package/.claude/lib/detailed-guides/page-planning.md

@@ -34,7 +34,7 @@ User: /pageplan @prd.md @project_brief.md
 Main Claude:
 1. Reads user-specified files (@prd.md, @brief.md)
 2. Reads proposal.md (technical architecture)
-3. Reads STYLE_GUIDE.md (visual design)
+3. Reads data.yaml (design tokens)
 4. Searches existing components (Glob/Grep)
 5. Generates: openspec/changes/{id}/page-plan.md
    - 🔄 Reuse: Navbar, Footer (found)
@@ -99,7 +99,7 @@ User: /cdev landing-page
 |----------------------|------------------------|
 | ❌ Agent guesses structure | ✅ Clear structure defined |
 | ❌ Duplicate components | ✅ Reuse existing components |
-| ❌ Inconsistent design | ✅ Sync with STYLE_GUIDE |
+| ❌ Inconsistent design | ✅ Sync with data.yaml |
 | ❌ Lorem ipsum content | ✅ Real content from PRD |
 | ❌ Missing assets | ✅ Asset checklist prepared |
 | ❌ Agent wastes time searching | ✅ Search done once upfront (25% faster) |
@@ -124,14 +124,14 @@ User: /cdev landing-page
 
 ---
 
-## Integration with STYLE_GUIDE
+## Integration with data.yaml
 
 ```
-STYLE_GUIDE.md → Visual design (colors, spacing, shadows)
+data.yaml      → Design tokens (colors, spacing, shadows, psychology)
 page-plan.md   → Content structure (sections, components, assets)
 
 uxui-frontend agent combines both:
-- Colors from STYLE_GUIDE (#0d7276)
+- Colors from data.yaml (#0d7276)
 - Content from page-plan ("Master TOEIC...")
 - Result: Consistent + Real content
 ```
@@ -141,7 +141,7 @@ uxui-frontend agent combines both:
 ## 🔗 See Also
 
 - `../../commands/pageplan.md` - /pageplan command implementation
-- `../../commands/designsetup.md` - /designsetup command (generates STYLE_GUIDE.md)
+- `../../commands/designsetup.md` - /designsetup command (generates data.yaml + README.md)
 - `../../contexts/patterns/ui-component-consistency.md` - Component reuse patterns
 - `../../contexts/patterns/frontend-component-strategy.md` - When to create vs reuse
 - `../document-loader.md` - Token-efficient loading patterns