@champpaba/claude-agent-kit 1.0.0 → 1.1.1

package/README.md

@@ -1,468 +1,756 @@
-# Claude Multi-Agent Template
+# Claude Agent Kit
 
-> Reusable multi-agent system for spec-driven development with automatic Context7 integration.
+> 🤖 **Multi-Agent Implementation Engine** - The perfect companion for [OpenSpec](https://github.com/Fission-AI/OpenSpec) spec-driven development
 
+[![npm version](https://badge.fury.io/js/@champpaba%2Fclaude-agent-kit.svg)](https://www.npmjs.com/package/@champpaba/claude-agent-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@champpaba/claude-agent-kit)](https://nodejs.org)
 
 ---
 
 ## 🎯 What is this?
 
-A **production-ready template** for building software with AI agents that:
+**Claude Agent Kit picks up where OpenSpec planning ends.**
 
-- ✅ **Coordinate complex tasks** - Orchestrator delegates to specialists
-- ✅ **Always up-to-date** - Uses Context7 MCP for latest framework docs
-- ✅ **Zero maintenance** - No tech stack docs to update (Context7 handles it)
-- ✅ **Reusable** - Works for Next.js, FastAPI, Vue, Django, or any stack
-- ✅ **Incremental** - 4-phase methodology (MVT → Complexity → Scale → Deploy)
+While OpenSpec handles **alignment** (Draft Proposal → Review & Align), Claude Agent Kit handles **implementation** (Implement Tasks → Archive & Update) with specialized AI agents.
+
+### The Complete Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    OpenSpec Planning                        │
+│  (Spec-Driven Development for AI Coding Assistants)        │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+              Generates: proposal.md + tasks.md
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│              Claude Agent Kit Implementation                │
+│         (Multi-Agent Execution with 6 Specialists)          │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+              Completes: All tasks with quality gates
+```
 
 ---
 
-## 🚀 Quick Start
+## 🔄 How They Work Together
 
-### มาถึงปุ๊บ ต้องทำอะไร? (Step-by-Step)
+| Stage | Tool | What Happens | Output |
+|-------|------|--------------|--------|
+| **1. Draft Proposal** | OpenSpec | Human requests change, AI scaffolds structure | `proposal.md` + `tasks.md` |
+| **2. Review & Align** | OpenSpec | Team iterates until consensus | Approved specs |
+| **2.5. Page Planning** | **Claude Agent Kit** | *(UI tasks only)* Generate content & component plan | `page-plan.md` |
+| **3. Setup Context** | **Claude Agent Kit** | Classify tasks, generate workflow | `workflow.md` |
+| **4. Implement Tasks** | **Claude Agent Kit** | 6 specialized agents execute work | Working code + tests |
+| **5. Archive & Update** | OpenSpec | Merge changes back to specs | Updated `specs/` |
 
-#### 📥 Step 1: Clone Template (1 นาที)
+### What OpenSpec Generates
 
-```bash
-# Clone template มา
-git clone https://github.com/anongecko/claude-multi-agent-template.git my-project
-cd my-project
+**proposal.md** - Business case and scope
+```markdown
+# Change Proposal: User Authentication System
 
-# ลบ .git เดิม แล้วสร้างใหม่
-rm -rf .git
-git init
-git add .
-git commit -m "Initial commit from template"
+## Motivation
+Users need secure login functionality...
+
+## Scope
+- Email/password authentication
+- JWT token generation
+- Protected routes middleware
 ```
 
+**tasks.md** - Implementation checklist
+```markdown
+## Database Setup
+- [ ] Create User model with email, password fields
+- [ ] Add unique constraint on email
+
+## Backend Implementation
+- [ ] POST /api/auth/login endpoint
+- [ ] Password hashing with bcrypt
+- [ ] JWT token generation
+
+## Frontend Implementation
+- [ ] Login form component
+- [ ] Form validation
+- [ ] Token storage
+```
+
+### What Claude Agent Kit Does
+
+**Input:** Reads `proposal.md` + `tasks.md` from OpenSpec
+
+**Process:**
+1. `/pageplan` *(UI tasks only)* - Generate content & component reuse plan
+2. `/csetup {change-id}` - Analyze tasks, classify by agent, generate workflow
+3. `/cdev {change-id}` - Execute with 6 specialized agents in phases:
+   - **Phase 1:** UI with mock data (uxui-frontend)
+   - **Phase 2:** Real API + database (backend + database, parallel)
+   - **Phase 2.5:** Validate contracts (integration)
+   - **Phase 3:** Connect UI to API (frontend)
+   - **Phase 4:** Tests + bug fixes (test-debug)
+
+**Output:** Working implementation ready for review
+
 ---
 
-#### 🔌 Step 2: Setup Context7 MCP (2 นาที)
+## 🎨 NEW: Page Planning for UI Tasks
 
-**ทำไมต้องมี?** ให้ AI หา docs ล่าสุดของ framework ให้เอง (Next.js, FastAPI, Vue, etc.)
+**Problem:** Before `/pageplan`, agents would:
+- ❌ Create duplicate components (3 different Navbar components!)
+- ❌ Use inconsistent colors (`#0d7276` on landing, `#4f46e5` on dashboard)
+- ❌ Generate lorem ipsum instead of real content
+- ❌ Waste time searching for components during implementation
 
-**วิธีติดตั้ง:**
+**Solution:** `/pageplan` command analyzes BEFORE implementing
 
-1. เปิด Claude Code Settings → MCP Servers
-2. เพิ่ม config นี้:
+### How It Works
 
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@context7/mcp"]
-    }
-  }
-}
+```bash
+# Step 1: OpenSpec generates tasks
+User: "Build landing page for TOEIC app"
+→ Creates: .changes/landing-page/proposal.md + tasks.md
+
+# Step 2: Generate page plan (NEW!)
+User: /pageplan @prd.md @project_brief.md
+
+# What it does:
+# 1. Reads user-specified files (PRD, brief)
+# 2. Reads proposal.md (technical architecture)
+# 3. Reads STYLE_GUIDE.md (visual design)
+# 4. Searches existing components (Navbar, Footer, etc.)
+# 5. AI drafts real content from PRD
+# 6. Generates: .changes/landing-page/page-plan.md
 ```
 
