@champpaba/claude-agent-kit 1.7.1 → 2.0.0

package/.claude/commands/csetup.md

@@ -44,23 +44,54 @@ Read in order:
 
 ---
 
-### Step 2.5: Validate Design System (Context Optimization v1.2.0)
+### Step 2.5: Validate Design System & Page Plan (v2.0.0)
 
-> **New:** Validate design files exist for UI work
+> **Updated v2.0.0:** Validate design files + read page-plan.md if exists
 
 ```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)
 
+let tokens = null
+let pagePlan = null
+let pageType = 'generic'
+
 if (hasFrontend) {
   output(`\n🎨 UI work detected - validating design system...`)
 
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
+  const tokensPath = 'design-system/tokens.json' // v2.0 tokens
   const styleGuidePath = 'design-system/STYLE_GUIDE.md'
+  const pagePlanPath = `openspec/changes/${changeId}/page-plan.md`
 
   const hasTokens = fileExists(tokensPath)
   const hasStyleGuide = fileExists(styleGuidePath)
+  const hasPagePlan = fileExists(pagePlanPath)
+
+  // ========== LOAD tokens.json (v2.0 structure) ==========
+  if (hasTokens) {
+    tokens = JSON.parse(Read(tokensPath))
+    output(`✅ tokens.json Loaded:`)
+    output(`   - Style: ${tokens.style.name}`)
+    output(`   - Theme: ${tokens.theme.name}`)
+    output(`   - Animations: ${tokens.animations.enabled ? 'Enabled' : 'Disabled'}`)
+  }
+
+  // ========== LOAD page-plan.md (if exists) ==========
+  if (hasPagePlan) {
+    pagePlan = Read(pagePlanPath)
+    output(`✅ page-plan.md Found`)
+
+    // Extract page type from page-plan.md
+    const pageTypeMatch = pagePlan.match(/Page Type:\*\*\s*(.*)/i)
+    if (pageTypeMatch) {
+      pageType = pageTypeMatch[1].trim().toLowerCase()
+      output(`   - Page Type: ${pageType}`)
+    }
+  } else {
+    output(`ℹ️ page-plan.md not found (optional)`)
+    output(`   → Run /pageplan first for better component planning`)
+  }
 
   if (!hasTokens || !hasStyleGuide) {
     warn(`
