@champpaba/claude-agent-kit 1.7.1 → 2.0.0

package/README.md

@@ -917,304 +917,100 @@ Built with:
 
 ---
 
-## 🆕 What's New in v1.7.1
+## 🆕 What's New in v2.0.0
 
-**Patch: OpenSpec File Naming Conventions - Clarify design.md vs STYLE_GUIDE.md** 📁
+**Major Release: Design System v2.0.0 - Interactive Setup & Smart Page Planning** 🎨
 
-### The Issue
-
-Users were confused between two files with similar names:
-- `design.md` (from OpenSpec) = Technical/Architecture decisions
-- `STYLE_GUIDE.md` (from Template) = Visual design (colors, fonts, spacing)
-
-### The Fix
-
-Added clear documentation in CLAUDE.md and agent-discovery.md:
-
-| Source | File | Purpose |
-|--------|------|---------|
-| **OpenSpec** | `design.md` | Technical Architecture (API structure, data flow) |
-| **Template** | `STYLE_GUIDE.md` | Visual Design (colors, typography, spacing) |
-
-### Updated Files
-
-- `CLAUDE.md` - New "📁 File Naming Conventions" section
-- `agent-discovery.md` - Added notes explaining design.md vs STYLE_GUIDE.md
-
-### No Breaking Changes
-
-All existing workflows continue to work. This is a documentation improvement only.
-
----
-
-## 📋 What's New in v1.7.0
-
-**Feature: Opus 4.5 Model Upgrade - All Subagents Now Use Latest Claude Model** 🧠
-
-### The Change
-
-All 6 specialized agents now use **Claude Opus 4.5** (the latest and most capable Claude model) instead of Haiku:
-
-| Agent | Model (Before) | Model (After) |
-|-------|----------------|---------------|
-| integration | haiku | **opus** |
-| uxui-frontend | haiku | **opus** |
-| test-debug | haiku | **opus** |
-| frontend | haiku | **opus** |
-| backend | haiku | **opus** |
-| database | haiku | **opus** |
-
-### Benefits
-
-- ✅ **Best-in-class reasoning** - Opus 4.5 handles complex multi-step tasks better
-- ✅ **Improved code quality** - More accurate implementations with fewer errors
-- ✅ **Better context understanding** - Agents maintain context over longer sessions
-- ✅ **Enhanced problem-solving** - Complex debugging and architectural decisions improved
-
-### Updated Files
-
-- All agent files (`.claude/agents/*.md`) - `model: opus`
-- `/cdev` command - Model strategy updated
-- `agent-executor.md` - Task invocation uses opus
-
-### No Breaking Changes
-
-All existing workflows continue to work exactly as before, just with better performance!
-
----
-
-## 🔄 What's New in v1.6.0
-
-**Feature: Incremental Testing - Milestone-based Validation for High-Risk Tasks** 🔄
-
-### The Problem: All-or-Nothing Testing
-
-**Before v1.6.0:**
-```
-Task: "Integrate Google Maps API"
-→ Agent implements complete solution (1000 locations)
-→ Tests with full dataset
-→ Bug found → Hard to debug (which part failed?)
-→ Fix → Retest full dataset → Slow iteration
-
-Problem:
-❌ Large scope = hard to debug
-❌ Late bug detection (at scale)
-❌ Rework expensive (threw away 1000-location implementation)
-❌ No confidence in progressive scaling
-```
-
-**After v1.6.0:**
-```
-Task: "Integrate Google Maps API"
-→ Milestone 1: Test 1 location (hardcoded)
-   → Bug found → Easy to debug (small scope)
-   → Fix → Retest 1 location → Fast iteration
-→ Milestone 2: Test 10 locations (parameterized)
-   → Works! Confidence++
-→ Milestone 3: Error handling
-   → Refine edge cases
-→ Milestone 4: Scale to 1000
-   → Already confident (1 and 10 worked)
-
-Benefits:
-✅ Small scope = easy debugging
-✅ Early bug detection (at milestone 1)
-✅ Low rework (fix before scaling)
-✅ Progressive confidence
-```
-
-### The Solution: Milestone-based Validation
-
-**Automatic Detection:** `/csetup` detects high-risk tasks automatically
-- Risk = HIGH (payment, auth, security)
-- Risk = MEDIUM + Complexity ≥ 7 (complex forms)
-- External API dependency (Google Maps, Stripe, OpenAI)
-- Data-intensive operation (ETL, migration, batch processing)
-
-**3 Milestone Patterns:**
-
-1. **Backend API Integration** (4 milestones)
-   - M1: Core implementation (1 record, hardcoded)
-   - M2: Parameterized query (10 records, dynamic)
-   - M3: Error handling (invalid input, timeouts)
-   - M4: Scale + performance (100-1000 records)
-
-2. **Complex Form** (3 milestones)
-   - M1: Architecture + skeleton (2-3 critical fields)
-   - M2: E2E flow validation (submit → API → DB)
-   - M3: Complete all fields (all 20 fields + validation)
-
-3. **Database Migration / ETL** (3 milestones)
-   - M1: Dry-run (10 records)
-   - M2: Scale to 100 records
-   - M3: Full dataset (staging)
-
-### Round-based Retry Logic
-
-**Per-Milestone Quota:**
-- **2 attempts per round** (not total)
-- **Unlimited rounds** (Main Claude decides when to stop)
-- **Hints reset quota** (fresh start)
-
-**Example:**
-```
-Milestone 1: Core implementation
-→ Round 1: Attempt 1 ❌ (API key missing)
-→ Round 1: Attempt 2 ❌ (Still missing)
-→ Main Claude: "Check API_KEY env variable" 💡
-→ Round 2: Attempt 1 ✅ (Fixed!)
-
-Total attempts: 3 (2 in Round 1, 1 in Round 2)
-```
-
-### Main Claude Intervention
-
-**Decision Matrix:**
-
-| Error Pattern | Complexity | Confidence | Action |
-|---------------|------------|------------|--------|
-| Same error 2x | SIMPLE | HIGH | Give Hints |
-| Same error 2x | COMPLEX | LOW | Ask Human |
-| Different errors | ANY | ANY | Ask Human |
-| Intermittent | ANY | ANY | Ask Human |
-| 2+ rounds no progress | ANY | ANY | Ask Human |
-
-**Pattern-based Hints:**
-- 401 Unauthorized → Check API_KEY, verify key validity
-- Timeout → Increase threshold, check network
-- Schema mismatch → Compare actual vs expected, check API version
-
-### Benefits & Trade-offs
-
-**Benefits:**
-- ✅ **75% faster debug** - Catch bugs at M1 (1 record) vs M4 (1000 records)
-- ✅ **60-70% rework reduction** - Fix before scaling
-- ✅ **80% faster debugging** - Small scope (1 record) vs full dataset
-- ✅ **90% success rate** - Progressive confidence at M4
-- ✅ **40-50% net speedup** - +15-20% time upfront → -60-70% rework time
-
-**Trade-offs:**
-- ⚠️ **Timeline:** +15-20% upfront (but saves 60-70% rework)
-- ⚠️ **Complexity:** phases.md 2-3x longer (summary table at top)
-- ⚠️ **Learning curve:** More coordination (automated by `/csetup`)
-
-**Net benefit:** +15-20% time → -60-70% rework = **40-50% faster overall**
-
-### When to Use Incremental Testing
-
-**✅ Use for:**
-- Payment integration, Auth systems (HIGH risk)
-- Complex forms with 20+ fields (Complexity ≥ 7)
-- External APIs (Google Maps, Stripe, OpenAI)
-- Data migrations, ETL pipelines (data-intensive)
-
-**❌ Skip for:**
-- Simple CRUD operations (LOW risk, Complexity < 5)
-- UI components (standard testing sufficient)
-- Configuration changes (no integration testing needed)
-
-**Detection Rate:** ~20-30% of tasks (only high-risk)
-
----
-
-## 🎉 What's New in v1.4.0
-
-**Major Update: Context Optimization & DRY Consolidation**
-
-### Token Efficiency Improvements
+### Complete Design System Overhaul
 
 **Problem Solved:**
