@champpaba/claude-agent-kit 1.1.1 → 1.4.0

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 1.1.0 - Universal Multi-Agent Template
-> **Latest:** Production-ready with validation enforcement, TDD classification, and retry logic
+> **Template Version:** 1.3.0 - Universal Multi-Agent Template
+> **Latest:** TaskMaster Integration - Intelligent task analysis with complexity, dependencies, risk assessment
 
 ---
 
@@ -28,8 +28,10 @@ Universal, framework-agnostic template for AI-assisted development.
 ## 📖 Quick Navigation
 
 **Design/UI:**
-- `/designsetup` - **NEW!** Auto-generate style guide from reference/codebase/AI
-- `design-system/STYLE_GUIDE.md` - Project-specific style guide (generated by /designsetup)
+- `/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 ✨
 - `@/.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)
@@ -80,475 +82,81 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ## 📚 Best Practices System
 
-### How It Works:
+**→ See:** `@/.claude/lib/detailed-guides/best-practices-system.md` for complete guide
 
-1. **Run `/agentsetup`** to detect tech stack and generate best practices
-2. **Context7 queries** latest framework docs (React, Next.js, Prisma, etc.)
-3. **Best practices files** created in `domain/{project}/best-practices/`
-4. **Agents auto-discover** project via 3-level indexing
-5. **Code quality** enforced by framework-specific patterns
-
-### Generated Files:
-
-```
-.claude/contexts/domain/
-├── index.md                              # Level 1 - Project Registry
-└── {project}/
-    ├── README.md                         # Level 2 - Project Overview
-    ├── tech-stack.md                     # Tech details
-    └── best-practices/
-        ├── index.md                      # Level 3 - Best Practices Registry
-        ├── react-18.md                   # ✅ DO's, ❌ DON'Ts, 🎯 Checklist
-        ├── nextjs-15.md
-        ├── prisma-6.md
-        └── vitest-2.md
-```
-
-### Agent Discovery Flow:
-
-**Every agent follows this sequence (STEP 0):**
-
-```
-1. Read: domain/index.md → Get current project name
-2. Read: domain/{project}/README.md → Get tech stack
-3. Read: domain/{project}/best-practices/index.md → Get relevant files
-4. Read: domain/{project}/best-practices/{files} → Load best practices
-5. Report: "✅ Project Context Loaded"
-```
-
-**Example: uxui-frontend agent**
-```
-✅ Project Context Loaded
-
-📁 Project: my-app
-🛠️ Stack: Next.js 15, React 18, Prisma 6
-📚 Best Practices Loaded:
-   - React 18 ✓
-   - Next.js 15 ✓
-
-🎯 Ready to create UI components!
-```
+**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
 
 ---
 
 ## 🎨 Design System / Style Guide Generation
 
-### How It Works:
-
-`/designsetup` **auto-detects** your project context and generates a comprehensive style guide.
-
-**Three Smart Paths:**
-
-1. **Path 1: Reference Design** (Priority 1)
-   - Detects: `reference/`, `design-reference/`, `designs/` folders
-   - Analyzes: HTML files (SingleFile exports), screenshots
-   - **Auto-detects design style** (Neo-Brutalism, Minimalist, Modern, etc.)
-   - Output: Style guide based on reference design (17 sections, always)
+**→ See:** `@/.claude/lib/detailed-guides/design-system.md` for complete guide
 