-3. Restart Claude Code
-4. เช็คว่าใช้งานได้: พิมพ์ `/mcp` ดู list → ต้องมี `context7`
+### page-plan.md Output
 
----
+```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 - see content below */}
+  <FeatureGrid />
+  <TestimonialCarousel />
+  <Footer /> {/* Reuse */}
+</Layout>
+
+## 3. Assets to Prepare
+- [ ] hero-image.jpg (1920x1080)
+- [ ] logo.svg (200x60)
+- [ ] feature-icons (3x 24x24 SVG)
+
+## 4. Content Draft (AI-Generated - Please Review & Edit)
+**Headline:** "Master TOEIC with AI-Powered Tests"
+**Subheadline:** "Experience exam-quality questions with instant AI scoring"
+**CTA:** "Start Free Test"
+
+**Features:**
+- Real TOEIC-style questions
+- Instant AI scoring
+- Progress tracking dashboard
+```
+
+### Step 3: User Prepares
 
-#### ⚡ Step 3: Auto-Setup Tech Stack (30 วินาที)
+- ✅ Review content draft (edit as needed)
+- ✅ Prepare assets (images, icons)
+- ✅ Approve `page-plan.md`
 
-**ใช้ `/agentsetup` command:**
+### Step 4: Implementation
 
 ```bash
-/agentsetup
+/csetup landing-page
+/cdev landing-page
+
+# uxui-frontend agent automatically:
+# - STEP 0.5: Reads page-plan.md ✅
+# - STEP 3: SKIP component search (already done!) ⚡ 25% faster
+# - Uses: Real content from page-plan
+# - Reuses: Navbar, Footer (no duplicates)
+# - Creates: HeroSection, FeatureGrid, TestimonialCarousel
+# - Applies: Colors/spacing from STYLE_GUIDE.md
 ```
 
-**Command จะทำอะไร?**
+### Benefits
 
-**1. ตรวจสอบ Greenfield vs Brownfield:**
-- **Brownfield** (มีโปรเจคอยู่แล้ว):
-  - อ่าน `package.json` / `requirements.txt` / `composer.json`
-  - ตรวจจับ stack อัตโนมัติ (Next.js 15, Prisma 6, etc.)
-  - ดึง docs จาก Context7
+| Before (No page-plan) | After (With page-plan) |
+|----------------------|------------------------|
+| ❌ Agent searches during implementation | ✅ Search done once upfront (25% faster) |
+| ❌ Duplicate components created | ✅ Clear reuse plan |
+| ❌ Lorem ipsum content | ✅ Real content from PRD |
+| ❌ Missing assets mid-work | ✅ Asset checklist prepared |
+| ❌ Inconsistent design | ✅ Synced with STYLE_GUIDE |
+| ❌ Agent guesses structure | ✅ Clear component hierarchy |
 
-- **Greenfield** (เริ่มใหม่):
-  - ถามว่าจะใช้ stack อะไร (Next.js? FastAPI? Django?)
-  - ถามต่อ: Database ORM? Testing framework?
-  - ดึง docs จาก Context7
+### When to Use /pageplan
 
-**2. สร้างไฟล์ Domain Context:**
 ```
-.claude/contexts/domain/{project}/
-├─ tech-stack.md       ← Stack + versions + Context7 IDs
-├─ architecture.md     ← (ถ้า spec มี)
-├─ business-rules.md   ← (ถ้า spec มี)
-└─ design-tokens.md    ← (ถ้า spec มี)
+✅ Use for:
+- Landing pages
+- Dashboards
+- Multi-section UI pages
+- Any task with multiple components
+
+❌ Skip for:
+- Backend API endpoints
+- Database schemas
+- Single-component tasks
+- Non-UI work
 ```
 
