@champpaba/claude-agent-kit 2.0.0 → 2.1.0

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

@@ -35,6 +35,81 @@ If not found:
 Please create the change with OpenSpec first
 ```
 
+### Step 1.5: Read PROJECT_STATUS.yml (v2.1.0)
+
+**WHY:** Cross-session context helps understand blockers and infrastructure state before starting work.
+
+```typescript
+const projectStatusPath = 'PROJECT_STATUS.yml'
+
+if (fileExists(projectStatusPath)) {
+  const projectStatus = parseYaml(Read(projectStatusPath))
+
+  output(`\n📊 Project Context (from PROJECT_STATUS.yml)`)
+
+  // Show current focus
+  if (projectStatus.current_focus?.description) {
+    output(`   Focus: ${projectStatus.current_focus.description}`)
+  }
+
+  // Check for blockers that might affect this change
+  if (projectStatus.blockers?.length > 0) {
+    const relevantBlockers = projectStatus.blockers.filter(b =>
+      b.blocks?.some(blocked =>
+        blocked.toLowerCase().includes(changeId.toLowerCase()) ||
+        changeId.toLowerCase().includes(blocked.toLowerCase())
+      )
+    )
+
+    if (relevantBlockers.length > 0) {
+      output(`\n   ⚠️ Potential blockers for this change:`)
+      relevantBlockers.forEach(b => {
+        output(`      - ${b.id}: ${b.description}`)
+      })
+      output(`\n   Consider resolving blockers before starting.`)
+    }
+  }
+
+  // Show infrastructure status summary
+  if (projectStatus.infrastructure) {
+    const downServices = Object.entries(projectStatus.infrastructure)
+      .filter(([_, info]) => info.status === 'down' || info.status === 'degraded')
+
+    if (downServices.length > 0) {
+      output(`\n   ⚠️ Infrastructure issues:`)
+      downServices.forEach(([service, info]) => {
+        output(`      - ${service}: ${info.status}${info.notes ? ` (${info.notes})` : ''}`)
+      })
+    }
+  }
+
+  // Check stale status
+  const lastUpdated = new Date(projectStatus.last_updated)
+  const daysSinceUpdate = Math.floor((Date.now() - lastUpdated) / (1000 * 60 * 60 * 24))
+  const staleThreshold = projectStatus._config?.stale_warning_days || 7
+
+  if (daysSinceUpdate > staleThreshold) {
+    output(`\n   ℹ️ PROJECT_STATUS.yml last updated ${daysSinceUpdate} days ago.`)
+    output(`      Consider running /pstatus to refresh.`)
+  }
+
+  // Update active change
+  if (projectStatus.current_focus?.active_change !== changeId) {
+    output(`\n   📍 Update current_focus.active_change to "${changeId}"? (yes/no)`)
+    const updateFocus = await askUser()
+    if (updateFocus) {
+      projectStatus.current_focus = projectStatus.current_focus || {}
+      projectStatus.current_focus.active_change = changeId
+      projectStatus.last_updated = new Date().toISOString().split('T')[0]
+      Write(projectStatusPath, toYaml(projectStatus))
+      output(`   ✅ Updated active_change to "${changeId}"`)
+    }
+  }
+
+  output(``) // Blank line
+}
+```
+
 ### Step 2: Read OpenSpec Files
 
 Read in order:
@@ -310,13 +385,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)}
 
@@ -329,7 +404,7 @@ ${extractChecklist(context7Docs)}
 
 ---
 
-**⚠️ Agents MUST read this file before writing ${tech} code!**
+**Agents read this file in STEP 0 before implementation.**
 `
 }
 ```
@@ -487,7 +562,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
@@ -627,7 +702,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
 
@@ -880,18 +955,19 @@ pageType.includes('auth') ?
 - patterns/cards.md ✅
 - patterns/forms.md ✅`}
 
-**Agent Instructions (uxui-frontend STEP 0.5):**
-1. Read: tokens.json (~800 tokens) ✅
-2. Read: page-plan.md (if exists) ✅
+**Agent Loading (STEP 0.5 for uxui-frontend):**
+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
 
-**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)
-- ${pageType.includes('landing') ? '✅ Apply decorations from theme' : '❌ Skip decorations for this page type'}
+**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'} | | |
 `
 }