@champpaba/claude-agent-kit 3.2.0 → 3.4.0

package/.claude/CHANGELOG.md

@@ -5,6 +5,135 @@
 
 ---
 
+## v3.4.0: Complete Pseudocode Elimination
+
+**Problem Solved:** Agents read TypeScript/JavaScript pseudocode and interpreted it as "examples" or "reference documentation" rather than executable instructions. This caused agents to not follow the intended workflow.
+
+**Solution:** Converted ~3,210 lines of pseudocode across all 8 command files to imperative step-by-step instructions following the pattern established in `design-validator.md`.
+
+### Key Changes
+
+| File | Lines Converted | Key Sections |
+|------|-----------------|--------------|
+| `cdev.md` | ~300 | Steps 2-5, approval gate, page plan validation |
+| `csetup.md` | ~800 | Steps 7-8, helper functions |
+| `designsetup.md` | ~1,200 | Steps 5-6, data.yaml generation |
+| `extract.md` | ~400 | Steps 0-6, Chrome DevTools extraction |
+| `pageplan.md` | ~200 | Steps 1-5, context loading |
+| `cview.md` | ~100 | Formatting helpers |
+| `cstatus.md` | ~60 | Steps 1-2, infrastructure summary |
+| `pstatus.md` | ~150 | Steps 1-5, YAML updates |
+
+### Conversion Pattern
+
+```markdown
+# ❌ BEFORE (Pseudocode - agents ignore):
+```typescript
+if (fileExists(path)) {
+  const data = JSON.parse(Read(path))
+  return data.value
+}
+```
+
+# ✅ AFTER (Imperative - agents follow):
+**If the file exists:**
+1. Read the file at `{path}`
+2. Parse the content as JSON
+3. Extract and return the `value` field
+```
+
+### Why This Matters
+
+**Before:**
+- TypeScript code blocks treated as documentation
+- Agents skipped procedural logic
+- Inconsistent behavior between runs
+- User had to manually guide agents
+
+**After:**
+- Clear numbered steps agents execute
+- Conditional logic as "If X, then Y" blocks
+- Consistent, reproducible behavior
+- Agents self-navigate through workflows
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `.claude/commands/cdev.md` | All pseudocode → imperative |
+| `.claude/commands/csetup.md` | All pseudocode → imperative |
+| `.claude/commands/designsetup.md` | All pseudocode → imperative |
+| `.claude/commands/extract.md` | All pseudocode → imperative |
+| `.claude/commands/pageplan.md` | All pseudocode → imperative |
+| `.claude/commands/cview.md` | All pseudocode → imperative |
+| `.claude/commands/cstatus.md` | All pseudocode → imperative |
+| `.claude/commands/pstatus.md` | All pseudocode → imperative |
+| `tests/` | Removed (tests passed, cleanup) |
+
+---
+
+## v3.3.0: Design Validation System (No Pseudocode)
+
+**Problem Solved:** Design system compliance was not enforced. uxui-frontend agents didn't read `design-system/data.yaml`, resulting in hardcoded colors, arbitrary spacing, and inconsistent animations. The validation logic was written as TypeScript pseudocode that Claude never executed.
+
+**Solution:** Created a single source of truth (`design-validator.md`) with imperative Thai/English instructions. Converted all procedural pseudocode to step-by-step commands that Claude follows.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| design-validator.md | Did not exist | NEW - Single source of truth |
+| cdev.md Step 2-5 | TypeScript pseudocode | Imperative instructions |
+| ux-tester.md Steps 2-5 | TypeScript pseudocode | Imperative instructions |
+| uxui-frontend STEP 0.5 | Brief mention | Full step-by-step protocol |
+
+### Design Validation Flow
+
+```
+PREVENTION (Before Implementation)
+├── Main Claude: Pre-Flight Check before invoking uxui-frontend
+└── uxui-frontend: STEP 0.5 - Read data.yaml, report tokens
+
+DETECTION (After Implementation)
+└── ux-tester: Step 5.5 - Chrome DevTools style comparison
+```
+
+### What Gets Validated
+
+| Token Category | Violation Example | Expected |
+|----------------|-------------------|----------|
+| Colors | #3b82f6, text-blue-500 | bg-primary, text-foreground |
+| Spacing | p-5, gap-7 | p-4, p-6, gap-8 (scale) |
+| Animation | duration-200 | duration-150, 300, 500ms |
+| Shadows | mixed sm+xl | consistent level |
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `.claude/lib/design-validator.md` | NEW - Single source of truth |
+| `.claude/agents/02-uxui-frontend.md` | v2.1.0 - Enhanced STEP 0.5 |
+| `.claude/agents/07-ux-tester.md` | v1.1.0 - Steps 2-5 rewritten |
+| `.claude/commands/cdev.md` | Steps 2-5 rewritten, Step 4.0 added |
+| `.claude/lib/README.md` | Added design-validator.md entry |
+| `.claude/CLAUDE.md` | v3.3.0 + Design Validation section |
+
+### Why This Matters
+
+**Before:**
+- Logic scattered across 4 files
+- TypeScript pseudocode that Claude ignored
+- No enforcement of design tokens
+- ux-tester couldn't validate actual CSS
+
+**After:**
+- Single source of truth (design-validator.md)
+- Imperative instructions Claude follows
+- Pre-flight check before visual agents
+- Chrome DevTools validation of computed styles
+
+---
+
 ## v3.2.0: Consolidated Pre-Work Context
 
 **Problem Solved:** `/csetup` generated two separate pseudocode outputs (`research-checklist.md` and `INTEGRATION_RISKS.md`) that were never actually created. Agents had to discover context from multiple scattered sources.

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 3.2.0 - Consolidated Pre-Work Context
-> **Latest:** Step 2.6 generates `pre-work-context.md` - single file with all agent context
+> **Template Version:** 3.4.0 - Complete Pseudocode Elimination
+> **Latest:** Single Source of Truth for design compliance (prevention + detection)
 
 ---
 
