@champpaba/claude-agent-kit 1.7.1 → 2.0.0

package/.claude/CLAUDE.md

@@ -1,46 +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
-
----
-
-## 📁 File Naming Conventions (OpenSpec + Template)
-
-> **IMPORTANT:** Avoid confusion between OpenSpec files and Template files
-
-### OpenSpec Files (from [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec))
-
-| File | Purpose | When to Read |
-|------|---------|--------------|
-| `proposal.md` | WHY - Goals, scope, rationale | Phase planning |
-| `tasks.md` | WHAT - Implementation checklist | Task tracking |
-| `design.md` | **Technical/Architecture decisions** (optional) | Backend/Database phases |
-| `specs/` | Delta specs (ADDED/MODIFIED/REMOVED) | Requirement validation |
-
-### Template Files (from claude-multi-agent-template)
-
-| File | Purpose | When to Read |
-|------|---------|--------------|
-| `STYLE_GUIDE.md` | **Visual design** (colors, typography, spacing) | UI/Frontend phases |
-| `STYLE_TOKENS.json` | Lightweight design tokens (~500 tokens) | Quick UI reference |
-| `page-plan.md` | UI component layout + content strategy | uxui-frontend agent |
-| `phases.md` | Execution plan with agent assignments | All phases |
-| `flags.json` | Progress tracking | All phases |
-
-### Key Distinction
-
-```
-OpenSpec design.md    = Technical Architecture (data flow, API structure, system design)
-Template STYLE_GUIDE  = Visual Design (colors, fonts, spacing, component styles)
-```
-
-**Agents should read BOTH when relevant:**
-- `uxui-frontend` → STYLE_GUIDE.md (visual) + design.md (if has UI architecture)
-- `backend` → design.md (API/data architecture)
-- `database` → design.md (data models, relationships)
-- `frontend` → STYLE_GUIDE.md (visual) + design.md (API contracts)
+> **Template Version:** 2.0.0 - Universal Multi-Agent Template
+> **Latest:** Design System v2.0 - Interactive setup, theme selection, selective pattern loading, page type detection
 
 ---
 
@@ -65,14 +27,15 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ## 📖 Quick Navigation
 
-**Design/UI:**
-- `/designsetup` - Auto-generate style guide from reference/codebase/AI
-- `design-system/STYLE_TOKENS.json` - **NEW!** Lightweight design tokens (~500 tokens) ✨
-- `design-system/STYLE_GUIDE.md` - Full style guide (17 sections, ~5000 tokens)
-- `@/.claude/lib/document-loader.md` - **NEW!** Token-efficient loading patterns ✨
+**Design/UI (v2.0.0):**
+- `/extract https://site.com` - **NEW!** Extract design from reference sites (multi-URL, style detection)
+- `/designsetup @prd.md` - **ENHANCED!** Interactive design setup (3-round loop, theme selection)
+- `design-system/tokens.json` - **v2.0!** Design tokens with style/theme/animations (~800 tokens) ✨
+- `design-system/patterns/*.md` - **NEW!** Selective code patterns (buttons, cards, forms, animations, decorations)
+- `design-system/STYLE_GUIDE.md` - Human-readable guide (no code, ~150 lines)
+- `.claude/extractions/*.json` - **NEW!** Extracted site data
+- `@/.claude/lib/document-loader.md` - Token-efficient loading patterns
 - `@/.claude/contexts/design/index.md` (General design principles - fallback)
-- `@/.claude/contexts/design/box-thinking.md` (Layout analysis)
-- `@/.claude/contexts/patterns/ui-component-consistency.md` (Visual consistency)
 
 **Development:**
 - `@/.claude/contexts/patterns/task-classification.md` (Agent selection guide)
@@ -84,15 +47,18 @@ 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)
+- `/extract https://site.com` - Extract design from reference sites
+- `/designsetup @prd.md` - Interactive design system setup
 - `/psetup` - One-time project setup (detect tech stack, generate best practices)
 - `/agentsetup` - Auto-detect tech stack and generate best practices
 
-**Page Planning (UI Tasks):**
-- `/pageplan @prd.md @brief.md` - **ENHANCED v1.4.0!** Generate page structure & conversion-optimized content
+**Page Planning (UI Tasks) - v2.0.0:**
+- `/pageplan @prd.md @brief.md` - **ENHANCED v2.0.0!** Generate page structure with auto page type detection
 - Output: `openspec/changes/{id}/page-plan.md` (component reuse, buyer avatar, conversion copy, asset checklist)
