@champpaba/claude-agent-kit 1.1.1 → 1.4.0

package/.claude/commands/designsetup.md

@@ -224,30 +224,6 @@ if (!contextAnalysis.has_context) {
 
 ## STEP 2: Style Direction Analysis (AI Pondering)
 
-```javascript
-const ponderingPrompt = `
-You are a design systems architect creating style direction recommendations.
-
-Extracted Sites Summary:
-${Object.entries(extractedData).map(([site, data]) => `
-## ${site}
-- Style: ${data.sections.overview.style || 'Unknown'}
-- Colors: ${data.sections.color_palette.primary.slice(0, 3).map(c => c.hex).join(', ')}
-- Shadows: ${data.sections.shadows_elevation.values.slice(0, 2).join(', ')}
-- Border Radius: ${data.sections.border_radius.values.slice(0, 3).join(', ')}
-- Typography: ${data.sections.typography.fonts.slice(0, 2).join(', ')}
-- Button Animation: ${Object.values(data.animations).find(a => a.type === 'button')?.description || 'N/A'}
-- Card Animation: ${Object.values(data.animations).find(a => a.type === 'card')?.description || 'N/A'}
-`).join('\n')}
-
-Project Context:
-- Product: ${contextAnalysis.product_type}
-- Target Audience: ${contextAnalysis.target_audience.demographics} (tech-savvy: ${contextAnalysis.target_audience.tech_savvy})
-- Brand Personality: ${contextAnalysis.brand_personality.join(', ')}
-- Market Position: ${contextAnalysis.market_position || 'Not specified'}
-
-Task: Generate 2-3 style direction options ranked by fit.
-
 Instructions:
 1. Wrap thinking in <pondering> tags
 2. Consider:
@@ -400,6 +376,91 @@ Return only the YAML content.
 
 ---
 
+## STEP 3.5: Quick User Input (🆕 v1.4.0)
+
+> **NEW:** Ask user for quick feedback before presenting options
+
+```javascript
+output(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📝 Quick Question
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`)
+
+const userFeedback = await AskUserQuestion({
+  questions: [{
+    question: "มีอะไรอยากปรับหรือเน้นเป็นพิเศษไหม? (optional)",
+    header: "Preferences",
+    multiSelect: false,
+    options: [
+      { label: "ไม่มี ใช้ AI แนะนำ", description: "ให้ AI เลือกสิ่งที่เหมาะสมที่สุด" },
+      { label: "มีสี CI ของตัวเอง", description: "ระบุสีแบรนด์" },
+      { label: "ชอบ component เฉพาะ", description: "ชอบ button/card ของเว็บใดเป็นพิเศษ" },
+      { label: "ปรับอื่นๆ", description: "Typography, shadows, หรืออื่นๆ" }
+    ]
+  }]
+})
+
+let userPreferences = { type: 'none' }
+
+// Process user feedback
+if (userFeedback.answers["Preferences"] === "มีสี CI ของตัวเอง") {
+  output(`
+กรุณาระบุสี (HEX format, คั่นด้วย comma):
+ตัวอย่าง: #0d7276, #f97316
+
+สีของคุณ:
+  `)
+
+  const colorInput = await getUserTextInput()
+  const colors = colorInput.split(',').map(s => s.trim()).filter(s => s.match(/^#[0-9A-Fa-f]{6}$/))
+
+  if (colors.length > 0) {
+    userPreferences = {
+      type: 'custom_colors',
+      colors: {
+        primary: colors[0],
+        secondary: colors[1] || null,
+        accent: colors[2] || null
+      }
+    }
+    output(`✅ รับสีแล้ว: ${colors.join(', ')}`)
+  }
+
+} else if (userFeedback.answers["Preferences"] === "ชอบ component เฉพาะ") {
+  output(`
+ระบุความชอบ (ตัวอย่าง: "ชอบ button ของ motherduck, card ของ gitingest"):
+  `)
+
+  const preferenceText = await getUserTextInput()
+  userPreferences = {
+    type: 'component_preference',
+    text: preferenceText
+  }
+  output(`✅ บันทึกความชอบแล้ว`)
+
+} else if (userFeedback.answers["Preferences"] === "ปรับอื่นๆ") {
+  output(`
+ระบุสิ่งที่อยากปรับ (ตัวอย่าง: "ใช้ font Inter, shadow แบบ soft"):
+  `)
+
+  const adjustmentText = await getUserTextInput()
+  userPreferences = {
+    type: 'other_adjustment',
+    text: adjustmentText
+  }
+  output(`✅ บันทึกการปรับแต่งแล้ว`)
+}
+
+output(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔄 กำลังสร้าง style options (พร้อม preferences ของคุณ)...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`)
+```
+
+---
+
 ## STEP 4: Present Options to User
 
 ```javascript
@@ -413,6 +474,7 @@ Based on:
 ✓ Target: ${contextAnalysis.target_audience.demographics}
 ✓ Brand: ${contextAnalysis.brand_personality.join(', ')}
 ✓ Product: ${contextAnalysis.product_type}
+${userPreferences.type !== 'none' ? `✓ User preferences: ${JSON.stringify(userPreferences)}` : ''}
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `);
@@ -720,6 +782,270 @@ Write('design-system/STYLE_GUIDE.md', styleGuideMD);
 
 ---
 
+## STEP 5.5: Generate STYLE_TOKENS.json (Context Optimization)
+
+> **New in v1.2.0:** Generate lightweight design tokens file for token-efficient loading
+
+```javascript
+output(`
+🔄 Extracting design tokens for efficient loading...
+`);
+
+// Extract design tokens from STYLE_GUIDE.md
+const tokensPrompt = `
+You are extracting design tokens from the STYLE_GUIDE.md into a lightweight JSON format.
+
+Source: STYLE_GUIDE.md content below
+${styleGuideMD}
+
+Task: Extract ALL design tokens into JSON format following this exact structure:
+
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "version": "1.0.0",
+  "meta": {
+    "generated_at": "${new Date().toISOString()}",
+    "generated_by": "/designsetup command",
+    "source": "design-system/STYLE_GUIDE.md",
+    "design_style": "${selectedOption.name}",
+    "description": "Lightweight design tokens extracted from STYLE_GUIDE.md (~500 tokens vs ~5000 tokens for full guide)"
+  },
+  "tokens": {
+    "colors": {
+      "primary": {
+        "DEFAULT": "[extract from guide]",
+        "foreground": "[extract]",
+        "hover": "[extract or generate]",
+        "description": "Primary brand color for CTAs, links, and accents",
+        "tailwind": "bg-primary, text-primary, border-primary"
+      },
+      "secondary": { ... },
+      "background": { ... },
+      "foreground": { ... },
+      "border": { ... },
+      "semantic": {
+        "success": "[extract]",
+        "warning": "[extract]",
+        "error": "[extract]",
+        "info": "[extract]"
+      }
+    },
+    "spacing": {
+      "scale": [extract spacing scale array],
+      "description": "4px or 8px base unit spacing scale",
+      "tailwind_mapping": { ... },
+      "common_patterns": {
+        "component_padding": "p-4 (16px) or p-6 (24px)",
+        "section_gap": "gap-8 (32px) or gap-12 (48px)",
+        "layout_margin": "mt-16 (64px) or mt-24 (96px)"
+      }
+    },
+    "typography": {
+      "font_family": { ... },
+      "font_size": { ... },
+      "font_weight": { ... },
+      "line_height": { ... },
+      "headings": { ... }
+    },
+    "shadows": {
+      "sm": "[extract]",
+      "DEFAULT": "[extract]",
+      "md": "[extract]",
+      "lg": "[extract]",
+      "xl": "[extract]",
+      "usage": {
+        "cards": "shadow-md",
+        "dropdowns": "shadow-lg",
+        "modals": "shadow-xl",
+        "buttons_hover": "shadow-sm"
+      }
+    },
+    "borders": {
+      "radius": { ... },
+      "width": { ... },
+      "usage": { ... }
+    },
+    "animation": {
+      "duration": { ... },
+      "easing": { ... },
+      "common": { ... }
+    },
+    "breakpoints": { ... },
+    "z_index": { ... }
+  },
+  "component_library": {
+    "name": "[extract from guide]",
+    "install_command": "[extract]",
+    "common_components": [extract array]
+  },
+  "component_patterns": {
+    "button": {
+      "primary": "[extract full Tailwind classes from Button component section - exact copy of primary button pattern]",
+      "secondary": "[extract secondary button pattern]",
+      "ghost": "[extract ghost button pattern]",
+      "outline": "[extract outline button pattern]",
+      "destructive": "[extract destructive/danger button pattern]",
+      "link": "[extract link button pattern]",
+      "icon": "[extract icon-only button pattern]",
+      "sizes": {
+        "sm": "[extract small button classes]",
+        "md": "[extract medium/default button classes]",
+        "lg": "[extract large button classes]"
+      },
+      "states": {
+        "default": "[base classes]",
+        "hover": "[hover state classes]",
+        "active": "[active/pressed state classes]",
+        "disabled": "[disabled state classes]",
+        "loading": "[loading state classes with spinner]"
+      }
+    },
+    "card": {
+      "default": "[extract default card pattern with border/shadow/padding]",
+      "elevated": "[extract elevated card with larger shadow]",
+      "outlined": "[extract outlined card variant]",
+      "interactive": "[extract interactive card with hover effects]",
+      "composition": {
+        "header": "[extract card header classes]",
+        "content": "[extract card content/body classes]",
+        "footer": "[extract card footer classes]",
+        "image": "[extract card image wrapper classes]"
+      }
+    },
+    "input": {
+      "base": "[extract base input field classes]",
+      "variants": {
+        "default": "[extract default input]",
+        "error": "[extract error state input with red border]",
+        "success": "[extract success state input]",
+        "disabled": "[extract disabled input]"
+      },
+      "sizes": {
+        "sm": "[extract small input]",
+        "md": "[extract medium input]",
+        "lg": "[extract large input]"
+      }
+    },
+    "form_field": {
+      "wrapper": "[extract form field wrapper classes]",
+      "label": "[extract label classes]",
+      "input": "[reference to input.base]",
+      "helper_text": "[extract helper text classes]",
+      "error_message": "[extract error message classes with red text]",
+      "composition": "[extract full form field pattern: label + input + helper + error]"
+    },
+    "badge": {
+      "default": "[extract default badge]",
+      "variants": {
+        "primary": "[extract primary badge]",
+        "secondary": "[extract secondary badge]",
+        "success": "[extract success/green badge]",
+        "warning": "[extract warning/yellow badge]",
+        "error": "[extract error/red badge]",
+        "outline": "[extract outline badge]"
+      }
+    },
+    "alert": {
+      "base": "[extract base alert classes]",
+      "variants": {
+        "info": "[extract info alert with blue accent]",
+        "success": "[extract success alert with green accent]",
+        "warning": "[extract warning alert with yellow accent]",
+        "error": "[extract error alert with red accent]"
+      },
+      "composition": {
+        "wrapper": "[alert container classes]",
+        "icon": "[icon wrapper classes]",
+        "content": "[content wrapper classes]",
+        "title": "[alert title classes]",
+        "description": "[alert description classes]",
+        "actions": "[action buttons wrapper classes]"
+      }
+    }
+  },
+  "layout_patterns": {
+    "container": {
+      "default": "[extract default container: max-w-7xl mx-auto px-4 sm:px-6 lg:px-8]",
+      "narrow": "[extract narrow container: max-w-4xl]",
+      "wide": "[extract wide container: max-w-screen-2xl]",
+      "full": "[extract full-width: w-full]",
+      "fluid": "[extract fluid container with responsive padding]"
+    },
+    "grid": {
+      "auto": "[extract auto-fit grid: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6]",
+      "feature": "[extract feature grid: grid grid-cols-1 md:grid-cols-3 gap-8]",
+      "dashboard": "[extract dashboard grid: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4]",
+      "gallery": "[extract gallery grid: grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-2]",
+      "masonry": "[extract masonry-style grid classes]"
+    },
+    "flex": {
+      "row_center": "[extract centered row: flex items-center justify-center]",
+      "row_between": "[extract space-between row: flex items-center justify-between]",
+      "row_start": "[extract left-aligned row: flex items-center justify-start]",
+      "col_center": "[extract centered column: flex flex-col items-center justify-center]",
+      "col_start": "[extract top-aligned column: flex flex-col items-start]"
+    },
+    "section_spacing": {
+      "tight": "[extract tight section spacing: py-8 md:py-12]",
+      "normal": "[extract normal section spacing: py-12 md:py-16]",
+      "loose": "[extract loose section spacing: py-16 md:py-24]",
+      "hero": "[extract hero section spacing: py-20 md:py-32]"
+    },
+    "page_layouts": {
+      "landing": "[extract landing page layout structure]",
+      "dashboard": "[extract dashboard layout: sidebar + main content]",
+      "auth": "[extract auth page layout: centered card]",
+      "settings": "[extract settings page layout: tabs + content]"
+    }
+  },
+  "critical_rules": {
+    "colors": [
+      "❌ NO hardcoded hex values (#64748b)",
+      "✅ USE theme tokens (text-foreground/70)",
+      "❌ NO random opacity values",
+      "✅ USE consistent opacity scale (/50, /70, /90)"
+    ],
+    "spacing": [
+      "❌ NO arbitrary values (p-5, gap-7, mt-15)",
+      "✅ USE spacing scale (p-4, p-6, gap-8, mt-16)",
+      "❌ NO hardcoded px values",
+      "✅ USE Tailwind scale"
+    ],
+    "consistency": [
+      "❌ NO mixing patterns (shadow-sm on Card A, shadow-lg on Card B)",
+      "✅ USE consistent patterns (all cards use shadow-md)",
+      "❌ NO mixing border radius (rounded-md vs rounded-lg)",
+      "✅ USE same border radius for similar components"
+    ]
+  }
+}
+
+IMPORTANT:
+- Extract ALL values from STYLE_GUIDE.md (don't use placeholders)
+- If a value isn't in the guide, infer it logically (e.g., hover = 10% darker than DEFAULT)
+- Keep descriptions concise but clear
+- Return ONLY valid JSON (no markdown, no explanations)
+`;
+
+const tokensJSON = await LLM({
+  prompt: tokensPrompt,
+  max_tokens: 4000,
+  temperature: 0.1 // Low temperature for consistent extraction
+});
+
+// Validate JSON
+try {
+  JSON.parse(tokensJSON);
+  Write('design-system/STYLE_TOKENS.json', tokensJSON);
+  output(`✅ STYLE_TOKENS.json generated (~500 tokens)`);
+} catch (e) {
+  warn(`⚠️ Failed to generate STYLE_TOKENS.json: ${e.message}`);
+  warn(`Continuing without tokens file...`);
+}
+```
+
+---
+
 ## STEP 6: Final Report
 
 ```
@@ -740,7 +1066,8 @@ Write('design-system/STYLE_GUIDE.md', styleGuideMD);
 ${selectedOption.advantages.slice(0, 4).map(a => `   ✓ ${a}`).join('\n')}
 
 📦 Files Created:
-   ✓ design-system/STYLE_GUIDE.md (final guide)
+   ✓ design-system/STYLE_GUIDE.md (final guide, ~2000 lines)
+   ✓ design-system/STYLE_TOKENS.json (lightweight tokens, ~500 tokens) 🆕
    ✓ design-system/synthesis/options/ (${styleOptions.options.length} YAMLs)
 
 ⚠️ Trade-offs:
@@ -756,17 +1083,21 @@ ${selectedOption.disadvantages.slice(0, 2).map(d => `   • ${d}`).join('\n')}
 
 🚀 Next Steps:
 
-1. Review STYLE_GUIDE.md:
-   cat design-system/STYLE_GUIDE.md | head -100
+1. Review generated files:
+   - Full guide: cat design-system/STYLE_GUIDE.md | head -100
+   - Tokens: cat design-system/STYLE_TOKENS.json
 
-2. Setup project (if needed):
+2. Setup project (generates design-context.md):
    /psetup
 
 3. Start development:
    /csetup feature-login
    /cdev feature-login
 
-4. Agents will automatically use STYLE_GUIDE.md ✓
+4. Context Optimization (v1.2.0):
+   ✅ Commands use STYLE_TOKENS.json (~500 tokens, not full guide ~5K)
+   ✅ Agents load design-context.md + STYLE_TOKENS.json (~1.5K total)
+   ✅ 70% token reduction while maintaining quality ✨
 ```
 
 ---

package/.claude/commands/pageplan.md

@@ -21,7 +21,8 @@
 1. **Reads User-Specified Context:**
    - Only reads files that user mentions with `@` prefix
    - Always reads `.changes/{change-id}/proposal.md` (if exists)
-   - Always reads `design-system/STYLE_GUIDE.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)
 
 2. **Searches Existing Components:**
    - Glob: `**/{Navbar,Footer,Sidebar,Header}*.{tsx,jsx,vue}`
@@ -64,16 +65,34 @@ const userFiles = extractMentionedFiles(userMessage) // @prd.md, @brief.md
 
 // Always read (if exists)
 const proposalPath = `.changes/${changeId}/proposal.md`
-const styleGuidePath = `design-system/STYLE_GUIDE.md`
+const tokensPath = `design-system/STYLE_TOKENS.json` // 🆕 Lightweight tokens
+const styleGuidePath = `design-system/STYLE_GUIDE.md` // Validate only, don't load
 
 const contextFiles = [
   ...userFiles,
-  proposalPath,
-  styleGuidePath
+  proposalPath
 ].filter(fileExists)
 
 // Read all context
-const context = contextFiles.map(readFile).join('\n\n---\n\n')
+let context = contextFiles.map(readFile).join('\n\n---\n\n')
+
+// 🆕 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 += `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`)
+}
+
+// Total context: ~1.5K tokens (vs 5K+ if loading full STYLE_GUIDE.md)
 ```
 
 ### STEP 3: Search Existing Components
@@ -181,11 +200,22 @@ _([length] chars - based on [source])_
 ---
 
 ## 5. Design Notes
-- Follow \`design-system/STYLE_GUIDE.md\`:
-  - Primary color: [from STYLE_GUIDE]
-  - Font family: [from STYLE_GUIDE]
-  - Spacing scale: [from STYLE_GUIDE]
-  - Component library: [from STYLE_GUIDE]
+
+**Design System Files:**
+- Tokens (lightweight): \`design-system/STYLE_TOKENS.json\`
+- Full guide (reference): \`design-system/STYLE_GUIDE.md\`
+
+**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]
+
+**Agent Instructions:**
+- uxui-frontend MUST read STYLE_TOKENS.json in STEP 0.5
+- Use theme tokens (text-foreground/70), NOT hardcoded colors
+- Use spacing scale (p-4, p-6), NOT arbitrary values (p-5)
 
 ## 6. Implementation Notes
 

package/.claude/lib/README.md

@@ -1,10 +1,11 @@
 # .claude/lib/ - Implementation Logic
 
 > **Logic specifications for Main Claude orchestrator**
+> **Version:** 1.4.0 - Context Optimization & DRY Consolidation
 
 ---
 
-## 📁 Files
+## 📁 Core Logic Files
 
 **`agent-executor.md`** - Agent retry & escalation logic
 Used by `/cdev` to execute agents with automatic retry, validation, and user escalation
@@ -12,15 +13,56 @@ Used by `/cdev` to execute agents with automatic retry, validation, and user esc
 **`tdd-classifier.md`** - TDD classification logic
 Used by `/csetup` to automatically determine which phases require TDD workflow
 
-**`flags-updater.md`** - 🆕 Progress tracking protocol
+**`flags-updater.md`** - Progress tracking protocol
 Ensures Main Claude updates flags.json after EVERY phase completion. Provides helper functions for extracting files, tasks, and calculating duration.
 
-**`agent-router.md`** - 🆕 Mandatory agent routing rules
+**`agent-router.md`** - Mandatory agent routing rules
 Enforces strict agent boundaries. Main Claude MUST delegate implementation work to specialized agents. Includes work type detection patterns and self-check protocol.
 
-**`validation-gates.md`** - 🆕 Validation checkpoints
+**`validation-gates.md`** - Validation checkpoints
 Four validation gates that Main Claude MUST pass: before work, after agent responds, before reporting, and before phase start. Ensures quality and correctness at each step.
 
+**`task-analyzer.md`** - TaskMaster-style task analysis (v1.3.0)
+Used by `/csetup` to analyze tasks with 6 dimensions: complexity, dependencies, risk, research, subtasks, priority. Generates intelligent phases.md with time buffers and metadata.
+
+---
+
+## 📁 Shared Documentation (v1.4.0 - NEW!)
+
+**`context-loading-protocol.md`** - Universal context loading strategy
+Consolidated protocol used by ALL agents (STEP 0). Includes package manager discovery, framework detection via Context7, and best practices loading.
+
+**`handoff-protocol.md`** - Agent handoff templates
+Standardized handoff formats for agent-to-agent communication. Includes all 15 handoff paths with clear templates.
+
+**`tdd-workflow.md`** - TDD workflow examples
+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.
+
+---
+
+## 📁 Detailed Guides (v1.4.0 - NEW!)
+
+**`detailed-guides/best-practices-system.md`** - How best practices work
+Complete guide to auto-generated best practices via Context7 MCP. Covers `/agentsetup`, 3-level indexing, and agent discovery flow.
+
+**`detailed-guides/context-optimization.md`** - Token optimization strategy
+Details the 70% token reduction in design system loading. Explains 3-tier loading, before/after comparisons, and benefits.
+
+**`detailed-guides/page-planning.md`** - /pageplan command guide
+Complete guide to page planning system. Covers component reuse, content drafting, asset preparation, and 25% speed improvement.
+
+**`detailed-guides/taskmaster-analysis.md`** - 6-dimension task analysis
+Detailed explanation of TaskMaster-style analysis. Covers complexity scoring, dependency detection, risk assessment, research requirements, subtask breakdown, priority ranking.
+
+**`detailed-guides/design-system.md`** - Style guide generation
+How `/designsetup` works. Covers 3 smart paths (reference → brownfield → greenfield), 17-section output, and agent discovery.
+
+**`detailed-guides/agent-system.md`** - Agent overview & workflow
+Complete agent system guide. Covers 6 specialist agents, Main Claude's role, self-check protocol, and pre-work requirements.
+
 ---
 
 ## 🚨 Important