-**ตัวอย่าง Output:**
-```
-✅ Agent Setup Complete!
+---
 
-📦 Project Type: Brownfield
+## 🤖 The 6 Specialized Agents
 
-🛠️ Tech Stack Detected:
-- Frontend: Next.js 15.5.0
-- Database: Prisma 6.5.0
-- State: Zustand 5.0.0
-- Testing: Vitest 2.0.0
+| Agent | Color | Responsibility | Phase |
+|-------|-------|---------------|-------|
+| **uxui-frontend** | 🔵 Blue | Design UI components with mock data | 1 |
+| **backend** | 🟣 Purple | Create API endpoints with validation | 2 |
+| **database** | 🩷 Pink | Design schemas, migrations, queries | 2 |
+| **integration** | 🟠 Orange | Validate API contracts before connecting | 2.5 |
+| **frontend** | 🟢 Green | Connect UI to backend APIs | 3 |
+| **test-debug** | 🔴 Red | Run tests and fix bugs (max 3-4 iterations) | 1,3,4 |
 
-📁 Domain Context Created:
-- .claude/contexts/domain/myproject/tech-stack.md
+Each agent:
+- ✅ Auto-discovers your project context (tech stack, best practices)
+- ✅ Follows framework-specific patterns from Context7 MCP
+- ✅ Maintains design consistency across the codebase
+- ✅ Reports progress with detailed logging
 
-📚 Context7 Docs Retrieved:
-- Next.js 15 App Router (5000 tokens)
-- Prisma 6 Best Practices (5000 tokens)
-- Zustand 5 TypeScript (3000 tokens)
+---
 
-🚀 Ready to start!
+## 📦 Installation
+
+```bash
+npm install -g @champpaba/claude-agent-kit
 ```
 
-**หมายเหตุ:** ถ้าไม่รู้จะใช้ stack อะไร ให้ข้าม step นี้ไปก่อน แล้วค่อยกลับมารัน `/agentsetup` ทีหลัง
+### Alternative Package Managers
+
+```bash
+# Using pnpm
+pnpm add -g @champpaba/claude-agent-kit
+
+# Using yarn
+yarn global add @champpaba/claude-agent-kit
+```
 
 ---
 
-#### 🎨 Step 4: (Optional) กำหนดสี Design Tokens (5 นาที)
+## 🚀 Quick Start (with OpenSpec)
 
-ถ้าโปรเจคมีสีเฉพาะ เช่น brand colors:
+### Step 1: OpenSpec Planning
 
 ```bash
-mkdir -p .claude/contexts/domain/myproject
-```
+# In your OpenSpec-enabled project
+cd my-app
 
-สร้างไฟล์ `.claude/contexts/domain/myproject/design-tokens.md`:
+# Draft a change proposal (OpenSpec handles this)
+"I want to build a landing page for my TOEIC app"
+# → Generates: .changes/landing-page/proposal.md + tasks.md
+```
 
-```markdown
-# MyProject Design Tokens
+### Step 2: Initialize Claude Agent Kit
 
-## Brand Colors
-- Primary: `rgb(255, 87, 34)` (Orange - Energy, Innovation)
-- Secondary: `rgb(33, 150, 243)` (Blue - Trust, Stability)
-- Accent: `rgb(76, 175, 80)` (Green - Success)
+```bash
+# Initialize the agent system
+cak init
 
-## Usage
-- Primary: CTA buttons, links, brand elements
-- Secondary: Headers, navigation
-- Accent: Success messages, completed states
+# Setup project context (detects tech stack)
+# In Claude Code:
+/psetup
 ```
 
-**หมายเหตุ:** ถ้าไม่กำหนดเอง AI จะใช้ design foundation จาก `.claude/contexts/design/` (สีทั่วไป)
+### Step 3: Generate Page Plan (UI tasks only)
 
----
+```bash
+# In Claude Code:
+/pageplan @prd.md @project_brief.md
 
-#### 🏗️ Step 5: เริ่มทำงาน - เลือก 1 ใน 2 วิธี
+# → Generates: .changes/landing-page/page-plan.md
+# → Review content, prepare assets
+```
 
-### **วิธีที่ 1: สั่งตรงๆ (Simple, Ad-hoc)**
+### Step 4: Setup Change Context
 
 ```bash
-# เปิด Orchestrator
-/agents orchestrator
-
-# สั่งงาน
-"สร้าง login form ใช้ Next.js + Prisma"
+/csetup landing-page
 ```
 
-**Orchestrator จะ:**
-1. ตรวจสอบ tech stack ในโปรเจค (อ่าน `package.json` หรือ `requirements.txt`)
-2. ค้น Context7 หา docs (Next.js 15, Prisma 6)
-3. มอบหมายงานให้ agents:
-   - **UX-UI Frontend**: สร้าง form + mock data
-   - **Test-Debug**: เขียน tests
-   - **Frontend**: ต่อ API
-   - **Backend**: สร้าง POST /api/auth/login
-   - **Database**: สร้าง User model
+**What happens:**
+- Reads `.changes/landing-page/proposal.md` (business context)
+- Reads `.changes/landing-page/tasks.md` (implementation checklist)
+- Reads `.changes/landing-page/page-plan.md` (if exists - content plan)
+- Classifies tasks by agent (database, backend, frontend, etc.)
+- Generates `workflow.md` (execution plan)
 
----
+### Step 5: Execute Implementation
+
+```bash
+/cdev landing-page
+```
 
-### **วิธีที่ 2: ใช้ tasks.md (Structured, Complex Projects)**
+**What happens:**
+1. **Phase 1:** uxui-frontend reads `page-plan.md` → creates UI with real content
+2. **Phase 2:** backend + database create APIs + models (parallel, if needed)
+3. **Phase 2.5:** integration validates API contracts
+4. **Phase 3:** frontend connects UI to APIs (if needed)
+5. **Phase 4:** test-debug runs tests, fixes bugs
 
-สร้างไฟล์ `tasks.md`:
+### Step 6: Monitor Progress
 
-```markdown
-# Feature: User Authentication
+```bash
+# View detailed progress
+/cview landing-page
 
-## Tech Stack
-- Frontend: Next.js 15 App Router
-- Backend: Next.js API Routes
-- Database: Prisma + PostgreSQL
-- Testing: Vitest
+# Quick status check
+/cstatus landing-page
+# → Phase 1/4 - UI Implementation (100%)
+```
 
 ---
 