@@ -68,7 +99,8 @@ if (hasFrontend) {
 
 Found:
   ${hasStyleGuide ? '✅' : '❌'} STYLE_GUIDE.md
-  ${hasTokens ? '✅' : '❌'} STYLE_TOKENS.json
+  ${hasTokens ? '✅' : '❌'} tokens.json
+  ${hasPagePlan ? '✅' : '❌'} page-plan.md
 
 This may result in:
   - Inconsistent colors (random hex codes)
@@ -77,7 +109,8 @@ This may result in:
 
 Recommendation:
   1. Run: /designsetup
-  2. Then: /csetup ${changeId}
+  2. Run: /pageplan @prd.md (optional but recommended)
+  3. Then: /csetup ${changeId}
 
 Continue anyway? (yes/no)
     `)
@@ -89,8 +122,215 @@ Continue anyway? (yes/no)
   } else {
     output(`✅ Design System Ready`)
     output(`   - STYLE_GUIDE.md ✓`)
-    output(`   - STYLE_TOKENS.json ✓`)
+    output(`   - tokens.json ✓`)
+    if (hasPagePlan) output(`   - page-plan.md ✓`)
+  }
+}
+```
+
+---
+
+### Step 2.7: Auto-Setup Best Practices (v1.8.0)
+
+> **NEW:** Auto-detect tech stack and generate best-practices (replaces /psetup and /agentsetup)
+
+```typescript
+// 1. Detect tech stack from multiple sources
+output(`\n🔍 Detecting Tech Stack...`)
+
+// Source 1: package.json / requirements.txt (if exists)
+let packageStack = []
+if (fileExists('package.json')) {
+  const pkg = JSON.parse(Read('package.json'))
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  packageStack = Object.keys(deps).filter(d =>
+    ['next', 'react', 'vue', 'express', 'fastapi', 'prisma', 'drizzle', 'vitest', 'jest'].some(k => d.includes(k))
+  )
+  output(`   📦 From package.json: ${packageStack.join(', ') || 'none'}`)
+}
+
+// Source 2: design.md (architecture section)
+let designStack = []
+const designPath = `openspec/changes/${changeId}/design.md`
+if (fileExists(designPath)) {
+  const designContent = Read(designPath)
+  // Look for tech stack section
+  const techMatch = designContent.match(/tech.*stack|architecture|framework/gi)
+  if (techMatch) {
+    designStack = extractTechFromText(designContent)
+    output(`   📐 From design.md: ${designStack.join(', ') || 'none'}`)
+  }
+}
+
+// Source 3: proposal.md + tasks.md (keywords)
+const proposalContent = Read(`openspec/changes/${changeId}/proposal.md`)
+const tasksContent = Read(`openspec/changes/${changeId}/tasks.md`)
+const combined = (proposalContent + ' ' + tasksContent).toLowerCase()
+
+const techDetection = {
+  react: /\b(react|jsx|tsx|use[A-Z]\w+|usestate|useeffect)\b/i,
+  nextjs: /\b(next\.?js|next js|app router|pages router)\b/i,
+  vue: /\b(vue|vuex|pinia|nuxt)\b/i,
+  express: /\b(express\.js|express js|expressjs)\b/i,
+  fastapi: /\b(fastapi|fast api)\b/i,
+  django: /\b(django)\b/i,
+  prisma: /\b(prisma)\b/i,
+  drizzle: /\b(drizzle)\b/i,
+  postgres: /\b(postgres|postgresql)\b/i,
+  mongodb: /\b(mongodb|mongoose)\b/i,
+  tailwind: /\b(tailwind)\b/i,
+  typescript: /\b(typescript)\b/i,
+  vitest: /\b(vitest)\b/i,
+  jest: /\b(jest)\b/i,
+  playwright: /\b(playwright)\b/i
+}
+
+const proposalStack = []
+for (const [tech, pattern] of Object.entries(techDetection)) {
+  if (pattern.test(combined)) {
+    proposalStack.push(tech)
+  }
+}
+output(`   📝 From proposal/tasks: ${proposalStack.join(', ') || 'none'}`)
+
+// Merge all sources (remove duplicates)
+const detectedStack = [...new Set([...packageStack, ...designStack, ...proposalStack])]
+
+// 2. If no stack detected, ask user
+if (detectedStack.length === 0) {
+  output(`\n⚠️ Could not auto-detect tech stack`)
+
+  const answer = await askUserQuestion({
+    questions: [{
+      question: 'What tech stack will you use?',
+      header: 'Stack',
+      options: [
+        { label: 'Next.js + React', description: 'Full-stack React framework' },
+        { label: 'FastAPI + Python', description: 'Python async API' },
+        { label: 'Express + Node', description: 'Node.js backend' },
+        { label: 'Vue + Nuxt', description: 'Vue.js framework' }
+      ],
+      multiSelect: true
+    }]
+  })
+
+  // Parse user selection into detectedStack
+  detectedStack.push(...parseUserStackSelection(answer))
+}
+
+output(`\n✅ Final Tech Stack: ${detectedStack.join(', ')}`)
+
+// 3. Check if best-practices already exist
+const bpDir = '.claude/contexts/domain/project/best-practices/'
+const existingBp = fileExists(bpDir) ? listFiles(bpDir) : []
+
+const missingBp = detectedStack.filter(tech => {
+  return !existingBp.some(f => f.toLowerCase().includes(tech.toLowerCase()))
+})
+
+// 4. Generate missing best-practices from Context7
+if (missingBp.length > 0) {
+  output(`\n📚 Generating Best Practices from Context7...`)
+
+  // Create directory structure if needed
+  if (!fileExists('.claude/contexts/domain/')) {
+    mkdir('.claude/contexts/domain/project/best-practices/')
+  }
+
+  // Context7 library ID mapping
+  const context7Ids = {
+    react: '/facebook/react',
+    nextjs: '/vercel/next.js',
+    vue: '/vuejs/vue',
+    express: '/expressjs/express',
+    fastapi: '/fastapi/fastapi',
+    prisma: '/prisma/prisma',
+    drizzle: '/drizzle-team/drizzle-orm',
+    vitest: '/vitest-dev/vitest',
+    jest: '/jestjs/jest',
+    playwright: '/microsoft/playwright',
+    tailwind: '/tailwindlabs/tailwindcss'
+  }
+
+  for (const tech of missingBp) {
+    const libraryId = context7Ids[tech.toLowerCase()]
+
+    if (libraryId) {
+      output(`   📖 Fetching ${tech} best practices...`)
+
+      // Query Context7 for best practices
+      const docs = await mcp__context7__get-library-docs({
+        context7CompatibleLibraryID: libraryId,
+        topic: 'best practices, common mistakes, anti-patterns, patterns',
+        mode: 'code'
+      })
+
+      // Generate best-practices file
+      const bpContent = generateBestPracticesFile(tech, docs)
+      Write(`.claude/contexts/domain/project/best-practices/${tech}.md`, bpContent)
+
+      output(`   ✅ ${tech}.md generated`)
+    } else {
+      output(`   ⚠️ ${tech} - no Context7 mapping, using universal patterns`)
+    }
+  }
+
+  // Generate index.md
+  generateBestPracticesIndex(detectedStack, changeId)
+  output(`   ✅ index.md generated`)
+
+  // Generate domain/index.md if not exists
+  if (!fileExists('.claude/contexts/domain/index.md')) {
+    generateDomainIndex('project', detectedStack)
+    output(`   ✅ domain/index.md generated`)
   }
+
+  output(`\n✅ Best Practices Setup Complete!`)
+  output(`   Files: ${missingBp.length + 1} generated`)
+  output(`   Location: .claude/contexts/domain/project/best-practices/`)
+} else {
+  output(`\n✅ Best Practices: Already configured (${existingBp.length} files)`)
+}
+
+// 5. Store detected stack in context.md (for agents to reference)
+const stackForContext = {
+  detected: detectedStack,
+  bestPracticesPath: '.claude/contexts/domain/project/best-practices/',
+  files: [...existingBp, ...missingBp.map(t => `${t}.md`)]
+}
+```
+
+**Helper: generateBestPracticesFile()**
+```typescript
+function generateBestPracticesFile(tech: string, context7Docs: string): string {
+  return `# ${tech} Best Practices
+
+> **Source:** Context7 MCP
+> **Generated:** ${new Date().toISOString().split('T')[0]}
+
+---
+
+## ✅ DO (Best Practices)
+
+${extractDos(context7Docs)}
+
+---
+
+## ❌ DON'T (Anti-Patterns)
+
+${extractDonts(context7Docs)}
+
+---
+
+## 🎯 Quick Checklist
+
+Before committing ${tech} code:
+${extractChecklist(context7Docs)}
+
+---
+
+**⚠️ Agents MUST read this file before writing ${tech} code!**
+`
 }
 ```
 
@@ -593,39 +833,66 @@ 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)
+// 🆕 Load design info (if UI work) - v2.0.0
 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}
