@champpaba/claude-agent-kit 1.1.1 → 1.4.0

package/.claude/commands/csetup.md

@@ -42,6 +42,60 @@ Read in order:
 2. `openspec/changes/{change-id}/tasks.md`
 3. `openspec/changes/{change-id}/design.md` (if exists)
 
+---
+
+### Step 2.5: Validate Design System (Context Optimization v1.2.0)
+
+> **New:** Validate design files exist for UI work
+
+```typescript
+// Detect if change involves UI/frontend work
+const tasksContent = Read('openspec/changes/{change-id}/tasks.md')
+const hasFrontend = tasksContent.toLowerCase().match(/(ui|component|page|frontend|design|responsive)/i)
+
+if (hasFrontend) {
+  output(`\n🎨 UI work detected - validating design system...`)
+
+  const tokensPath = 'design-system/STYLE_TOKENS.json'
+  const styleGuidePath = 'design-system/STYLE_GUIDE.md'
+
+  const hasTokens = fileExists(tokensPath)
+  const hasStyleGuide = fileExists(styleGuidePath)
+
+  if (!hasTokens || !hasStyleGuide) {
+    warn(`
+⚠️ WARNING: UI work detected but design system incomplete!
+
+Found:
+  ${hasStyleGuide ? '✅' : '❌'} STYLE_GUIDE.md
+  ${hasTokens ? '✅' : '❌'} STYLE_TOKENS.json
+
+This may result in:
+  - Inconsistent colors (random hex codes)
+  - Arbitrary spacing (p-5, gap-7)
+  - Duplicate components
+
+Recommendation:
+  1. Run: /designsetup
+  2. Then: /csetup ${changeId}
+
+Continue anyway? (yes/no)
+    `)
+
+    const answer = await askUser()
+    if (answer === 'no') {
+      return error('Setup cancelled. Run /designsetup first.')
+    }
+  } else {
+    output(`✅ Design System Ready`)
+    output(`   - STYLE_GUIDE.md ✓`)
+    output(`   - STYLE_TOKENS.json ✓`)
+  }
+}
+```
+
+---
+
 ### Step 3: Analyze Tasks
 
 **Parse tasks.md content and detect keywords:**
