@champpaba/claude-agent-kit 1.8.0 → 2.0.1

package/.claude/agents/_shared/README.md

@@ -0,0 +1,57 @@
+# Shared Agent Components
+
+> **Version:** 2.0.0 (Claude 4.5 Optimized)
+> **Purpose:** Single source of truth for content shared across all 6 agents
+
+---
+
+## Why This Exists
+
+**Before v2.0.0:**
+- Same content duplicated 6 times (once per agent)
+- ~3,000 tokens wasted on duplication
+- Updates required changing 6 files
+
+**After v2.0.0:**
+- Shared content in `_shared/` folder
+- Agents reference with 1-line link
+- ~2,500 tokens saved (83% reduction)
+- Updates require changing 1 file
+
+---
+
+## Files in This Folder
+
+| File | Purpose | Token Savings |
+|------|---------|---------------|
+| `pre-work-checklist.md` | Validation before implementation | ~200 tokens × 6 |
+| `package-manager.md` | Package manager protocol | ~100 tokens × 6 |
+| `documentation-policy.md` | What files agents can create | ~70 tokens × 6 |
+| `agent-boundaries.md` | When to use which agent | ~80 tokens × 6 |
+
+---
+
+## How Agents Reference
+
+Instead of duplicating content, agents use:
+
+```markdown
+## Pre-Work Checklist
+→ See `.claude/agents/_shared/pre-work-checklist.md`
+```
+
+This approach:
+- Saves tokens (1 line vs 30 lines)
+- Ensures consistency (single source of truth)
+- Simplifies maintenance (update once)
+
+---
+
+## Claude 4.5 Optimization Notes
+
+These files follow Claude 4.5 best practices:
+
+1. **Professional tone** - No aggressive CAPS or threats
+2. **Positive instructions** - "Use X" instead of "Don't use Y"
+3. **WHY context** - Each rule explains its purpose
+4. **Concise format** - Tables and bullet points, not prose

package/.claude/agents/_shared/agent-boundaries.md

@@ -0,0 +1,64 @@
+# Agent Boundaries (Shared Reference)
+
+> **Purpose:** Clear boundaries prevent agents from doing wrong work
+
+---
+
+## Why Boundaries Matter
+
+Without clear boundaries:
+- Agents overlap work (duplicate effort)
+- Wrong agent does wrong task (quality drops)
+- Integration issues (mismatched interfaces)
+
+With clear boundaries:
+- Each agent focuses on specialty
+- Clean handoffs between phases
+- Higher quality output
+
+---
+
+## Agent Routing Quick Reference
+
+| Task Type | Use Agent | Phase |
+|-----------|-----------|-------|
+| UI components (mock data) | uxui-frontend | 1 |
+| API endpoints | backend | 2 |
+| Database schemas/migrations | database | 2 |
+| Contract validation | integration | 2.5 |
+| Connect UI to API | frontend | 3 |
+| Tests, bugs, debugging | test-debug | 1,3,4 |
+
+---
+
+## Boundary Violations to Avoid
+
+**uxui-frontend:**
+- Uses mock data with setTimeout
+- Connect to real APIs → use frontend agent instead
+
+**frontend:**
+- Connects existing UI to real APIs
+- Create new UI from scratch → use uxui-frontend instead
+
+**backend:**
+- Creates API endpoints with validation
+- Write database queries directly → use database agent instead
+
+**database:**
+- Creates schemas, migrations, typed queries
+- Write API logic → use backend agent instead
+
+---
+
+## Why Agent Specialization Works
+
+Each agent has deep context for its domain:
+- uxui-frontend: Design patterns, accessibility, visual consistency
+- backend: Security patterns, validation, error handling
+- database: Query optimization, indexes, relationships
+- integration: Contract validation, type safety
+- frontend: State management, API integration, error UI
+- test-debug: Test patterns, debugging, coverage
+
+→ Full routing rules: `.claude/lib/agent-router.md`

package/.claude/agents/_shared/documentation-policy.md