-## Phase 1: MVT (Minimum Viable Test)
-**Goal:** 1 user สามารถ login ได้
+## 🎯 Complete Workflow Examples
 
-### Task 1.1: Create Login Form (UX-UI Frontend Agent)
-- Email input (required, type=email)
-- Password input (required, minLength=8)
-- Submit button
-- Mock data: `{ email: 'test@example.com', password: 'password123' }`
+### Workflow A: UI Feature (with /pageplan)
 
-### Task 1.2: Write Unit Tests (Test-Debug Agent)
-- Test form validation (empty fields, invalid email)
-- Test mock login flow
+```bash
+# 1. OpenSpec Planning
+User: "Build landing page for TOEIC app"
+→ Creates: proposal.md + tasks.md
+
+# 2. Page Planning (NEW!)
+/pageplan @prd.md @project_brief.md
+→ Creates: page-plan.md
+→ User reviews content & prepares assets
+
+# 3. Setup Context
+/csetup landing-page
+→ Reads: proposal.md, tasks.md, page-plan.md
+→ Generates: workflow.md
+
+# 4. Implementation
+/cdev landing-page
+→ uxui-frontend reads page-plan.md (STEP 0.5)
+→ Skips redundant component search
+→ Uses real content + reuse plan
+→ 25% faster implementation
+
+# 5. Monitor
+/cview landing-page
+```
 
-### Task 1.3: Human Approval ✋
-**STOP** - User tests manually, approves before Phase 2
+### Workflow B: Backend Feature (skip /pageplan)
 
----
+```bash
+# 1. OpenSpec Planning
+User: "Add payment processing API"
+→ Creates: proposal.md + tasks.md
+
+# 2. Setup Context (skip /pageplan - not UI work)
+/csetup payment-api
+
+# 3. Implementation
+/cdev payment-api
+→ Phase 2: backend + database agents (parallel)
+→ Phase 2.5: integration validates contracts
+→ Phase 3: frontend connects (if UI exists)
+→ Phase 4: test-debug validates
+
+# 4. Monitor
+/cview payment-api
+```
 
-## Phase 2: Complexity (Add Real API)
-**Goal:** Connect form to real backend
+### Workflow C: Full-Stack Feature (with /pageplan)
 
-### Task 2.1: Create Login API (Backend Agent)
-- POST /api/auth/login
-- Validate email + password with Zod
-- Return 200 + JWT token OR 401 error
+```bash
+# 1. OpenSpec Planning
+User: "Build user authentication system"
+→ Creates: proposal.md + tasks.md
+
+# 2. Page Planning (for login UI only)
+/pageplan @prd.md
+→ Creates: page-plan.md (login form content + components)
+
+# 3. Setup Context
+/csetup auth-system
+
+# 4. Implementation
+/cdev auth-system
+→ Phase 1: uxui-frontend (login form, reads page-plan.md)
+→ Phase 2: backend (POST /api/auth/login) + database (User model)
+→ Phase 2.5: integration (validate contract)
+→ Phase 3: frontend (connect form to API)
+→ Phase 4: test-debug (E2E tests)
+
+# 5. Monitor
+/cview auth-system
+```
+
+---
 
-### Task 2.2: Connect Form to API (Frontend Agent)
-- Replace mock data with fetch('/api/auth/login')
-- Handle loading state
-- Handle error messages
+## 📁 Project Structure After Init
 
-### Task 2.3: Add State Management (Frontend Agent)
-- Zustand store for auth state
-- Store JWT token in localStorage
-- Add logout action
+```
+your-project/
+├── openspec/
+│   ├── specs/                       # Source of truth (OpenSpec)
+│   └── changes/
+│       └── landing-page/
+│           ├── proposal.md          ← OpenSpec generates
+│           ├── tasks.md             ← OpenSpec generates
+│           ├── page-plan.md         ← /pageplan generates (UI tasks)
+│           ├── workflow.md          ← /csetup generates
+│           └── flags.json           ← /cdev tracks progress
+│
+├── design-system/
+│   └── STYLE_GUIDE.md               ← /designsetup generates
+│
+└── .claude/
+    ├── CLAUDE.md                    # Navigation guide
+    │
+    ├── agents/                      # 6 specialized agents
+    │   ├── 01-integration.md
+    │   ├── 02-uxui-frontend.md
+    │   ├── 03-test-debug.md
+    │   ├── 04-frontend.md
+    │   ├── 05-backend.md
+    │   └── 06-database.md
+    │
+    ├── commands/                    # Slash commands
+    │   ├── designsetup.md           # Generate style guide
+    │   ├── pageplan.md              # Generate page plan (NEW!)
+    │   ├── psetup.md                # Project setup
+    │   ├── csetup.md                # Change setup
+    │   ├── cdev.md                  # Change development
+    │   ├── cview.md                 # View progress
+    │   └── cstatus.md               # Quick status
+    │
+    ├── contexts/
+    │   ├── design/                  # Design foundation
+    │   ├── patterns/                # Universal patterns
+    │   └── domain/                  # Project context
+    │
+    └── lib/                         # Implementation logic
+        ├── agent-executor.md
+        ├── tdd-classifier.md
+        ├── flags-updater.md
+        └── agent-router.md
+```
 
 ---
 
-## Phase 3: Scale (Full Auth Flow)
+## 🎯 Why Use Claude Agent Kit?
 
-### Task 3.1: Database Schema (Database Agent)
-```prisma
-model User {
-  id        String   @id @default(uuid())
-  email     String   @unique
-  password  String   // bcrypt hash
-  name      String?
-  createdAt DateTime @default(now())
-}
-```
+### Without Claude Agent Kit (Manual Implementation)
 
