@champpaba/claude-agent-kit 1.8.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.claude/CLAUDE.md +189 -39
  2. package/.claude/agents/01-integration.md +106 -552
  3. package/.claude/agents/02-uxui-frontend.md +188 -850
  4. package/.claude/agents/03-test-debug.md +152 -521
  5. package/.claude/agents/04-frontend.md +169 -549
  6. package/.claude/agents/05-backend.md +132 -661
  7. package/.claude/agents/06-database.md +149 -698
  8. package/.claude/agents/_shared/README.md +57 -0
  9. package/.claude/agents/_shared/agent-boundaries.md +64 -0
  10. package/.claude/agents/_shared/documentation-policy.md +47 -0
  11. package/.claude/agents/_shared/package-manager.md +59 -0
  12. package/.claude/agents/_shared/pre-work-checklist.md +57 -0
  13. package/.claude/commands/cdev.md +36 -61
  14. package/.claude/commands/csetup.md +101 -39
  15. package/.claude/commands/designsetup.md +1402 -337
  16. package/.claude/commands/extract.md +520 -245
  17. package/.claude/commands/pageplan.md +6 -6
  18. package/.claude/contexts/design/box-thinking.md +1 -1
  19. package/.claude/contexts/design/index.md +1 -1
  20. package/.claude/contexts/patterns/agent-discovery.md +2 -2
  21. package/.claude/contexts/patterns/animation-patterns.md +1 -1
  22. package/.claude/contexts/patterns/change-workflow.md +8 -5
  23. package/.claude/contexts/patterns/code-standards.md +10 -8
  24. package/.claude/contexts/patterns/error-recovery.md +4 -4
  25. package/.claude/contexts/patterns/frontend-component-strategy.md +1 -1
  26. package/.claude/contexts/patterns/performance-optimization.md +1 -1
  27. package/.claude/contexts/patterns/task-breakdown.md +2 -2
  28. package/.claude/contexts/patterns/task-classification.md +2 -2
  29. package/.claude/contexts/patterns/ui-component-consistency.md +3 -3
  30. package/.claude/contexts/patterns/validation-framework.md +36 -33
  31. package/.claude/lib/README.md +4 -4
  32. package/.claude/lib/agent-executor.md +31 -40
  33. package/.claude/lib/agent-router.md +91 -213
  34. package/.claude/lib/context-loading-protocol.md +19 -36
  35. package/.claude/lib/detailed-guides/agent-system.md +43 -121
  36. package/.claude/lib/detailed-guides/taskmaster-analysis.md +1 -1
  37. package/.claude/lib/document-loader.md +22 -25
  38. package/.claude/lib/flags-updater.md +24 -32
  39. package/.claude/templates/STYLE_GUIDE.template.md +1 -1
  40. package/.claude/templates/design-context-template.md +1 -1
  41. package/.claude/templates/phases-sections/frontend-mockup.md +8 -5
  42. package/README.md +99 -40
  43. package/package.json +1 -1
@@ -2,7 +2,7 @@
2
2
 
3
3
  > **Detailed guide to the multi-agent architecture**
4
4
  > **Source:** Extracted from CLAUDE.md (Navigation Hub)
5
- > **Version:** 1.7.0 (Opus 4.5)
5
+ > **Version:** 2.0.0 (Claude 4.5 Optimized)
6
6
 
7
7
  ---
8
8
 
@@ -58,77 +58,38 @@ Main Claude: *Executes uxui-frontend agent directly*
58
58
 
59
59
  ---
60
60
 
61
- ## 🔒 Main Claude Self-Check Protocol (MANDATORY)
61
+ ## 🔒 Main Claude Self-Check Protocol
62
62
 
63
- **⚠️ CRITICAL: Main Claude MUST complete this checklist BEFORE doing ANY work**
63
+ **Before starting work, Main Claude routes tasks appropriately.**
64
64
 
65
- See: `@/.claude/lib/agent-router.md` for complete routing protocol
65
+ See: `@/.claude/lib/agent-router.md` for complete routing protocol
66
66
 