@@ -0,0 +1,47 @@
+# Documentation Policy v1.8.0 (Shared by All Agents)
+
+> **Purpose:** Single source of truth for what files agents create
+
+---
+
+## Core Principle
+
+Agents create **code files only**. Results go to terminal output.
+
+---
+
+## Allowed Files
+
+- Source code (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, etc.)
+- Config files (`package.json`, `tsconfig.json`, `.env.example`)
+- Schema files (`schema.prisma`, `models.py`)
+- Test files (`*.test.ts`, `*.spec.ts`, `test_*.py`)
+- Style files (`.css`, `.scss`, `tailwind.config.js`)
+
+---
+
+## Forbidden Files (Auto-Deleted)
+
+These files waste tokens and clutter the project:
+
+| Pattern | Example | Why Forbidden |
+|---------|---------|---------------|
+| `*_REPORT.md` | `IMPLEMENTATION_REPORT.md` | Use terminal output |
+| `*_SUMMARY.txt` | `PHASE_SUMMARY.txt` | Use terminal output |
+| `PHASE_*.txt` | `PHASE_11_DELIVERY.txt` | Removed in v1.8.0 |
+| ALL_CAPS filenames | `README_FINAL.md` | Usually temp files |
+
+---
+
+## Rule of Thumb
+
+> If it wouldn't be committed to git, don't create it.
+
+---
+
+## Why This Matters
+
+Token optimization:
+- Report files waste 500-2000 tokens each
+- v1.8.0 removed doc/report phases for 25 min savings
+- Terminal output is sufficient for status updates

package/.claude/agents/_shared/package-manager.md

@@ -0,0 +1,59 @@
+# Package Manager Protocol (Shared by All Agents)
+
+> **Version:** 2.0.0 (Claude 4.5 Optimized)
+> **Purpose:** Single source of truth for package manager usage
+
+---
+
+## Quick Rule
+
+Read `tech-stack.md` before ALL install/run commands.
+
+```bash
+# Location:
+.claude/contexts/domain/{project}/tech-stack.md
+```
+
+---
+
+## Why This Matters
+
+Using wrong package manager causes:
+- Duplicate lock files (package-lock.json + pnpm-lock.yaml)
+- CI/CD pipeline failures
+- Version conflicts
+- Incorrect dependency locations
+
+---
+
+## Protocol
+
+**Step 1:** Read tech-stack.md
+
+**Step 2:** Extract and use detected tool
+
+| If Detected | Install Command | Run Command |
+|-------------|-----------------|-------------|
+| pnpm | `pnpm install {pkg}` | `pnpm run {script}` |
+| npm | `npm install {pkg}` | `npm run {script}` |
+| bun | `bun add {pkg}` | `bun run {script}` |
+| uv | `uv pip install {pkg}` | `uv run {script}` |
+| poetry | `poetry add {pkg}` | `poetry run {cmd}` |
+
+**Step 3:** Report in validation
+
+```
+Package Manager: pnpm (from tech-stack.md)
+```
+
+---
+
+## If tech-stack.md Missing
+
+```
+Warning: tech-stack.md not found
+Suggestion: Run /csetup to generate tech-stack.md
+Fallback: Detect from package.json or pyproject.toml
+```
+
+→ Full details: `.claude/lib/context-loading-protocol.md#level-0`

package/.claude/agents/_shared/pre-work-checklist.md

@@ -0,0 +1,57 @@
+# Pre-Work Checklist (Shared by All Agents)
+
+> **Version:** 2.0.0 (Claude 4.5 Optimized)
+> **Purpose:** Single source of truth for pre-work validation
+
+---
+
+## Pre-Work Steps
+
+Complete these steps before implementation to ensure alignment with project standards:
+
+1. **Context Discovery** - Load project context via agent-discovery.md
+2. **Pattern Loading** - Load relevant patterns for your agent type
+3. **Validation Report** - Provide pre-implementation validation report
+4. **Wait for Approval** - Proceed only after orchestrator validation
+
+→ Details: `.claude/contexts/patterns/validation-framework.md` (agent-specific sections)
+
+---
+
+## Validation Report Template
+
+```markdown
+Pre-Implementation Validation
+
+Project Context:
+- Project: {name}
+- Stack: {tech-stack}
+- Package Manager: {pm} (from tech-stack.md)
+
+Patterns Loaded:
+- [ ] error-handling.md
+- [ ] logging.md
+- [ ] testing.md
+- [ ] code-standards.md
+- [ ] {agent-specific patterns}
+
+Best Practices:
+- [ ] {framework} best practices loaded (from Context7)
+
+Ready to Implement:
+- [ ] Task understood
+- [ ] Dependencies identified
+- [ ] Approach planned
+```
+
+---
+
+## Why This Matters
+
+Pre-work validation prevents:
+- Misaligned implementations (wrong patterns, wrong style)
+- Duplicate components (not searching existing code first)
+- Wrong package manager usage (CI/CD breaks)
+- Missing best practices (outdated patterns)
+
+→ 80% of implementation issues caught at validation stage