-2. **Path 2: Brownfield - Reverse Engineering** (Priority 2)
-   - Detects: Existing codebase (> 10 components)
-   - Extracts: Colors, spacing, typography, component patterns
-   - Output: Style guide reflecting current state + cleanup suggestions
-
-3. **Path 3: Greenfield - AI-Generated** (Priority 3)
-   - Detects: Empty project (< 10 components)
-   - Asks: Application type (SaaS, Marketing, E-commerce, etc.)
-   - Output: Modern, best-practice style guide
-
-### Generated File:
-
-```
-design-system/
-└── STYLE_GUIDE.md    ← Comprehensive 17-section guide
-```
-
-**All 17 Sections (Complete):**
-1. Overview
-2. Design Philosophy
-3. Color Palette (HEX codes, usage, Tailwind classes)
-4. Typography (headings, body, weights)
-5. Spacing System (4px/8px grid)
-6. Component Styles (Button, Card, Input, Badge, etc.)
-7. Shadows & Elevation
-8. Animations & Transitions
-9. Border Styles
-10. Border Radius
-11. **Opacity & Transparency** (standalone)
-12. **Z-Index Layers** (standalone)
-13. **Responsive Breakpoints** (standalone)
-14. CSS Variables / Tailwind Theme (Design Tokens in JSON)
-15. Layout Patterns
-16. Example Component Reference (React + Tailwind code)
-17. Additional Sections (Best Practices, Accessibility, Icon System)
-
-### Workflow:
-
-```bash
-# Recommended flow:
-
-# 1. Generate style guide FIRST (optional but recommended)
-/designsetup
-
-# 2. Setup project (discovers style guide)
-/psetup
-
-# 3. Start development (agents use STYLE_GUIDE.md)
-/csetup feature-login
-/cdev feature-login
-```
-
-### Agent Discovery:
-
-**uxui-frontend agent automatically reads:**
-1. `design-system/STYLE_GUIDE.md` (if exists) ← **Priority #1**
-2. `.claude/contexts/design/*.md` (general principles) ← Fallback
-
-**Why this matters:**
-- ✅ Ensures visual consistency (no hardcoded colors, spacing)
-- ✅ Prevents duplicate components
-- ✅ Enforces accessibility standards
-- ✅ Speeds up development (reuse patterns)
+**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
 
 ---
 
-## 📋 Page Planning System (NEW!)
-
-### What is /pageplan?
-
-**Problem it solves:**
-- ❌ Before: Agent creates UI without knowing existing components → duplicates Navbar 3 times
-- ❌ Before: Agent uses random colors, spacing → Landing page `#0d7276`, Dashboard `#4f46e5` (inconsistent!)
-- ❌ Before: Agent uses lorem ipsum → No real content
-
-**Solution: /pageplan command**
-- ✅ Searches existing components BEFORE implementing
-- ✅ Generates component reuse plan (Navbar ✅ reuse, HeroSection ❌ create)
-- ✅ AI drafts real content from PRD (headlines, descriptions)
-- ✅ Creates asset checklist for user to prepare (images, icons)
-
-### How It Works:
-
-```bash
-# Step 1: OpenSpec generates proposal
-User: "Build landing page"
-→ proposal.md + tasks.md
-
-# Step 2: Generate page plan
-User: /pageplan @prd.md @project_brief.md
-
-Main Claude:
-1. Reads user-specified files (@prd.md, @brief.md)
-2. Reads proposal.md (technical architecture)
-3. Reads STYLE_GUIDE.md (visual design)
-4. Searches existing components (Glob/Grep)
-5. Generates: .changes/{id}/page-plan.md
-   - 🔄 Reuse: Navbar, Footer (found)
-   - ✅ New: HeroSection, FeatureGrid (create)
-   - 📝 Content draft (AI-generated from PRD)
-   - 📦 Asset checklist (user prepares)
-
-# Step 3: User reviews & prepares
-→ Edit content draft
-→ Prepare assets (images, icons)
-→ Approve page-plan.md
-
-# Step 4: Setup & implement
-User: /csetup landing-page
-User: /cdev landing-page
-
-→ uxui-frontend agent:
-  - STEP 0.5: Reads page-plan.md ✅
-  - STEP 3: SKIP component search (page-plan did it!) ⚡
-  - Implements: Reuse Navbar, create HeroSection
-  - Uses: Real content from page-plan
-  - References: Assets user prepared
-```
+## ⚡ Context Optimization (v1.2.0)
 