-- Before v1.4.0: Same documentation duplicated across 6 agent files + CLAUDE.md
-- Package Manager warnings: 360 lines duplicated 6x
-- Context Loading Strategy: 1,200 lines duplicated 6x
-- TDD Workflow examples: 1,200 lines duplicated 3x
-- Handoff templates: 900 lines duplicated 6x
-- Documentation policies: 480 lines duplicated 6x
-- CLAUDE.md: 890 lines mixing navigation + detailed guides
+- Before: One massive STYLE_GUIDE.md loaded everywhere (~5000 tokens)
+- Before: No theme direction, random decorations
+- Before: Same patterns loaded for landing pages AND dashboards
+- Before: Manual style selection with no recommendations
 
 **Solution Implemented:**
-- ✅ Created consolidated lib files (context-loading-protocol.md, handoff-protocol.md, tdd-workflow.md)
-- ✅ Extracted detailed guides from CLAUDE.md to lib/detailed-guides/
-- ✅ Applied consistent reference pattern: Brief summary + "→ See: path" + agent-specific additions
-- ✅ Maintained 100% content quality (all information preserved)
+- ✅ `/extract` - Extract design from multiple reference sites
+- ✅ `/designsetup` - Interactive 3-round loop with theme recommendations
+- ✅ `tokens.json` - Smart design tokens with style/theme/animations (~800 tokens)
+- ✅ `patterns/*.md` - Selective code patterns based on page type
+- ✅ Auto page type detection (landing/dashboard/auth)
 
 **Results:**