package/.claude/commands/cdev.md

@@ -108,7 +108,7 @@ ${changeContext.tasks}
 ${phase.instructions}
 `
 
-  // 🆕 v1.8.0: Add best-practices reference for ALL agents
+  // Add best-practices reference for ALL agents
   const bpDir = '.claude/contexts/domain/project/best-practices/'
   if (fileExists(bpDir)) {
     const bpFiles = listFiles(bpDir).filter(f => f.endsWith('.md') && f !== 'index.md')
@@ -133,24 +133,19 @@ ${phase.instructions}
 
 ---
 
-## 📚 Best Practices (MANDATORY - STEP 0)
+## 📚 Best Practices (STEP 0)
 
-**YOU MUST READ these files before writing ANY code:**
+Read these files before implementation for quality output:
 
-${relevantFiles.map(f => `
-### ${f.replace('.md', '')}
-\`\`\`
-Read: ${bpDir}${f}
-\`\`\`
-`).join('')}
+${relevantFiles.map(f => `- Read: ${bpDir}${f}`).join('\n')}
 
-**After reading, REPORT:**
+**Report format:**
 \`\`\`
 ✅ Best Practices Loaded
    ${relevantFiles.map(f => `- ${f.replace('.md', '')} ✓`).join('\n   ')}
 \`\`\`
 
-**If you skip this, your work will be REJECTED!**
+WHY: Best practices ensure consistency with project patterns.
 
 ---
 `
@@ -169,45 +164,29 @@ Read: ${bpDir}${f}
 
 ---
 
-## 🎨 Design System (MANDATORY Reading - STEP 0.5)
-
-**Required Files (YOU MUST READ in STEP 0.5):**
-
-${hasTokens ? `
-1. **STYLE_TOKENS.json** (~500 tokens) ✅ REQUIRED
-   \`\`\`
-   Read: design-system/STYLE_TOKENS.json
-   \`\`\`
-   Contains: Colors, spacing, typography, shadows, borders, animations
-` : ''}
-
-${hasStyleGuide ? `
-2. **STYLE_GUIDE.md** (selective sections ~2K tokens) 📖 OPTIONAL
-   \`\`\`
-   Read: design-system/STYLE_GUIDE.md
-   \`\`\`
-   Load only sections you need:
-   - Section 6: Component Styles
-   - Section 15: Layout Patterns
-   - Section 16: Example Component Reference
-` : ''}
-
-**Critical Rules:**
-- ❌ **NO** hardcoded colors: \`text-gray-500\`, \`#64748b\`
-- ✅ **USE** theme tokens: \`text-foreground/70\`, \`bg-muted\`
-- ❌ **NO** arbitrary spacing: \`p-5\`, \`gap-7\`
-- ✅ **USE** spacing scale: \`p-4\`, \`p-6\`, \`gap-8\`
-- ❌ **NO** inconsistent shadows: mixing \`shadow-sm\` and \`shadow-lg\`
-- ✅ **USE** consistent patterns: all cards use \`shadow-md\`
-
-**YOU MUST REPORT:**
+## 🎨 Design System (STEP 0.5)
+
+**Files to read:**
+
+${hasTokens ? `- design-system/STYLE_TOKENS.json (~500 tokens) - Colors, spacing, typography` : ''}
+${hasStyleGuide ? `- design-system/STYLE_GUIDE.md (selective sections) - Component Styles, Layout Patterns` : ''}
+
+**Style Guidelines:**
+
+| Instead of | Use | WHY |
+|------------|-----|-----|
+| text-gray-500, #64748b | text-foreground/70, bg-muted | Theme-aware |
+| p-5, gap-7 | p-4, p-6, gap-8 | Spacing scale |
+| mixing shadow-sm/lg | consistent shadow-md | Visual consistency |
+
+**Report format:**
 \`\`\`
 ✅ Design System Loaded
    - STYLE_TOKENS.json ✓
    - Design Tokens Extracted: [list key tokens]
 \`\`\`
 
-If you skip this, your work will be REJECTED!
+WHY: Design tokens ensure visual consistency across components.
 
 ---
 `