-### Task 3.2: Password Hashing (Backend Agent)
-- Install bcrypt
-- Hash password before saving
-- Compare hash during login
+```
+❌ You manually interpret tasks.md
+❌ You context-switch between frontend/backend/database
+❌ You might forget edge cases or tests
+❌ Inconsistent code patterns across features
+❌ No systematic error handling
+❌ Duplicate components everywhere
+❌ Lorem ipsum content in UI
+```
 
-### Task 3.3: JWT Generation (Backend Agent)
-- Install jsonwebtoken
-- Generate token with user.id payload
-- Set expiry (7 days)
+### With Claude Agent Kit
 
-### Task 3.4: Protected Routes (Frontend Agent)
-- Create middleware to check JWT
-- Redirect to /login if not authenticated
+```
+✅ Agents auto-classify and execute tasks
+✅ Each agent focuses on its specialty
+✅ Built-in validation gates (integration agent)
+✅ Consistent patterns via auto-discovery
+✅ Automatic retry with escalation
+✅ Component reuse plan (/pageplan)
+✅ Real content from PRD
+✅ 25% faster UI implementation
+```
 
 ---
 
-## Phase 4: Deploy (Production Ready)
+## 📚 Key Features
 
-### Task 4.1: Error Handling (Backend Agent)
-- Add try-catch to all API routes
-- Return proper HTTP status codes
-- Log all errors with logger.error()
+### ✅ Seamless OpenSpec Integration
 
-### Task 4.2: Integration Tests (Test-Debug Agent)
-- Test complete login flow (form → API → database)
-- Test error cases (wrong password, user not found)
+- Reads `proposal.md` for business context
+- Parses `tasks.md` for implementation checklist
+- Generates `page-plan.md` for UI tasks (NEW!)
+- Tracks progress in `flags.json`
+- Updates completion status back to OpenSpec
 
-### Task 4.3: Security Review (Backend Agent)
-- Add rate limiting (max 5 login attempts/minute)
-- Add CORS configuration
-- Add input sanitization
+### ✅ Auto-Generated Best Practices
 
-### Task 4.4: Documentation (Orchestrator)
-- API documentation (endpoints, request/response)
-- Setup instructions (environment variables)
+Uses Context7 MCP to fetch latest framework docs:
+
+```bash
+/psetup
+# → Detects: Next.js 15, React 18, Prisma 6
+# → Generates: .claude/contexts/domain/{project}/best-practices/
+#    - nextjs-15.md
+#    - react-18.md
+#    - prisma-6.md
 ```
 
-**วิธีใช้:**
+### ✅ 3-Level Project Indexing
 
-```bash
-/agents orchestrator
-"Execute tasks.md"
+Agents auto-discover context:
+
+```
+1. Read: domain/index.md → Get current project
+2. Read: domain/{project}/README.md → Get tech stack
+3. Read: domain/{project}/best-practices/index.md → Load patterns
 ```
 
-**Orchestrator จะ:**
-1. อ่าน tasks.md ทั้งหมด
-2. ตรวจสอบ tech stack (Next.js 15, Prisma)
-3. ดึง docs จาก Context7
-4. ทำงาน Phase 1 → รอ approval → Phase 2 → Phase 3 → Phase 4
-5. หยุดรอที่ "Human Approval ✋" (Task 1.3, 2.3, etc.)
+### ✅ Design Foundation
+
+Universal design principles:
+- Color theory (WCAG AAA contrast)
+- Typography scales
+- 8px spacing grid (8, 16, 24, 32, 40, 48px)
+- 4-level shadow system
+- Box thinking framework
+- Accessibility (WCAG 2.1 AA)
+
+### ✅ Quality Gates
+
+- **TDD for critical paths** (auth, payments, data transforms)
+- **Test-alongside for simple code** (CRUD, UI components)
+- **Max 3-4 retry iterations** before escalation
+- **Integration validation** before connecting UI to API
 
 ---
 
-#### 🔄 Step 6: ใช้งานต่อเนื่อง
+## 🔧 CLI Commands
 
-**เพิ่ม Feature ใหม่:**
-```bash
-/agents orchestrator
-"สร้าง user profile page - ให้แก้ไขชื่อ/อีเมลได้"
-```
+### `cak init`
+Initialize agent system in current project
 
-**แก้ Bug:**
 ```bash
-/agents test-debug
-"Login form ไม่แสดง error message เมื่อ password ผิด"
+cak init
+cak init --force  # Overwrite existing .claude/
 ```
 
-**Refactor Code:**
+**Creates:**
+- `.claude/` folder with 6 agents
+- Slash commands (`/psetup`, `/csetup`, `/cdev`, etc.)
+- Universal patterns & design foundation
+
+---
+
+### `cak update`
+Update to latest agent templates
+
 ```bash
-/agents backend
-"Refactor /api/auth/login - แยก validation logic ออกมา"
+cak update
+cak update --backup  # Create .claude.backup/ first
 ```
 
+**What it does:**
+- Updates all template files to latest version
+- Preserves your customizations in `domain/`
+- Creates backup before updating (with `--backup` flag)
+
 ---
 
-#### 📚 Step 7: เรียนรู้เพิ่มเติม
+### `cak --version`
+Show version number
 
-**อ่าน navigation guide:**
 ```bash