67
- **Pre-Work Checklist (Run for EVERY user request):**
67
+ **Quick Routing Table:**
68
68
 
69
- ```markdown
70
- ## ✅ Pre-Work Self-Check
71
-
72
- [ ] 1. Read user request carefully
73
- - What are they asking for?
74
- - What is the end goal?
75
-
76
- [ ] 2. Detect work type
77
- - Is this implementation work? (writing code, creating files)
78
- - Is this planning/analysis? (reading, explaining, breaking down)
79
-
80
- [ ] 3. If IMPLEMENTATION work:
81
- - Read: @/.claude/contexts/patterns/task-classification.md
82
- - Which agent should handle this?
83
- • UI components → uxui-frontend
84
- • API endpoints → backend
85
- • Database schemas → database
86
- • API integration → frontend
87
- • Tests/bugs → test-debug
88
- • Contracts → integration
89
-
90
- [ ] 4. Can Main Claude do this?
91
- ✅ YES for: Planning, reading files, explaining, orchestrating workflows
92
- ❌ NO for: Writing components, creating endpoints, designing schemas
93
-
94
- [ ] 5. If MUST delegate:
95
- - Use Task tool with selected agent
96
- - Include all necessary context
97
- - Wait for agent response
98
- - Update flags.json after completion (if using /cdev)
99
-
100
- [ ] 6. Report decision to user
101
- ```
102
- 🔍 Task Analysis:
103
- - Work type: [type]
104
- - Requires: [agent] agent
105
- - Reason: [explanation]
106
-
107
- 🚀 Invoking [agent] agent...
108
- ```
109
- ```
69
+ | Task Type | Route To |
70
+ |-----------|----------|
71
+ | UI components | uxui-frontend |
72
+ | API endpoints | backend |
73
+ | Database schemas | database |
74
+ | API integration | frontend |
75
+ | Tests/bugs | test-debug |
76
+ | Contracts | integration |
77
+ | Planning, reading, explaining | Main Claude (direct) |
110
78
 
111
79
  **Main Claude's Role:**
112
- - Orchestrator (plan, coordinate, report)
113
- - Progress tracker (update flags.json)
114
- - Analyst (read files, explain code)
115
- - ❌ NOT implementer (no writing code directly)
80
+ - Orchestrator (plan, coordinate, report)
81
+ - Progress tracker (update flags.json)
82
+ - Analyst (read files, explain code)
116
83
 
117
- **If Main Claude skips this self-check for implementation work, it violates system protocol.**
84
+ WHY routing matters: Specialist agents have domain-specific validation (design tokens, TDD patterns, error handling) that ensures higher quality output.
118
85
 
119
86
  ---
120
87
 
121
- ## ⚠️ Agent Pre-Work Requirements
88
+ ## 📋 Agent Pre-Work Requirements
122
89
 
123
- **STEP 0 (ALL agents):** Every agent must discover project context first
90
+ See: `.claude/agents/_shared/pre-work-checklist.md` for detailed checklist
124
91
 
125
- **STEP 1-5 (uxui-frontend only):** Design fundamentals checklist
126
-
127
- ---
128
-
129
- ### STEP 0: Project Discovery (ALL Agents)
130
-
131
- **Every agent MUST complete this before ANY work:**
92
+ ### STEP 0: Project Discovery (All Agents)
132
93
 
133
94
  ```
134
95
  1. Read: domain/index.md → Get current project name
@@ -138,80 +99,41 @@ See: `@/.claude/lib/agent-router.md` for complete routing protocol
138
99
  5. Report: "✅ Project Context Loaded"
139
100
  ```
140
101
 
141
- **STEP 0.5 (uxui-frontend ONLY):**
102
+ ### STEP 0.5: Design Context (uxui-frontend only)
142
103
 
143
104
  ```
144
105
  6. Check: design-system/STYLE_GUIDE.md exists?
145
- - If YES → Read STYLE_GUIDE.md (Priority #1 - project-specific)
146
- - If NO → Read .claude/contexts/design/*.md (Fallback - general principles)
147
- 7. Report: "✅ Style Guide Loaded" or "⚠️ No style guide - using general principles"
106
+ - If YES → Read STYLE_GUIDE.md (project-specific)
107
+ - If NO → Read .claude/contexts/design/*.md (fallback)
108
+ 7. Report: "✅ Style Guide Loaded"
148
109
  ```
