@champpaba/claude-agent-kit 2.5.0 → 2.7.0

package/.claude/templates/design-context-template.md

@@ -8,8 +8,8 @@
 ## 🎨 Design System Overview
 
 **Status:** {DESIGN_SYSTEM_STATUS}
-- ✅ Complete (STYLE_GUIDE.md + STYLE_TOKENS.json exist)
-- ⚠️ Partial (STYLE_GUIDE.md only)
+- ✅ Complete (data.yaml + README.md exist)
+- ⚠️ Partial (only one file exists)
 - ❌ None (needs /designsetup)
 
 **Generated from:**
@@ -24,20 +24,20 @@
 
 ### Primary Reference (Lightweight)
 ```
-✅ STYLE_TOKENS.json (~500 tokens)
-   design-system/STYLE_TOKENS.json
+✅ data.yaml (~800 tokens)
+   design-system/data.yaml
 
    Contains: Colors, spacing, typography, shadows, borders, animations
    Use: Quick reference for all commands and agents
 ```
 
-### Full Reference (Optional - Load on Demand)
+### Human-Readable Summary (For Humans Only)
 ```
-📖 STYLE_GUIDE.md (~5000 tokens)
-   design-system/STYLE_GUIDE.md
+📖 README.md (~100 tokens)
+   design-system/README.md
 
-   Contains: 17 sections including component examples, layout patterns
-   Use: Only load specific sections when needed
+   Contains: Summary of design system for human review
+   Use: Humans reviewing design, NOT for agents
 ```
 
 ### Fallback (Universal Principles)
@@ -139,13 +139,13 @@ Read: .claude/contexts/domain/{PROJECT_NAME}/design-context.md
 Tokens: ~1000
 ```
 
-**Step 2: Load STYLE_TOKENS.json (if needed)**
+**Step 2: Load data.yaml (if needed)**
 ```
-Read: design-system/STYLE_TOKENS.json
-Tokens: ~500
+Read: design-system/data.yaml
+Tokens: ~800
 ```
 
-**Total: ~1500 tokens (vs 5000+ for full STYLE_GUIDE.md)**
+**Total: ~1500 tokens (efficient loading)**
 
 ---
 
@@ -158,22 +158,16 @@ Tokens: ~500
    - File paths
    - Critical rules
 
-2. **Read STYLE_TOKENS.json**
+2. **Read data.yaml**
    - Full design tokens
    - Component library info
    - Usage patterns
 
-3. **Optional: Read STYLE_GUIDE.md sections**
-   - Only load sections needed for current task
-   - Example: Component Styles, Layout Patterns
-   - Tokens: ~2000 (selective loading)
-
-4. **Report:**
+3. **Report:**
    ```
    ✅ Design Context Loaded
    📁 design-context.md ✓
-   📦 STYLE_TOKENS.json ✓
-   📖 STYLE_GUIDE.md (Section 6: Component Styles) ✓
+   📦 data.yaml ✓
 
    Design Tokens Extracted:
    - Primary: {PRIMARY_COLOR}
@@ -187,9 +181,8 @@ Tokens: ~500
 
 | Approach | Tokens | Speed | Recommended |
 |----------|--------|-------|-------------|
-| **Old: Load full STYLE_GUIDE.md** | ~5000 | Slow | ❌ |
-| **New: design-context.md + STYLE_TOKENS.json** | ~1500 | Fast | ✅ |
-| **Agent: Selective STYLE_GUIDE sections** | ~3500 | Medium | ✅ (when needed) |
+| **design-context.md + data.yaml** | ~1800 | Fast | ✅ |
+| **data.yaml only** | ~800 | Very Fast | ✅ (quick tasks) |
 
 ---
 
@@ -198,15 +191,15 @@ Tokens: ~500
 Run `/csetup` or `/designsetup` again when:
 - ✅ Design tokens change (new colors, spacing)
 - ✅ Component library changes (shadcn → Chakra UI)
-- ✅ STYLE_GUIDE.md updated
+- ✅ data.yaml updated
 - ✅ New project phase (rebrand, redesign)
 
 ---
 
 ## 📖 References
 
-- **Full Style Guide:** `design-system/STYLE_GUIDE.md`
-- **Design Tokens:** `design-system/STYLE_TOKENS.json`
+- **Design Tokens:** `design-system/data.yaml` (agent reads this)
+- **Human Summary:** `design-system/README.md` (for humans)
 - **Universal Design:** `.claude/contexts/design/`
 - **Best Practices:** `.claude/contexts/domain/{PROJECT_NAME}/best-practices/`
 
