@champpaba/claude-agent-kit 2.5.0 → 2.7.0

package/.claude/commands/pageplan.md

@@ -24,8 +24,9 @@
 1. **Reads User-Specified Context:**
    - Only reads files that user mentions with `@` prefix
    - Always reads `openspec/changes/{change-id}/proposal.md` (if exists)
-   - **Always reads `design-system/STYLE_TOKENS.json`** (lightweight, ~500 tokens) ✅
-   - Validates `design-system/STYLE_GUIDE.md` exists (doesn't load full content)
+   - Always reads `openspec/changes/{change-id}/tasks.md` (for page type detection)
+   - **Always reads `openspec/changes/{change-id}/.claude/phases.md`** (if exists - for phase info) ✅ NEW v2.6.0
+   - **Always reads `design-system/data.yaml`** (design tokens + psychology, ~500 tokens) ✅
 
 2. **Searches Existing Components:**
    - Glob: `**/{Navbar,Footer,Sidebar,Header}*.{tsx,jsx,vue}`
@@ -70,8 +71,8 @@ const userFiles = extractMentionedFiles(userMessage) // @prd.md, @brief.md
 
 // Always read (if exists)
 const proposalPath = `openspec/changes/${changeId}/proposal.md`
-const tokensPath = `design-system/STYLE_TOKENS.json` // 🆕 Lightweight tokens
-const styleGuidePath = `design-system/STYLE_GUIDE.md` // Validate only, don't load
+const tokensPath = `design-system/data.yaml` // Design tokens + psychology
+// data.yaml contains all design information - single source of truth
 
 const contextFiles = [
   ...userFiles,
@@ -97,6 +98,22 @@ if (fileExists(tasksPath)) {
   tasksContent = Read(tasksPath)
 }
 
+// 🆕 v2.6.0: Read phases.md if exists (for phase info, UI detection)
+const phasesPath = `openspec/changes/${changeId}/.claude/phases.md`
+let phasesContent = ''
+if (fileExists(phasesPath)) {
+  phasesContent = Read(phasesPath)
+  output(`✅ phases.md Found - reading phase information`)
+
+  // Extract UI phases from phases.md
+  const uiPhaseMatch = phasesContent.match(/uxui-frontend|frontend-mockup|Frontend Mockup/gi)
+  if (uiPhaseMatch) {
+    output(`   - UI phases detected: ${uiPhaseMatch.length}`)
+  }
+} else {
+  output(`ℹ️ phases.md not found - run /csetup first if you want phase-aware planning`)
+}
+
 // Extract brief from user files
 const briefFile = userFiles.find(f => f.toLowerCase().includes('brief'))
 if (briefFile && fileExists(briefFile)) {
@@ -106,20 +123,19 @@ if (briefFile && fileExists(briefFile)) {
 // 🆕 Load design tokens (lightweight)
 if (fileExists(tokensPath)) {
   const tokens = JSON.parse(Read(tokensPath))
-  context += `\n\n---\n\n# Design Tokens (STYLE_TOKENS.json)\n\n`
+  context += `\n\n---\n\n# Design Tokens (data.yaml)\n\n`
   context += `Primary Color: ${tokens.tokens.colors.primary.DEFAULT}\n`
   context += `Spacing Scale: ${tokens.tokens.spacing.scale.join(', ')}px\n`
   context += `Component Library: ${tokens.component_library.name}\n`
   context += `Shadows: ${Object.keys(tokens.tokens.shadows).join(', ')}\n`
 }
 
-// Validate STYLE_GUIDE.md exists (don't load!)
-const hasStyleGuide = fileExists(styleGuidePath)
-if (!hasStyleGuide) {
-  warn(`⚠️ No STYLE_GUIDE.md found - run /designsetup first`)
+// Validate data.yaml exists
+if (!fileExists(tokensPath)) {
+  warn(`⚠️ No data.yaml found - run /designsetup first`)
 }
 
-// Total context: ~1.5K tokens (vs 5K+ if loading full STYLE_GUIDE.md)
+// Total context: ~1.5K tokens (data.yaml is lightweight)
 ```
 
 ### STEP 3: Search Existing Components
@@ -294,12 +310,12 @@ Based on context + found components, generate:
 ## 2.6. 🎬 Animation Blueprint (Micro-interactions)
 
 > **Purpose:** Define animation strategy BEFORE implementation to ensure consistency and polish
-> **Source:** `design-system/STYLE_TOKENS.json` (animation tokens)
+> **Source:** `design-system/data.yaml` (animation tokens)
 > **Philosophy:** Match Flow Engineer Step 3 - Design animations systematically, not randomly
 
 ### Animation Principles
 
-**From STYLE_TOKENS.json:**
+**From data.yaml:**
 - **Durations:** 150ms (quick), 300ms (normal), 500ms (slow)
 - **Easing:** ease-in-out (default), cubic-bezier for custom
 - **Properties:** GPU-accelerated ONLY (transform, opacity) - NOT width, height, top, left
@@ -494,7 +510,7 @@ className="hover:scale-105 transform"
 - [ ] All buttons use scale + shadow pattern (150ms)
 - [ ] All cards use shadow elevation pattern (300ms)
 - [ ] All inputs use ring pattern (200ms)
-- [ ] All durations from STYLE_TOKENS.json (150/300/500ms)
+- [ ] All durations from data.yaml (150/300/500ms)
 - [ ] All properties GPU-accelerated (transform, opacity)
 - [ ] No random durations (e.g., 200ms, 400ms) unless intentional
 - [ ] Tested on mobile (animations not janky)
@@ -510,7 +526,7 @@ className="hover:scale-105 transform"
 4. **Short Durations (150-300ms):** Feels responsive, not sluggish
 5. **GPU Properties:** 60fps smooth animations, no jank
 
-**Inspiration:** Based on extracted animations from reference sites + STYLE_TOKENS.json
+**Inspiration:** Based on extracted animations from reference sites + data.yaml
 
 ---
 
@@ -555,7 +571,7 @@ className="hover:scale-105 transform"
       → **Format:** SVG (preferred) or PNG sprite (if 10+ icons)
       → **Optimization:** Remove unnecessary metadata (use SVGO)
       → **Place at:** `/public/icons/` or inline in component
-      → **Style:** Match STYLE_GUIDE colors
+      → **Style:** Match data.yaml colors
       → **Estimated size:** 1-3KB per icon
 
 **If using 10+ icons:** Consider SVG sprite sheet (combine → 1 HTTP request)
@@ -570,18 +586,18 @@ className="hover:scale-105 transform"
 ## 4. Design Notes
 
 **Design System Files:**
-- Tokens (lightweight): \`design-system/STYLE_TOKENS.json\`
-- Full guide (reference): \`design-system/STYLE_GUIDE.md\`
+- Tokens + Psychology: \`design-system/data.yaml\` (agent reads this)
+- Human summary: \`design-system/README.md\` (for humans)
 
 **Key Design Tokens:**
-- Primary color: [from STYLE_TOKENS.json]
-- Font family: [from STYLE_TOKENS.json]
-- Spacing scale: [from STYLE_TOKENS.json]
-- Component library: [from STYLE_TOKENS.json]
-- Shadows: [from STYLE_TOKENS.json]
+- Primary color: [from data.yaml]
+- Font family: [from data.yaml]
+- Spacing scale: [from data.yaml]
+- Component library: [from data.yaml]
+- Shadows: [from data.yaml]
 
 **Agent Instructions:**
-- uxui-frontend reads STYLE_TOKENS.json in STEP 0.5
+- uxui-frontend reads data.yaml in STEP 0.5
 - Use theme tokens (text-foreground/70) for theme-awareness
 - Use spacing scale (p-4, p-6) for consistency
 
@@ -684,8 +700,8 @@ Result:
    - Warning: "This change appears to be backend/API work. /pageplan is for UI tasks."
    - Ask: "Continue anyway? (Y/N)"
 
-4. **STYLE_GUIDE.md missing:**
-   - Warning: "No STYLE_GUIDE.md found. Run /designsetup first for best results."
+4. **data.yaml missing:**
+   - Warning: "No data.yaml found. Run /designsetup first for best results."
    - Continue: Use general design principles as fallback
 
 ---
@@ -711,9 +727,9 @@ Result:
 ```
 /designsetup → /pageplan → /csetup → /cdev
      ↓             ↓            ↓         ↓
-  tokens.json   page-plan.md  research   uxui-frontend
+  data.yaml   page-plan.md  research   uxui-frontend
   patterns/     (visual)      -checklist reads both
-  STYLE_GUIDE               (content)
+  README.md                 (content)
 ```
 
 **Separation of Concerns:**

package/.claude/contexts/design/box-thinking.md

@@ -8,12 +8,12 @@
 
 **This file contains layout analysis METHODOLOGY** (applies to all projects).
 
-**If your project has a STYLE_GUIDE.md with reference screenshot:**
-→ View the screenshot and apply Box Thinking to understand its layout
-→ Use STYLE_GUIDE.md spacing values when implementing boxes
+**If your project has a data.yaml:**
+→ Use data.yaml spacing values when implementing boxes
+→ Apply Box Thinking methodology with project-specific tokens
 
 Box Thinking = **How to think about layout**
-STYLE_GUIDE.md = **What values to use**
+data.yaml = **What values to use**
 
 ---
 

package/.claude/contexts/design/color-theory.md

@@ -9,20 +9,20 @@
 
 **This file contains GENERIC color theory principles.**
 
-**If your project has a STYLE_GUIDE.md:**
-→ STYLE_GUIDE.md colors take **priority** (use exact hex values from it)
+**If your project has a data.yaml:**
+→ data.yaml colors take **priority** (use exact hex values from it)
 → This file = **reference** for color theory concepts only
 
-**Check:** `.claude/contexts/domain/{project}/STYLE_GUIDE.md`
+**Check:** `design-system/data.yaml`
 
 **Priority order:**
-1. `STYLE_GUIDE.md` (project-specific hex values) ← **Use this if exists!**
+1. `data.yaml` (project-specific hex values) ← **Use this if exists!**
 2. Existing components (brownfield) ← Extract colors from code
 3. This file (generic principles) ← Theory and fallback defaults
 
 **When using this file:**
 - Apply **concepts** (60-30-10 rule, accessibility, harmony)
-- Don't use **example colors** if STYLE_GUIDE.md exists
+- Don't use **example colors** if data.yaml exists
 
 ---
 

package/.claude/contexts/design/index.md

@@ -8,14 +8,14 @@
 
 **uxui-frontend agents should check this priority order:**
 
-### Priority 1: Project-Specific Style Guide (Highest)
+### Priority 1: Project-Specific Design Tokens (Highest)
 ```
-design-system/STYLE_GUIDE.md
+design-system/data.yaml
 ```
 
 **If this file exists:**
-- ✅ Use STYLE_GUIDE.md as **PRIMARY source of truth**
-- Contains: Complete design system (colors, typography, spacing, components)
+- ✅ Use data.yaml as **PRIMARY source of truth**
+- Contains: Complete design tokens + psychology (colors, typography, spacing, components)
 - Generated by: `/designsetup` command (from reference/codebase/AI)
 - **DO NOT** override with universal principles below
 
@@ -29,7 +29,7 @@ design-system/STYLE_GUIDE.md
 ```
 
 **Use these when:**
-- No STYLE_GUIDE.md exists
+- No data.yaml exists
 - Need general design theory
 - Understanding design concepts (box thinking, color theory)
 
@@ -38,7 +38,7 @@ design-system/STYLE_GUIDE.md
 .claude/contexts/domain/[project]/design-tokens.md
 ```
 
-**Note:** This is being replaced by STYLE_GUIDE.md
+**Note:** This is being replaced by data.yaml
 
 ---
 
@@ -46,8 +46,8 @@ design-system/STYLE_GUIDE.md
 
 **Before ANY design recommendation, ask:**
 
-1. **Do we have a style guide?**
-   - Check: `design-system/STYLE_GUIDE.md`
+1. **Do we have a design tokens file?**
+   - Check: `design-system/data.yaml`
    - If YES → Use it (Priority 1)
    - If NO → Use universal principles (Priority 2)
 
@@ -60,7 +60,7 @@ design-system/STYLE_GUIDE.md
    - Box Relationships
 
 3. **What context?**
-   - Project-specific style guide (STYLE_GUIDE.md)
+   - Project-specific design tokens (data.yaml)
    - Universal design principles (this directory)
 
 4. **What's the user goal?**

package/.claude/contexts/design/spacing.md

@@ -8,14 +8,14 @@
 
 **This file contains GENERIC spacing guidelines.**
 
-**If your project has a STYLE_GUIDE.md:**
-→ STYLE_GUIDE.md values take **priority** (use its spacing values)
+**If your project has a data.yaml:**
+→ data.yaml values take **priority** (use its spacing values)
 → This file = **reference** for concepts and principles only
 
-**Check:** `.claude/contexts/domain/{project}/STYLE_GUIDE.md`
+**Check:** `design-system/data.yaml`
 
 **Priority order:**
-1. `STYLE_GUIDE.md` (project-specific) ← **Use this if exists!**
+1. `data.yaml` (project-specific) ← **Use this if exists!**
 2. Existing components (brownfield) ← Extract from code
 3. This file (generic defaults) ← Fallback only
 

package/.claude/contexts/patterns/agent-discovery.md

@@ -110,7 +110,7 @@ ls openspec/changes/{change-id}/.claude/
    ```
 
    > **Note:** `design.md` = Technical/Architecture decisions (API structure, data flow)
-   > This is DIFFERENT from `STYLE_GUIDE.md` which is Visual Design (colors, fonts)
+   > This is DIFFERENT from `data.yaml` which is Visual Design (colors, fonts, tokens)
    > See CLAUDE.md "File Naming Conventions" for details.
 
 **If change context doesn't exist:**

package/.claude/contexts/patterns/animation-patterns.md

@@ -18,7 +18,7 @@
 
 **Priority:**
 1. **Page-specific plan:** `openspec/changes/{id}/page-plan.md` Section 2.6 (if exists)
-2. **Project tokens:** `design-system/STYLE_TOKENS.json` (animation tokens)
+2. **Project tokens:** `design-system/data.yaml` (animation tokens)
 3. **General guidelines:** This file (fallback when above don't exist)
 
 **When to read:**
@@ -67,7 +67,7 @@
 
 ## 🎯 Animation Duration Guidelines
 
-**Standard Durations (from STYLE_TOKENS.json):**
+**Standard Durations (from data.yaml):**
 
 | Token | Duration | Use Case | Example |
 |-------|----------|----------|---------|
@@ -101,7 +101,7 @@
 ## 🧩 Component Animation Patterns
 
 > **Purpose:** Standard animation patterns for common components
-> **Source:** Based on STYLE_TOKENS.json + `/pageplan` Section 2.6
+> **Source:** Based on data.yaml + `/pageplan` Section 2.6
 > **Principle:** Same component type = same animation pattern (consistency)
 
 ### Button Components

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:**