@champpaba/claude-agent-kit 1.7.1 → 1.8.0

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 1.7.1 - Universal Multi-Agent Template (Opus 4.5)
-> **Latest:** Incremental Testing - Milestone-based validation for high-risk tasks with round-based retry
+> **Template Version:** 1.8.0 - Universal Multi-Agent Template (Opus 4.5)
+> **Latest:** Token Optimization - Removed documentation/report phases, verbose terminal output instead
 
 ---
 
@@ -57,8 +57,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - ✅ Domain-Specific Support (add your business logic)
 
 **What's NOT Included:**
-- ❌ Framework patterns → Generated dynamically via `/agentsetup`
-- ❌ Package managers → Detected by `/agentsetup`
+- ❌ Framework patterns → Generated dynamically via `/csetup`
+- ❌ Package managers → Auto-detected by `/csetup`
 - ❌ Spec frameworks → Optional (OpenSpec, BMAD, SpecKit)
 
 ---
@@ -84,9 +84,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/contexts/patterns/frontend-component-strategy.md`
 
 **Project Setup:**
-- `/designsetup` - **NEW!** Auto-generate style guide (reference → codebase → AI)
-- `/psetup` - One-time project setup (detect tech stack, generate best practices)
-- `/agentsetup` - Auto-detect tech stack and generate best practices
+- `/designsetup` - Auto-generate style guide (reference → codebase → AI)
+- `/csetup` - **v1.8.0:** Now auto-detects tech stack + generates best practices (replaces /psetup, /agentsetup)
 
 **Page Planning (UI Tasks):**
 - `/pageplan @prd.md @brief.md` - **ENHANCED v1.4.0!** Generate page structure & conversion-optimized content
@@ -102,7 +101,7 @@ Universal, framework-agnostic template for AI-assisted development.
 - `/cstatus {change-id}` - Quick progress status for a change
 
 **Best Practices (Dynamic):**
-- `.claude/contexts/domain/{project}/best-practices/` (generated by `/agentsetup`)
+- `.claude/contexts/domain/project/best-practices/` (auto-generated by `/csetup`)
 - Framework-specific guidelines from Context7 MCP
 
 **Indexing (3 Levels):**
@@ -121,15 +120,20 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 📚 Best Practices System
-
-**→ See:** `@/.claude/lib/detailed-guides/best-practices-system.md` for complete guide
+## 📚 Best Practices System (v1.8.0)
 
 **Quick Summary:**
-- Run `/agentsetup` → Auto-detects tech stack → Queries Context7 → Generates framework-specific best practices
-- Files created in `.claude/contexts/domain/{project}/best-practices/` (React, Next.js, Prisma, etc.)
-- Agents auto-discover via 3-level indexing (domain → project → best-practices)
-- Enforces code quality with framework-specific patterns
+- `/csetup` **auto-detects tech stack** from: package.json → design.md → proposal/tasks (3 sources)
+- **Auto-generates best practices** from Context7 MCP (React, Next.js, Prisma, etc.)
+- Files created in `.claude/contexts/domain/project/best-practices/`
+- **Agents MUST read** best practices before coding (validated by agent-executor)
+- `/cdev` **injects** relevant best-practices paths into agent prompts
+
+**Flow:**
+```
+/csetup → detect stack → query Context7 → generate best-practices
+/cdev   → inject paths into prompt → agent reads → validation checks
+```
 
 ---
 

package/.claude/agents/01-integration.md

@@ -526,7 +526,7 @@ Frontend expects `email` but backend doesn't return it.
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### Validation Standards
 - ✅ Read ACTUAL code files (don't guess or assume)
@@ -638,14 +638,18 @@ Found: 3 endpoints
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code/config files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO INTEGRATION_REPORT.md, CONTRACT_ANALYSIS.md, API_CONTRACTS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with validation results
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ---

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

@@ -922,14 +922,19 @@ Return to Orchestrator:
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
 
-**Quick Rule:**
-- ❌ **NEVER** create .md documentation files (README, DOCS, GUIDE, etc.)
-- ✅ **ALWAYS** report results as verbose text output in final message
-- Exception: ONLY when user explicitly requests documentation
+**Simple Rule:** Only create **actual component/style files**. No reports, summaries, or temp files.
+
+**Quick Reference:**
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with component list and files created
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 

package/.claude/agents/03-test-debug.md

@@ -431,15 +431,19 @@ Recommendation:
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code/test files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO TEST_REPORT.md, DEBUG_LOG.md, TEST_RESULTS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with test results (passed/failed/coverage)
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -451,7 +455,7 @@ Recommendation:
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### Testing Standards
 - ✅ Run tests automatically (no manual testing)

package/.claude/agents/04-frontend.md

@@ -561,15 +561,19 @@ test('failed login shows error message', async () => {
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO README.md, IMPLEMENTATION_GUIDE.md, API_DOCS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with integration results
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -581,7 +585,7 @@ test('failed login shows error message', async () => {
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### TDD Compliance
 - ✅ Check `tdd_required` flag from Orchestrator

package/.claude/agents/05-backend.md

@@ -579,14 +579,19 @@ Response: { token: string, user: { id, email, name } }
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
 
-**Quick Rule:**
-- ❌ **NEVER** create .md documentation files (README, API_DOCS, etc.)
-- ✅ **ALWAYS** report results as verbose text output in final message
-- Exception: ONLY when user explicitly requests documentation
+**Simple Rule:** Only create **actual code files**. No reports, summaries, or temp files.
+
+**Quick Reference:**
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with endpoints created
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 

package/.claude/agents/06-database.md

@@ -620,15 +620,19 @@ users = await db.execute(
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual schema/migration files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO SCHEMA_DOCUMENTATION.md, DATABASE_GUIDE.md, MIGRATION_GUIDE.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with schema changes and migrations
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -640,7 +644,7 @@ users = await db.execute(
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### TDD Compliance
 - ✅ Check `tdd_required` flag from Orchestrator

package/.claude/commands/cdev.md

@@ -94,7 +94,7 @@ See: `.claude/lib/agent-executor.md` for full implementation
 ```typescript
 // Step 4: Invoke Agent with Retry & Validation
 