+if (hasFrontend && tokens) {
+  designInfo = `
+## 🎨 Design System (v2.0.0)
+
+**Design Files:**
+- tokens.json: \`design-system/tokens.json\` (~800 tokens)
+- patterns/: \`design-system/patterns/*.md\` (selective loading)
+- STYLE_GUIDE.md: \`design-system/STYLE_GUIDE.md\` (human-readable, ~150 lines)
+${pagePlan ? `- page-plan.md: \`openspec/changes/${changeId}/page-plan.md\` ✅` : ''}
+
+**Style Direction:**
+- Style: ${tokens.style.name}
+- Theme: ${tokens.theme.name}
+- Feel: ${tokens.style.feel}
+
+**Design Tokens:**
+- Primary Color: ${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
+- Spacing Scale: ${tokens.spacing.scale.join(', ')}px
+- Animations: ${tokens.animations.enabled ? 'Enabled' : 'Disabled'}
+
+**Theme & Decorations:**
+${pageType.includes('landing') || pageType.includes('marketing') ? `
+- Decorations: ✅ Enabled
+- USE: ${tokens.theme.decorative_elements.use.slice(0, 3).join(', ')}
+- AVOID: ${tokens.theme.decorative_elements.avoid.slice(0, 2).join(', ') || '(none)'}
+- Scroll Animations: ✅ Enabled
+` : `
+- Decorations: ❌ Disabled (${pageType} page)
+- Scroll Animations: ❌ Disabled
+`}
+
+**Pattern Files to Load:**
+${pageType.includes('landing') || pageType.includes('marketing') ?
+`- patterns/buttons.md ✅
+- patterns/cards.md ✅
+- patterns/scroll-animations.md ✅
+- patterns/decorations.md ✅` :
+pageType.includes('auth') ?
+`- patterns/buttons.md ✅
+- patterns/forms.md ✅` :
+`- patterns/buttons.md ✅
+- patterns/cards.md ✅
+- patterns/forms.md ✅`}
+
+**Agent Instructions (uxui-frontend STEP 0.5):**
+1. Read: tokens.json (~800 tokens) ✅
+2. Read: page-plan.md (if exists) ✅
+3. Load patterns selectively based on page type
+4. Report: Design tokens + page type 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)
+- ${pageType.includes('landing') ? '✅ Apply decorations from theme' : '❌ Skip decorations for this page type'}
 `
-  }
 }
 
 // Replace placeholders
@@ -711,8 +978,6 @@ function getAgentForPhase(phaseId: string): string {
     'refactor': 'test-debug',
     'regression-tests': 'test-debug',
     'test-coverage': 'test-debug',
-    'documentation': 'integration',
-    'report': 'integration',
     'script-implementation': 'backend',
     'automated-tests': 'test-debug',
     'manual-testing': 'user',
@@ -786,19 +1051,19 @@ Detected:
 Change type: feature
 
 📋 Template selected: frontend-only
-   - Total phases: 11
-   - Estimated time: 3.25 hours
+   - Total phases: 9
+   - Estimated time: 2h 50m
    - Reason: Frontend work detected, no backend/API needed
 
 Generating workflow...
-✓ Generated phases.md (127 lines, 11 phases)
+✓ Generated phases.md (115 lines, 9 phases)
 ✓ Generated flags.json (initialized all phases as pending)
 ✓ Generated context.md (change context with core tech references)
 
 ✅ Change setup complete!
 
 📦 Change: CHANGE-003
-📋 Template: frontend-only (11 phases)
+📋 Template: frontend-only (9 phases)
 🛠️ Detected: Frontend
 
 📁 Files created:
@@ -816,10 +1081,12 @@ Generating workflow...
    Phase 7: Responsive Test (user, 15 min)
    Phase 8: Refactor (test-debug, 20 min)
    Phase 9: Test Coverage (test-debug, 5 min)
-   Phase 10: Documentation (integration, 15 min)
-   Phase 11: Final Report (integration, 10 min)
 
-⏱️ Total estimated time: ~3h 15m
+⏱️ Total estimated time: ~2h 50m
+
+💡 Note: Documentation/Report phases removed in v1.2.0
+   → Verbose summary output in terminal when change completes
+   → flags.json contains full execution history
 
 🚀 Ready to start development!
 

package/.claude/commands/cstatus.md

@@ -1,60 +1,60 @@
----
-name: Change Status
-description: Quick progress status for a change
-category: Multi-Agent
-tags: [status, progress, quick]
----
-
-## Usage
-
-```bash
-/cstatus {change-id}
-```
-
-## What It Does
-
-Shows quick progress summary:
-- Progress percentage with bar
-- Current phase
-- Time spent/remaining
-- Quick stats
-
-## Output Format
-
-```
-📊 CHANGE-{id}: {type} | {template}
-
-Progress: [████████░░] 64% (7/11 phases)
-
-Current Phase: #8 Refactor (test-debug)
-├─ Started: 14:15 (15 minutes ago)
-├─ Estimated: 20 minutes
-└─ Status: in_progress
-
-✅ Completed: 7 phases
-🔄 In Progress: 1 phase
-⏳ Remaining: 3 phases
-
-⏱️ Time:
-├─ Spent: 2h 55min (estimated: 3h 15min)
-├─ Remaining: ~35 minutes
-└─ Efficiency: 111% (ahead of estimate)
-
-📈 Stats:
-├─ Tests: 12 passed, 0 failed (75% coverage)
-├─ Issues: 2 found, 2 fixed, 0 remaining
-└─ Files: 4 created, 2 modified
-
-🎯 Next Steps:
-1. Complete refactoring (20 min)
-2. Test coverage report (5 min)
-3. Documentation (15 min)
-
-Commands:
-→ Detailed view: /cview {change-id}
-→ Continue dev: /cdev {change-id}
-```
-
-## Implementation
-
-Read `openspec/changes/{change-id}/.claude/flags.json` and format output using helper functions.
+---
+name: Change Status
+description: Quick progress status for a change
+category: Multi-Agent
+tags: [status, progress, quick]
+---
+
+## Usage
+
+```bash
+/cstatus {change-id}
+```
+
+## What It Does
+
+Shows quick progress summary:
+- Progress percentage with bar
+- Current phase
+- Time spent/remaining
+- Quick stats
+
+## Output Format
+
+```
+📊 CHANGE-{id}: {type} | {template}
+
+Progress: [████████░░] 64% (7/11 phases)
+
+Current Phase: #8 Refactor (test-debug)
+├─ Started: 14:15 (15 minutes ago)
+├─ Estimated: 20 minutes
+└─ Status: in_progress
+
+✅ Completed: 7 phases
+🔄 In Progress: 1 phase
+⏳ Remaining: 3 phases
+
+⏱️ Time:
+├─ Spent: 2h 55min (estimated: 3h 15min)
+├─ Remaining: ~35 minutes
+└─ Efficiency: 111% (ahead of estimate)
+
+📈 Stats:
+├─ Tests: 12 passed, 0 failed (75% coverage)
+├─ Issues: 2 found, 2 fixed, 0 remaining
+└─ Files: 4 created, 2 modified
+
+🎯 Next Steps:
+1. Complete refactoring (20 min)
+2. Test coverage report (5 min)
+3. Documentation (15 min)
+
+Commands:
+→ Detailed view: /cview {change-id}
+→ Continue dev: /cdev {change-id}
+```
+
+## Implementation
+
+Read `openspec/changes/{change-id}/.claude/flags.json` and format output using helper functions.