@@ -79,6 +133,133 @@ Detected:
 Change type: feature
 ```
 
+---
+
+### Step 3.5: Analyze Tasks (TaskMaster-style - v1.3.0)
+
+> **NEW:** Enhanced task analysis with complexity, dependencies, risk assessment
+
+**See:** `.claude/lib/task-analyzer.md` for complete analysis logic
+
+```typescript
+import { analyzeTask } from '.claude/lib/task-analyzer.md'
+
+// Parse tasks from tasks.md
+const tasks = parseTasksFromMd(tasksContent)
+const analyzedTasks = []
+
+output(`\n📊 Analyzing ${tasks.length} tasks...`)
+
+for (const task of tasks) {
+  // 1. Complexity scoring (1-10)
+  const complexity = calculateComplexity(task)
+
+  // 2. Dependency detection
+  const dependencies = detectDependencies(task, tasks)
+
+  // 3. Risk assessment
+  const risk = assessRisk(task, complexity)
+  risk.mitigation = generateMitigation(risk, task)
+
+  // 4. Research requirements
+  const research = detectResearchNeeds(task)
+
+  // 5. Subtask breakdown (if needed)
+  const needsBreakdown = needsSubtaskBreakdown(task, complexity)
+  const subtasks = needsBreakdown ? generateSubtasks(task) : []
+
+  // 6. Priority ranking
+  const priority = calculatePriority(task, { complexity, dependencies, risk })
+
+  analyzedTasks.push({
+    ...task,
+    complexity: {
+      score: complexity,
+      level: getComplexityLevel(complexity),
+      factors: explainComplexity(task, complexity)
+    },
+    dependencies,
+    risk: {
+      ...risk,
+      mitigation
+    },
+    research,
+    subtasks,
+    priority: {
+      score: priority,
+      label: getPriorityLabel(priority),
+      reason: explainPriority(task, priority)
+    },
+    estimatedTime: {
+      original: task.estimatedTime,
+      adjusted: adjustTimeForComplexity(task.estimatedTime, complexity, risk),
+      buffer: calculateBuffer(complexity, risk)
+    }
+  })
+}
+
+// Sort by priority (CRITICAL → HIGH → MEDIUM → LOW)
+analyzedTasks.sort((a, b) => b.priority.score - a.priority.score)
+
+// Store for phases.md generation
+const taskAnalysis = {
+  tasks: analyzedTasks,
+  summary: {
+    total: analyzedTasks.length,
+    priority: {
+      critical: analyzedTasks.filter(t => t.priority.label === 'CRITICAL').length,
+      high: analyzedTasks.filter(t => t.priority.label === 'HIGH').length,
+      medium: analyzedTasks.filter(t => t.priority.label === 'MEDIUM').length,
+      low: analyzedTasks.filter(t => t.priority.label === 'LOW').length
+    },
+    risk: {
+      high: analyzedTasks.filter(t => t.risk.level === 'HIGH').length,
+      medium: analyzedTasks.filter(t => t.risk.level === 'MEDIUM').length,
+      low: analyzedTasks.filter(t => t.risk.level === 'LOW').length
+    },
+    researchRequired: analyzedTasks.filter(t => t.research?.required).length,
+    subtasksExpanded: analyzedTasks.filter(t => t.subtasks.length > 0).length,
+    averageComplexity: (analyzedTasks.reduce((sum, t) => sum + t.complexity.score, 0) / analyzedTasks.length).toFixed(1)
+  }
+}
+```
+
+**Output analysis report:**
+```
+✅ Task Analysis Complete
+
+📊 Summary:
+   Total tasks: 8
+   Expanded to: 15 subtasks
+
+📈 Priority Distribution:
+   🔴 CRITICAL: 2 tasks (Login, Payment)
+   🟠 HIGH: 3 tasks (User Profile, API endpoints)
+   🟡 MEDIUM: 2 tasks (Email notifications)
+   🟢 LOW: 1 task (Documentation)
+
+⚠️ Risk Assessment:
+   🚨 HIGH risk: 2 tasks (Payment integration, Auth system)
+      → Mitigation: TDD required, security checklist
+   ⚠️ MEDIUM risk: 3 tasks
+   ✅ LOW risk: 3 tasks
+
+🔬 Research Required: 2 tasks
+   - React Query v5 migration (15 min)
+   - Stripe payment best practices (15 min)
+
+📦 Subtask Breakdown: 3 tasks expanded
+   - Login system → 3 subtasks (UI, API, Integration)
+   - User CRUD → 4 subtasks (Create, Read, Update, Delete)
+
+⏱️ Time Estimates:
+   Original: 6.5 hours
+   Adjusted: 9.2 hours (+41% buffer for complexity/risk)
+   Average complexity: 5.8/10
+```
+
+---
+
 ### Step 4: Select Template
 
 **Selection logic:**
@@ -145,18 +326,66 @@ For each phase, add TDD metadata:
 
 ---
 
-**Generate phases.md:**
+**🆕 ENHANCED v1.3.0: Inject Task Analysis Metadata**
+
+```typescript
+// Add research phases (if needed)
+const researchPhases = []
+analyzedTasks.filter(t => t.research?.required).forEach((task, i) => {
+  researchPhases.push({
+    id: `research-${i + 1}`,
+    phaseNumber: `0.${i + 1}`, // Before implementation
+    name: `Research: ${task.research.category}`,
+    agent: 'integration',
+    estimatedMinutes: task.research.estimatedTime,
+    task: task,
+    queries: task.research.queries,
+    reason: task.research.reason
+  })
+})
+
+// Merge with existing phases (research goes first)
+const allPhases = [...researchPhases, ...phaseSections]
+```
+
+**Generate enhanced phases.md:**
 ```markdown
 # Agent Workflow: {CHANGE_ID} {Change Title}
 
 > **Auto-generated by `/csetup {change-id}`**
 > **Template:** {template-name} ({total-phases} phases)
 > **Reason:** {detection-reason}
-> **Source:** proposal.md + tasks.md + design.md
+> **Source:** proposal.md + tasks.md (TaskMaster-analyzed)
 > **Last updated:** {current-datetime}
 
 ---
 
+## 📊 Task Analysis Summary (v1.3.0 - TaskMaster-style)
+
+**Analyzed Tasks:** {taskAnalysis.summary.total}
+**Average Complexity:** {taskAnalysis.summary.averageComplexity}/10
+
+**Priority Distribution:**
+- 🔴 CRITICAL: {taskAnalysis.summary.priority.critical}
+- 🟠 HIGH: {taskAnalysis.summary.priority.high}
+- 🟡 MEDIUM: {taskAnalysis.summary.priority.medium}
+- 🟢 LOW: {taskAnalysis.summary.priority.low}
+
+**Risk Assessment:**
+- 🚨 HIGH risk: {taskAnalysis.summary.risk.high} tasks
+- ⚠️ MEDIUM risk: {taskAnalysis.summary.risk.medium} tasks
+- ✅ LOW risk: {taskAnalysis.summary.risk.low} tasks
+
+**Research Phases:** {taskAnalysis.summary.researchRequired} added
+**Subtasks Expanded:** {taskAnalysis.summary.subtasksExpanded} tasks
+
+**Time Estimates:**
+- Original: {calculateOriginalTime(analyzedTasks)} hours
+- Adjusted: {calculateAdjustedTime(analyzedTasks)} hours
+- Buffer: +{calculateTotalBuffer(analyzedTasks)}%
+
+---
+
 ## 📊 Workflow Overview
 
 | Phase | Agent | Type | Est. Time | Status |
@@ -170,15 +399,63 @@ For each phase, add TDD metadata:
 
 ---
 
-{phase-section-1}
-
 ---
 