-// 4.1: Build agent prompt (with design reference - Context Optimization v1.2.0)
+// 4.1: Build agent prompt (with design reference + best practices - v1.8.0)
 function buildAgentPrompt(phase, changeContext) {
   let prompt = `
 # Phase ${phase.phase_number}: ${phase.name}
@@ -108,7 +108,56 @@ ${changeContext.tasks}
 ${phase.instructions}
 `
 
-  // 🆕 Add design reference for uxui-frontend agent (not full content!)
+  // 🆕 v1.8.0: Add best-practices reference for ALL agents
+  const bpDir = '.claude/contexts/domain/project/best-practices/'
+  if (fileExists(bpDir)) {
+    const bpFiles = listFiles(bpDir).filter(f => f.endsWith('.md') && f !== 'index.md')
+
+    // Map agent type to relevant best-practices
+    const agentBpMapping = {
+      'uxui-frontend': ['react', 'nextjs', 'vue', 'tailwind'],
+      'frontend': ['react', 'nextjs', 'vue', 'typescript'],
+      'backend': ['express', 'fastapi', 'django', 'prisma', 'drizzle'],
+      'database': ['prisma', 'drizzle', 'postgres', 'mongodb'],
+      'test-debug': ['vitest', 'jest', 'playwright'],
+      'integration': ['typescript'] // minimal
+    }
+
+    const relevantTechs = agentBpMapping[phase.agent] || []
+    const relevantFiles = bpFiles.filter(f =>
+      relevantTechs.some(tech => f.toLowerCase().includes(tech))
+    )
+
+    if (relevantFiles.length > 0) {
+      prompt += `
+
+---
+
+## 📚 Best Practices (MANDATORY - STEP 0)
+
+**YOU MUST READ these files before writing ANY code:**
+
+${relevantFiles.map(f => `
+### ${f.replace('.md', '')}
+\`\`\`
+Read: ${bpDir}${f}
+\`\`\`
+`).join('')}
+
+**After reading, REPORT:**
+\`\`\`
+✅ Best Practices Loaded
+   ${relevantFiles.map(f => `- ${f.replace('.md', '')} ✓`).join('\n   ')}
+\`\`\`
+
+**If you skip this, your work will be REJECTED!**
+
+---
+`
+    }
+  }
+
+  // Add design reference for uxui-frontend agent (not full content!)
   if (phase.agent === 'uxui-frontend') {
     const tokensPath = 'design-system/STYLE_TOKENS.json'
     const styleGuidePath = 'design-system/STYLE_GUIDE.md'
@@ -392,11 +441,65 @@ output(`   ⏱️  ${formatDuration(flags.meta.time_remaining_estimate)} remaini
 
 // 4. Check next phase
 if (flags.ready_to_archive) {
-  output('\n✅ All phases complete! Ready to archive.')
-  output(`\nNext steps:`)
-  output(`1. Review: /cview ${changeId}`)
-  output(`2. Update tasks.md (mark all [x])`)
-  output(`3. Archive: openspec archive ${changeId}`)
+  // 🆕 v1.2.0: Verbose Summary Output (replaces documentation/report phases)
+  output(`\n`)
+  output(`╔════════════════════════════════════════════════════════════╗`)
+  output(`║           ✅ CHANGE COMPLETED SUCCESSFULLY                 ║`)
+  output(`╚════════════════════════════════════════════════════════════╝`)
+  output(``)
+  output(`📦 Change: ${changeId}`)
+  output(`📋 Template: ${flags.template} (${flags.meta.total_phases} phases)`)
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`📊 EXECUTION SUMMARY`)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(``)
+  output(`⏱️  Time:`)
+  output(`   • Estimated: ${formatDuration(flags.meta.total_estimated_minutes)}`)
+  output(`   • Actual:    ${formatDuration(flags.meta.total_actual_minutes)}`)
+  output(`   • Variance:  ${calculateVariance(flags.meta)}`)
+  output(``)
+  output(`📈 Phases Completed: ${flags.meta.completed_phases}/${flags.meta.total_phases}`)
+
+  // List all phases with status
+  Object.entries(flags.phases).forEach(([phaseId, phase]) => {
+    const status = phase.status === 'completed' ? '✅' :
+                   phase.status === 'skipped' ? '⏭️' : '❌'
+    const time = phase.actual_minutes ? `(${phase.actual_minutes}m)` : ''
+    output(`   ${status} ${phase.phase_number}. ${phaseId} ${time}`)
+  })
+
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`📁 FILES CREATED/MODIFIED`)
+  output(`═══════════════════════════════════════════════════════════════`)
+
+  // Collect all files from phase outputs
+  const allFiles = collectFilesFromPhases(flags.phases)
+  if (allFiles.created.length > 0) {
+    output(``)
+    output(`✨ Created (${allFiles.created.length}):`)
+    allFiles.created.forEach(f => output(`   • ${f}`))
+  }
+  if (allFiles.modified.length > 0) {
+    output(``)
+    output(`📝 Modified (${allFiles.modified.length}):`)
+    allFiles.modified.forEach(f => output(`   • ${f}`))
+  }
+
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`🚀 NEXT STEPS`)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(``)
+  output(`1. Review changes:  /cview ${changeId}`)
+  output(`2. Test manually:   Verify the implementation works`)
+  output(`3. Mark complete:   Update tasks.md (mark all [x])`)
+  output(`4. Archive:         openspec archive ${changeId}`)
+  output(``)
+  output(`💡 Note: flags.json contains full execution history`)
+  output(`   Path: openspec/changes/${changeId}/.claude/flags.json`)
+  output(``)
 } else {
   const nextPhase = flags.phases[flags.current_phase]
 

package/.claude/commands/csetup.md

@@ -96,6 +96,212 @@ Continue anyway? (yes/no)
 
 ---
 
+### 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!**
+`
+}
+```
+
+---
+
 ### Step 3: Analyze Tasks
 
 **Parse tasks.md content and detect keywords:**
@@ -711,8 +917,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 +990,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 +1020,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!