@champpaba/claude-agent-kit 1.4.0 → 1.4.2

package/README.md

@@ -1,1179 +1,1278 @@
-# Claude Agent Kit
-
-> 🤖 **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?
-
-**Claude Agent Kit picks up where OpenSpec planning ends.**
-
-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
-```
-
----
-
-## 🔄 How They Work Together
-
-| 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/` |
-
-### What OpenSpec Generates
-
-**proposal.md** - Business case and scope
-```markdown
-# Change Proposal: User Authentication System
-
-## 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
-
----
-
-## 🎨 NEW: Page Planning for UI Tasks
-
-**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
-
-### How It Works
-
-```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
-```
-
-### 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
-
-- ✅ Review content draft (edit as needed)
-- ✅ Prepare assets (images, icons)
-- ✅ Approve `page-plan.md`
-
-### Step 4: Implementation
-
-```bash
-/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
-```
-
-### Benefits
-
-| 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 |
-
-### When to Use /pageplan
-
-```
-✅ 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
-```
-
----
-
-## 🤖 The 6 Specialized Agents
-
-| 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 |
-
-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
-
----
-
-## 📦 Installation
-
-```bash
-npm install -g @champpaba/claude-agent-kit
-```
-
-### Alternative Package Managers
-
-```bash
-# Using pnpm
-pnpm add -g @champpaba/claude-agent-kit
-
-# Using yarn
-yarn global add @champpaba/claude-agent-kit
-```
-
----
-
-## 🚀 Quick Start (with OpenSpec)
-
-### Step 1: OpenSpec Planning
-
-```bash
-# In your OpenSpec-enabled project
-cd my-app
-
-# 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
-```
-
-### Step 2: Initialize Claude Agent Kit
-
-```bash
-# Initialize the agent system
-cak init
-
-# Setup project context (detects tech stack)
-# In Claude Code:
-/psetup
-```
-
-### Step 3: Generate Page Plan (UI tasks only)
-
-```bash
-# In Claude Code:
-/pageplan @prd.md @project_brief.md
-
-# → Generates: .changes/landing-page/page-plan.md
-# → Review content, prepare assets
-```
-
-### Step 4: Setup Change Context
-
-```bash
-/csetup landing-page
-```
-
-**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
-```
-
-**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
-
-### Step 6: Monitor Progress
-
-```bash
-# View detailed progress
-/cview landing-page
-
-# Quick status check
-/cstatus landing-page
-# → Phase 1/4 - UI Implementation (100%)
-```
-
----
-
-## 🎯 Complete Workflow Examples
-
-### Workflow A: UI Feature (with /pageplan)
-
-```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
-```
-
-### 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
-```
-
-### Workflow C: Full-Stack Feature (with /pageplan)
-
-```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
-```
-
----
-
-## 📁 Project Structure After Init
-
-```
-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
-```
-
----
-
-## 🎯 Why Use Claude Agent Kit?
-
-### Without Claude Agent Kit (Manual Implementation)
-
-```
-❌ 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
-```
-
-### With Claude Agent Kit
-
-```
-✅ 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
-```
-
----
-
-## 📚 Key Features
-
-### ✅ Seamless OpenSpec Integration
-
-- 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
-
-### ✅ Auto-Generated Best Practices
-
-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
-
-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
-```
-
-### ✅ 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
-
----
-
-## 🔧 CLI Commands
-
-### `cak init`
-Initialize agent system in current project
-
-```bash
-cak init
-cak init --force  # Overwrite existing .claude/
-```
-
-**Creates:**
-- `.claude/` folder with 6 agents
-- Slash commands (`/psetup`, `/csetup`, `/cdev`, etc.)
-- Universal patterns & design foundation
-
----
-
-### `cak update`
-Update to latest agent templates
-
-```bash
-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)
-
----
-
-### `cak --version`
-Show version number
-
-```bash
-cak --version
-# → 1.0.0
-```
-
----
-
-### `cak --help`
-Display help information
-
-```bash
-cak --help
-```
-
----
-
-## 🔄 Workflow Commands (in Claude Code)
-
-### `/designsetup` - Generate style guide (one-time)
-
-```bash
-/designsetup
-```
-
-**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
-/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)
-
----
-
-### `/psetup` - Setup project (one-time)
-
-```bash
-/psetup
-```
-
-**What it does:**
-- Detects tech stack (Next.js, React, Prisma, etc.)
-- Creates `domain/{project}/README.md`
-- Generates best practices via Context7 MCP
-
----
-
-### `/csetup {change-id}` - Setup change context
-
-```bash
-/csetup landing-page
-```
-
-**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)
-
----
-
-### `/cdev {change-id}` - Execute implementation
-
-```bash
-/cdev landing-page
-```
-
-**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
-
----
-
-### `/cview {change-id}` - View detailed progress
-
-```bash
-/cview landing-page
-```
-
-**Shows:**
-- Completed/pending tasks
-- Agent activity log
-- Current phase
-- Error messages (if any)
-
----
-
-### `/cstatus {change-id}` - Quick status
-
-```bash
-/cstatus landing-page
-# → Phase 2/4 - Backend Implementation (75%)
-```
-
----
-
-## 🎨 Design System Integration
-
-### Auto-Generate Style Guide
-
-```bash
-/designsetup
-```
-
-**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)
-
----
-
-## 🧪 Testing Philosophy
-
-**Agents follow TDD classification:**
-
-| Code Type | Approach | Example |
-|-----------|----------|---------|
-| **Critical paths** | TDD (Red-Green-Refactor) | Auth logic, payments, calculations |
-| **Simple code** | Test-alongside | CRUD, UI components, config |
-
-**Test-debug agent:**
-- Runs tests automatically after implementation
-- Fixes bugs (max 3-4 iterations)
-- Escalates if stuck (reports to user)
-
----
-
-## 🔧 Supported Tech Stacks
-
-Agents auto-detect your stack via Context7 MCP:
-
-**Frontend:**
-- Next.js, React, Vue, Svelte, Angular
-
-**Backend:**
-- FastAPI, Express, NestJS, Django, Flask, Next.js API Routes
-
-**Database:**
-- Prisma, SQLAlchemy, TypeORM, Drizzle
-
-**Testing:**
-- Vitest, Jest, Pytest, Playwright
-
----
-
-## 📖 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
-
----
-
-### Example 2: Complex Multi-Agent Workflow (OpenSpec)
-
-Using OpenSpec workflow:
-
-```bash
-# 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
-
-# 5. View progress
-/cview analytics-dashboard
-```
-
-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
-npm update -g @champpaba/claude-agent-kit
-```
-
-### Method 2: Update template in project
-
-```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 Project-Specific Context
-
-After running `cak init`, add your own context files:
-
-```bash
-mkdir -p .claude/contexts/domain/my-project
-```
-
-**Example:** E-commerce checkout flow
-```markdown
-<!-- .claude/contexts/domain/my-project/checkout-flow.md -->
-# Checkout Flow
-
-## Steps
-1. Cart review
-2. Shipping address
-3. Payment method
-4. Order confirmation
-
-## Business Rules
-- Free shipping over $50
-- Tax calculation by state
-- Inventory check before payment
-```
-
-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
-
-We welcome contributions!
-
-- 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)
-
----
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE)
-
----
-
-## 🙏 Credits
-
-Built with:
-- [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
-
----
-
-## 🆕 What's New in v1.4.0
-
-**Major Update: Context Optimization & DRY Consolidation** 🎉
-
-### Token Efficiency Improvements
-
-**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
-
-**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)
-
-**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 from v1.1.1 to v1.4.0
-
-```bash
-# Update npm package
-npm update -g @champpaba/claude-agent-kit
-
-# Update template in your project (creates backup)
-cd your-project
-cak update --backup
-```
-
-All your customizations in `.claude/contexts/domain/` are preserved!
-
----
-
-## 📜 Changelog
-
-### 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**
-
-**Added:**
-- 6-dimension task analysis in `/csetup`:
-  - Complexity scoring (1-10)
-  - Dependency detection (auto-detects blocks/blocked-by)
-  - Risk assessment (LOW/MEDIUM/HIGH with mitigation)
-  - Research requirements (auto-generates queries)
-  - Subtask breakdown (complex tasks → smaller steps)
-  - Priority ranking (CRITICAL → LOW, scored 0-100)
-- Task analyzer implementation: `.claude/lib/task-analyzer.md`
-- Enhanced phases.md with metadata, time buffers, research phases
-
-**Improved:**
-- Time estimates with automatic buffers (+41% average)
-- Research phases auto-added for new tech/libraries
-- Dependency order in workflow execution
-- Risk mitigation strategies per task
-
-**Inspired by:** [claude-task-master](https://github.com/eyaltoledano/claude-task-master)
-
-### v1.2.0 (2025-10-27)
-**Feature: Context Optimization - 70% Token Reduction**
-
-**Added:**
-- 3-tier loading strategy: STYLE_TOKENS.json (500) → design-context.md (1K) → STYLE_GUIDE.md (5K)
-- Document loader protocol: `.claude/lib/document-loader.md`
-- Lightweight design tokens: `design-system/STYLE_TOKENS.json`
-
-**Improved:**
-- Token usage: ~20K → ~4.7K (70% reduction for design system)
-- Speed: 3-4x faster command execution
-- Consistency: Enforced design tokens, no random colors
-
-### v1.1.1 (2025-10-25)
-**Patch: Minor Fixes**
-
-**Fixed:**
-- Template path correction: `template/.claude` → `.claude`
-- Documentation typos and formatting
-
-### v1.1.0 (2025-10-24)
-**Feature: Enhanced Implementation Logic**
-
-**Added:**
-- Implementation logic overview: `lib/README.md`
-- Agent executor with retry & escalation: `lib/agent-executor.md`
-- TDD classifier logic: `lib/tdd-classifier.md`
-- Progress tracking protocol: `lib/flags-updater.md`
-- Mandatory agent routing: `lib/agent-router.md`
-- Shared agent discovery flow: `contexts/patterns/agent-discovery.md`
-
-### v1.0.0 (2025-10-20)
-**Initial Release: Multi-Agent Template**
-
-**Core Features:**
-- 6 specialized agents (integration, uxui-frontend, test-debug, frontend, backend, database)
-- OpenSpec integration (`/csetup`, `/cdev`, `/cview`, `/cstatus`)
-- Auto-generated best practices via Context7 MCP
-- 3-level project indexing (domain → project → best-practices)
-- Design foundation (color theory, spacing, typography)
-- `/designsetup` command (auto-generate style guide)
-- `/pageplan` command (UI content & component planning)
-- Universal patterns (logging, testing, error-handling, TDD)
-- CLI: `cak init`, `cak update`
-
----
-
-## 🔗 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
-
----
-
-## 📋 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!
+# Claude Agent Kit
+
+> 🤖 **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?
+
+**Claude Agent Kit picks up where OpenSpec planning ends.**
+
+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
+```
+
+---
+
+## 🔄 How They Work Together
+
+| 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/` |
+
+### What OpenSpec Generates
+
+**proposal.md** - Business case and scope
+```markdown
+# Change Proposal: User Authentication System
+
+## 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
+
+---
+
+## 🎨 NEW: Page Planning for UI Tasks
+
+**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
+
+### How It Works
+
+```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
+```
+
+### 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
+
+- ✅ Review content draft (edit as needed)
+- ✅ Prepare assets (images, icons)
+- ✅ Approve `page-plan.md`
+
+### Step 4: Implementation
+
+```bash
+/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
+```
+
+### Benefits
+
+| 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 |
+
+### When to Use /pageplan
+
+```
+✅ 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
+```
+
+---
+
+## 🤖 The 6 Specialized Agents
+
+| 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 |
+
+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
+- ✅ **Smart auto-proceed:** Eliminates double confirmations when user approves workflow
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -g @champpaba/claude-agent-kit
+```
+
+### Alternative Package Managers
+
+```bash
+# Using pnpm
+pnpm add -g @champpaba/claude-agent-kit
+
+# Using yarn
+yarn global add @champpaba/claude-agent-kit
+```
+
+---
+
+## 🚀 Quick Start (with OpenSpec)
+
+### Step 1: OpenSpec Planning
+
+```bash
+# In your OpenSpec-enabled project
+cd my-app
+
+# 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
+```
+
+### Step 2: Initialize Claude Agent Kit
+
+```bash
+# Initialize the agent system
+cak init
+
+# Setup project context (detects tech stack)
+# In Claude Code:
+/psetup
+```
+
+### Step 3: Generate Page Plan (UI tasks only)
+
+```bash
+# In Claude Code:
+/pageplan @prd.md @project_brief.md
+
+# → Generates: .changes/landing-page/page-plan.md
+# → Review content, prepare assets
+```
+
+### Step 4: Setup Change Context
+
+```bash
+/csetup landing-page
+```
+
+**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
+```
+
+**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
+
+### Step 6: Monitor Progress
+
+```bash
+# View detailed progress
+/cview landing-page
+
+# Quick status check
+/cstatus landing-page
+# → Phase 1/4 - UI Implementation (100%)
+```
+
+---
+
+## 🎯 Complete Workflow Examples
+
+### Workflow A: UI Feature (with /pageplan)
+
+```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
+```
+
+### 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
+```
+
+### Workflow C: Full-Stack Feature (with /pageplan)
+
+```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
+```
+
+---
+
+## 📁 Project Structure After Init
+
+```
+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
+```
+
+---
+
+## 🎯 Why Use Claude Agent Kit?
+
+### Without Claude Agent Kit (Manual Implementation)
+
+```
+❌ 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
+```
+
+### With Claude Agent Kit
+
+```
+✅ 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
+```
+
+---
+
+## 📚 Key Features
+
+### ✅ Seamless OpenSpec Integration
+
+- 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
+
+### ✅ Auto-Generated Best Practices
+
+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
+
+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
+```
+
+### ✅ 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
+- **Smart auto-proceed** (eliminate redundant confirmations, 25% faster)
+
+---
+
+## 🔧 CLI Commands
+
+### `cak init`
+Initialize agent system in current project
+
+```bash
+cak init
+cak init --force  # Overwrite existing .claude/
+```
+
+**Creates:**
+- `.claude/` folder with 6 agents
+- Slash commands (`/psetup`, `/csetup`, `/cdev`, etc.)
+- Universal patterns & design foundation
+
+---
+
+### `cak update`
+Update to latest agent templates
+
+```bash
+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)
+
+---
+
+### `cak --version`
+Show version number
+
+```bash
+cak --version
+# → 1.0.0
+```
+
+---
+
+### `cak --help`
+Display help information
+
+```bash
+cak --help
+```
+
+---
+
+## 🔄 Workflow Commands (in Claude Code)
+
+### `/designsetup` - Generate style guide (one-time)
+
+```bash
+/designsetup
+```
+
+**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
+/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)
+
+---
+
+### `/psetup` - Setup project (one-time)
+
+```bash
+/psetup
+```
+
+**What it does:**
+- Detects tech stack (Next.js, React, Prisma, etc.)
+- Creates `domain/{project}/README.md`
+- Generates best practices via Context7 MCP
+
+---
+
+### `/csetup {change-id}` - Setup change context
+
+```bash
+/csetup landing-page
+```
+
+**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)
+
+---
+
+### `/cdev {change-id}` - Execute implementation
+
+```bash
+/cdev landing-page
+
+# Or with explicit approval
+"ลุยเลย"  # Continue without confirmation prompts
+```
+
+**What it does:**
+- Runs agents in phases (1 → 2 → 2.5 → 3 → 4)
+- uxui-frontend auto-reads `page-plan.md` (STEP 0.5)
+- **Auto-proceed:** Detects user approval ("continue", "ลุยเลย") and eliminates redundant confirmation prompts
+- Updates `flags.json` (progress tracking)
+- Reports completion status
+
+**Auto-Proceed Feature:**
+- When you say "continue", "proceed", "yes", or "ลุยเลย", Main Claude auto-responds to agent questions
+- **50-90% fewer confirmations** (1x per workflow instead of 2x per phase)
+- **25% faster execution** (no waiting for redundant approvals)
+
+---
+
+### `/cview {change-id}` - View detailed progress
+
+```bash
+/cview landing-page
+```
+
+**Shows:**
+- Completed/pending tasks
+- Agent activity log
+- Current phase
+- Error messages (if any)
+
+---
+
+### `/cstatus {change-id}` - Quick status
+
+```bash
+/cstatus landing-page
+# → Phase 2/4 - Backend Implementation (75%)
+```
+
+---
+
+## 🎨 Design System Integration
+
+### Auto-Generate Style Guide
+
+```bash
+/designsetup
+```
+
+**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)
+
+---
+
+## 🧪 Testing Philosophy
+
+**Agents follow TDD classification:**
+
+| Code Type | Approach | Example |
+|-----------|----------|---------|
+| **Critical paths** | TDD (Red-Green-Refactor) | Auth logic, payments, calculations |
+| **Simple code** | Test-alongside | CRUD, UI components, config |
+
+**Test-debug agent:**
+- Runs tests automatically after implementation
+- Fixes bugs (max 3-4 iterations)
+- Escalates if stuck (reports to user)
+
+---
+
+## 🔧 Supported Tech Stacks
+
+Agents auto-detect your stack via Context7 MCP:
+
+**Frontend:**
+- Next.js, React, Vue, Svelte, Angular
+
+**Backend:**
+- FastAPI, Express, NestJS, Django, Flask, Next.js API Routes
+
+**Database:**
+- Prisma, SQLAlchemy, TypeORM, Drizzle
+
+**Testing:**
+- Vitest, Jest, Pytest, Playwright
+
+---
+
+## 📖 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
+
+---
+
+### Example 2: Complex Multi-Agent Workflow (OpenSpec)
+
+Using OpenSpec workflow:
+
+```bash
+# 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
+
+# 5. View progress
+/cview analytics-dashboard
+```
+
+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
+npm update -g @champpaba/claude-agent-kit
+```
+
+### Method 2: Update template in project
+
+```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 Project-Specific Context
+
+After running `cak init`, add your own context files:
+
+```bash
+mkdir -p .claude/contexts/domain/my-project
+```
+
+**Example:** E-commerce checkout flow
+```markdown
+<!-- .claude/contexts/domain/my-project/checkout-flow.md -->
+# Checkout Flow
+
+## Steps
+1. Cart review
+2. Shipping address
+3. Payment method
+4. Order confirmation
+
+## Business Rules
+- Free shipping over $50
+- Tax calculation by state
+- Inventory check before payment
+```
+
+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
+
+We welcome contributions!
+
+- 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)
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🙏 Credits
+
+Built with:
+- [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
+
+---
+
+## 🆕 What's New in v1.4.1
+
+**Feature: Intelligent Auto-Proceed - Eliminate Double Confirmations** 🚀
+
+### Smart Approval Detection
+
+**Problem Solved:**
+- Before: Agent asks "Proceed?" → Main Claude asks user again (redundant!)
+- User frustration: "I already said 'ลุยเลย', why ask twice?"
+
+**Solution Implemented:**
+- ✅ Main Claude detects user approval keywords ("continue", "proceed", "yes", "ลุยเลย")
+- ✅ Passes approval context to agents in prompt
+- ✅ Auto-responds to agent questions without re-prompting user
+- ✅ Backward compatible: Manual approval mode still available
+
+**Results:**
+- **50-90% fewer confirmations** (1x per workflow vs 2x per phase)
+- **25% faster execution** (no waiting for redundant approvals)
+- **Better UX** (approve once, system handles the rest)
+- **Lean implementation** (80 lines, 1 file, +0.1% context)
+
+### How It Works
+
+```bash
+# Before v1.4.1 (Double confirmation ❌)
+User: "ลุยเลย"
+Main: Calls uxui-frontend agent
+Agent: "Pre-work done. Proceed?"
+Main: "Agent is asking... Proceed? (yes/no)"  ← Asks user again!
+User: "Why ask twice?"
+
+# After v1.4.1 (Smart auto-proceed ✅)
+User: "ลุยเลย"
+Main: Detects approval → auto_proceed = true
+Agent: "Pre-work done. Proceed?"
+Main: "YES, proceed immediately"  ← Answers agent directly!
+Agent: Continues work...
+```
+
+### Auto-Proceed Trigger Words
+
+These keywords enable auto-proceed mode:
+- ✅ `/cdev` command (implicit approval for all phases)
+- ✅ "continue", "proceed", "yes"
+- ✅ "ลุยเลย" (Thai: "go ahead")
+
+---
+
+## 🎉 What's New in v1.4.0
+
+**Major Update: Context Optimization & DRY Consolidation**
+
+### Token Efficiency Improvements
+
+**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
+
+**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)
+
+**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
+
+```bash
+# Update npm package
+npm update -g @champpaba/claude-agent-kit
+
+# Update template in your project (creates backup)
+cd your-project
+cak update --backup
+```
+
+**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)
+
+All your customizations in `.claude/contexts/domain/` are preserved!
+
+---
+
+## 📜 Changelog
+
+### v1.4.1 (2025-11-06)
+**Feature: Intelligent Auto-Proceed - Eliminate Double Confirmations**
+
+**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
+
+**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
+
+**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
+
+**When It Activates:**
+- User runs `/cdev` command (implicit approval)
+- User says "continue", "proceed", "yes", "ลุยเลย" (explicit approval)
+
+**Before:**
+```
+User approves → Agent asks → Main asks user again ❌
+```
+
+**After:**
+```
+User approves → Agent asks → Main answers directly ✅
+```
+
+### 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**
+
+**Added:**
+- 6-dimension task analysis in `/csetup`:
+  - Complexity scoring (1-10)
+  - Dependency detection (auto-detects blocks/blocked-by)
+  - Risk assessment (LOW/MEDIUM/HIGH with mitigation)
+  - Research requirements (auto-generates queries)
+  - Subtask breakdown (complex tasks → smaller steps)
+  - Priority ranking (CRITICAL → LOW, scored 0-100)
+- Task analyzer implementation: `.claude/lib/task-analyzer.md`
+- Enhanced phases.md with metadata, time buffers, research phases
+
+**Improved:**
+- Time estimates with automatic buffers (+41% average)
+- Research phases auto-added for new tech/libraries
+- Dependency order in workflow execution
+- Risk mitigation strategies per task
+
+**Inspired by:** [claude-task-master](https://github.com/eyaltoledano/claude-task-master)
+
+### v1.2.0 (2025-10-27)
+**Feature: Context Optimization - 70% Token Reduction**
+
+**Added:**
+- 3-tier loading strategy: STYLE_TOKENS.json (500) → design-context.md (1K) → STYLE_GUIDE.md (5K)
+- Document loader protocol: `.claude/lib/document-loader.md`
+- Lightweight design tokens: `design-system/STYLE_TOKENS.json`
+
+**Improved:**
+- Token usage: ~20K → ~4.7K (70% reduction for design system)
+- Speed: 3-4x faster command execution
+- Consistency: Enforced design tokens, no random colors
+
+### v1.1.1 (2025-10-25)
+**Patch: Minor Fixes**
+
+**Fixed:**
+- Template path correction: `template/.claude` → `.claude`
+- Documentation typos and formatting
+
+### v1.1.0 (2025-10-24)
+**Feature: Enhanced Implementation Logic**
+
+**Added:**
+- Implementation logic overview: `lib/README.md`
+- Agent executor with retry & escalation: `lib/agent-executor.md`
+- TDD classifier logic: `lib/tdd-classifier.md`
+- Progress tracking protocol: `lib/flags-updater.md`
+- Mandatory agent routing: `lib/agent-router.md`
+- Shared agent discovery flow: `contexts/patterns/agent-discovery.md`
+
+### v1.0.0 (2025-10-20)
+**Initial Release: Multi-Agent Template**
+
+**Core Features:**
+- 6 specialized agents (integration, uxui-frontend, test-debug, frontend, backend, database)
+- OpenSpec integration (`/csetup`, `/cdev`, `/cview`, `/cstatus`)
+- Auto-generated best practices via Context7 MCP
+- 3-level project indexing (domain → project → best-practices)
+- Design foundation (color theory, spacing, typography)
+- `/designsetup` command (auto-generate style guide)
+- `/pageplan` command (UI content & component planning)
+- Universal patterns (logging, testing, error-handling, TDD)
+- CLI: `cak init`, `cak update`
+
+---
+
+## 🔗 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
+
+---
+
+## 📋 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!