@@ -128,6 +128,7 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/lib/task-analyzer.md` - **v3.1.0!** Template-free task analysis with TDD classification (Step 2.6) ✨
 - `@/.claude/lib/flags-updater.md` - Progress tracking protocol (Main Claude updates flags.json)
 - `@/.claude/lib/agent-router.md` - Mandatory agent routing rules (enforce delegation)
+- `@/.claude/lib/design-validator.md` - **v3.3.0!** Design system validation (prevention + detection) ✨
 - `@/.claude/contexts/patterns/agent-discovery.md` - Shared agent discovery flow
 
 ---
@@ -212,6 +213,58 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
+## 🎯 Design Validation System (v3.3.0 - NEW!)
+
+**→ See:** `@/.claude/lib/design-validator.md` for full specification
+
+**Problem Solved:**
+- uxui-frontend agent ไม่อ่าน design-system/data.yaml → CSS ไม่ตรง design
+- ux-tester อ่านแค่ code ไม่ได้เห็น actual rendered output
+- Logic กระจายหลายไฟล์ → ไม่มี enforcement
+
+**Solution: Single Source of Truth**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PREVENTION (Pre-Work)                     │
+├─────────────────────────────────────────────────────────────┤
+│  Main Claude → Pre-Flight Design Check (before /cdev)        │
+│  uxui-frontend → STEP 0.5: Read data.yaml (MANDATORY)       │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│                    DETECTION (Post-Work)                     │
+├─────────────────────────────────────────────────────────────┤
+│  ux-tester → Chrome DevTools Style Comparison                │
+│              Compare computed styles vs data.yaml tokens     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**What Gets Validated:**
+
+| Token Category | Example Violation | Expected |
+|----------------|-------------------|----------|
+| Colors | #3b82f6 | bg-primary (from data.yaml) |
+| Spacing | p-5, gap-7 | p-4, p-6, gap-8 (scale) |
+| Animation | duration-200 | duration-150, 300, 500ms |
+| Shadows | mixed sm+xl | consistent level |
+
+**Agent Responsibilities:**
+
+| Agent | What to Do |
+|-------|------------|
+| Main Claude | Pre-flight check before invoking uxui-frontend |
+| uxui-frontend | STEP 0.5: Read data.yaml, report loaded tokens |
+| ux-tester | Step 5.5: Chrome DevTools validation |
+
+**Files Updated:**
+- `.claude/lib/design-validator.md` (NEW - Single Source of Truth)
+- `.claude/agents/02-uxui-frontend.md` (v2.1.0 - references design-validator)
+- `.claude/agents/07-ux-tester.md` (v1.1.0 - Design Compliance Check)
+- `.claude/commands/cdev.md` (Step 4.0 - Pre-Flight Check)
+
+---
+
 ## ⚡ Context Optimization (v2.1.0)
 
 **→ See:** `@/.claude/lib/detailed-guides/context-optimization.md` for complete guide
@@ -310,6 +363,8 @@ User: "Build login system"
 **Recent versions:**
 | Version | Key Feature |
 |---------|-------------|
+| v3.4.0 | **Complete Pseudocode Elimination** (~3,210 lines → imperative instructions) |
+| v3.3.0 | **Design Validation System** (prevention + detection, single source of truth) |
 | v3.2.0 | Consolidated Pre-Work Context (single `pre-work-context.md` for agents) |
 | v3.1.1 | Direct Best Practices Execution (Step 2.7 rewritten, no pseudocode) |
 | v3.1.0 | TDD Classification + Development Principles Injection |

package/.claude/agents/02-uxui-frontend.md

@@ -7,8 +7,9 @@ color: blue
 
 # UX-UI Frontend Agent
 
-> **Version:** 2.0.0 (Claude 4.5 Optimized)
+> **Version:** 2.1.0 (Design Validator Integration)
 > **Role:** Build UI components with mock data. Focus on design quality and accessibility.
+> **Design Validation:** `.claude/lib/design-validator.md` (Part 2)
 
 ---
 
@@ -68,27 +69,97 @@ WHY: UI development shouldn't be blocked by backend availability. Mock data enab
 
 → See `.claude/contexts/patterns/agent-discovery.md`
 
-**STEP 0.5: Load Design & Content (uxui-frontend specific)**
+---
 
-```bash
-# Check for project-specific design tokens
-Read: design-system/data.yaml
+## STEP 0.5: Load Design System (MANDATORY)
+
+→ **Full Protocol:** `.claude/lib/design-validator.md` (Part 3)
+
+**ก่อนเขียน CSS/Tailwind ใดๆ ต้องทำขั้นตอนนี้ก่อน:**
+
+### ขั้นตอนที่ 1: อ่าน design-system/data.yaml
+
+อ่านไฟล์ `design-system/data.yaml`
+
+**ถ้ามีไฟล์:** จดค่าต่อไปนี้:
+- colors: primary, secondary, background, foreground, muted, accent (พร้อม hex values)
+- spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
+- animation durations: **150ms, 300ms, 500ms เท่านั้น!**
+- shadows: sm, md, lg, xl
+- typography: font family, sizes
+
+**ถ้าไม่มีไฟล์:**
+```
+⚠️ Design System NOT FOUND
+   - Path: design-system/data.yaml (missing)
+   - Fallback: Using .claude/contexts/design/*.md
+   - Recommendation: Run /designsetup to generate design system
+```
+→ อ่าน `.claude/contexts/design/*.md` แทน
+
+### ขั้นตอนที่ 2: อ่าน page-plan.md (ถ้ามี)
+
+อ่านไฟล์ `openspec/changes/{change-id}/page-plan.md`
 
