@champpaba/claude-agent-kit 2.6.0 → 2.7.0

package/.claude/lib/document-loader.md

@@ -31,7 +31,7 @@ Why: Lightweight summary that points to full resources
 
 ### Tier 2: Design Tokens (Load for UI Work)
 ```
-File: design-system/STYLE_TOKENS.json
+File: design-system/data.yaml
 Tokens: ~500
 Contains: Colors, spacing, typography, shadows, borders, animations
 
@@ -39,14 +39,14 @@ When: Commands/agents that need design tokens (pageplan, csetup, uxui-frontend)
 Why: Lightweight token-only file for quick reference
 ```
 
-### Tier 3: Full Style Guide (Optional - Selective Loading)
+### Tier 3: Human-Readable Summary (Optional)
 ```
-File: design-system/STYLE_GUIDE.md
-Tokens: ~5000 (full) or ~2000 (selective sections)
-Contains: 17 sections including examples, patterns, component library
+File: design-system/README.md
+Tokens: ~100 (human-readable summary)
+Contains: Quick reference for humans, not for agents
 
-When: Agent needs detailed examples or specific sections
-Why: Full reference, but load selectively to save tokens
+When: Human wants to read design summary
+Why: Short, scannable summary for humans
 ```
 
 ### Tier 4: Universal Principles (Fallback)
@@ -65,7 +65,7 @@ Why: Universal design principles apply to any project
 
 ### Pattern A: Planning Commands (/pageplan, /csetup)
 
-**Goal:** Understand design system without loading full STYLE_GUIDE
+**Goal:** Understand design system efficiently
 
 ```typescript
 function loadDesignContext(projectName: string) {
@@ -77,18 +77,15 @@ function loadDesignContext(projectName: string) {
     context.summary = Read(designContextPath) // ~1K tokens
   }
 
-  // 2. Load STYLE_TOKENS.json (design tokens only)
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
+  // 2. Load data.yaml (design tokens only)
+  const tokensPath = 'design-system/data.yaml'
   if (exists(tokensPath)) {
     context.tokens = JSON.parse(Read(tokensPath)) // ~500 tokens
   }
 
-  // 3. Validate STYLE_GUIDE.md exists (don't load!)
-  const styleGuidePath = 'design-system/STYLE_GUIDE.md'
-  context.hasStyleGuide = exists(styleGuidePath)
-
-  if (!context.hasStyleGuide && hasFrontendWork) {
-    warn(`⚠️ UI work detected but no STYLE_GUIDE.md
+  // 3. Validate data.yaml loaded successfully
+  if (!context.tokens && hasFrontendWork) {
+    warn(`⚠️ UI work detected but no data.yaml
           Run: /designsetup`)
   }
 
@@ -115,8 +112,7 @@ const spacingScale = designContext.tokens.spacing.scale
 ```typescript
 function buildDesignReference(projectName: string): string {
   const designContextPath = `.claude/contexts/domain/${projectName}/design-context.md`
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
-  const styleGuidePath = 'design-system/STYLE_GUIDE.md'
+  const tokensPath = 'design-system/data.yaml'
 
   // Don't load content! Just send paths + minimal summary
   return `