@@ -404,16 +383,18 @@ if (phase.agent === 'uxui-frontend' && hasPagePlan) {
 
 ---
 
-### Step 5: Post-Execution (🆕 MANDATORY FLAGS UPDATE)
+### Step 5: Post-Execution (Flags Update)
+
+**Main Claude updates flags.json after each phase completion.**
 
-**⚠️ CRITICAL: Main Claude MUST update flags.json after EVERY phase completion**
+→ See: `.claude/lib/flags-updater.md` for complete protocol
 
-See: `.claude/lib/flags-updater.md` for complete protocol
+WHY: Immediate updates ensure /cstatus shows accurate progress.
 
-**Execution Order (MUST follow this sequence):**
+**Execution Order:**
 
 ```typescript
-// 1. MANDATORY: Update flags.json
+// 1. Update flags.json
 output(`\n🔄 Updating progress tracking...`)
 
 // See flags-updater.md for updateFlagsAfterPhase() implementation
@@ -516,19 +497,13 @@ if (flags.ready_to_archive) {
 }
 ```
 
-**Rules:**
-- ✅ Main Claude updates flags.json (NOT sub-agent)
-- ✅ Update happens IMMEDIATELY after sub-agent responds successfully
-- ✅ Update happens BEFORE asking user to continue
-- ✅ Progress is reported to user after EVERY update
-- ✅ No exceptions - even if agent "says" it updated flags
+**Key points:**
+- Main Claude updates flags.json (sub-agents don't have access)
+- Update happens immediately after sub-agent responds
+- Update happens before asking user to continue
 
-**Common Mistake:**
-```typescript
-❌ WRONG:
-Agent completes → Ask user to continue → (flags.json never updated)
-
-✅ CORRECT:
+**Correct flow:**
+```
 Agent completes → Update flags.json → Report progress → Ask user to continue
 ```
 

package/.claude/commands/csetup.md

@@ -44,23 +44,54 @@ Read in order:
 
 ---
 
-### Step 2.5: Validate Design System (Context Optimization v1.2.0)
+### Step 2.5: Validate Design System & Page Plan (v2.0.0)
 
-> **New:** Validate design files exist for UI work
+> **Updated v2.0.0:** Validate design files + read page-plan.md if exists
 
 ```typescript
 // Detect if change involves UI/frontend work
 const tasksContent = Read('openspec/changes/{change-id}/tasks.md')
 const hasFrontend = tasksContent.toLowerCase().match(/(ui|component|page|frontend|design|responsive)/i)
 
+let tokens = null
+let pagePlan = null
+let pageType = 'generic'
+
 if (hasFrontend) {
   output(`\n🎨 UI work detected - validating design system...`)
 
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
+  const tokensPath = 'design-system/tokens.json' // v2.0 tokens
   const styleGuidePath = 'design-system/STYLE_GUIDE.md'
+  const pagePlanPath = `openspec/changes/${changeId}/page-plan.md`
 
   const hasTokens = fileExists(tokensPath)
   const hasStyleGuide = fileExists(styleGuidePath)
+  const hasPagePlan = fileExists(pagePlanPath)
+
+  // ========== LOAD tokens.json (v2.0 structure) ==========
+  if (hasTokens) {
+    tokens = JSON.parse(Read(tokensPath))
+    output(`✅ tokens.json Loaded:`)
+    output(`   - Style: ${tokens.style.name}`)
+    output(`   - Theme: ${tokens.theme.name}`)
+    output(`   - Animations: ${tokens.animations.enabled ? 'Enabled' : 'Disabled'}`)
+  }
+
+  // ========== LOAD page-plan.md (if exists) ==========
+  if (hasPagePlan) {
+    pagePlan = Read(pagePlanPath)
+    output(`✅ page-plan.md Found`)
+
+    // Extract page type from page-plan.md
+    const pageTypeMatch = pagePlan.match(/Page Type:\*\*\s*(.*)/i)
+    if (pageTypeMatch) {
+      pageType = pageTypeMatch[1].trim().toLowerCase()
+      output(`   - Page Type: ${pageType}`)
+    }
+  } else {
+    output(`ℹ️ page-plan.md not found (optional)`)
+    output(`   → Run /pageplan first for better component planning`)
+  }
 
   if (!hasTokens || !hasStyleGuide) {
     warn(`
@@ -68,7 +99,8 @@ if (hasFrontend) {
 
 Found:
   ${hasStyleGuide ? '✅' : '❌'} STYLE_GUIDE.md
-  ${hasTokens ? '✅' : '❌'} STYLE_TOKENS.json
+  ${hasTokens ? '✅' : '❌'} tokens.json
+  ${hasPagePlan ? '✅' : '❌'} page-plan.md
 
 This may result in:
   - Inconsistent colors (random hex codes)
@@ -77,7 +109,8 @@ This may result in:
 
 Recommendation:
   1. Run: /designsetup
-  2. Then: /csetup ${changeId}
+  2. Run: /pageplan @prd.md (optional but recommended)
+  3. Then: /csetup ${changeId}
 
 Continue anyway? (yes/no)
     `)
@@ -89,7 +122,8 @@ Continue anyway? (yes/no)
   } else {
     output(`✅ Design System Ready`)
     output(`   - STYLE_GUIDE.md ✓`)
-    output(`   - STYLE_TOKENS.json ✓`)
+    output(`   - tokens.json ✓`)
+    if (hasPagePlan) output(`   - page-plan.md ✓`)
   }
 }
 ```
@@ -276,13 +310,13 @@ function generateBestPracticesFile(tech: string, context7Docs: string): string {
 
 ---
 
-## ✅ DO (Best Practices)
+## Best Practices
 
 ${extractDos(context7Docs)}
 
 ---
 
-## ❌ DON'T (Anti-Patterns)
+## Anti-Patterns to Avoid
 
 ${extractDonts(context7Docs)}
 
@@ -295,7 +329,7 @@ ${extractChecklist(context7Docs)}
 
 ---
 
-**⚠️ Agents MUST read this file before writing ${tech} code!**
+**Agents read this file in STEP 0 before implementation.**
 `
 }
 ```
@@ -453,7 +487,7 @@ const taskAnalysis = {
    🟢 LOW: 1 task (Documentation)
 
 ⚠️ Risk Assessment:
-   🚨 HIGH risk: 2 tasks (Payment integration, Auth system)
+   🔴 HIGH risk: 2 tasks (Payment integration, Auth system)
       → Mitigation: TDD required, security checklist
    ⚠️ MEDIUM risk: 3 tasks
    ✅ LOW risk: 3 tasks
@@ -593,7 +627,7 @@ const allPhases = [...researchPhases, ...phaseSections]
 - 🟢 LOW: {taskAnalysis.summary.priority.low}
 
 **Risk Assessment:**
-- 🚨 HIGH risk: {taskAnalysis.summary.risk.high} tasks
+- 🔴 HIGH risk: {taskAnalysis.summary.risk.high} tasks
 - ⚠️ MEDIUM risk: {taskAnalysis.summary.risk.medium} tasks
 - ✅ LOW risk: {taskAnalysis.summary.risk.low} tasks
 
@@ -799,39 +833,67 @@ const projectTech = Read('.claude/contexts/domain/project/tech-stack.md')
 // Detect additional tech from proposal/tasks
 const additionalTech = detectAdditionalTech(proposalContent, tasksContent)
 
-// 🆕 Load design info (if UI work)
+// 🆕 Load design info (if UI work) - v2.0.0
 let designInfo = ''
-if (hasFrontend) {
-  const tokensPath = 'design-system/STYLE_TOKENS.json'
-
-  if (fileExists(tokensPath)) {
-    const tokens = JSON.parse(Read(tokensPath))
-
-    designInfo = `
-## 🎨 Design System (Context Optimization v1.2.0)
-
-**Design Files (Token-Efficient):**
-- STYLE_TOKENS.json: \`design-system/STYLE_TOKENS.json\` (~500 tokens)
-- STYLE_GUIDE.md: \`design-system/STYLE_GUIDE.md\` (~5000 tokens, load selectively)
-
-**Key Design Tokens:**
-- Primary Color: ${tokens.tokens.colors.primary.DEFAULT}
+if (hasFrontend && tokens) {
+  designInfo = `
+## 🎨 Design System (v2.0.0)
+
+**Design Files:**
+- tokens.json: \`design-system/tokens.json\` (~800 tokens)
+- patterns/: \`design-system/patterns/*.md\` (selective loading)
+- STYLE_GUIDE.md: \`design-system/STYLE_GUIDE.md\` (human-readable, ~150 lines)
+${pagePlan ? `- page-plan.md: \`openspec/changes/${changeId}/page-plan.md\` ✅` : ''}
+
+**Style Direction:**
+- Style: ${tokens.style.name}
+- Theme: ${tokens.theme.name}
+- Feel: ${tokens.style.feel}
+
+**Design Tokens:**
+- Primary Color: ${tokens.colors.primary.DEFAULT}
 - Component Library: ${tokens.component_library.name}