-### page-plan.md Structure:
-
-```markdown
-# Page Plan: Landing Page
-
-## 1. Component Plan
-🔄 Reuse: Navbar, Footer (found in codebase)
-✅ New Shared: (none)
-✅ New Specific: HeroSection, FeatureGrid, TestimonialCarousel
-
-## 2. Page Structure
-<Layout>
-  <Navbar /> {/* Reuse */}
-  <HeroSection /> {/* New - content below */}
-  <FeatureGrid /> {/* New - content below */}
-  <Footer /> {/* Reuse */}
-</Layout>
-
-## 3. Assets to Prepare (คุณต้องเตรียม)
-- [ ] hero-image.jpg (1920x1080)
-- [ ] logo.svg (200x60)
-- [ ] feature-icons (3x 24x24 SVG)
-
-## 4. Content Draft (AI-Generated - กรุณา Review & Edit)
-**Headline:** "Master TOEIC with AI-Powered Tests"
-**Subheadline:** "Experience exam-quality questions..."
-**CTA:** "Start Free Test"
-...
-```
-
-### Benefits:
-
-| Before (No page-plan) | After (With page-plan) |
-|----------------------|------------------------|
-| ❌ Agent guesses structure | ✅ Clear structure defined |
-| ❌ Duplicate components | ✅ Reuse existing components |
-| ❌ Inconsistent design | ✅ Sync with STYLE_GUIDE |
-| ❌ Lorem ipsum content | ✅ Real content from PRD |
-| ❌ Missing assets | ✅ Asset checklist prepared |
-| ❌ Agent wastes time searching | ✅ Search done once upfront (25% faster) |
+**→ See:** `@/.claude/lib/detailed-guides/context-optimization.md` for complete guide
 
-### When to Use:
-
-```
-✅ Use /pageplan for:
-- Landing pages
-- Dashboards
-- Multi-section UI pages
-- Any task with multiple components
-
-❌ Skip /pageplan for:
-- Backend API endpoints
-- Database schemas
-- Simple single-component tasks
-- Non-UI work
-```
-
-### Integration with STYLE_GUIDE:
-
-```
-STYLE_GUIDE.md → Visual design (colors, spacing, shadows)
-page-plan.md   → Content structure (sections, components, assets)
-
-uxui-frontend agent combines both:
-- Colors from STYLE_GUIDE (#0d7276)
-- Content from page-plan ("Master TOEIC...")
-- Result: Consistent + Real content
-```
+**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
 
 ---
 
-## 🤖 Agent System
-
-### How It Works:
+## 📋 Page Planning System
 
-**Main Claude analyzes tasks → Invokes specialist agents directly**
+**→ See:** `@/.claude/lib/detailed-guides/page-planning.md` for complete guide
 