@@ -128,10 +124,7 @@ function buildDesignReference(projectName: string): string {
    → Project design summary, file paths
 
 2. Read: ${tokensPath} (~500 tokens)
-   → Design tokens (colors, spacing, typography)
-
-3. Optional: ${styleGuidePath} (selective sections ~2K tokens)
-   → Full guide - load Component Styles, Layout Patterns if needed
+   → Design tokens (colors, spacing, typography, psychology)
 
 **Style Guidelines:**
 | Instead of | Use | WHY |
@@ -140,7 +133,7 @@ function buildDesignReference(projectName: string): string {
 | p-5 | p-4 or p-6 | Spacing scale |
 
 **Report format:**
-"Design Context Loaded: design-context.md + STYLE_TOKENS.json"
+"Design Context Loaded: design-context.md + data.yaml"
 "Design Tokens Extracted: [list key tokens]"
   `
 
@@ -170,13 +163,13 @@ async function loadDesignSystem(projectName: string) {
     warn(`⚠️ No design-context.md - using fallback`)
   }
 
-  // STEP 0.5.2: Load STYLE_TOKENS.json
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
+  // STEP 0.5.2: Load data.yaml
+  const tokensPath = 'design-system/data.yaml'
   let tokens = null
 
   if (exists(tokensPath)) {
     tokens = JSON.parse(Read(tokensPath)) // ~500 tokens
-    report.push(`✅ STYLE_TOKENS.json loaded`)
+    report.push(`✅ data.yaml loaded`)
   }
 
   // STEP 0.5.3: Extract key tokens
@@ -192,14 +185,7 @@ async function loadDesignSystem(projectName: string) {
   report.push(`   - Spacing: ${extractedTokens.spacing.join(', ')}px`)
   report.push(`   - Component Library: ${extractedTokens.componentLibrary}`)
 
-  // STEP 0.5.4: Optional - Load specific STYLE_GUIDE sections
-  const styleGuidePath = 'design-system/STYLE_GUIDE.md'
-  if (needsDetailedExamples && exists(styleGuidePath)) {
-    // Selective loading: Only Component Styles section
-    const fullGuide = Read(styleGuidePath)
-    const componentSection = extractSection(fullGuide, '## 6. Component Styles')
-    report.push(`✅ STYLE_GUIDE.md (Section 6: Component Styles) loaded`)
-  }
+  // STEP 0.5.4: data.yaml contains all design info - no need for separate files
 
   // Report to user
   output(`
@@ -220,10 +206,9 @@ ${report.join('\n')}
 
 | Approach | Tier 1 | Tier 2 | Tier 3 | Total | Use Case |
 |----------|--------|--------|--------|-------|----------|
-| **Planning** (pageplan, csetup) | design-context.md (1K) | STYLE_TOKENS.json (500) | - | **1.5K** | ✅ Efficient |
+| **Planning** (pageplan, csetup) | design-context.md (1K) | data.yaml (500) | - | **1.5K** | ✅ Efficient |
 | **Execution** (/cdev) | Reference only (200) | - | - | **200** | ✅ Very efficient |
-| **Agent** (uxui-frontend) | design-context.md (1K) | STYLE_TOKENS.json (500) | Selective sections (2K) | **3.5K** | ✅ Good |
-| **Old approach** | - | - | Full STYLE_GUIDE (5K) | **5K** | ❌ Wasteful |
+| **Agent** (uxui-frontend) | design-context.md (1K) | data.yaml (500) | - | **1.5K** | ✅ Efficient |
 
 **Savings: 70-95% reduction in tokens!**
 
@@ -234,8 +219,8 @@ ${report.join('\n')}
 | Practice | WHY |
 |----------|-----|
 | Load design-context.md first | Entry point with file paths |
-| Load STYLE_TOKENS.json for UI work | Lightweight token reference |
-| Load STYLE_GUIDE.md selectively | Save tokens (5K → 2K) |
+| Load data.yaml for UI work | Lightweight token reference |
+| Use data.yaml for tokens | ~500 tokens, contains all design info |
 | Validate files exist before loading | Prevent errors |
 | Report what was loaded | Transparency for debugging |
 | Skip design files for backend/database | Not needed, saves tokens |
@@ -252,13 +237,13 @@ function loadDesignFallback() {
   warn(`⚠️ No design-context.md found
        Attempting fallback...`)
 
-  // Option 1: Load STYLE_TOKENS.json directly
-  if (exists('design-system/STYLE_TOKENS.json')) {
-    return { tokens: JSON.parse(Read('design-system/STYLE_TOKENS.json')) }
+  // Option 1: Load data.yaml directly
+  if (exists('design-system/data.yaml')) {
+    return { tokens: JSON.parse(Read('design-system/data.yaml')) }
   }
 
   // Option 2: Load universal design principles
-  warn(`⚠️ No STYLE_TOKENS.json - using universal principles`)
+  warn(`⚠️ No data.yaml - using universal principles`)
   return {
     universal: [
       Read('.claude/contexts/design/box-thinking.md'),
@@ -286,8 +271,8 @@ if (designContext.tokens) {
   output(`Using primary color: ${primary}`)
 }
 
-if (!designContext.hasStyleGuide) {
-  warn(`⚠️ No STYLE_GUIDE.md - run /designsetup first`)
+if (!designContext.tokens) {
+  warn(`⚠️ No data.yaml - run /designsetup first`)
 }
 ```
 
@@ -339,8 +324,8 @@ const Button = `
 - [ ] Identify if command deals with UI/design
 - [ ] Use appropriate loading pattern (A, B, or C)
 - [ ] Load design-context.md first
-- [ ] Load STYLE_TOKENS.json if needed
-- [ ] Only load STYLE_GUIDE.md selectively
+- [ ] Load data.yaml if needed
+- [ ] Load data.yaml for design tokens
 - [ ] Validate files exist
 - [ ] Report what was loaded
 - [ ] Handle fallback gracefully

package/.claude/lib/task-analyzer.md

@@ -255,7 +255,7 @@ function detectResearchNeeds(task: Task, changeContext: any): ResearchRequiremen
   }
 
   // Special case: If no design system exists and UI work detected
-  if (task.type === 'uxui-frontend' && !fileExists('design-system/STYLE_GUIDE.md')) {
+  if (task.type === 'uxui-frontend' && !fileExists('design-system/data.yaml')) {
     detectedPatterns.push({
       category: 'missingDesignSystem',
       reason: 'No design system found - component library selection needed',
@@ -1087,4 +1087,197 @@ function calculateBuffer(complexity: number, risk: RiskLevel): number {
 
 ---
 
+## 🧪 UX Testing Phase Injection (v2.7.0)
+
+> **NEW:** Auto-inject Phase 1.5 (UX Testing) after uxui-frontend phase
+
+### Purpose
+
+Ensure UI is tested from user perspectives before proceeding to backend development.
+
+### Detection Logic
+
+```typescript
+function shouldInjectUXTesting(phases: Phase[]): boolean {
+  // Check if any phase uses uxui-frontend agent
+  return phases.some(p => p.agent === 'uxui-frontend')
+}
+```
+
+### Injection Logic
+
+```typescript
+function injectUXTestingPhase(phases: Phase[], context?: ChangeContext): Phase[] {
+  // Step 1: Check if should inject
+  if (!shouldInjectUXTesting(phases)) {
+    return phases // No UI work, skip injection
+  }
+
+  // Step 2: Check skip conditions (optional context)
+  if (context && shouldSkipUXTesting(phases, context)) {
+    return phases // Skip due to context conditions
+  }
+
+  // Step 3: Find the last uxui-frontend phase
+  const lastUxuiFrontendIndex = phases
+    .map((p, i) => p.agent === 'uxui-frontend' ? i : -1)
+    .filter(i => i >= 0)
+    .pop()
+
+  if (lastUxuiFrontendIndex === undefined) {
+    return phases
+  }
+
+  // Step 4: Create UX Testing phase
+  const uxTestingPhase: Phase = {
+    number: `${phases[lastUxuiFrontendIndex].number}.5`, // e.g., "1.5"
+    name: 'UX Testing',
+    agent: 'ux-tester',
+    estimatedTime: 30,
+    metadata: ['approval-gate', 'user-testing', 'persona-based'],
+    requires_approval: true,
+    description: 'Test UI from user perspectives before backend development'
+  }
+
+  // Step 5: Insert after the last uxui-frontend phase
+  const newPhases = [...phases]
+  newPhases.splice(lastUxuiFrontendIndex + 1, 0, uxTestingPhase)
+
+  // Step 6: Renumber subsequent phases if needed
+  return renumberPhases(newPhases)
+}
+
+function renumberPhases(phases: Phase[]): Phase[] {
+  // Keep .5 phases as-is, renumber whole numbers
+  let wholeNumber = 1
+
+  return phases.map(phase => {
+    if (phase.number.toString().includes('.5')) {
+      return phase // Keep .5 as-is
+    }
+
+    const newPhase = { ...phase, number: wholeNumber }
+    wholeNumber++
+    return newPhase
+  })
+}
+```
+
+### Integration Point
+
+**In `/csetup` command, after phase generation:**
+
+```typescript
+// STEP 4: Generate phases from template
+let phases = generatePhasesFromTemplate(templateName, analyzedTasks)
+
+// STEP 4.5: Inject UX Testing phase (NEW v2.7.0)
+phases = injectUXTestingPhase(phases)
+
+output(`
+📊 Phases Generated:
+${phases.map(p => `   Phase ${p.number}: ${p.name} (${p.agent})`).join('\n')}
+
+${phases.some(p => p.agent === 'ux-tester') ?
+  '🧪 UX Testing phase auto-injected after uxui-frontend' : ''}
+`)
+
+// STEP 5: Write phases.md
+writePhasesFile(phases, changeId)
+```
+
+### Output Example
+
+**Before injection:**
+```
+Phase 1: Frontend Mockup (uxui-frontend)
+Phase 2: Backend API (backend)
+Phase 3: Database Schema (database)
+Phase 4: Frontend Integration (frontend)
+Phase 5: Testing (test-debug)
+```
+
+**After injection:**
+```
+Phase 1: Frontend Mockup (uxui-frontend)
+Phase 1.5: UX Testing (ux-tester) ← AUTO-INJECTED
+Phase 2: Backend API (backend)
+Phase 3: Database Schema (database)
+Phase 4: Frontend Integration (frontend)
+Phase 5: Testing (test-debug)
+```
+
+### Approval Gate Behavior
+
+When `/cdev` reaches Phase 1.5:
+
+1. `ux-tester` agent runs and generates report
+2. Workflow **PAUSES** - waits for user
+3. User options:
+   - `approve` → Continue to Phase 2
+   - `reject [feedback]` → Loop back to Phase 1
+
+```
+Phase 1 (uxui-frontend) ──► Phase 1.5 (ux-tester) ──► [PAUSE]
+        ▲                                                │
+        │                                                ▼
+        └──────────── reject ◄────────────────── User Decision
+                                                         │
+                                                         ▼
+                                               approve ──► Phase 2
+```
+
+### Skip Conditions
+
+**Do NOT inject UX Testing if:**
+
+```typescript
+function shouldSkipUXTesting(phases: Phase[], context: ChangeContext): boolean {
+  // 1. No UI work detected (redundant with shouldInjectUXTesting but kept for clarity)
+  if (!phases.some(p => p.agent === 'uxui-frontend')) {
+    return true
+  }
+
+  // 2. Backend-only or API-only change (detected from proposal/tasks)
+  const changeType = detectChangeType(context.proposal, context.tasks)
+  if (changeType === 'backend-only' || changeType === 'api-only') {
+    return true
+  }
+
+  // 3. User explicitly disabled (via flags.json)
+  if (context.flags?.skip_ux_testing === true) {
+    return true
+  }
+
+  // 4. Minor UI fix (average complexity < 3)
+  const uiPhases = phases.filter(p => p.agent === 'uxui-frontend')
+  if (uiPhases.length > 0) {
+    const avgComplexity = uiPhases.reduce((sum, p) => sum + (p.complexity || 5), 0) / uiPhases.length
+    if (avgComplexity < 3) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// Helper: Detect change type from content
+function detectChangeType(proposal: string, tasks: string): string {
+  const content = `${proposal} ${tasks}`.toLowerCase()
+
+  // Check for UI indicators
+  const hasUI = content.match(/landing|page|component|ui|frontend|form|button|modal|dashboard/i)
+
+  // Check for backend-only indicators
+  const isBackendOnly = content.match(/api.only|backend.only|no.ui|cli|cron|migration|script/i)
+
+  if (isBackendOnly && !hasUI) return 'backend-only'
+  if (!hasUI) return 'api-only'
+
+  return 'full-stack' // default
+}
+```
+
+---
+
 **This framework transforms simple tasks.md into intelligent, analyzed workflows! 🚀**