-cat .claude/CLAUDE.md
+cak --version
+# → 1.0.0
 ```
 
-**ดู agent ทั้งหมด:**
+---
+
+### `cak --help`
+Display help information
+
 ```bash
-ls .claude/agents/
+cak --help
 ```
 
-**ดู universal patterns:**
+---
+
+## 🔄 Workflow Commands (in Claude Code)
+
+### `/designsetup` - Generate style guide (one-time)
+
 ```bash
-ls .claude/contexts/patterns/
-# - logging.md (structured JSON logging)
-# - testing.md (TDD, Red-Green-Refactor)
-# - error-handling.md (try-catch, retry, circuit breaker)
-# - task-breakdown.md (4-phase methodology)
+/designsetup
 ```
 
-**ดู design foundation:**
+**Auto-detects from:**
+1. `reference/` folder → Extract design from HTML/screenshots
+2. Existing codebase → Reverse engineer patterns
+3. AI generation → Modern best practices
+
+**Creates:** `design-system/STYLE_GUIDE.md`
+
+---
+
+### `/pageplan` - Generate page plan (UI tasks only) 🆕
+
 ```bash
-ls .claude/contexts/design/
-# - box-thinking.md (layout analysis framework)
-# - accessibility.md (WCAG 2.1 AA compliance)
-# - color-theory.md, typography.md, spacing.md, etc.
+/pageplan @prd.md @project_brief.md
 ```
 
+**What it does:**
+- Reads user-specified files (PRD, brief)
+- Reads `proposal.md` + `STYLE_GUIDE.md`
+- Searches existing components
+- AI drafts real content from PRD
+- Generates asset checklist
+
+**Creates:** `page-plan.md`
+- Component reuse plan (🔄 Reuse vs ✅ New)
+- Page structure (component hierarchy)
+- Assets to prepare (images, icons)
+- Content draft (headlines, descriptions)
+
 ---
 
-## 🤖 Agents
+### `/psetup` - Setup project (one-time)
 
-### **Orchestrator** (Sonnet 4.5)
-Coordinates multi-step tasks, detects tech stack, delegates to specialists.
+```bash
+/psetup
+```
 
-### **UX-UI Frontend** (Haiku 4.5)
-Creates components with mock data, follows design foundation.
+**What it does:**
+- Detects tech stack (Next.js, React, Prisma, etc.)
+- Creates `domain/{project}/README.md`
+- Generates best practices via Context7 MCP
 
-### **Test-Debug** (Haiku 4.5)
-Runs tests, fixes bugs automatically (max 3-4 iterations, then escalates).
+---
 
-### **Frontend** (Haiku 4.5)
-Connects components to real APIs, implements state management.
+### `/csetup {change-id}` - Setup change context
 
-### **Backend** (Haiku 4.5)
-Builds API endpoints with validation (FastAPI, Express, Next.js API Routes).
+```bash
+/csetup landing-page
+```
 
-### **Database** (Haiku 4.5)
-Designs schemas, writes migrations (Prisma, SQLAlchemy, TypeORM).
+**What it does:**
+- Reads `proposal.md` (business context)
+- Reads `tasks.md` (implementation checklist)
+- Reads `page-plan.md` (if exists - UI content plan)
+- Classifies tasks by agent
+- Generates `workflow.md` (execution plan)
 
 ---
 
-## 📁 Structure
+### `/cdev {change-id}` - Execute implementation
 
+```bash
+/cdev landing-page
 ```
-.claude/
-├── CLAUDE.md                    # Navigation guide
-├── agents/                      # 6 agents (Orchestrator + 5 specialists)
-│   ├── 01-orchestrator.md
-│   ├── 02-uxui-frontend.md
-│   ├── 03-test-debug.md
-│   ├── 04-frontend.md
-│   ├── 05-backend.md
-│   └── 06-database.md
-│
-└── contexts/
-    ├── patterns/                # Universal patterns (static)
-    │   ├── logging.md
-    │   ├── testing.md
-    │   ├── error-handling.md
-    │   ├── task-breakdown.md
-    │   ├── development-principles.md
-    │   ├── code-standards.md
-    │   # REMOVED - Use Context7 MCP instead
-    │   # REMOVED - Use Context7 MCP instead
-    │   # REMOVED - Optional (OpenSpec, BMAD, SpecKit)
-    │
-    ├── design/                  # Design foundation (static)
-    │   ├── index.md
-    │   ├── color-theory.md
-    │   ├── typography.md
-    │   ├── spacing.md
-    │   ├── shadows.md
-    │   ├── layout.md
-    │   ├── responsive.md
-    │   ├── box-thinking.md
-    │   └── accessibility.md
-    │
-    └── domain/                  # Project-specific (you create)
-        └── README.md
-```
+
+**What it does:**
+- Runs agents in phases (1 → 2 → 2.5 → 3 → 4)
+- uxui-frontend auto-reads `page-plan.md` (STEP 0.5)
+- Updates `flags.json` (progress tracking)
+- Reports completion status
 
 ---
 
-## 🎨 Design System
+### `/cview {change-id}` - View detailed progress
 
-Template includes **universal design foundation**:
+```bash
+/cview landing-page
+```
 
-- **Color Theory** - Harmony, WCAG AAA contrast, shade generation
-- **Typography** - Font scales, hierarchy, readability
-- **Spacing** - 8px grid system
-- **Shadows** - 4-level elevation system
-- **Layout** - Grid, flexbox, responsive patterns
-- **Accessibility** - ARIA, keyboard nav, screen readers
+**Shows:**
+- Completed/pending tasks
+- Agent activity log
+- Current phase
+- Error messages (if any)
 