-```
-1. User provides task (e.g., "Build login system")
-   ↓
-2. Main Claude reads @task-classification.md
-   ↓
-3. Main Claude selects appropriate agent(s)
-   ↓
-4. Execute in proper sequence:
-   - Phase 1: uxui-frontend (UI with mock data)
-   - Phase 2: backend + database (parallel)
-   - Phase 2.5: integration (validate contracts)
-   - Phase 3: frontend (connect UI to API)
-   - Phase 4: test-debug (tests & bug fixes)
-```
-
-### Available Agents (6 specialists):
-
-| Agent | Color | When to Use | Phase |
-|-------|-------|-------------|-------|
-| **integration** | Orange | Validate API contracts before connecting | 2.5 |
-| **uxui-frontend** | Blue | Design UI components with mock data | 1 |
-| **test-debug** | Red | Run tests and fix bugs (max 3-4 iterations) | 1,3,4 |
-| **frontend** | Green | Connect UI to backend APIs | 3 |
-| **backend** | Purple | Create API endpoints with validation | 2 |
-| **database** | Pink | Design schemas, migrations, complex queries | 2 |
-
-### Usage:
-
-**For any task, Main Claude will:**
-1. Read `@/.claude/contexts/patterns/task-classification.md`
-2. Determine which agent(s) to use
-3. Invoke agents in proper sequence
-4. Coordinate between agents
-
-**You can also invoke agents directly:**
-```
-User: "/agents uxui-frontend"
-Main Claude: *Executes uxui-frontend agent directly*
-```
-
----
-
-### 🔒 Main Claude Self-Check Protocol (MANDATORY)
-
-**⚠️ CRITICAL: Main Claude MUST complete this checklist BEFORE doing ANY work**
-
-See: `@/.claude/lib/agent-router.md` for complete routing protocol
-
-**Pre-Work Checklist (Run for EVERY user request):**
-
-```markdown
-## ✅ Pre-Work Self-Check
-
-[ ] 1. Read user request carefully
-       - What are they asking for?
-       - What is the end goal?
-
-[ ] 2. Detect work type
-       - Is this implementation work? (writing code, creating files)
-       - Is this planning/analysis? (reading, explaining, breaking down)
-
-[ ] 3. If IMPLEMENTATION work:
-       - Read: @/.claude/contexts/patterns/task-classification.md
-       - Which agent should handle this?
-         • UI components → uxui-frontend
-         • API endpoints → backend
-         • Database schemas → database
-         • API integration → frontend
-         • Tests/bugs → test-debug
-         • Contracts → integration
-
-[ ] 4. Can Main Claude do this?
-       ✅ YES for: Planning, reading files, explaining, orchestrating workflows
-       ❌ NO for: Writing components, creating endpoints, designing schemas
-
-[ ] 5. If MUST delegate:
-       - Use Task tool with selected agent
-       - Include all necessary context
-       - Wait for agent response
-       - Update flags.json after completion (if using /cdev)
-
-[ ] 6. Report decision to user
-       ```
-       🔍 Task Analysis:
-       - Work type: [type]
-       - Requires: [agent] agent
-       - Reason: [explanation]
-
-       🚀 Invoking [agent] agent...
-       ```
-```
-
-**Main Claude's Role:**
-- ✅ Orchestrator (plan, coordinate, report)
-- ✅ Progress tracker (update flags.json)
-- ✅ Analyst (read files, explain code)
-- ❌ NOT implementer (no writing code directly)
-
-**If Main Claude skips this self-check for implementation work, it violates system protocol.**
+**Quick Summary:**
+- **Problem:** Agents duplicate components (Navbar 3x), use random colors, lorem ipsum content
+- **Solution:** `/pageplan @prd.md @brief.md` → Generates `.changes/{id}/page-plan.md` with component reuse plan, AI-drafted content, asset checklist
+- **Benefits:** Prevents duplicates, ensures design consistency, real content from PRD, 25% faster (search done once upfront)
+- **Use for:** Landing pages, dashboards, multi-section UI pages (skip for backend/database work)
 
 ---
 
-### ⚠️ Agent Pre-Work Requirements
+## 🧠 TaskMaster-style Analysis (v1.3.0)
 
-**STEP 0 (ALL agents):** Every agent must discover project context first
+**→ See:** `@/.claude/lib/detailed-guides/taskmaster-analysis.md` for complete guide
 
