@champpaba/claude-agent-kit 1.8.0 → 2.0.1

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 1.8.0 - Universal Multi-Agent Template (Opus 4.5)
-> **Latest:** Token Optimization - Removed documentation/report phases, verbose terminal output instead
+> **Template Version:** 2.0.0 - Claude 4.5 Optimized + Design System v2.0
+> **Latest:** Full template refactored with Claude 4.5 best practices (agents ~65% smaller) + Interactive design setup with theme selection
 
 ---
 
@@ -24,7 +24,7 @@
 | 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 |
+| `tokens.json` | Design tokens with style/theme/animations (~800 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 |
@@ -65,14 +65,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` - Extract design from reference sites (multi-URL, style detection)
+- `/designsetup @prd.md` - Interactive design setup (3-round loop, theme selection)
+- `design-system/tokens.json` - Design tokens with style/theme/animations (~800 tokens) ✨
+- `design-system/patterns/*.md` - Selective code patterns (buttons, cards, forms, animations, decorations)
+- `design-system/STYLE_GUIDE.md` - Human-readable guide (no code, ~150 lines)
+- `.claude/extractions/*.json` - 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,14 +85,17 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/contexts/patterns/frontend-component-strategy.md`
 
 **Project Setup:**
-- `/designsetup` - Auto-generate style guide (reference → codebase → AI)
-- `/csetup` - **v1.8.0:** Now auto-detects tech stack + generates best practices (replaces /psetup, /agentsetup)
+- `/extract https://site.com` - Extract design from reference sites
+- `/designsetup @prd.md` - Interactive design system setup
+- `/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
+**Page Planning (UI Tasks) - v2.0.0:**
+- `/pageplan @prd.md @brief.md` - 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)
+- Auto-detects page type (landing/dashboard/auth) from proposal.md/tasks.md
+- Reads tokens.json for style/theme/animations
+- 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:**
@@ -111,9 +115,9 @@ Universal, framework-agnostic template for AI-assisted development.
 
 **Implementation Logic:**
 - `@/.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) + Incremental testing execution
 - `@/.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/task-analyzer.md` - Task analysis with milestone generation
 - `@/.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
@@ -126,7 +130,7 @@ Universal, framework-agnostic template for AI-assisted development.
 - `/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)
+- **Agents read** best practices before coding (validated by agent-executor)
 - `/cdev` **injects** relevant best-practices paths into agent prompts
 
 **Flow:**
@@ -137,47 +141,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)
 
 ---
 
@@ -214,7 +256,7 @@ Universal, framework-agnostic template for AI-assisted development.
 **Quick Summary:**
 - **6 specialist agents**: integration (validate contracts), uxui-frontend (UI with mock data), test-debug (tests/bugs), frontend (connect UI to API), backend (API endpoints), database (schemas/migrations)
 - **Main Claude's role**: Orchestrator (plan, coordinate, report), NOT implementer (no writing code directly)
-- **Self-check protocol**: MANDATORY checklist before ANY work (detect work type → select agent → delegate)
+- **Self-check protocol**: Checklist before ANY work (detect work type → select agent → delegate)
 - **Agent pre-work**: STEP 0 (project discovery for ALL) + STEP 1-5 (design fundamentals for uxui-frontend only)
 
 **Example workflow:**
@@ -225,6 +267,114 @@ User: "Build login system"
 → Phase 2.5: integration (validate contracts)
 → Phase 3: frontend (connect UI to API)
 → Phase 4: test-debug (tests)
+```
+
+---
+
+## 🆕 v2.0.0: Claude 4.5 Optimization + Design System v2.0
+
+**Based on:** [Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+
+### Claude 4.5 Changes Applied
+
+| Before | After | WHY |
+|--------|-------|-----|
+| "MUST", "WILL BE REJECTED" | Professional tone | Claude 4.5 works better with respectful instructions |
+| "Don't do X", "Never Y" | "Use X instead" | Positive instructions are clearer |
+| Rules without context | Rules with WHY | Claude applies rules more intelligently |
+| Duplicated content (6x) | Shared `_shared/` folder | 83% token reduction |
+| ~1000 lines per agent | ~250-350 lines | 65% smaller |
+
+### New Shared Components
+
+```
+.claude/agents/_shared/
+├── pre-work-checklist.md     # Common validation steps
+├── package-manager.md        # Package manager protocol
+├── documentation-policy.md   # What files to create
+├── agent-boundaries.md       # When to use which agent
+└── README.md                 # Overview
+```
+
+### Token Savings
+
+| Agent | Before | After | Reduction |
+|-------|--------|-------|-----------|
+| uxui-frontend | ~1037 | ~375 | 64% |
+| integration | ~600 | ~210 | 65% |
+| backend | ~700 | ~244 | 65% |
+| database | ~680 | ~273 | 60% |
+| frontend | ~650 | ~296 | 54% |
+| test-debug | ~580 | ~252 | 57% |
+| **Total** | **~4247** | **~1650** | **61%** |
+
+Plus ~500 tokens in shared files = **~2150 total** (was ~4247)
+
+### Best Practices Applied
+
+1. **Tone Calibration** - Professional, direct (not aggressive)
+2. **Action Orientation** - Explicit "Write code" vs "Consider"
+3. **Prevent Overengineering** - Clear boundaries
+4. **Encourage Exploration** - Read before implementing
+5. **Rich Output When Needed** - Specify requirements
+6. **Context for Rules** - Explain WHY
+7. **Positive Instructions** - "Use X" not "Don't Y"
+
+### Additional Files Refactored
+
+Beyond the 6 agent files, these supporting files were also updated:
+
+**Implementation Logic (lib/):**
+| File | Changes |
+|------|---------|
+| `agent-router.md` | Routing table format, removed "CANNOT/forbidden" language |
+| `agent-executor.md` | Professional rejection messages, table format |
+| `context-loading-protocol.md` | WHY explanations, removed "CRITICAL" warnings |
+| `flags-updater.md` | Best practices table, removed "Step 3 CANNOT be skipped" |
+| `document-loader.md` | Table format for DO/DON'T sections |
+| `detailed-guides/agent-system.md` | Compact table format, shared file references |
+
+**Commands:**
+| File | Changes |
+|------|---------|
+| `cdev.md` | WHY context for best practices, softer tone |
+| `csetup.md` | Best Practices / Anti-Patterns format |
+| `pageplan.md` | "Guidelines" instead of "CRITICAL Rules" |
+| `designsetup.md` | "Follow this format" instead of "EXACT format" |
+
+**Patterns (contexts/patterns/):**
+| File | Changes |
+|------|---------|
+| `validation-framework.md` | WHY explanations, removed "🚨" symbols |
+| `error-recovery.md` | "⚠️" instead of "🚨", professional escalation format |
+| `ui-component-consistency.md` | "Common Issues" instead of "Red Flags" |
+| `task-breakdown.md` | Positive framing for incremental approach |
+| `agent-discovery.md` | Softer language, "⚠️ Fallback" instead of "🚨" |
+| `code-standards.md` | "File Creation Policy" with WHY table |
+| `animation-patterns.md` | "⚠️ Common Mistakes" instead of "🚨" |
+| `frontend-component-strategy.md` | "⚠️ Anti-Patterns" instead of "🚨" |
+| `performance-optimization.md` | "⚠️ Common Mistakes" instead of "🚨" |
+| `change-workflow.md` | Table format for read-only files |
+| `task-classification.md` | "Agent Capabilities Reference" section title |
+
+**Design (contexts/design/):**
+| File | Changes |
+|------|---------|
+| `index.md` | "should check" instead of "MUST check" |
+| `box-thinking.md` | "⚠️ Common Mistakes" instead of "🚨" |
+
+**Templates:**
+| File | Changes |
+|------|---------|
+| `phases-sections/frontend-mockup.md` | Table with WHY for design rules |
+| `design-context-template.md` | "⚠️ Design Rules" instead of "🚨 Critical" |
+| `STYLE_GUIDE.template.md` | "🔧 Troubleshooting" instead of "🚨" |
+
+**Other lib files:**
+| File | Changes |
+|------|---------|
+| `lib/README.md` | Softer descriptions, "📌 Important" |
+| `detailed-guides/taskmaster-analysis.md` | "🔴 HIGH" instead of "🚨 HIGH" |
 
 ---