-**Project-specific colors:** Define in `.claude/contexts/domain/{project}/design-tokens.md`
+---
+
+### `/cstatus {change-id}` - Quick status
+
+```bash
+/cstatus landing-page
+# → Phase 2/4 - Backend Implementation (75%)
+```
 
 ---
 
-## 🧪 Testing Philosophy
+## 🎨 Design System Integration
 
-### TDD for Critical Paths (Required)
-- Business logic (calculations, transformations)
-- API endpoints (validation, error handling)
-- External service integrations
-- Data transformations
+### Auto-Generate Style Guide
 
-### Test-Alongside for Simple Code
-- CRUD operations
-- UI components (presentational)
-- Configuration files
+```bash
+/designsetup
+```
 
-**Test-Debug agent** runs tests automatically, fixes bugs (max 3-4 iterations).
+**Detection priority:**
+1. **reference/ folder** (HTML/screenshots) → Extract design style
+2. **Existing codebase** (>10 components) → Reverse engineer patterns
+3. **AI generation** → Modern best practices
+
+**Output:** `design-system/STYLE_GUIDE.md`
+
+**17 Comprehensive Sections:**
+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
+12. Z-Index Layers
+13. Responsive Breakpoints
+14. CSS Variables / Tailwind Theme (Design Tokens)
+15. Layout Patterns
+16. Example Component Reference (React + Tailwind code)
+17. Additional Sections (Best Practices, Accessibility, Icon System)
+
+**Agents automatically use `STYLE_GUIDE.md` for:**
+- Color palette (no hardcoded colors)
+- Spacing scale (consistent gaps/padding)
+- Typography (font hierarchy)
+- Component patterns (reuse before create)
 
 ---
 
-## 📊 Logging & Observability
+## 🧪 Testing Philosophy
 
-**Every significant action must be logged** (structured JSON):
+**Agents follow TDD classification:**
 
-```typescript
-logger.info('api_route_entry', { route, method, requestId })
-logger.info('db_operation_success', { operation, table, duration })
-logger.error('api_route_error', { route, error, stack, requestId })
-```
+| Code Type | Approach | Example |
+|-----------|----------|---------|
+| **Critical paths** | TDD (Red-Green-Refactor) | Auth logic, payments, calculations |
+| **Simple code** | Test-alongside | CRUD, UI components, config |
 
-See: `.claude/contexts/patterns/logging.md`
+**Test-debug agent:**
+- Runs tests automatically after implementation
+- Fixes bugs (max 3-4 iterations)
+- Escalates if stuck (reports to user)
 
 ---
 
-## 🔧 Tech Stack Support
+## 🔧 Supported Tech Stacks
 
-### Automatically Detected via Context7
+Agents auto-detect your stack via Context7 MCP:
 
 **Frontend:**
 - Next.js, React, Vue, Svelte, Angular
 
 **Backend:**
-- FastAPI, Express, NestJS, Django, Flask
+- FastAPI, Express, NestJS, Django, Flask, Next.js API Routes
 
 **Database:**
 - Prisma, SQLAlchemy, TypeORM, Drizzle
@@ -470,49 +758,99 @@ See: `.claude/contexts/patterns/logging.md`
 **Testing:**
 - Vitest, Jest, Pytest, Playwright
 
-Agents search Context7 MCP for latest docs automatically.
+---
+
+## 📖 Usage Examples
+
+### Example 1: Simple UI Task (with /pageplan)
+
+```bash
+# In Claude Code
+"Build a user profile page with edit functionality"
+
+# If it's a UI task, optionally run:
+/pageplan @prd.md
+
+# Then execute:
+/csetup profile-page
+/cdev profile-page
+```
+
+Claude will:
+1. Read `task-classification.md`
+2. Select agents: `uxui-frontend` → `backend` → `frontend` → `test-debug`
+3. uxui-frontend reads `page-plan.md` (if exists)
+4. Execute in sequence
+5. Report completion
 
 ---
 
-## 📖 Examples
+### Example 2: Complex Multi-Agent Workflow (OpenSpec)
 
-### Example 1: Next.js + Prisma
+Using OpenSpec workflow:
 
 ```bash
-# Your project
-package.json: { "dependencies": { "next": "15.5.0", "@prisma/client": "6.5.0" } }
+# 1. OpenSpec generates proposal + tasks
+"I want to add a dashboard with analytics"
+# → proposal.md + tasks.md created
+
+# 2. Generate page plan
+/pageplan @prd.md @analytics_spec.md
+
+# 3. Setup change context
+/csetup analytics-dashboard
+
+# 4. Start development
+/cdev analytics-dashboard
 
-# Orchestrator detects:
-Frontend = Next.js 15
-Database = Prisma
-→ Agents use Context7: Next.js App Router docs + Prisma docs
+# 5. View progress
+/cview analytics-dashboard
 ```
 
-### Example 2: FastAPI + SQLAlchemy
+This follows a structured 4-phase approach:
+1. **Phase 1:** UI with mock data (uxui-frontend reads page-plan.md)
+2. **Phase 2:** Real API + database (backend + database)
+3. **Phase 2.5:** Validate contracts (integration)
+4. **Phase 3:** Connect UI to API (frontend)
+5. **Phase 4:** Tests + bug fixes (test-debug)
+
+---
+
+## 🔄 Updating to Latest Version
+
+### Method 1: Update the npm package
 
 ```bash
-# Your project
-requirements.txt: fastapi, sqlalchemy
+npm update -g @champpaba/claude-agent-kit
+```
+
+### Method 2: Update template in project
 