-- Spacing Scale: ${tokens.tokens.spacing.scale.join(', ')}px
-- Shadows: ${Object.keys(tokens.tokens.shadows).slice(0, 5).join(', ')}
+- Spacing Scale: ${tokens.spacing.scale.join(', ')}px
+- Animations: ${tokens.animations.enabled ? 'Enabled' : 'Disabled'}
+
+**Theme & Decorations:**
+${pageType.includes('landing') || pageType.includes('marketing') ? `
+- Decorations: ✅ Enabled
+- USE: ${tokens.theme.decorative_elements.use.slice(0, 3).join(', ')}
+- AVOID: ${tokens.theme.decorative_elements.avoid.slice(0, 2).join(', ') || '(none)'}
+- Scroll Animations: ✅ Enabled
+` : `
+- Decorations: ❌ Disabled (${pageType} page)
+- Scroll Animations: ❌ Disabled
+`}
+
+**Pattern Files to Load:**
+${pageType.includes('landing') || pageType.includes('marketing') ?
+`- patterns/buttons.md ✅
+- patterns/cards.md ✅
+- patterns/scroll-animations.md ✅
+- patterns/decorations.md ✅` :
+pageType.includes('auth') ?
+`- patterns/buttons.md ✅
+- patterns/forms.md ✅` :
+`- patterns/buttons.md ✅
+- patterns/cards.md ✅
+- patterns/forms.md ✅`}
 
 **Agent Loading (STEP 0.5 for uxui-frontend):**
-1. Read: STYLE_TOKENS.json (~500 tokens) ✅
-2. Optional: STYLE_GUIDE.md (selective sections ~2K tokens)
-3. Report: Design tokens extracted
-
-**Critical Rules:**
-- ❌ NO hardcoded colors (text-gray-500)
-- ✅ USE theme tokens (text-foreground/70)
-- ❌ NO arbitrary spacing (p-5)
-- ✅ USE spacing scale (p-4, p-6)
+1. Read: tokens.json (~800 tokens)
+2. Read: page-plan.md (if exists)
+3. Load patterns selectively based on page type
+4. Report: Design tokens + page type extracted
+
+**Style Guidelines:**
+
+| Instead of | Use | WHY |
+|------------|-----|-----|
+| text-gray-500 | text-foreground/70 | Theme-aware |
+| p-5 | p-4 or p-6 | Spacing scale |
+| ${pageType.includes('landing') ? '✅ Apply decorations from theme' : '❌ Skip decorations for this page type'} | | |
 `
-  }
 }
 
 // Replace placeholders