-- **All 6 agents:** 6,796 → 4,749 lines (-2,047, -30.1% reduction)
-- **CLAUDE.md:** 890 → 163 lines (-727, -81.7% reduction)
-- **Grand Total:** 7,686 → 4,912 lines (-2,774, -36.1% reduction)
-- **Token savings:** ~36% reduction in total context size
-- **Speed improvement:** Faster agent loading and execution
-- **Maintainability:** Single source of truth for shared documentation
-
-### New Consolidated Documentation Structure
-
-**Created in v1.4.0:**
-```
-.claude/lib/
-├── context-loading-protocol.md     # Universal context loading strategy
-├── handoff-protocol.md             # Agent handoff templates
-├── tdd-workflow.md                 # TDD workflow examples
-└── detailed-guides/
-    ├── best-practices-system.md    # How best practices work
-    ├── context-optimization.md     # Token optimization strategy
-    ├── page-planning.md            # /pageplan command guide
-    ├── taskmaster-analysis.md      # 6-dimension task analysis
-    ├── design-system.md            # Style guide generation
-    └── agent-system.md             # Agent overview & workflow
-```
-
-### Benefits for Users
-
-**For Developers:**
-- ⚡ 36% faster context loading
-- 📖 Cleaner, easier-to-navigate documentation
-- 🎯 CLAUDE.md is now a pure navigation hub (163 lines)
-- 🔍 Detailed guides are modular and focused
-
-**For Claude Agents:**
-- 🚀 Faster startup (less context to load)
-- 💾 More token budget for actual work
-- 📚 Single source of truth (no conflicting info)
-- 🔄 Easier maintenance (update once, apply everywhere)
-
-### Migration Notes
-
-**No breaking changes!** All existing workflows continue to work:
-- ✅ `/psetup`, `/csetup`, `/cdev` commands unchanged
-- ✅ Agent behavior unchanged (same quality, faster execution)
-- ✅ All features from v1.1-1.3 preserved
-- ✅ Existing projects can update with `cak update`
-
-**New Reference Pattern:**
-Agents now use lightweight references instead of duplicating full documentation:
-
-```markdown
-## Context Loading Strategy
-
-**→ See:** `.claude/lib/context-loading-protocol.md` for complete protocol
-
-**Agent-Specific Additions (frontend):**
-### State Management Libraries
-...
-```
-
-### Upgrading to v1.4.1
+- **84% token reduction** (~800 vs ~5000 tokens)
+- **Theme consistency** (USE/AVOID decorations enforced)
+- **Smart patterns** (only load what's needed per page type)
+- **Interactive setup** (AI recommends, user confirms)
+
+### New Flow
+
+```
+/extract https://site.com → .claude/extractions/*.json
+                    ↓
+/designsetup @prd.md → tokens.json + patterns/*.md + STYLE_GUIDE.md
+                    ↓
+/pageplan @prd.md → page-plan.md (auto-detects page type)
+                    ↓
+/csetup → phases.md (reads page-plan.md)
+                    ↓
+/cdev → uxui-frontend (loads patterns selectively)
+```
+
+### Page Type Auto-Detection
+
+| 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 |
+
+### New Features
+
+**`/extract` command:**
+- Multi-URL support (extract from multiple sites)
+- Style detection (Neo-Brutalism, Minimalist, Glassmorphism, Modern SaaS)
+- Animation library detection (GSAP, ScrollTrigger, Framer Motion)
+- Scroll pattern detection (stacking-cards, parallax, fade-in)
+- Decorative element detection (blobs, gradients, 3D elements)
+
+**`/designsetup` v2.0.0:**
+- Interactive 3-round loop (Present → Feedback → Adjust)
+- Verbose style options with match scores
+- AI recommends themes based on project context
+- USE/AVOID decorative direction
+
+**`tokens.json` v2.0.0:**
+- `style` - Detected design style with confidence
+- `theme` - Theme name, feeling, decorative direction
+- `animations` - Libraries, patterns, component animations
+- `patterns_index` - References to pattern files
+
+**`patterns/*.md` files:**
+- `buttons.md` - Button patterns (primary, secondary, ghost, sizes, states)
+- `cards.md` - Card patterns (default, interactive, feature, pricing)
+- `forms.md` - Form patterns (input, error state, select, checkbox)
+- `scroll-animations.md` - Scroll animation patterns
+- `decorations.md` - Decorative elements (gradients, blobs, grids)
+
+### Upgrading to v2.0.0
 
 ```bash
 # Update npm package
 npm update -g @champpaba/claude-agent-kit
 
-# Update template in your project (creates backup)
+# Update template in your project
 cd your-project
 cak update --backup
+
+# Generate new design system
+/extract https://your-reference.com  # Optional
+/designsetup @prd.md
 ```
 
-**What's New:**
-- ✅ Auto-proceed feature (eliminate double confirmations)
-- ✅ 50-90% fewer approval prompts
-- ✅ 25% faster workflow execution
-- ✅ All v1.4.0 features (context optimization, DRY consolidation)
+**Breaking Changes:**
+- `STYLE_TOKENS.json` → `tokens.json` (new structure)
+- `STYLE_GUIDE.md` no longer contains code (moved to `patterns/*.md`)
+- Commands read `tokens.json` instead of `STYLE_TOKENS.json`
 
 All your customizations in `.claude/contexts/domain/` are preserved!
 
@@ -1222,90 +1018,46 @@ All your customizations in `.claude/contexts/domain/` are preserved!
 
 ## 📜 Changelog
 
-### v1.7.1 (2025-11-25)
-**Patch: OpenSpec File Naming Conventions**
+### v2.0.0 (2025-01-28)
+**Major: Design System v2.0.0 - Interactive Setup & Smart Page Planning**
 
 **Added:**
-- New "📁 File Naming Conventions" section in CLAUDE.md
-- Clear distinction between OpenSpec files and Template files
-- Notes in agent-discovery.md explaining design.md purpose
-
-**Documentation:**
-- `design.md` (OpenSpec) = Technical Architecture (API, data flow)
-- `STYLE_GUIDE.md` (Template) = Visual Design (colors, fonts, spacing)
-- Updated agent reading guidance per role
-
-### v1.7.0 (2025-11-25)
-**Feature: Opus 4.5 Model Upgrade**
+- `/extract` command - Multi-URL design extraction with style/animation detection
+- Interactive `/designsetup` - 3-round loop with theme recommendations
+- `tokens.json` v2.0.0 - Enhanced design tokens with style/theme/animations (~800 tokens)
+- `patterns/*.md` files - Selective code patterns (buttons, cards, forms, scroll-animations, decorations)
+- Auto page type detection in `/pageplan` (landing/dashboard/auth)
 
 **Changed:**
-- All 6 agents upgraded from `model: haiku` to `model: opus`
-- Updated `/cdev` model strategy description
-- Updated `agent-executor.md` Task invocation
-
-**Benefits:**
-- Best-in-class reasoning with Opus 4.5
-- Improved code quality and fewer errors
-- Better context understanding
-- Enhanced problem-solving for complex tasks
+- `STYLE_TOKENS.json` → `tokens.json` (new structure)
+- `STYLE_GUIDE.md` - Human-readable only, code moved to patterns/*.md
+- `/csetup` - Reads tokens.json + page-plan.md
 
-### v1.4.1 (2025-11-06)
-**Feature: Intelligent Auto-Proceed - Eliminate Double Confirmations**
+**Performance:**
+- 84% token reduction (~800 vs ~5000 tokens)
+- Selective pattern loading based on page type
+- Theme consistency with USE/AVOID decorations
 
-**Added:**
-- Auto-proceed approval context in agent prompts
-- Smart detection of user approval keywords ("continue", "proceed", "yes", "ลุยเลย")
-- Agent question handling logic (auto-respond vs ask user)
-- Auto-proceed decision tree in agent-executor.md
+**Breaking Changes:**
+- `STYLE_TOKENS.json` renamed to `tokens.json`
+- `STYLE_GUIDE.md` no longer contains code
+- Commands read `tokens.json` instead of `STYLE_TOKENS.json`
 
-**Improved:**
-- User experience: 50-90% fewer confirmation prompts
-- Execution speed: 25% faster (no waiting for redundant approvals)
-- Workflow clarity: User approves once, system handles agent interactions
+### v1.6.0 (2025-01-27)
+**Feature: Page Plan Enhancement - Buyer Avatar & Conversion Copy**
 
-**Technical Details:**
-- Modified: `.claude/lib/agent-executor.md` (+80 lines)
-- Implementation: Lean solution (1 file, 0.1% context increase)
-- Backward compatible: Manual approval mode still available
+### v1.5.1 (2025-01-26)
+**Patch: Git Compatibility Fix**
 
-**When It Activates:**
-- User runs `/cdev` command (implicit approval)
-- User says "continue", "proceed", "yes", "ลุยเลย" (explicit approval)
+### v1.5.0 (2025-01-25)
+**Feature: Minor Improvements**
 
-**Before:**
-```
-User approves → Agent asks → Main asks user again ❌
-```
-
-**After:**
-```
-User approves → Agent asks → Main answers directly ✅
-```
+### v1.4.1 (2025-11-06)
+**Feature: Intelligent Auto-Proceed**
 
 ### v1.4.0 (2025-11-05)
 **Major: Context Optimization & DRY Consolidation**
 
-**Added:**
-- New consolidated lib files: `context-loading-protocol.md`, `handoff-protocol.md`, `tdd-workflow.md`
-- New detailed guides folder: `lib/detailed-guides/` (6 focused guides)
-- Reference pattern across all agents (Brief summary → See: path → Additions)
-
-**Changed:**
-- All 6 agents refactored: 30.1% size reduction (6,796 → 4,749 lines)
-- CLAUDE.md refactored: 81.7% size reduction (890 → 163 lines, pure navigation hub)
-- Documentation structure: Moved detailed content to modular lib files
-
-**Performance:**
-- 36% total context reduction (7,686 → 4,912 lines)
-- Faster agent loading and execution
-- More token budget available for actual work
-
-**Improved:**
-- Maintainability: Single source of truth for shared docs
-- Discoverability: Clear navigation in CLAUDE.md
-- Modularity: Detailed guides in separate files
-- Consistency: Same content quality, zero duplication
-
 ### v1.3.0 (2025-10-30)
 **Feature: TaskMaster-style Intelligent Task Analysis**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champpaba/claude-agent-kit",
-  "version": "1.7.1",
+  "version": "2.0.0",
   "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
   "main": "bin/cli.js",
   "bin": {