149
110
 
150
- **Why this matters:**
151
- - STYLE_GUIDE.md = project-specific design system (colors, spacing, components)
152
- - design/*.md = universal design principles (box thinking, color theory)
153
- - Priority: STYLE_GUIDE.md > design/*.md
111
+ WHY: STYLE_GUIDE.md has project-specific tokens. design/*.md has universal principles.
154
112
 
155
- **Fallback:** If discovery fails, warn user to run `/agentsetup` or `/designsetup`
113
+ **Fallback:** If discovery fails, suggest `/agentsetup` or `/designsetup`
156
114
 
157
115
  ---
158
116
 
159
117
  ### STEP 1-5: Design Fundamentals (uxui-frontend only)
160
118
 
161
- **When invoking uxui-frontend agent, Main Claude MUST include these requirements in the Task prompt:**
119
+ See: `.claude/agents/02-uxui-frontend.md` for complete checklist
162
120
 
163
- ```
164
- MANDATORY PRE-WORK CHECKLIST (after STEP 0):
165
-
166
- Before writing ANY code, you MUST:
167
-
168
- 1. **Read ALL design contexts:**
169
- - @/.claude/contexts/design/index.md
170
- - @/.claude/contexts/design/box-thinking.md
171
- - @/.claude/contexts/design/color-theory.md
172
- - @/.claude/contexts/design/spacing.md
173
- - @/.claude/contexts/patterns/ui-component-consistency.md
174
- - @/.claude/contexts/patterns/frontend-component-strategy.md
175
-
176
- 2. **Do Box Thinking Analysis:**
177
- - Identify all boxes (parent, children, siblings)
178
- - Document relationships (container, adjacent, nested)
179
- - Plan space flow using spacing scale (8, 16, 24, 32, 40, 48px)
180
- - Plan responsive behavior (stack/merge/compress)
181
-
182
- 3. **Search for Existing Components:**
183
- - Glob: "**/*{Keyword}*.{tsx,jsx,vue}"
184
- - Grep: "[similar-pattern]"
185
- - Decision: Reuse > Compose > Extend > Create New
186
- - If creating new: Extract design tokens from most similar component
187
-
188
- 4. **Extract Design Tokens from Reference Component:**
189
- ```typescript
190
- const DESIGN_TOKENS = {
191
- spacing: { padding: '[from reference]', gap: '[from reference]' },
192
- colors: { bg: '[theme token]', text: '[theme token]', border: '[theme token]' },
193
- shadows: '[from reference - e.g., shadow-sm]',
194
- borderRadius: '[from reference - e.g., rounded-md]'
195
- }
196
- ```
197
-
198
- 5. **Report Pre-Implementation Analysis:**
199
- You MUST provide a detailed report covering steps 1-4 BEFORE writing any code.
200
-
201
- CRITICAL RULES:
202
- - ❌ NO hardcoded colors (text-gray-500) → ✅ Use theme tokens (text-foreground/70)
203
- - ❌ NO arbitrary spacing (p-5) → ✅ Use spacing scale (p-4, p-6)
204
- - ❌ NO inconsistent icons (h-5 w-5, opacity-50) → ✅ Match reference (h-4 w-4, text-foreground/70)
205
- - ❌ NO creating duplicate components → ✅ Search and reuse first
206
-
207
- If you skip these steps, your work will be rejected.
208
- ```
121
+ **Summary:**
122
+ 1. Read design contexts (box-thinking, color-theory, spacing)
123
+ 2. Do Box Thinking Analysis (identify boxes, relationships, spacing)
124
+ 3. Search for existing components (Reuse > Compose > Extend > Create)
125
+ 4. Extract design tokens from reference component
126
+ 5. Report pre-implementation analysis
127
+
128
+ **Style Guidelines:**
129
+
130
+ | Instead of | Use | WHY |
131
+ |------------|-----|-----|
132
+ | text-gray-500 | text-foreground/70 | Theme-aware |
133
+ | p-5 | p-4 or p-6 | Spacing scale |
134
+ | h-5 w-5, opacity-50 | h-4 w-4, text-foreground/70 | Consistency |
209
135
 
210
- **Why this enforcement matters:**
211
- - Prevents visual inconsistency (mismatched colors, spacing, shadows)
212
- - Ensures component reuse (avoids duplicates)
213
- - Maintains design system integrity
214
- - Saves implementation time
136
+ WHY these steps matter: Prevents visual inconsistency, ensures component reuse, maintains design system integrity.
215
137
 
216
138
  ---
217
139
 
@@ -166,7 +166,7 @@ Priority Distribution:
166
166
  - 🟢 LOW: 1
167
167
 
168
168
  Risk Assessment:
169
- - 🚨 HIGH: 2 tasks → TDD required
169
+ - 🔴 HIGH: 2 tasks → TDD required
170
170
  - ⚠️ MEDIUM: 3 tasks
171
171
  - ✅ LOW: 3 tasks
172
172
 
@@ -1,7 +1,7 @@
1
1
  # Document Loader - Unified Loading Pattern
2
2
 
3
3
  > **Token-efficient, consistent document loading for all commands and agents**
4
- > **Version:** 1.0.0 (Context Optimization)
4
+ > **Version:** 2.0.0 (Claude 4.5 Optimized)
5
5
 
6
6
  ---
7
7
 
@@ -120,9 +120,9 @@ function buildDesignReference(projectName: string): string {
120
120
 
121
121
  // Don't load content! Just send paths + minimal summary
122
122
  return `
