@champpaba/claude-agent-kit 1.1.1 → 1.4.0

package/.claude/lib/detailed-guides/best-practices-system.md

@@ -0,0 +1,150 @@
+# Best Practices System
+
+> **Detailed guide to auto-generated framework-specific best practices**
+> **Source:** Extracted from CLAUDE.md (Navigation Hub)
+> **Version:** 1.4.0
+
+---
+
+## 📚 How It Works
+
+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!
+```
+
+---
+
+## 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)
+
+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)
+
+---
+
+## 🔗 See Also
+
+- `../../commands/agentsetup.md` - /agentsetup command (generates best practices)
+- `../../commands/designsetup.md` - /designsetup command (generates style guide)
+- `../../commands/psetup.md` - /psetup command (one-time project setup)
+- `../../contexts/patterns/agent-discovery.md` - Shared agent discovery flow
+- `context-loading-protocol.md` - How agents load framework-specific context

package/.claude/lib/detailed-guides/context-optimization.md

@@ -0,0 +1,118 @@
+# Context Optimization (v1.2.0)
+
+> **Detailed guide to token-efficient loading strategies**
+> **Source:** Extracted from CLAUDE.md (Navigation Hub)
+> **Version:** 1.4.0
+
+---
+
+## ⚡ The Problem: Token Waste
+
+**Before v1.2.0:**
+```
+/pageplan     → reads STYLE_GUIDE.md (~5K tokens)
+/csetup       → reads STYLE_GUIDE.md (~5K tokens)
+/cdev         → sends STYLE_GUIDE.md (~5K tokens)
+uxui-frontend → reads STYLE_GUIDE.md (~5K tokens)
+────────────────────────────────────────────────
+Total: ~20K tokens (same content read 4 times!)
+```
+
+**After v1.2.0:**
+```
+/designsetup  → generates STYLE_TOKENS.json (~500 tokens) ✅
+/pageplan     → reads STYLE_TOKENS.json (~500 tokens) ✅
+/csetup       → validates files exist (0 tokens) ✅
+/cdev         → sends reference only (~200 tokens) ✅
+uxui-frontend → reads STYLE_TOKENS.json + selective STYLE_GUIDE (~3.5K) ✅
+────────────────────────────────────────────────
+Total: ~4.7K tokens (70% reduction!) ✨
+```
+
+---
+
+## The Solution: 3-Tier Loading
+
+### Tier 1: STYLE_TOKENS.json (500 tokens)
+
+- Lightweight design tokens only
+- Used by: /pageplan, /csetup, agents
+- Contains: Colors, spacing, typography, shadows
+
+**Purpose:** Quick reference for planning and validation
+
+### Tier 2: design-context.md (1K tokens)
+
+- Project design summary
+- File paths and quick reference
+- Used by: agents (STEP 0.5)
+
+**Purpose:** Agent orientation and file discovery
+
+### Tier 3: STYLE_GUIDE.md (5K tokens)
+
+- Full reference with examples
+- Loaded selectively (specific sections only)
+- Used by: agents (when needed)
+
+**Purpose:** Complete design system documentation
+
+---
+
+## Document Loading Pattern
+
+**See:** `../document-loader.md` for complete unified pattern
+
+### Pattern A: Planning (/pageplan, /csetup)
+
+```typescript
+Read: STYLE_TOKENS.json (~500 tokens)
+Validate: STYLE_GUIDE.md exists (0 tokens)
+Total: ~500 tokens
+```
+
+### Pattern B: Execution (/cdev)
+
+```typescript
+Send: Design reference (~200 tokens)
+Agent reads: STYLE_TOKENS.json (~500 tokens)
+Total: ~700 tokens
+```
+
+### Pattern C: Agent (uxui-frontend)
+
+```typescript
+Read: STYLE_TOKENS.json (~500 tokens)
+Read: STYLE_GUIDE sections (~2K tokens, selective)
+Total: ~2.5K tokens
+```
+
+---
+
+## Benefits
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| **Token Usage** | ~20K | ~4.7K | 70% reduction |
+| **Speed** | Slow | Fast | 3-4x faster |
+| **Consistency** | Random | Enforced | 100% |
+| **Quality** | Same | Same | Maintained |
+
+---
+
+## Generated Files
+
+**/designsetup now creates:**
+1. `design-system/STYLE_GUIDE.md` (full guide, 17 sections)
+2. `design-system/STYLE_TOKENS.json` (tokens only) **NEW!**
+
+**Agents automatically use both!**
+
+---
+
+## 🔗 See Also
+
+- `../document-loader.md` - Complete unified loading pattern
+- `../../commands/designsetup.md` - /designsetup command (generates both files)
+- `context-loading-protocol.md` - How agents load context
+- `../../contexts/patterns/ui-component-consistency.md` - Component reuse patterns

package/.claude/lib/detailed-guides/design-system.md

@@ -0,0 +1,98 @@
+# Design System / Style Guide Generation
+
+> **Detailed guide to auto-generated style guides**
+> **Source:** Extracted from CLAUDE.md (Navigation Hub)
+> **Version:** 1.4.0
+
+---
+
+## 🎨 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)
+
+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)
+
+---
+
+## 🔗 See Also
+
+- `../../commands/designsetup.md` - /designsetup command (generates style guide)
+- `context-optimization.md` - 3-tier loading strategy (STYLE_TOKENS.json)
+- `../../contexts/design/index.md` - General design principles (fallback)
+- `../../contexts/patterns/ui-component-consistency.md` - Component reuse patterns

package/.claude/lib/detailed-guides/page-planning.md

@@ -0,0 +1,147 @@
+# Page Planning System
+
+> **Detailed guide to /pageplan command**
+> **Source:** Extracted from CLAUDE.md (Navigation Hub)
+> **Version:** 1.4.0
+
+---
+
+## 📋 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
+```
+
+---
+
+## 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) |
+
+---
+
+## 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
+```
+
+---
+
+## 🔗 See Also
+
+- `../../commands/pageplan.md` - /pageplan command implementation
+- `../../commands/designsetup.md` - /designsetup command (generates STYLE_GUIDE.md)
+- `../../contexts/patterns/ui-component-consistency.md` - Component reuse patterns
+- `../../contexts/patterns/frontend-component-strategy.md` - When to create vs reuse
+- `../document-loader.md` - Token-efficient loading patterns