@@ -214,7 +207,7 @@ Run `/csetup` or `/designsetup` again when:
 
 **🎯 Next Steps for Agents:**
 1. Load design-context.md (~1K tokens) ✅
-2. Load STYLE_TOKENS.json (~500 tokens) ✅
+2. Load data.yaml (~800 tokens) ✅
 3. Extract design tokens ✅
 4. Report loaded context ✅
 5. Begin implementation with design system awareness ✅

package/.claude/templates/page-plan-example.md

@@ -1,6 +1,6 @@
 # Page Plan: Landing Page (EXAMPLE)
 > This is an example template showing the structure of page-plan.md
-> Generated from: proposal.md, prd.md, project_brief.md, STYLE_GUIDE.md
+> Generated from: proposal.md, prd.md, project_brief.md, data.yaml
 > Change ID: landing-page
 
 ---
@@ -562,18 +562,18 @@ _Length: 75 words_
 
 ## 5. Design Notes
 
-**Follow STYLE_GUIDE.md for all design decisions:**
+**Follow data.yaml for all design decisions:**
 
-- **Primary Color:** `#0d7276` (from STYLE_GUIDE.md Section 3)
-- **Font Family:** `Prompt` (from STYLE_GUIDE.md Section 4)
-- **Spacing Scale:** 8px grid system - use `p-4`, `p-6`, `p-8`, `gap-4`, `gap-6` (from STYLE_GUIDE.md Section 5)
-- **Component Library:** shadcn/ui (from STYLE_GUIDE.md Section 6)
-- **Icons:** Material Symbols (Outline style) (from STYLE_GUIDE.md Section 17)
+- **Primary Color:** `#0d7276` (from data.yaml colors section)
+- **Font Family:** `Prompt` (from data.yaml typography section)
+- **Spacing Scale:** 8px grid system - use `p-4`, `p-6`, `p-8`, `gap-4`, `gap-6` (from data.yaml spacing)
+- **Component Library:** shadcn/ui (from data.yaml)
+- **Icons:** Material Symbols (Outline style) (from data.yaml)
 - **Shadows:**
   - Cards: `shadow-sm` on default, `shadow-md` on hover
   - Elevated elements: `shadow-lg`
 - **Border Radius:** `rounded-lg` for cards, `rounded-md` for buttons/inputs
-- **Responsive Breakpoints:** (from STYLE_GUIDE.md Section 13)
+- **Responsive Breakpoints:** (from data.yaml)
   - Mobile: < 640px
   - Tablet: 640px - 1024px
   - Desktop: > 1024px
@@ -686,7 +686,7 @@ public/
 **Generated by:** /pageplan command
 **Date:** 2025-01-15
 **For:** Change ID `landing-page`
-**Context files used:** proposal.md, prd.md, project_brief.md, STYLE_GUIDE.md
+**Context files used:** proposal.md, prd.md, project_brief.md, data.yaml
 
 ---
 

package/.claude/templates/phases-sections/ux-testing.md

