@champpaba/claude-agent-kit 1.0.0

package/lib/update.js

@@ -0,0 +1,73 @@
+/**
+ * Update Command - Update Claude Agent Kit template to latest version
+ *
+ * This function updates the .claude/ folder with the latest template files.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+module.exports = async function update(options = {}) {
+  const { backup } = options;
+
+  // Paths
+  const templatePath = path.join(__dirname, '../template/.claude');
+  const targetPath = path.join(process.cwd(), '.claude');
+  const backupPath = path.join(process.cwd(), '.claude.backup');
+
+  console.log(chalk.cyan('\n🤖 Claude Agent Kit - Updating...\n'));
+
+  // Check if .claude/ exists
+  if (!fs.existsSync(targetPath)) {
+    console.log(chalk.yellow('⚠️  .claude/ not found in this project.'));
+    console.log(chalk.gray('   Run init first:\n'));
+    console.log(chalk.cyan('   cak init\n'));
+    return;
+  }
+
+  // Check if template exists
+  if (!fs.existsSync(templatePath)) {
+    throw new Error('Template folder not found. Please reinstall the package.');
+  }
+
+  // Create backup if requested
+  if (backup) {
+    console.log(chalk.gray('📦 Creating backup...\n'));
+
+    // Remove old backup if exists
+    if (fs.existsSync(backupPath)) {
+      await fs.remove(backupPath);
+    }
+
+    // Copy current .claude/ to backup
+    await fs.copy(targetPath, backupPath);
+    console.log(chalk.green('✅ Backup created: ') + chalk.cyan('.claude.backup\n'));
+  }
+
+  // Update template
+  try {
+    // Strategy: Overwrite all files from template
+    // User customizations in domain/ should be preserved if they don't conflict
+    await fs.copy(templatePath, targetPath, {
+      overwrite: true,
+      errorOnExist: false
+    });
+
+    console.log(chalk.green('✅ Successfully updated Claude Agent Kit!\n'));
+    console.log(chalk.white('📁 Updated files in: ') + chalk.cyan(targetPath));
+
+    if (backup) {
+      console.log(chalk.white('\n💾 Backup available at: ') + chalk.cyan(backupPath));
+      console.log(chalk.gray('   You can restore it if needed:\n'));
+      console.log(chalk.cyan('   rm -rf .claude && mv .claude.backup .claude\n'));
+    }
+
+    console.log(chalk.white('\n📚 What\'s new:\n'));
+    console.log(chalk.gray('   Check CHANGELOG.md for latest changes'));
+    console.log(chalk.gray('   Or visit: ') + chalk.cyan('https://github.com/your-username/claude-agent-kit\n'));
+
+  } catch (error) {
+    throw new Error(`Failed to update template: ${error.message}`);
+  }
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@champpaba/claude-agent-kit",
+  "version": "1.0.0",
+  "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
+  "main": "bin/cli.js",
+  "bin": {
+    "claude-agent-kit": "./bin/cli.js",
+    "cak": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "multi-agent",
+    "template",
+    "cli",
+    "development",
+    "automation"
+  ],
+  "author": "ChampPABA <aimilic@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChampPABA/claude-multi-agent-template"
+  },
+  "bugs": {
+    "url": "https://github.com/ChampPABA/claude-multi-agent-template/issues"
+  },
+  "homepage": "https://github.com/ChampPABA/claude-multi-agent-template#readme",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/template/.claude/CHANGELOG-v1.1.1.md

@@ -0,0 +1,259 @@
+# Changelog v1.1.1 - Critical Fixes
+
+> **Release Date:** 2025-10-31
+> **Type:** Bug fixes and enforcement improvements
+> **Status:** Production-ready
+
+---
+
+## 🎯 Problem Statement
+
+Two critical issues identified in real-world usage:
+
+1. **Main Agent Not Updating flags.json**
+   - Users couldn't track progress
+   - flags.json rarely updated after phase completion
+   - ~30% update rate (should be 100%)
+
+2. **Main Agent Doing Work Directly**
+   - Implementation work not delegated to specialized agents
+   - Only ~60% proper delegation rate (should be 95%+)
+   - Lost benefits of specialized agents
+
+---
+
+## 🔧 Solutions Implemented
+
+### ✅ Solution 1: Mandatory Progress Tracking
+
+**New File:** `.claude/lib/flags-updater.md`
+
+**What it does:**
+- Defines WHO updates flags.json: Main Claude (NOT sub-agents)
+- Defines WHEN: Immediately after sub-agent completes
+- Defines HOW: Exact implementation with helper functions
+- Provides parsing utilities for extracting files, tasks, duration
+
+**Key Features:**
+```typescript
+updateFlagsAfterPhase(changeId, phaseName, agentResponse)
+  → Extracts files created/modified
+  → Calculates actual duration
+  → Updates meta statistics (progress %, time remaining)
+  → Moves to next phase
+  → Reports to user
+```
+
+**Enforcement:**
+- Updated `/cdev` Step 5 to REQUIRE flags update
+- Added to CLAUDE.md as mandatory protocol
+- No exceptions allowed
+
+---
+
+### ✅ Solution 2: Mandatory Agent Routing
+
+**New File:** `.claude/lib/agent-router.md`
+
+**What it does:**
+- Defines strict agent boundaries
+- Provides work type detection patterns
+- Enforces delegation for implementation work
+- Includes self-check protocol for Main Claude
+
+**Key Features:**
+```typescript
+WORK_PATTERNS = {
+  'ui-component': { agent: 'uxui-frontend', canMainDo: false },
+  'api-endpoint': { agent: 'backend', canMainDo: false },
+  'database-work': { agent: 'database', canMainDo: false },
+  'api-integration': { agent: 'frontend', canMainDo: false },
+  'testing-debugging': { agent: 'test-debug', canMainDo: false },
+  'planning': { agent: 'main-claude', canMainDo: true }
+}
+```
+
+**Enforcement:**
+- Added self-check checklist to CLAUDE.md
+- Main Claude MUST complete before any work
+- Override protection (even if user says "do it yourself")
+
+---
+
+### ✅ Solution 3: Validation Gates
+
+**New File:** `.claude/lib/validation-gates.md`
+
+**What it does:**
+- Four checkpoints Main Claude MUST pass:
+  1. **Before work** - Ensure correct routing
+  2. **After agent responds** - Validate agent output
+  3. **Before reporting** - Ensure flags.json updated
+  4. **Before phase start** - Check phase readiness
+
+**Key Benefits:**
+- Catch errors early
+- Ensure quality at each step
+- Provide clear error messages
+- Enable automatic recovery
+
+---
+
+## 📝 Files Changed
+
+### New Files (3)
+```
+.claude/lib/
+├── flags-updater.md      (NEW - 450 lines)
+├── agent-router.md       (NEW - 500 lines)
+└── validation-gates.md   (NEW - 400 lines)
+```
+
+### Modified Files (3)
+```
+.claude/
+├── CLAUDE.md             (MODIFIED - Added self-check protocol)
+├── lib/README.md         (MODIFIED - Added new file descriptions)
+└── commands/cdev.md      (MODIFIED - Step 5 now mandatory flags update)
+```
+
+---
+
+## 📊 Expected Impact
+
+### Metric 1: flags.json Update Rate
+- **Before:** ~30%
+- **After:** 100%
+- **How:** Mandatory update in /cdev Step 5
+
+### Metric 2: Agent Delegation Rate
+- **Before:** ~60%
+- **After:** 95%+
+- **How:** Self-check protocol + work type detection
+
+### Metric 3: User Visibility
+- **Before:** Must run `/cstatus` manually
+- **After:** Auto-reported after every phase
+- **How:** Progress report in flags-updater protocol
+
+---
+
+## 🎯 Breaking Changes
+
+**None** - All changes are additive:
+- New files add protocols
+- Existing files enhanced (not breaking)
+- Backward compatible with v1.1.0
+
+---
+
+## ✅ Migration Guide
+
+**No migration needed** - Changes are effective immediately:
+
+1. **For existing projects:**
+   - Templates automatically use new protocols
+   - Next `/cdev` run will use updated Step 5
+   - Main Claude will read new CLAUDE.md instructions
+
+2. **For in-progress changes:**
+   - Continue current phase normally
+   - New protocols apply from next `/cdev` invocation
+   - flags.json will start updating correctly
+
+---
+
+## 🔍 Testing Checklist
+
+Before considering this release complete, verify:
+
+- [ ] `/cdev` updates flags.json after phase completion
+- [ ] Main Claude delegates implementation work (not doing it directly)
+- [ ] Progress reported to user automatically
+- [ ] Self-check protocol appears in Main Claude output
+- [ ] Validation gates catch common errors
+- [ ] `/cview` and `/cstatus` show accurate data
+
+---
+
+## 📚 Documentation Updates
+
+### CLAUDE.md
+- Added "Main Claude Self-Check Protocol" section
+- Links to agent-router.md for complete routing rules
+- Lists new lib/ files in Quick Navigation
+
+### cdev.md
+- Step 5 completely rewritten
+- Now REQUIRES flags.json update
+- Shows exact execution order
+- Includes common mistake examples
+
+### lib/README.md
+- Added descriptions for 3 new files
+- Explains purpose of each
+
+---
+
+## 🚀 Future Enhancements (Not in v1.1.1)
+
+**Phase 2 Candidates:**
+- Automated testing of validation gates
+- Progress visualization in terminal
+- Metrics dashboard for delegation rate
+- Agent performance profiling
+
+**Phase 3 Candidates:**
+- LLM-based validation (use Claude to validate Claude)
+- Predictive time estimation
+- Automatic recovery from common errors
+- Multi-change parallel execution
+
+---
+
+## 🙏 Acknowledgments
+
+Issues identified through:
+- Real-world usage testing
+- User feedback on progress tracking
+- Analysis of Main Agent behavior patterns
+
+---
+
+## 📞 Support
+
+**Issues with v1.1.1?**
+1. Check validation gate error messages
+2. Verify flags.json exists and is valid JSON
+3. Review Main Claude output for self-check protocol
+4. Open issue with details
+
+**Questions?**
+- Read: `.claude/lib/flags-updater.md`
+- Read: `.claude/lib/agent-router.md`
+- Read: `.claude/lib/validation-gates.md`
+
+---
+
+**Version:** 1.1.1
+**Previous:** 1.1.0
+**Next:** TBD (based on feedback)
+
+---
+
+## 🎯 Quick Reference
+
+**Problem 1: flags.json not updated**
+→ Solution: `.claude/lib/flags-updater.md`
+→ Enforced by: `/cdev` Step 5
+
+**Problem 2: Main Agent doing work**
+→ Solution: `.claude/lib/agent-router.md`
+→ Enforced by: CLAUDE.md self-check protocol
+
+**Both problems validated by:**
+→ `.claude/lib/validation-gates.md` (4 checkpoints)
+
+---
+
+**🎉 Ready for production use!**

package/template/.claude/CLAUDE.md

@@ -0,0 +1,329 @@
+# CLAUDE.md
+
+> **Navigation Hub for AI Agents**
+> **Template Version:** 1.1.0 - Universal Multi-Agent Template
+> **Latest:** Production-ready with validation enforcement, TDD classification, and retry logic
+
+---
+
+## 🎯 What is This Template?
+
+Universal, framework-agnostic template for AI-assisted development.
+
+**What's Included:**
+- ✅ 6 Specialized Agents (integration + 5 domain specialists)
+- ✅ Universal Patterns (logging, testing, error-handling, agent selection)
+- ✅ Design Foundation (color theory, spacing, typography)
+- ✅ **Auto-Generated Best Practices** (from Context7 MCP per project)
+- ✅ **3-Level Indexing** (agents auto-discover project context)
+- ✅ Domain-Specific Support (add your business logic)
+
+**What's NOT Included:**
+- ❌ Framework patterns → Generated dynamically via `/agentsetup`
+- ❌ Package managers → Detected by `/agentsetup`
+- ❌ Spec frameworks → Optional (OpenSpec, BMAD, SpecKit)
+
+---
+
+## 📖 Quick Navigation
+
+**Design/UI:**
+- `@/.claude/contexts/design/index.md` (Start here)
+- `@/.claude/contexts/design/box-thinking.md` (Layout analysis)
+- `@/.claude/contexts/patterns/ui-component-consistency.md` (Visual consistency)
+
+**Development:**
+- `@/.claude/contexts/patterns/task-classification.md` (Agent selection guide)
+- `@/.claude/contexts/patterns/agent-coordination.md` (When to run agents parallel/sequential)
+- `@/.claude/contexts/patterns/error-recovery.md` (How agents handle errors & escalate)
+- `@/.claude/contexts/patterns/logging.md`
+- `@/.claude/contexts/patterns/testing.md`
+- `@/.claude/contexts/patterns/task-breakdown.md`
+- `@/.claude/contexts/patterns/frontend-component-strategy.md`
+
+**Project Setup:**
+- `/psetup` - One-time project setup (detect tech stack, generate best practices)
+- `/agentsetup` - Auto-detect tech stack and generate best practices
+
+**OpenSpec Multi-Agent Workflow:**
+- `/csetup {change-id}` - Setup change context (analyze tasks, generate workflow)
+- `/cdev {change-id}` - Start/continue multi-agent development
+- `/cview {change-id}` - View detailed progress for a change
+- `/cstatus {change-id}` - Quick progress status for a change
+
+**Best Practices (Dynamic):**
+- `.claude/contexts/domain/{project}/best-practices/` (generated by `/agentsetup`)
+- Framework-specific guidelines from Context7 MCP
+
+**Indexing (3 Levels):**
+- Level 1: `.claude/contexts/domain/index.md` (Project Registry)
+- Level 2: `.claude/contexts/domain/{project}/README.md` (Project Overview)
+- Level 3: `.claude/contexts/domain/{project}/best-practices/index.md` (Best Practices Registry)
+
+**🆕 Implementation Logic (v1.1.0):**
+- `@/.claude/lib/README.md` - Implementation logic overview
+- `@/.claude/lib/agent-executor.md` - Agent retry & escalation logic (used by /cdev)
+- `@/.claude/lib/tdd-classifier.md` - TDD classification logic (used by /csetup)
+- `@/.claude/lib/flags-updater.md` - 🆕 Progress tracking protocol (Main Claude updates flags.json)
+- `@/.claude/lib/agent-router.md` - 🆕 Mandatory agent routing rules (enforce delegation)
+- `@/.claude/contexts/patterns/agent-discovery.md` - Shared agent discovery flow
+
+---
+
+## 📚 Best Practices System
+
+### How It Works:
+
+1. **Run `/agentsetup`** to detect tech stack and generate best practices
+2. **Context7 queries** latest framework docs (React, Next.js, Prisma, etc.)
+3. **Best practices files** created in `domain/{project}/best-practices/`
+4. **Agents auto-discover** project via 3-level indexing
+5. **Code quality** enforced by framework-specific patterns
+
+### Generated Files:
+
+```
+.claude/contexts/domain/
+├── index.md                              # Level 1 - Project Registry
+└── {project}/
+    ├── README.md                         # Level 2 - Project Overview
+    ├── tech-stack.md                     # Tech details
+    └── best-practices/
+        ├── index.md                      # Level 3 - Best Practices Registry
+        ├── react-18.md                   # ✅ DO's, ❌ DON'Ts, 🎯 Checklist
+        ├── nextjs-15.md
+        ├── prisma-6.md
+        └── vitest-2.md
+```
+
+### Agent Discovery Flow:
+
+**Every agent follows this sequence (STEP 0):**
+
+```
+1. Read: domain/index.md → Get current project name
+2. Read: domain/{project}/README.md → Get tech stack
+3. Read: domain/{project}/best-practices/index.md → Get relevant files
+4. Read: domain/{project}/best-practices/{files} → Load best practices
+5. Report: "✅ Project Context Loaded"
+```
+
+**Example: uxui-frontend agent**
+```
+✅ Project Context Loaded
+
+📁 Project: my-app
+🛠️ Stack: Next.js 15, React 18, Prisma 6
+📚 Best Practices Loaded:
+   - React 18 ✓
+   - Next.js 15 ✓
+
+🎯 Ready to create UI components!
+```
+
+---
+
+## 🤖 Agent System
+
+### How It Works:
+
+**Main Claude analyzes tasks → Invokes specialist agents directly**
+
+```
+1. User provides task (e.g., "Build login system")
+   ↓
+2. Main Claude reads @task-classification.md
+   ↓
+3. Main Claude selects appropriate agent(s)
+   ↓
+4. Execute in proper sequence:
+   - Phase 1: uxui-frontend (UI with mock data)
+   - Phase 2: backend + database (parallel)
+   - Phase 2.5: integration (validate contracts)
+   - Phase 3: frontend (connect UI to API)
+   - Phase 4: test-debug (tests & bug fixes)
+```
+
+### Available Agents (6 specialists):
+
+| Agent | Color | When to Use | Phase |
+|-------|-------|-------------|-------|
+| **integration** | Orange | Validate API contracts before connecting | 2.5 |
+| **uxui-frontend** | Blue | Design UI components with mock data | 1 |
+| **test-debug** | Red | Run tests and fix bugs (max 3-4 iterations) | 1,3,4 |
+| **frontend** | Green | Connect UI to backend APIs | 3 |
+| **backend** | Purple | Create API endpoints with validation | 2 |
+| **database** | Pink | Design schemas, migrations, complex queries | 2 |
+
+### Usage:
+
+**For any task, Main Claude will:**
+1. Read `@/.claude/contexts/patterns/task-classification.md`
+2. Determine which agent(s) to use
+3. Invoke agents in proper sequence
+4. Coordinate between agents
+
+**You can also invoke agents directly:**
+```
+User: "/agents uxui-frontend"
+Main Claude: *Executes uxui-frontend agent directly*
+```
+
+---
+
+### 🔒 Main Claude Self-Check Protocol (MANDATORY)
+
+**⚠️ CRITICAL: Main Claude MUST complete this checklist BEFORE doing ANY work**
+
+See: `@/.claude/lib/agent-router.md` for complete routing protocol
+
+**Pre-Work Checklist (Run for EVERY user request):**
+
+```markdown
+## ✅ Pre-Work Self-Check
+
+[ ] 1. Read user request carefully
+       - What are they asking for?
+       - What is the end goal?
+
+[ ] 2. Detect work type
+       - Is this implementation work? (writing code, creating files)
+       - Is this planning/analysis? (reading, explaining, breaking down)
+
+[ ] 3. If IMPLEMENTATION work:
+       - Read: @/.claude/contexts/patterns/task-classification.md
+       - Which agent should handle this?
+         • UI components → uxui-frontend
+         • API endpoints → backend
+         • Database schemas → database
+         • API integration → frontend
+         • Tests/bugs → test-debug
+         • Contracts → integration
+
+[ ] 4. Can Main Claude do this?
+       ✅ YES for: Planning, reading files, explaining, orchestrating workflows
+       ❌ NO for: Writing components, creating endpoints, designing schemas
+
+[ ] 5. If MUST delegate:
+       - Use Task tool with selected agent
+       - Include all necessary context
+       - Wait for agent response
+       - Update flags.json after completion (if using /cdev)
+
+[ ] 6. Report decision to user
+       ```
+       🔍 Task Analysis:
+       - Work type: [type]
+       - Requires: [agent] agent
+       - Reason: [explanation]
+
+       🚀 Invoking [agent] agent...
+       ```
+```
+
+**Main Claude's Role:**
+- ✅ Orchestrator (plan, coordinate, report)
+- ✅ Progress tracker (update flags.json)
+- ✅ Analyst (read files, explain code)
+- ❌ NOT implementer (no writing code directly)
+
+**If Main Claude skips this self-check for implementation work, it violates system protocol.**
+
+---
+
+### ⚠️ Agent Pre-Work Requirements
+
+**STEP 0 (ALL agents):** Every agent must discover project context first
+
+**STEP 1-5 (uxui-frontend only):** Design fundamentals checklist
+
+---
+
+#### STEP 0: Project Discovery (ALL Agents)
+
+**Every agent MUST complete this before ANY work:**
+
+```
+1. Read: domain/index.md → Get current project name
+2. Read: domain/{project}/README.md → Get tech stack summary
+3. Read: domain/{project}/best-practices/index.md → Find relevant files
+4. Read: domain/{project}/best-practices/{files} → Load best practices
+5. Report: "✅ Project Context Loaded"
+```
+
+**Fallback:** If discovery fails, warn user to run `/agentsetup`
+
+---
+
+#### STEP 1-5: Design Fundamentals (uxui-frontend only)
+
+**When invoking uxui-frontend agent, Main Claude MUST include these requirements in the Task prompt:**
+
+```
+MANDATORY PRE-WORK CHECKLIST (after STEP 0):
+
+Before writing ANY code, you MUST:
+
+1. **Read ALL design contexts:**
+   - @/.claude/contexts/design/index.md
+   - @/.claude/contexts/design/box-thinking.md
+   - @/.claude/contexts/design/color-theory.md
+   - @/.claude/contexts/design/spacing.md
+   - @/.claude/contexts/patterns/ui-component-consistency.md
+   - @/.claude/contexts/patterns/frontend-component-strategy.md
+
+2. **Do Box Thinking Analysis:**
+   - Identify all boxes (parent, children, siblings)
+   - Document relationships (container, adjacent, nested)
+   - Plan space flow using spacing scale (8, 16, 24, 32, 40, 48px)
+   - Plan responsive behavior (stack/merge/compress)
+
+3. **Search for Existing Components:**
+   - Glob: "**/*{Keyword}*.{tsx,jsx,vue}"
+   - Grep: "[similar-pattern]"
+   - Decision: Reuse > Compose > Extend > Create New
+   - If creating new: Extract design tokens from most similar component
+
+4. **Extract Design Tokens from Reference Component:**
+   ```typescript
+   const DESIGN_TOKENS = {
+     spacing: { padding: '[from reference]', gap: '[from reference]' },
+     colors: { bg: '[theme token]', text: '[theme token]', border: '[theme token]' },
+     shadows: '[from reference - e.g., shadow-sm]',
+     borderRadius: '[from reference - e.g., rounded-md]'
+   }
+   ```
+
+5. **Report Pre-Implementation Analysis:**
+   You MUST provide a detailed report covering steps 1-4 BEFORE writing any code.
+
+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)
+- ❌ NO inconsistent icons (h-5 w-5, opacity-50) → ✅ Match reference (h-4 w-4, text-foreground/70)
+- ❌ NO creating duplicate components → ✅ Search and reuse first
+
+If you skip these steps, your work will be rejected.
+```
+
+**Why this enforcement matters:**
+- Prevents visual inconsistency (mismatched colors, spacing, shadows)
+- Ensures component reuse (avoids duplicates)
+- Maintains design system integrity
+- Saves implementation time
+
+**Example: Build Login System**
+```
+User: "Build a login system"
+Main Claude analyzes → Breaks into phases:
+  Phase 1: /agents uxui-frontend (create login form UI)
+  Phase 2: /agents backend (create POST /api/login)
+          /agents database (create User model) [parallel]
+  Phase 2.5: /agents integration (verify contracts)
+  Phase 3: /agents frontend (connect form to API)
+  Phase 4: /agents test-debug (test everything)
+```
+
+---
+
+**💡 Remember:** This template is universal. Use Context7 for framework-specific docs!