-# Check for page plan (from /pageplan command)
-Read: openspec/changes/{change-id}/page-plan.md
+**ถ้ามี:**
+- ดู Component reuse list, new components, animation blueprint
+- ข้าม STEP 3 (component search) ไปเลย เพราะ page-plan ทำไว้แล้ว
+- Implement ทุก section ใน Section 2 (Page Structure)
+
+### ขั้นตอนที่ 3: Report ก่อนเริ่มเขียน code
+
+**ต้อง report นี้ก่อนเขียน CSS/Tailwind:**
+
+```
+✅ Design System Loaded (STEP 0.5)
+   - Source: design-system/data.yaml
+   - Colors: primary=#xxx, secondary=#xxx, background=#xxx, foreground=#xxx
+   - Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64
+   - Animation durations: 150ms, 300ms, 500ms
+   - Shadows: sm, md, lg, xl
 ```
 
-**Priority order:**
-1. **data.yaml** (project-specific) → Use all tokens, colors, spacing, psychology
-2. **page-plan.md** (if exists) → Use component plan, content draft, animation blueprint
-3. **design/*.md** (fallback) → General design principles
+### กฎการใช้ Design Tokens
 
-**If page-plan.md exists:**
-- Extract: Component reuse list, new components, content draft, animation blueprint (Section 2.6)
-- Skip STEP 3 (component search already done)
-- Implement ALL sections from Section 2 (Page Structure)
+**ห้ามใช้ (NEVER):**
 
-WHY: page-plan.md has buyer avatar analysis and conversion-optimized content that tasks.md doesn't provide.
+| ห้าม | ตัวอย่าง |
+|------|---------|
+| Hardcoded colors | `#3b82f6`, `rgb(59,130,246)`, `text-blue-500` |
+| Arbitrary spacing | `p-5`, `gap-7`, `m-[13px]`, `p-[22px]` |
+| Random duration | `duration-200`, `duration-250`, `duration-400` |
+| Mixed shadow levels | ใช้ `shadow-sm` ที่หนึ่ง `shadow-xl` ที่อื่น |
+
+**ต้องใช้ (ALWAYS):**
+
+| ใช้ | ตัวอย่าง |
+|-----|---------|
+| Theme colors | `bg-primary`, `text-foreground`, `bg-muted` |
+| Spacing scale | `p-4`, `p-6`, `gap-8`, `m-16` |
+| Standard durations | `duration-150`, `duration-300`, `duration-500` |
+| Consistent shadows | เลือก level เดียวสำหรับ cards ทั้งหมด |
+
+### ขั้นตอนที่ 4: Report หลังเขียน code เสร็จ
+
+**ต้อง report การใช้ tokens ใน output:**
+
+```
+📊 Design Token Usage Report
+   Colors used: text-foreground, bg-primary, bg-muted, border-border
+   Spacing used: p-4, p-6, p-8, gap-4, gap-8
+   Animations: duration-150, duration-300
+   Shadows: shadow-md (consistent)
+
+   ✅ All tokens from data.yaml
+```
+
+**ถ้ามี non-standard values ต้องบอกเหตุผล:**
+
+```
+⚠️ Non-standard values used:
+   - p-5 (reason: needed odd spacing for alignment)
+   - #custom-color (reason: brand requirement not in data.yaml)
+```
 
 ---
 
@@ -311,9 +382,21 @@ Design:
 - Shadows: {level}
 - Accessibility: {features}
 
+📊 Design Token Usage Report:
+- Colors used: text-foreground, bg-primary, bg-muted, ...
+- Spacing used: p-4, p-6, gap-8, ...
+- Animations: duration-150, duration-300
+- Shadows: shadow-md
+
+✅ All tokens from data.yaml
+OR
+⚠️ Non-standard values: {list with reasons}
+
 Next Step: {next task or agent}
 ```
 
+**IMPORTANT:** Include token usage report in final output. ux-tester will validate these against data.yaml using Chrome DevTools.
+
 ---
 
 ## Handoff to Frontend Agent