-# Orchestrator detects:
-Backend = FastAPI
-Database = SQLAlchemy
-→ Agents use Context7: FastAPI docs + SQLAlchemy docs
+```bash
+cd your-project
+cak update --backup
 ```
 
+This will:
+- Create backup at `.claude.backup/`
+- Update all template files
+- Preserve your customizations in `domain/`
+
 ---
 
 ## 🎯 Customization
 
-### Add Domain-Specific Context
+### Add Project-Specific Context
+
+After running `cak init`, add your own context files:
 
 ```bash
-mkdir -p .claude/contexts/domain/myproject
+mkdir -p .claude/contexts/domain/my-project
 ```
 
-Example (E-commerce):
+**Example:** E-commerce checkout flow
 ```markdown
-<!-- .claude/contexts/domain/ecommerce/checkout-flow.md -->
+<!-- .claude/contexts/domain/my-project/checkout-flow.md -->
 # Checkout Flow
 
 ## Steps
@@ -522,24 +860,34 @@ Example (E-commerce):
 4. Order confirmation
 
 ## Business Rules
-- Free shipping > $50
+- Free shipping over $50
 - Tax calculation by state
 - Inventory check before payment
 ```
 
-Agents will load these patterns automatically.
+Agents will auto-discover and use these patterns.
+
+---
+
+## 🔗 Ecosystem
+
+**Claude Agent Kit works with:**
+
+| Tool | Purpose | Integration |
+|------|---------|-------------|
+| **OpenSpec** | Spec-driven planning | Reads `proposal.md` + `tasks.md` |
+| **Context7 MCP** | Always-updated docs | Auto-generates best practices |
+| **Claude Code** | AI coding assistant | Execution environment |
 
 ---
 
 ## 🤝 Contributing
 
-This is a template repo. Fork and customize for your needs!
+We welcome contributions!
 
-**Improvements welcome:**
-- Additional patterns (caching, rate limiting, etc.)
-- More design foundation content
-- Example projects
-- Documentation improvements
+- Report bugs: [GitHub Issues](https://github.com/ChampPABA/claude-multi-agent-template/issues)
+- Feature requests: [Discussions](https://github.com/ChampPABA/claude-multi-agent-template/discussions)
+- Pull requests: Follow [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ---
 
@@ -552,10 +900,89 @@ MIT License - see [LICENSE](LICENSE)
 ## 🙏 Credits
 
 Built with:
-- [Claude Code](https://claude.com/claude-code) - AI-powered coding assistant
-- [Context7 MCP](https://context7.com) - Always up-to-date library documentation
-- [OpenSpec](https://openspec.dev) - Spec-driven development framework (optional)
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) - Spec-driven development framework
+- [Claude Code](https://claude.com/claude-code) - AI coding assistant
+- [Context7 MCP](https://context7.com) - Always up-to-date library docs
+
+---
+
+## 🔗 Links
+
+- **npm Package:** https://www.npmjs.com/package/@champpaba/claude-agent-kit
+- **GitHub:** https://github.com/ChampPABA/claude-multi-agent-template
+- **OpenSpec:** https://github.com/Fission-AI/OpenSpec
+- **Issues:** https://github.com/ChampPABA/claude-multi-agent-template/issues
+
+---
+
+## 💡 Quick Tips
+
+1. **Run `/designsetup` FIRST** - Ensures visual consistency from day 1
+2. **Use `/pageplan` for UI tasks** - 25% faster implementation, better content
+3. **Review `page-plan.md` before `/cdev`** - Edit content, prepare assets
+4. **Setup Context7 MCP** - Agents get latest framework docs automatically
+5. **Use OpenSpec for complex features** - Better alignment before implementation
+6. **Monitor with `/cview`** - See exactly what agents are doing
+7. **Always use `--backup` when updating** - Protects your customizations
 
 ---
 
-**Ready to build?** Clone this template and start creating! 🚀
+## 📋 Complete Flow Summary
+
+```
+1️⃣ OpenSpec Planning
+   → proposal.md + tasks.md
+
+2️⃣ Generate Style Guide (one-time)
+   /designsetup
+   → STYLE_GUIDE.md
+
+3️⃣ Setup Project (one-time)
+   /psetup
+   → domain/{project}/best-practices/
+
+4️⃣ Generate Page Plan (UI tasks only)
+   /pageplan @prd.md
+   → page-plan.md (content + component plan)
+
+5️⃣ Setup Change Context
+   /csetup {change-id}
+   → workflow.md
+
+6️⃣ Execute Implementation
+   /cdev {change-id}
+   → Working code + tests
+
+7️⃣ Monitor Progress
+   /cview {change-id}
+   → Detailed progress report
+
+8️⃣ OpenSpec Archive & Update
+   → Merge to specs/
+```
+
+---
+
+**Ready to implement with confidence?** 🚀
+
+```bash
+# Install globally
+npm install -g @champpaba/claude-agent-kit
+
+# Initialize in your project
+cd your-project
+cak init
+
+# Setup project context
+/psetup
+
+# Generate style guide (optional but recommended)
+/designsetup
+
+# Start building (after OpenSpec planning)
+/pageplan @prd.md           # UI tasks only
+/csetup your-feature
+/cdev your-feature
+```
+
+Let specialized agents handle implementation while you focus on specs and architecture!