123
- ## 🎨 Design System (Required Reading)
123
+ ## 🎨 Design System Reference
124
124
 
125
- **MANDATORY for uxui-frontend agent (STEP 0.5):**
125
+ **For uxui-frontend agent (STEP 0.5):**
126
126
 
127
127
  1. Read: ${designContextPath} (~1K tokens)
128
128
  → Project design summary, file paths
@@ -133,15 +133,15 @@ function buildDesignReference(projectName: string): string {
133
133
  3. Optional: ${styleGuidePath} (selective sections ~2K tokens)
134
134
  → Full guide - load Component Styles, Layout Patterns if needed
135
135
 
136
- **Critical Rules:**
137
- - NO hardcoded colors (text-gray-500)
138
- - ✅ USE theme tokens (text-foreground/70)
139
- - NO arbitrary spacing (p-5)
140
- - USE spacing scale (p-4, p-6)
136
+ **Style Guidelines:**
137
+ | Instead of | Use | WHY |
138
+ |------------|-----|-----|
139
+ | text-gray-500 | text-foreground/70 | Theme-aware |
140
+ | p-5 | p-4 or p-6 | Spacing scale |
141
141
 
142
- **You MUST report:**
143
- "Design Context Loaded: design-context.md + STYLE_TOKENS.json"
144
- "Design Tokens Extracted: [list key tokens]"
142
+ **Report format:**
143
+ "Design Context Loaded: design-context.md + STYLE_TOKENS.json"
144
+ "Design Tokens Extracted: [list key tokens]"
145
145
  `
146
146
 
147
147
  // Total sent: ~200 tokens (reference only, not content!)
@@ -229,20 +229,17 @@ ${report.join('\n')}
229
229
 
230
230
  ---
231
231
 
232
- ## 🚨 Critical Rules
233
-
234
- ### DO:
235
- - ✅ Always load design-context.md first (if exists)
236
- - Load STYLE_TOKENS.json for UI work
237
- - Load STYLE_GUIDE.md selectively (specific sections only)
238
- - Validate files exist before loading
239
- - Report what was loaded (transparency)
240
-
241
- ### DON'T:
242
- - Load full STYLE_GUIDE.md unless absolutely needed
243
- - ❌ Skip design-context.md (it's the entry point!)
244
- - ❌ Load design files for non-UI work (backend, database)
245
- - ❌ Hardcode paths (use project name variable)
232
+ ## 📋 Best Practices
233
+
234
+ | Practice | WHY |
235
+ |----------|-----|
236
+ | Load design-context.md first | Entry point with file paths |
237
+ | Load STYLE_TOKENS.json for UI work | Lightweight token reference |
238
+ | Load STYLE_GUIDE.md selectively | Save tokens (5K → 2K) |
239
+ | Validate files exist before loading | Prevent errors |
240
+ | Report what was loaded | Transparency for debugging |
241
+ | Skip design files for backend/database | Not needed, saves tokens |
242
+ | Use project name variable for paths | Portability |
246
243
 
247
244
  ---
248
245
 
@@ -2,18 +2,16 @@
2
2
 
3
3
  > **WHO:** Main Claude (orchestrator)
4
4
  > **WHEN:** Immediately after sub-agent completes phase
5
- > **HOW:** Follow this exact flow
6
- > **PURPOSE:** Ensure real-time progress tracking for users
5
+ > **PURPOSE:** Real-time progress tracking for users
6
+ > **Version:** 2.0.0 (Claude 4.5 Optimized)
7
7
 
8
8
  ---
9
9
 
10
10
  ## 🎯 Core Principle
11
11
 
12
- **Main Claude is ALWAYS responsible for updating flags.json**
12
+ **Main Claude updates flags.json after each phase.**
13
13
 
14
- - ❌ NOT sub-agents (they don't have direct access)
15
- - ❌ NOT user (they shouldn't have to)
16
- - ✅ Main Claude after EVERY phase completion
14
+ WHY: Sub-agents don't have direct access to flags.json. Users shouldn't have to manually track progress. Immediate updates ensure accurate /cstatus and /cview output.
17
15
 
18
16
  ---
19
17
 
@@ -24,14 +22,14 @@ Step 1: Sub-agent responds with completion message
24
22
 
25
23
  Step 2: Main Claude validates response quality
26
24
 
27
- Step 3: Main Claude updates flags.json (MANDATORY - THIS STEP!)
25
+ Step 3: Main Claude updates flags.json
28
26
 
29
27
  Step 4: Main Claude reports progress to user
30
28
 
31
29
  Step 5: Main Claude asks to continue (or auto-continue)
32
30
  ```
33
31
 
34
- **⚠️ CRITICAL:** Step 3 CANNOT be skipped. Ever.
32
+ WHY Step 3 is important: Without immediate update, /cstatus shows stale data and users can't track real progress.
35
33
 
36
34
  ---
37
35
 
@@ -279,34 +277,28 @@ function calculateTimeRemaining(flags: Flags): number {
279
277
 
280
278
  ---
281
279
 
282
- ## ⚠️ CRITICAL RULES
280
+ ## 📋 Best Practices
283
281
 
284
- ### Rule 1: NEVER Skip This Step
282
+ ### Update Timing
285
283
 
286
- ```markdown
287
- ❌ WRONG:
288
- Sub-agent completes Main Claude asks user to continue
289
- (flags.json not updated)
284
+ | When | Action |
285
+ |------|--------|
286
+ | Sub-agent returns success | Update flags.json immediately |
287
+ | Before asking user to continue | Flags should already be updated |
288
+ | After each phase | Update individually (not batched) |
290
289
 
291
- CORRECT:
292
- Sub-agent completes → Main Claude updates flags.json → Main Claude reports progress → Main Claude asks user to continue
293
- ```
290
+ WHY: Immediate updates ensure /cstatus always shows accurate progress.
294
291
 
295
- ### Rule 2: Update IMMEDIATELY After Sub-Agent Responds
292
+ ### Correct Flow
296
293
 
297
- ```markdown
298
- Don't wait for:
299
- - User confirmation
300
- - Next phase to start
301
- - Batch multiple updates
302
-
303
- Update:
304
- - ✅ As soon as sub-agent returns success
305
- - ✅ Before asking user anything
306
- - ✅ After EACH individual phase
294
+ ```
295
+ Sub-agent completes
296
+ Main Claude updates flags.json
297
+ Main Claude reports progress
298
+ Main Claude asks user to continue
307
299
  ```
308
300
 
309
- ### Rule 3: Validate Before Update
301
+ ### Validate Before Update
310
302
 
311
303
  ```typescript
312
304
  // Check 1: flags.json exists
@@ -329,10 +321,10 @@ if (!agentResponse.includes('✅') && !agentResponse.includes('Complete')) {
329
321
  }
330
322
  ```
331
323
 
332
- ### Rule 4: Always Report to User
324
+ ### Report to User
333
325
 
334
326
  ```markdown
335
- After updating flags.json, ALWAYS show:
327
+ After updating flags.json, show:
336
328
 
337
329
  📊 Progress Updated:
338
330
  ✅ Phase "frontend-mockup" marked complete
@@ -466,4 +458,4 @@ if (flags.ready_to_archive) {
466
458
 
467
459
  ---
468
460
 
469
- **💡 Remember:** Main Claude updates flags.json. Always. No exceptions.
461
+ **💡 Summary:** Main Claude updates flags.json immediately after each phase completes. This ensures accurate progress tracking.
@@ -815,7 +815,7 @@ Before submitting a new component, verify:
815
815
 
816
816
  ---
817
817
 
818
- ## 🚨 Troubleshooting
818
+ ## 🔧 Troubleshooting
819
819
 
820
820
  ### Colors look different than expected
821
821
 
@@ -109,7 +109,7 @@ Buttons (hover): shadow-sm
109
109
 
110
110
  ---
111
111
 
112
- ## 🚨 Critical Design Rules
112
+ ## ⚠️ Design Rules
113
113
 
114
114
  ### Colors
115
115
  - ❌ **NO** hardcoded colors: `text-gray-500`, `#64748b`
@@ -70,11 +70,14 @@ Create UI components with mockup data. Focus on visual design, layout, and user
70
70
  - Error states: user-friendly messages (mockup errors)
71
71
  - Responsive design: test 3 breakpoints minimum
72
72
 
73
- **CRITICAL RULES:**
74
- - ❌ NO hardcoded colors → ✅ Use theme tokens
75
- - NO arbitrary spacing Use spacing scale
76
- - ❌ NO inconsistent icons → ✅ Match reference components
77
- - NO creating duplicate components Search and reuse first
73
+ **Design Consistency Rules:**
74
+
75
+ | Instead of | Use | WHY |
76
+ |------------|-----|-----|
77
+ | Hardcoded colors | Theme tokens | Maintains dark/light mode support |
78
+ | Arbitrary spacing | Spacing scale (8, 16, 24...) | Consistent visual rhythm |
79
+ | Random icons | Reference component icons | Visual consistency |
80
+ | Creating new components | Search and reuse existing | Prevents duplicates, faster development |
78
81
 
79
82
  ## ✅ Success Criteria
80
83
 
package/README.md CHANGED
@@ -903,60 +903,98 @@ Built with:
903
903
 
904
904
  ---
905
905
 
906
- ## 🆕 What's New in v1.8.0
906
+ ## 🆕 What's New in v2.0.0
907
907
 
908
- **Major: Token Optimization & Streamlined Workflow** 🚀
908
+ **Two Major Improvements:** Claude 4.5 Optimization + Design System v2.0 🚀🎨
909
909
 
910
- ### Key Changes
910
+ ### Part 1: Claude 4.5 Optimization
911
911
 
912
- 1. **Removed `/psetup` and `/agentsetup`** - Best practices now auto-generated by `/csetup`
913
- 2. **Removed documentation/report phases** - No more `PHASE_*.txt`, `*_REPORT.md` clutter
914
- 3. **Verbose terminal output** - Results shown in terminal, not saved to files
915
- 4. **Auto-cleanup temp files** - Any forbidden files auto-deleted after phases
916
- 5. **Agents inject best-practices** - `/cdev` now injects relevant best-practices paths into agent prompts
912
+ 1. **Claude 4.5 Best Practices** - All files refactored for better AI comprehension
913
+ 2. **Professional Tone** - Replaced aggressive language with respectful instructions
914
+ 3. **Positive Instructions** - "Use X" instead of "Don't do Y" with WHY explanations
915
+ 4. **Token Reduction** - Agent files ~65% smaller + 30 supporting files optimized
916
+ 5. **Shared Components** - New `.claude/agents/_shared/` folder prevents duplication
917
917
 
918
- ### Streamlined Workflow
918
+ ### Tone Calibration
919
919
 
920
- **Before (v1.7.x):**
921
- ```bash
922
- /psetup # Setup project
923
- /csetup landing-page # Setup change
924
- /cdev landing-page # Execute
925
- Creates: PHASE_11_DELIVERY.txt, FINAL_REPORT.md, etc. 😞
926
- ```
920
+ | Before | After | WHY |
921
+ |--------|-------|-----|
922
+ | "MUST", "WILL BE REJECTED" | Professional tone | Claude 4.5 works better with respectful instructions |
923
+ | "Don't do X", "Never Y" | "Use X instead" | Positive instructions are clearer |
924
+ | "🚨 CRITICAL!", "🚫 Forbidden" | "📋 Guidelines", "⚠️ Note" | Less aggressive, same clarity |
925
+ | Rules without context | Rules with WHY | Claude applies rules more intelligently |
927
926
 
928
- **After (v1.8.0):**
929
- ```bash
930
- /csetup landing-page # Setup + auto-detect stack + generate best-practices
931
- /cdev landing-page # Execute
932
- Verbose summary in terminal ✅
933
- No temp files created ✅
927
+ ### New Shared Components
928
+
929
+ ```
930
+ .claude/agents/_shared/
931
+ ├── pre-work-checklist.md # Common validation steps
932
+ ├── package-manager.md # Package manager protocol
933
+ ├── documentation-policy.md # What files to create
934
+ ├── agent-boundaries.md # When to use which agent
935
+ └── README.md # Overview
934
936
  ```
935
937
 
936
- ### Token Savings
938
+ ### Token Savings (Agents)
939
+
940
+ | Agent | Before | After | Reduction |
941
+ |-------|--------|-------|-----------|
942
+ | uxui-frontend | ~1037 | ~375 | 64% |
943
+ | integration | ~600 | ~210 | 65% |
944
+ | backend | ~700 | ~244 | 65% |
945
+ | database | ~680 | ~273 | 60% |
946
+ | frontend | ~650 | ~296 | 54% |
947
+ | test-debug | ~580 | ~252 | 57% |
948
+ | **Total** | **~4247** | **~1650** | **61%** |
949
+
950
+ Plus ~500 tokens in shared files = **~2150 total** (was ~4247)
951
+
952
+ ### Part 2: Design System v2.0
953
+
954
+ **Complete overhaul of design system with interactive setup, theme selection, and smart page planning.**
955
+
956
+ ### New Design System Features
957
+
958
+ - 🎯 **`/extract`** - Multi-URL design extraction with style detection
959
+ - 🎭 **`/designsetup`** - Interactive 3-round loop with theme recommendations
960
+ - 📦 **`tokens.json`** - Enhanced design tokens with style/theme/animations (~800 tokens)
961
+ - 📝 **`patterns/*.md`** - Selective code patterns (buttons, cards, forms, scroll-animations, decorations)
962
+ - 🔍 **Auto Page Type Detection** - `/pageplan` auto-detects landing/dashboard/auth
937
963
 
938
- | Template | Before | After | Saved |
939
- |----------|--------|-------|-------|
940
- | full-stack | 19 phases | 17 phases | ~25 min |
941
- | frontend-only | 11 phases | 9 phases | ~25 min |
942
- | backend-only | 10 phases | 8 phases | ~25 min |
943
- | bug-fix | 5 phases | 4 phases | ~10 min |
964
+ ### Page Type Handling
944
965
 
945
- ### Forbidden Files (Auto-Deleted)
966
+ | Page Type | Decorations | Scroll Anims | Buyer Avatar | Patterns Loaded |
967
+ |-----------|-------------|--------------|--------------|-----------------|
968
+ | Landing/Marketing | ✅ Full | ✅ Enabled | ✅ Enabled | buttons, cards, scroll-anims, decorations |
969
+ | Dashboard/Admin | ❌ Minimal | ❌ Disabled | ❌ Skipped | buttons, cards, forms |
970
+ | Auth (Login/Register) | ❌ None | ❌ Disabled | ❌ Skipped | buttons, forms |
946
971
 
947
- Agents should only create **actual code files**. These are now forbidden:
948
- - Report/summary files (`*_REPORT.md`, `*_SUMMARY.txt`)
949
- - Phase output files (`PHASE_*.txt`, `*_DELIVERY.txt`)
950
- - Temp files (ALL_CAPS filenames)
972
+ ### Design System Token Savings
951
973
 
952
- **Rule of thumb:** If it wouldn't be committed to git, don't create it.
974
+ | Approach | Tokens | Improvement |
975
+ |----------|--------|-------------|
976
+ | Old: Full STYLE_GUIDE.md | ~5000 | - |
977
+ | New: tokens.json + selective patterns | ~800-1200 | **84%** |
953
978
 
954
- ### Best Practices Now Enforced
979
+ ### Files Refactored (36 total)
955
980
 
956
- - `/csetup` auto-detects stack from: `package.json` `design.md` → `proposal.md`
957
- - Auto-generates best practices from Context7 MCP
958
- - `/cdev` injects relevant files into agent prompts
959
- - Agents MUST report "Best Practices Loaded" (validated)
981
+ - **6 agent files** - Professional tone, positive instructions
982
+ - **6 lib files** - WHY explanations, table formats
983
+ - **4 command files** - Softer language, guidelines
984
+ - **11 pattern files** - "⚠️ Common Mistakes" instead of "🚨 Critical"
985
+ - **3 design files** - "should check" instead of "MUST check"
986
+ - **3 template files** - Table with WHY
987
+ - **3 other lib files** - Consistent formatting
988
+
989
+ ### Best Practices Applied (Claude 4 Guidelines)
990
+
991
+ 1. **Tone Calibration** - Professional, direct (not aggressive)
992
+ 2. **Action Orientation** - Explicit "Write code" vs "Consider"
993
+ 3. **Prevent Overengineering** - Clear boundaries
994
+ 4. **Encourage Exploration** - Read before implementing
995
+ 5. **Rich Output When Needed** - Specify requirements
996
+ 6. **Context for Rules** - Explain WHY
997
+ 7. **Positive Instructions** - "Use X" not "Don't Y"
960
998
 
961
999
  ---
962
1000
 
@@ -1265,6 +1303,27 @@ All your customizations in `.claude/contexts/domain/` are preserved!
1265
1303
 
1266
1304
  ## 📜 Changelog
1267
1305
 
1306
+ ### v2.0.0 (2025-11-30)
1307
+ **Major: Claude 4.5 Optimization - Full Template Refactor**
1308
+
1309
+ **Added:**
1310
+ - Shared components folder `.claude/agents/_shared/`
1311
+ - WHY explanations for all rules
1312
+
1313
+ **Changed:**
1314
+ - All 6 agent files refactored (~65% smaller)
1315
+ - 30 supporting files updated for Claude 4.5 best practices
1316
+ - "MUST", "CRITICAL" → Professional tone
1317
+ - "Don't do X" → "Use Y instead" with WHY
1318
+ - "🚨" → "⚠️" throughout
1319
+
1320
+ **Benefits:**
1321
+ - Better AI comprehension with professional tone
1322
+ - 61% token reduction in agent files
1323
+ - No duplication (shared components)
1324
+
1325
+ ---
1326
+
1268
1327
  ### v1.8.0 (2025-11-26)
1269
1328
  **Major: Token Optimization & Streamlined Workflow**
1270
1329
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@champpaba/claude-agent-kit",
3
- "version": "1.8.0",
3
+ "version": "2.0.1",
4
4
  "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
5
5
  "main": "bin/cli.js",
6
6
  "bin": {