-{phase-section-2}
+## 🔬 Research Phases (if applicable)
+
+${researchPhases.map((phase, i) => `
+### Phase 0.${i + 1}: ${phase.name}
+
+**Agent:** integration
+**Estimated Time:** ${phase.estimatedMinutes} min
+**Type:** Research
+
+**Reason:** ${phase.reason}
+
+**Research Queries:**
+${phase.queries.map(q => `- ${q}`).join('\n')}
+
+**Instructions:**
+1. Use WebSearch or Context7 to gather information
+2. Summarize findings in research notes
+3. Update task context with relevant insights
+4. Proceed to implementation with informed decisions
+
+---
+`).join('')}
 
 ---
 
-... (all phases)
+## 🚀 Implementation Phases
+
+${allPhases.map((phaseSection, index) => {
+  // Find matching task from analyzedTasks
+  const matchingTask = analyzedTasks.find(t =>
+    phaseSection.toLowerCase().includes(t.description.toLowerCase().split(' ')[0])
+  )
+
+  let metadata = ''
+  if (matchingTask) {
+    metadata = `
+**Task Metadata (TaskMaster Analysis):**
+- **Complexity:** ${matchingTask.complexity.score}/10 (${matchingTask.complexity.level})
+  - Factors: ${matchingTask.complexity.factors.join(', ')}
+- **Priority:** ${matchingTask.priority.label} (${matchingTask.priority.score}/100)
+  - ${matchingTask.priority.reason}
+- **Risk:** ${matchingTask.risk.level}
+${matchingTask.risk.mitigation.length > 0 ? `  - Mitigation:\n${matchingTask.risk.mitigation.map(m => `    - ${m}`).join('\n')}` : ''}
+- **Dependencies:**
+  - Blocked by: ${matchingTask.dependencies.blockedBy.length > 0 ? matchingTask.dependencies.blockedBy.join(', ') : 'None'}
+  - Blocks: ${matchingTask.dependencies.blocks.length > 0 ? matchingTask.dependencies.blocks.join(', ') : 'None'}
+  - Can parallelize with: ${matchingTask.dependencies.parallelizable.length > 0 ? matchingTask.dependencies.parallelizable.slice(0, 3).join(', ') : 'None'}
+- **Time Estimate:** ${matchingTask.estimatedTime.original} min → ${matchingTask.estimatedTime.adjusted} min (+${matchingTask.estimatedTime.buffer}% buffer)
+
+${matchingTask.subtasks.length > 0 ? `**Subtasks:**\n${matchingTask.subtasks.map(st => `  - ${st.id}: ${st.description} (${st.estimatedTime} min)`).join('\n')}\n` : ''}
+`
+  }
+
+  return `${phaseSection}\n${metadata}`
+}).join('\n---\n\n')}
 
 ---
 
@@ -237,6 +514,41 @@ const projectTech = Read('.claude/contexts/domain/project/tech-stack.md')
 // Detect additional tech from proposal/tasks
 const additionalTech = detectAdditionalTech(proposalContent, tasksContent)
 
+// 🆕 Load design info (if UI work)
+let designInfo = ''
+if (hasFrontend) {
+  const tokensPath = 'design-system/STYLE_TOKENS.json'
+
+  if (fileExists(tokensPath)) {
+    const tokens = JSON.parse(Read(tokensPath))
+
+    designInfo = `
+## 🎨 Design System (Context Optimization v1.2.0)
+
+**Design Files (Token-Efficient):**
+- STYLE_TOKENS.json: \`design-system/STYLE_TOKENS.json\` (~500 tokens)
+- STYLE_GUIDE.md: \`design-system/STYLE_GUIDE.md\` (~5000 tokens, load selectively)
+
+**Key Design Tokens:**
+- Primary Color: ${tokens.tokens.colors.primary.DEFAULT}
+- Component Library: ${tokens.component_library.name}
+- Spacing Scale: ${tokens.tokens.spacing.scale.join(', ')}px
+- Shadows: ${Object.keys(tokens.tokens.shadows).slice(0, 5).join(', ')}
+
+**Agent Loading (STEP 0.5 for uxui-frontend):**
+1. Read: STYLE_TOKENS.json (~500 tokens) ✅
+2. Optional: STYLE_GUIDE.md (selective sections ~2K tokens)
+3. Report: Design tokens extracted
+
+**Critical Rules:**
+- ❌ NO hardcoded colors (text-gray-500)
+- ✅ USE theme tokens (text-foreground/70)
+- ❌ NO arbitrary spacing (p-5)
+- ✅ USE spacing scale (p-4, p-6)
+`
+  }
+}
+
 // Replace placeholders
 contextTemplate = contextTemplate
   .replace('{CHANGE_ID}', changeId)
@@ -249,6 +561,7 @@ contextTemplate = contextTemplate
   .replace('{ADDITIONAL_TECH_LIST}', generateAdditionalTechList(additionalTech))
   .replace('{CURRENT_PHASE}', templateData.phases[0])
   .replace('{STATUS}', 'pending')
+  .replace('{DESIGN_SYSTEM}', designInfo) // 🆕 Add design section
 ```
 
 Write to: `openspec/changes/{change-id}/.claude/context.md`