-- **NEW:** Buyer avatar analysis (Eugene Schwartz framework) for marketing pages
-- **NEW:** Conversion-optimized content (pain → promise → CTA)
+- **NEW v2.0.0:** Auto-detects page type (landing/dashboard/auth) from proposal.md/tasks.md
+- **NEW v2.0.0:** Reads tokens.json for style/theme/animations
+- **NEW v2.0.0:** Loads patterns/*.md selectively based on page type
+- Buyer avatar analysis (Eugene Schwartz framework) for marketing pages only
 - Used by: uxui-frontend agent (auto-reads in STEP 0.5)
 
 **OpenSpec Multi-Agent Workflow:**
@@ -110,13 +76,12 @@ Universal, framework-agnostic template for AI-assisted development.
 - Level 2: `.claude/contexts/domain/{project}/README.md` (Project Overview)
 - Level 3: `.claude/contexts/domain/{project}/best-practices/index.md` (Best Practices Registry)
 
-**Implementation Logic:**
+**🆕 Implementation Logic (v1.1.0):**
 - `@/.claude/lib/README.md` - Implementation logic overview
-- `@/.claude/lib/agent-executor.md` - Agent retry & escalation logic (used by /cdev) + 🆕 Incremental testing execution (v1.6.0)
+- `@/.claude/lib/agent-executor.md` - Agent retry & escalation logic (used by /cdev)
 - `@/.claude/lib/tdd-classifier.md` - TDD classification logic (used by /csetup)
-- `@/.claude/lib/task-analyzer.md` - 🆕 Task analysis with milestone generation (v1.6.0)
-- `@/.claude/lib/flags-updater.md` - Progress tracking protocol (Main Claude updates flags.json)
-- `@/.claude/lib/agent-router.md` - Mandatory agent routing rules (enforce delegation)
+- `@/.claude/lib/flags-updater.md` - 🆕 Progress tracking protocol (Main Claude updates flags.json)
+- `@/.claude/lib/agent-router.md` - 🆕 Mandatory agent routing rules (enforce delegation)
 - `@/.claude/contexts/patterns/agent-discovery.md` - Shared agent discovery flow
 
 ---
@@ -133,47 +98,85 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 🎨 Design System / Style Guide Generation
+## 🎨 Design System v2.0.0 (Interactive Setup)
 
 **→ See:** `@/.claude/lib/detailed-guides/design-system.md` for complete guide
 
 **Quick Summary:**
-- `/designsetup` auto-detects project context with **3 smart paths**: Reference design → Brownfield (reverse engineering) → Greenfield (AI-generated)
-- Generates comprehensive `design-system/STYLE_GUIDE.md` (17 sections: colors, typography, spacing, components, etc.)
-- **uxui-frontend agent** auto-reads style guide (Priority #1) or falls back to general design principles
-- Ensures visual consistency, prevents duplicates, enforces accessibility
+- `/extract https://site.com` → Extracts design from reference sites (multi-URL, style detection)
+- `/designsetup @prd.md` → Interactive 3-round loop with theme selection
+- Generates:
+  - `tokens.json` - Design tokens with style/theme/animations (~800 tokens) **FOR AGENTS**
+  - `patterns/*.md` - Code patterns (buttons, cards, forms, animations, decorations) **SELECTIVE LOADING**
+  - `STYLE_GUIDE.md` - Human-readable guide (no code, ~150 lines) **FOR HUMANS**
+
+**New Features in v2.0.0:**
+- 🎯 **Style Detection:** Neo-Brutalism, Minimalist, Glassmorphism, Modern SaaS, etc.
+- 🎭 **Theme Selection:** AI recommends themes based on project context
+- 🎬 **Animation Support:** GSAP, ScrollTrigger, Framer Motion detection
+- 📜 **Scroll Patterns:** stacking-cards, parallax, fade-in, slide-in
+- 🖼️ **Decorative Direction:** USE/AVOID elements for theme consistency
+
+**Flow:**
+```
+/extract → .claude/extractions/*.json
+           ↓
+/designsetup → tokens.json + patterns/*.md + STYLE_GUIDE.md
+           ↓
+/pageplan → page-plan.md (reads tokens.json, auto-detects page type)
+           ↓
+/csetup → phases.md (reads page-plan.md)
+           ↓
+/cdev → uxui-frontend (reads tokens.json + patterns/*.md selectively)
+```
 
 ---
 
-## ⚡ Context Optimization (v1.2.0)
+## ⚡ Context Optimization (v2.0.0)
 
 **→ See:** `@/.claude/lib/detailed-guides/context-optimization.md` for complete guide
 
 **Quick Summary:**
 - **Problem:** 20K tokens wasted (STYLE_GUIDE.md read 4x by different commands/agents)
-- **Solution:** 3-tier loading → STYLE_TOKENS.json (500 tokens) → design-context.md (1K) → STYLE_GUIDE.md (5K, selective)
-- **Result:** 70% token reduction (~4.7K total), 3-4x faster, maintained quality
+- **Solution (v2.0.0):**
+  - `tokens.json` (~800 tokens) - **PRIMARY: All agents read this**
+  - `patterns/*.md` - **SELECTIVE: Load based on page type**
+  - `STYLE_GUIDE.md` (~150 lines) - **HUMAN-READABLE: No code**
+- **Page Type Detection:**
+  - Landing/Marketing → Full patterns (buttons, cards, scroll-animations, decorations)
+  - Dashboard/Admin → Minimal patterns (buttons, cards, forms)
+  - Auth → Clean patterns (buttons, forms)
+- **Result:** 84% token reduction (~800 tokens vs ~5000), 4x faster, theme consistency
 
 ---
 
-## 📋 Page Planning System (v1.4.0 - Conversion-Optimized)
+## 📋 Page Planning System (v2.0.0 - Auto Page Type Detection)
 
 **→ See:** `@/.claude/lib/detailed-guides/page-planning.md` for complete guide
 
 **Quick Summary:**
-- **Problem:** Agents duplicate components (Navbar 3x), use random colors, lorem ipsum content, **generic copy that doesn't convert**
+- **Problem:** Agents duplicate components (Navbar 3x), use random colors, lorem ipsum content, wrong decorations for page type
 - **Solution:** `/pageplan @prd.md @brief.md` → Generates `openspec/changes/{id}/page-plan.md` with:
+  - **Auto page type detection** 🆕 (landing/dashboard/auth from proposal.md/tasks.md)
+  - **tokens.json integration** 🆕 (style, theme, animations, decorative direction)
+  - **Selective pattern loading** 🆕 (only load patterns relevant to page type)
   - Component reuse plan ✅ (prevent duplicates)
-  - **Buyer avatar analysis** 🆕 (Eugene Schwartz framework)
-  - **Conversion-optimized content** 🆕 (pain → promise → CTA)
+  - Buyer avatar analysis (Eugene Schwartz framework) **for marketing pages only**
+  - Conversion-optimized content (pain → promise → CTA) **for marketing pages only**
   - Asset checklist ✅ (performance-optimized)
-- **Benefits:**
-  - Prevents duplicates, ensures design consistency
-  - **Real content from PRD with conversion psychology** 🆕
-  - **2-5x better conversion rates** (pain-based headlines vs generic)
-  - 25% faster (search + copy strategy done once upfront)
-- **Use for:** Landing pages, marketing sites, product pages (auto-detects marketing vs dashboard)
-- **Skips for:** Dashboards, admin panels, backend/database work (no buyer avatar needed)
+
+**Page Type Handling:**
+| Page Type | Decorations | Scroll Anims | Buyer Avatar | Patterns Loaded |
+|-----------|-------------|--------------|--------------|-----------------|
+| Landing/Marketing | ✅ Full | ✅ Enabled | ✅ Enabled | buttons, cards, scroll-anims, decorations |
+| Dashboard/Admin | ❌ Minimal | ❌ Disabled | ❌ Skipped | buttons, cards, forms |
+| Auth (Login/Register) | ❌ None | ❌ Disabled | ❌ Skipped | buttons, forms |
+
+**Benefits:**
+- Auto-detects page type from context (no manual config)
+- Theme + decorations from tokens.json applied consistently
+- 84% token reduction (selective pattern loading)
+- Conversion-optimized only where needed (marketing pages)
 
 ---
 
@@ -189,20 +192,6 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 🔄 Incremental Testing (v1.6.0)
-
-**→ See:** `@/.claude/lib/detailed-guides/incremental-testing.md` for complete guide
-
-**Quick Summary:**
-- **Problem:** All-or-nothing testing → bugs found at scale (1000 records) → hard to debug, expensive rework
-- **Solution:** Milestone-based validation → Test 1 record → 10 → errors → scale → catch bugs early (75% faster debug)
-- **3 Patterns:** Backend API (4 milestones), Complex Form (3 milestones), Database Migration (3 milestones)
-- **Round-based Retry:** 2 attempts → Main Claude intervention (hints vs ask human) → new round (unlimited)
-- **Detection:** Auto-triggered for Risk=HIGH OR (Risk=MEDIUM + Complexity≥7) OR External API OR Data-intensive (~20-30% of tasks)
-- **Benefits:** 60-70% rework reduction, 40-50% net speedup, 90% success rate with progressive confidence
-
----
-
 ## 🤖 Agent System
 
 **→ See:** `@/.claude/lib/detailed-guides/agent-system.md` for complete guide

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]