-**STEP 1-5 (uxui-frontend only):** Design fundamentals checklist
+**Quick Summary:**
+- **Problem:** Dumb task lists treat all tasks equally → no complexity/dependency/risk analysis → tasks fail, delays, security issues
+- **Solution:** `/csetup` uses **6 analysis dimensions**: Complexity (1-10), Dependencies (auto-detected), Risk (LOW/MEDIUM/HIGH), Research requirements, Subtask breakdown, Priority (0-100)
+- **Benefits:** Intelligent phases.md with time buffers (+41%), auto-added research phases, dependency order, risk mitigation
+- **Inspired by:** [claude-task-master](https://github.com/eyaltoledano/claude-task-master)
 
 ---
 
-#### STEP 0: Project Discovery (ALL Agents)
-
-**Every agent MUST complete this before ANY work:**
-
-```
-1. Read: domain/index.md → Get current project name
-2. Read: domain/{project}/README.md → Get tech stack summary
-3. Read: domain/{project}/best-practices/index.md → Find relevant files
-4. Read: domain/{project}/best-practices/{files} → Load best practices
-5. Report: "✅ Project Context Loaded"
-```
-
-**STEP 0.5 (uxui-frontend ONLY):**
-
-```
-6. Check: design-system/STYLE_GUIDE.md exists?
-   - If YES → Read STYLE_GUIDE.md (Priority #1 - project-specific)
-   - If NO → Read .claude/contexts/design/*.md (Fallback - general principles)
-7. Report: "✅ Style Guide Loaded" or "⚠️ No style guide - using general principles"
-```
-
-**Why this matters:**
-- STYLE_GUIDE.md = project-specific design system (colors, spacing, components)
-- design/*.md = universal design principles (box thinking, color theory)
-- Priority: STYLE_GUIDE.md > design/*.md
-
-**Fallback:** If discovery fails, warn user to run `/agentsetup` or `/designsetup`
-
----
-
-#### STEP 1-5: Design Fundamentals (uxui-frontend only)
+## 🤖 Agent System
 
-**When invoking uxui-frontend agent, Main Claude MUST include these requirements in the Task prompt:**
+**→ See:** `@/.claude/lib/detailed-guides/agent-system.md` for complete guide
 
-```
-MANDATORY PRE-WORK CHECKLIST (after STEP 0):
-
-Before writing ANY code, you MUST:
-
-1. **Read ALL design contexts:**
-   - @/.claude/contexts/design/index.md
-   - @/.claude/contexts/design/box-thinking.md
-   - @/.claude/contexts/design/color-theory.md
-   - @/.claude/contexts/design/spacing.md
-   - @/.claude/contexts/patterns/ui-component-consistency.md
-   - @/.claude/contexts/patterns/frontend-component-strategy.md
-
-2. **Do Box Thinking Analysis:**
-   - Identify all boxes (parent, children, siblings)
-   - Document relationships (container, adjacent, nested)
-   - Plan space flow using spacing scale (8, 16, 24, 32, 40, 48px)
-   - Plan responsive behavior (stack/merge/compress)
-
-3. **Search for Existing Components:**
-   - Glob: "**/*{Keyword}*.{tsx,jsx,vue}"
-   - Grep: "[similar-pattern]"
-   - Decision: Reuse > Compose > Extend > Create New
-   - If creating new: Extract design tokens from most similar component
-
-4. **Extract Design Tokens from Reference Component:**
-   ```typescript
-   const DESIGN_TOKENS = {
-     spacing: { padding: '[from reference]', gap: '[from reference]' },
-     colors: { bg: '[theme token]', text: '[theme token]', border: '[theme token]' },
-     shadows: '[from reference - e.g., shadow-sm]',
-     borderRadius: '[from reference - e.g., rounded-md]'
-   }
-   ```
-
-5. **Report Pre-Implementation Analysis:**
-   You MUST provide a detailed report covering steps 1-4 BEFORE writing any code.
-
-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)
-- ❌ NO inconsistent icons (h-5 w-5, opacity-50) → ✅ Match reference (h-4 w-4, text-foreground/70)
-- ❌ NO creating duplicate components → ✅ Search and reuse first
-
-If you skip these steps, your work will be rejected.
-```
+**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)
+- **Agent pre-work**: STEP 0 (project discovery for ALL) + STEP 1-5 (design fundamentals for uxui-frontend only)
 
-**Why this enforcement matters:**
-- Prevents visual inconsistency (mismatched colors, spacing, shadows)
-- Ensures component reuse (avoids duplicates)
-- Maintains design system integrity
-- Saves implementation time
-
-**Example: Build Login System**
-```
-User: "Build a login system"
-Main Claude analyzes → Breaks into phases:
-  Phase 1: /agents uxui-frontend (create login form UI)
-  Phase 2: /agents backend (create POST /api/login)
-          /agents database (create User model) [parallel]
-  Phase 2.5: /agents integration (verify contracts)
-  Phase 3: /agents frontend (connect form to API)
-  Phase 4: /agents test-debug (test everything)
+**Example workflow:**
 ```
+User: "Build login system"
+→ Phase 1: uxui-frontend (UI)
+→ Phase 2: backend + database (parallel)
+→ Phase 2.5: integration (validate contracts)
+→ Phase 3: frontend (connect UI to API)
+→ Phase 4: test-debug (tests)
 
 ---