@@ -0,0 +1,164 @@
+# Phase: UX Testing (Persona-Based)
+
+**Agent:** `ux-tester`
+**Metadata:** `| approval-gate | user-testing | persona-based |`
+**Estimated time:** 30 minutes
+**Requires Approval:** YES (blocks until user approves/rejects)
+
+## 🎯 Purpose
+
+ทดสอบ UI จากมุมมอง User จริง ก่อนที่จะไป Phase ถัดไป (Backend)
+- Auto-generate personas จาก product context
+- Test แต่ละ persona ผ่าน Chrome DevTools
+- คำนวณ weighted conversion prediction
+- รอ User approve หรือ reject
+
+## 📋 Pre-Requisites
+
+- ✅ Phase 1 (Frontend Mockup) completed
+- ✅ Dev server running (localhost:3000 or similar)
+- ✅ Chrome DevTools MCP connected
+
+## 🔄 Process
+
+### Step 1: Load Context
+```bash
+Read: openspec/changes/{change-id}/proposal.md
+Read: openspec/changes/{change-id}/page-plan.md (if exists)
+Read: openspec/changes/{change-id}/tasks.md
+Read: design-system/data.yaml (if exists)
+```
+
+### Step 2: Auto-Generate Personas
+- Analyze product/service from context
+- Generate 3-5 personas with % breakdown
+- Explain reasoning
+
+### Step 3: Find Dev Server
+- Auto-detect running server (3000, 3001, 5173, 8080)
+- Error if no server found
+
+### Step 4: Test Each Persona
+For each persona:
+1. Navigate to page
+2. Take screenshot + snapshot
+3. First impression (3 seconds)
+4. Test main flow (click through)
+5. Test mobile (resize to 375px)
+6. Would buy? Why/why not?
+
+### Step 5: Calculate Weighted Score
+- Weight each persona's decision by their %
+- Calculate total conversion prediction
+- Calculate potential after fixes
+
+### Step 6: Generate Report
+Output: `openspec/changes/{change-id}/ux-test-report.md`
+
+## ✅ Success Criteria
+
+- [ ] Personas generated with % breakdown
+- [ ] Each persona tested (desktop + mobile)
+- [ ] Conversion prediction calculated
+- [ ] Critical issues identified
+- [ ] Recommendations with impact %
+- [ ] Report generated
+
+## 📤 Output
+
+**Files created:**
+- `openspec/changes/{change-id}/ux-test-report.md`
+
+**Update flags.json:**
+```json
+{
+  "phases": {
+    "ux_testing": {
+      "status": "awaiting_approval",
+      "completed_at": "{ISO-timestamp}",
+      "actual_minutes": {duration},
+      "personas_tested": {count},
+      "conversion_prediction": "{percentage}",
+      "critical_issues": {count},
+      "report_path": "ux-test-report.md"
+    }
+  }
+}
+```
+
+## 🛑 Approval Gate
+
+**After report generated, PAUSE and ask user:**
+
+```markdown
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧪 UX Testing Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Summary:
+- Personas tested: {count}
+- Conversion prediction: {percentage}%
+- Critical issues: {count}
+- Potential after fixes: {percentage}%
+
+📄 Full report: openspec/changes/{change-id}/ux-test-report.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+กรุณา:
+1. Review report ด้านบน
+2. ทดสอบ {dev-url} ด้วยตัวเอง
+3. ตัดสินใจ:
+
+✅ "approve" → ไป Phase 2 (Backend)
+❌ "reject [feedback]" → กลับ Phase 1 แก้ไข
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 🔄 Rejection Loop
+
+**If user rejects:**
+
+1. Parse feedback from rejection
+2. Update flags.json:
+   ```json
+   {
+     "phases": {
+       "ux_testing": {
+         "status": "rejected",
+         "rejection_feedback": "{user feedback}",
+         "rejection_count": 1
+       },
+       "frontend_mockup": {
+         "status": "pending",
+         "rerun_reason": "UX testing rejected: {feedback}"
+       }
+     }
+   }
+   ```
+3. Loop back to Phase 1 (uxui-frontend)
+4. After Phase 1 completes → Re-run Phase 1.5 (ux-testing)
+
+## 📊 Report to User
+
+**After approval:**
+```
+✅ Phase 1.5: UX Testing approved!
+
+⏱️ Time: {actual} minutes
+🧪 Personas: {count} tested
+📈 Conversion: {percentage}%
+
+📍 Next phase: Phase 2 - Backend API
+```
+
+**After rejection:**
+```
+🔄 Phase 1.5: UX Testing rejected
+
+📝 Feedback: {user feedback}
+🔙 Returning to: Phase 1 - Frontend Mockup
+
+uxui-frontend agent จะได้รับ feedback นี้เพื่อแก้ไข
+```

package/README.md

@@ -21,6 +21,7 @@ cak init
 | Agent | Phase | Role |
 |-------|-------|------|
 | uxui-frontend | 1 | UI with mock data |
+| ux-tester | 1.5 | Persona-based UX testing (approval gate) |
 | backend | 2 | API endpoints |
 | database | 2 | Schemas |
 | integration | 2.5 | Contract validation |
@@ -29,12 +30,13 @@ cak init
 
 ## Features
 
+- **UX-Tester Agent (v2.7.0)** - Persona-based UX testing with weighted conversion prediction
 - **Smart Topic Query (v2.5.0)** - Cross-library integration detection + risk summary
 - **Adaptive Depth Research (v2.4.0)** - Dynamic research layers (0-10+) based on change complexity
 - **Zero-Maintenance Tech Detection** - Auto-detects ANY library in ANY language via Context7
 - **Visual Page Planning** - Layout wireframes, component plans, animation blueprints
 - **Cross-session Context** - `PROJECT_STATUS.yml` maintains state across sessions
-- **Design System v2.0** - Interactive setup with theme selection
+- **Design System v2.1** - YAML-based extraction with single data.yaml output
 
 ## Smart Topic Query (v2.5.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champpaba/claude-agent-kit",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
   "main": "bin/cli.js",
   "bin": {