@champpaba/claude-agent-kit 1.7.0 → 1.8.0

package/.claude/CLAUDE.md

@@ -1,8 +1,46 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 1.7.0 - Universal Multi-Agent Template (Opus 4.5)
-> **Latest:** Incremental Testing - Milestone-based validation for high-risk tasks with round-based retry
+> **Template Version:** 1.8.0 - Universal Multi-Agent Template (Opus 4.5)
+> **Latest:** Token Optimization - Removed documentation/report phases, verbose terminal output instead
+
+---
+
+## 📁 File Naming Conventions (OpenSpec + Template)
+
+> **IMPORTANT:** Avoid confusion between OpenSpec files and Template files
+
+### OpenSpec Files (from [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec))
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `proposal.md` | WHY - Goals, scope, rationale | Phase planning |
+| `tasks.md` | WHAT - Implementation checklist | Task tracking |
+| `design.md` | **Technical/Architecture decisions** (optional) | Backend/Database phases |
+| `specs/` | Delta specs (ADDED/MODIFIED/REMOVED) | Requirement validation |
+
+### Template Files (from claude-multi-agent-template)
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `STYLE_GUIDE.md` | **Visual design** (colors, typography, spacing) | UI/Frontend phases |
+| `STYLE_TOKENS.json` | Lightweight design tokens (~500 tokens) | Quick UI reference |
+| `page-plan.md` | UI component layout + content strategy | uxui-frontend agent |
+| `phases.md` | Execution plan with agent assignments | All phases |
+| `flags.json` | Progress tracking | All phases |
+
+### Key Distinction
+
+```
+OpenSpec design.md    = Technical Architecture (data flow, API structure, system design)
+Template STYLE_GUIDE  = Visual Design (colors, fonts, spacing, component styles)
+```
+
+**Agents should read BOTH when relevant:**
+- `uxui-frontend` → STYLE_GUIDE.md (visual) + design.md (if has UI architecture)
+- `backend` → design.md (API/data architecture)
+- `database` → design.md (data models, relationships)
+- `frontend` → STYLE_GUIDE.md (visual) + design.md (API contracts)
 
 ---
 
@@ -19,8 +57,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - ✅ Domain-Specific Support (add your business logic)
 
 **What's NOT Included:**
-- ❌ Framework patterns → Generated dynamically via `/agentsetup`
-- ❌ Package managers → Detected by `/agentsetup`
+- ❌ Framework patterns → Generated dynamically via `/csetup`
+- ❌ Package managers → Auto-detected by `/csetup`
 - ❌ Spec frameworks → Optional (OpenSpec, BMAD, SpecKit)
 
 ---
@@ -46,9 +84,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/contexts/patterns/frontend-component-strategy.md`
 
 **Project Setup:**
-- `/designsetup` - **NEW!** Auto-generate style guide (reference → codebase → AI)
-- `/psetup` - One-time project setup (detect tech stack, generate best practices)
-- `/agentsetup` - Auto-detect tech stack and generate best practices
+- `/designsetup` - Auto-generate style guide (reference → codebase → AI)
+- `/csetup` - **v1.8.0:** Now auto-detects tech stack + generates best practices (replaces /psetup, /agentsetup)
 
 **Page Planning (UI Tasks):**
 - `/pageplan @prd.md @brief.md` - **ENHANCED v1.4.0!** Generate page structure & conversion-optimized content
@@ -64,7 +101,7 @@ Universal, framework-agnostic template for AI-assisted development.
 - `/cstatus {change-id}` - Quick progress status for a change
 
 **Best Practices (Dynamic):**
-- `.claude/contexts/domain/{project}/best-practices/` (generated by `/agentsetup`)
+- `.claude/contexts/domain/project/best-practices/` (auto-generated by `/csetup`)
 - Framework-specific guidelines from Context7 MCP
 
 **Indexing (3 Levels):**
@@ -83,15 +120,20 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 📚 Best Practices System
-
-**→ See:** `@/.claude/lib/detailed-guides/best-practices-system.md` for complete guide
+## 📚 Best Practices System (v1.8.0)
 
 **Quick Summary:**
-- Run `/agentsetup` → Auto-detects tech stack → Queries Context7 → Generates framework-specific best practices
-- Files created in `.claude/contexts/domain/{project}/best-practices/` (React, Next.js, Prisma, etc.)
-- Agents auto-discover via 3-level indexing (domain → project → best-practices)
-- Enforces code quality with framework-specific patterns
+- `/csetup` **auto-detects tech stack** from: package.json → design.md → proposal/tasks (3 sources)
+- **Auto-generates best practices** from Context7 MCP (React, Next.js, Prisma, etc.)
+- Files created in `.claude/contexts/domain/project/best-practices/`
+- **Agents MUST read** best practices before coding (validated by agent-executor)
+- `/cdev` **injects** relevant best-practices paths into agent prompts
+
+**Flow:**
+```
+/csetup → detect stack → query Context7 → generate best-practices
+/cdev   → inject paths into prompt → agent reads → validation checks
+```
 
 ---
 

package/.claude/agents/01-integration.md

@@ -526,7 +526,7 @@ Frontend expects `email` but backend doesn't return it.
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### Validation Standards
 - ✅ Read ACTUAL code files (don't guess or assume)
@@ -638,14 +638,18 @@ Found: 3 endpoints
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code/config files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO INTEGRATION_REPORT.md, CONTRACT_ANALYSIS.md, API_CONTRACTS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with validation results
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ---

package/.claude/agents/02-uxui-frontend.md

@@ -922,14 +922,19 @@ Return to Orchestrator:
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
 
-**Quick Rule:**
-- ❌ **NEVER** create .md documentation files (README, DOCS, GUIDE, etc.)
-- ✅ **ALWAYS** report results as verbose text output in final message
-- Exception: ONLY when user explicitly requests documentation
+**Simple Rule:** Only create **actual component/style files**. No reports, summaries, or temp files.
+
+**Quick Reference:**
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with component list and files created
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 

package/.claude/agents/03-test-debug.md

@@ -431,15 +431,19 @@ Recommendation:
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code/test files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO TEST_REPORT.md, DEBUG_LOG.md, TEST_RESULTS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with test results (passed/failed/coverage)
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -451,7 +455,7 @@ Recommendation:
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### Testing Standards
 - ✅ Run tests automatically (no manual testing)

package/.claude/agents/04-frontend.md

@@ -561,15 +561,19 @@ test('failed login shows error message', async () => {
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual code files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO README.md, IMPLEMENTATION_GUIDE.md, API_DOCS.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with integration results
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -581,7 +585,7 @@ test('failed login shows error message', async () => {
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### TDD Compliance
 - ✅ Check `tdd_required` flag from Orchestrator

package/.claude/agents/05-backend.md

@@ -579,14 +579,19 @@ Response: { token: string, user: { id, email, name } }
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
 
-**Quick Rule:**
-- ❌ **NEVER** create .md documentation files (README, API_DOCS, etc.)
-- ✅ **ALWAYS** report results as verbose text output in final message
-- Exception: ONLY when user explicitly requests documentation
+**Simple Rule:** Only create **actual code files**. No reports, summaries, or temp files.
+
+**Quick Reference:**
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with endpoints created
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 

package/.claude/agents/06-database.md

@@ -620,15 +620,19 @@ users = await db.execute(
 
 ---
 
-## Documentation Policy
+## Documentation Policy (v1.8.0)
 
-**→ See:** `.claude/contexts/patterns/code-standards.md` for complete policy
+**→ See:** `.claude/contexts/patterns/code-standards.md` → "Forbidden Files" section
+
+**Simple Rule:** Only create **actual schema/migration files**. No reports, summaries, or temp files.
 
 **Quick Reference:**
-- ❌ NEVER create documentation files unless explicitly requested
-- ❌ NO SCHEMA_DOCUMENTATION.md, DATABASE_GUIDE.md, MIGRATION_GUIDE.md, etc.
-- ✅ Return comprehensive text reports in your final message instead
-- ✅ Exception: Only when user explicitly says "create documentation"
+- ❌ NEVER create files for: reports, summaries, logs, guides, analysis results
+- ❌ NEVER create ALL_CAPS filenames or files with PHASE_/STEP_ prefixes
+- ✅ Return all results in your **final response text**
+- ✅ Update `flags.json` with schema changes and migrations
+
+**Rule of thumb:** If it wouldn't be committed to git as part of the feature, don't create it.
 
 ## Rules
 
@@ -640,7 +644,7 @@ users = await db.execute(
 - ✅ ALWAYS read `tech-stack.md` before ANY install/run commands
 - ✅ Use exact package manager from tech-stack.md (pnpm, npm, bun, uv, poetry, pip)
 - ❌ NEVER assume or hardcode package manager
-- ❌ If tech-stack.md missing → warn user to run `/agentsetup`
+- ❌ If tech-stack.md missing → warn user to run `/csetup`
 
 ### TDD Compliance
 - ✅ Check `tdd_required` flag from Orchestrator

package/.claude/commands/cdev.md

@@ -94,7 +94,7 @@ See: `.claude/lib/agent-executor.md` for full implementation
 ```typescript
 // Step 4: Invoke Agent with Retry & Validation
 
-// 4.1: Build agent prompt (with design reference - Context Optimization v1.2.0)
+// 4.1: Build agent prompt (with design reference + best practices - v1.8.0)
 function buildAgentPrompt(phase, changeContext) {
   let prompt = `
 # Phase ${phase.phase_number}: ${phase.name}
@@ -108,7 +108,56 @@ ${changeContext.tasks}
 ${phase.instructions}
 `
 
-  // 🆕 Add design reference for uxui-frontend agent (not full content!)
+  // 🆕 v1.8.0: 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')
+
+    // Map agent type to relevant best-practices
+    const agentBpMapping = {
+      'uxui-frontend': ['react', 'nextjs', 'vue', 'tailwind'],
+      'frontend': ['react', 'nextjs', 'vue', 'typescript'],
+      'backend': ['express', 'fastapi', 'django', 'prisma', 'drizzle'],
+      'database': ['prisma', 'drizzle', 'postgres', 'mongodb'],
+      'test-debug': ['vitest', 'jest', 'playwright'],
+      'integration': ['typescript'] // minimal
+    }
+
+    const relevantTechs = agentBpMapping[phase.agent] || []
+    const relevantFiles = bpFiles.filter(f =>
+      relevantTechs.some(tech => f.toLowerCase().includes(tech))
+    )
+
+    if (relevantFiles.length > 0) {
+      prompt += `
+
+---
+
+## 📚 Best Practices (MANDATORY - STEP 0)
+
+**YOU MUST READ these files before writing ANY code:**
+
+${relevantFiles.map(f => `
+### ${f.replace('.md', '')}
+\`\`\`
+Read: ${bpDir}${f}
+\`\`\`
+`).join('')}
+
+**After reading, REPORT:**
+\`\`\`
+✅ Best Practices Loaded
+   ${relevantFiles.map(f => `- ${f.replace('.md', '')} ✓`).join('\n   ')}
+\`\`\`
+
+**If you skip this, your work will be REJECTED!**
+
+---
+`
+    }
+  }
+
+  // Add design reference for uxui-frontend agent (not full content!)
   if (phase.agent === 'uxui-frontend') {
     const tokensPath = 'design-system/STYLE_TOKENS.json'
     const styleGuidePath = 'design-system/STYLE_GUIDE.md'
@@ -392,11 +441,65 @@ output(`   ⏱️  ${formatDuration(flags.meta.time_remaining_estimate)} remaini
 
 // 4. Check next phase
 if (flags.ready_to_archive) {
-  output('\n✅ All phases complete! Ready to archive.')
-  output(`\nNext steps:`)
-  output(`1. Review: /cview ${changeId}`)
-  output(`2. Update tasks.md (mark all [x])`)
-  output(`3. Archive: openspec archive ${changeId}`)
+  // 🆕 v1.2.0: Verbose Summary Output (replaces documentation/report phases)
+  output(`\n`)
+  output(`╔════════════════════════════════════════════════════════════╗`)
+  output(`║           ✅ CHANGE COMPLETED SUCCESSFULLY                 ║`)
+  output(`╚════════════════════════════════════════════════════════════╝`)
+  output(``)
+  output(`📦 Change: ${changeId}`)
+  output(`📋 Template: ${flags.template} (${flags.meta.total_phases} phases)`)
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`📊 EXECUTION SUMMARY`)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(``)
+  output(`⏱️  Time:`)
+  output(`   • Estimated: ${formatDuration(flags.meta.total_estimated_minutes)}`)
+  output(`   • Actual:    ${formatDuration(flags.meta.total_actual_minutes)}`)
+  output(`   • Variance:  ${calculateVariance(flags.meta)}`)
+  output(``)
+  output(`📈 Phases Completed: ${flags.meta.completed_phases}/${flags.meta.total_phases}`)
+
+  // List all phases with status
+  Object.entries(flags.phases).forEach(([phaseId, phase]) => {
+    const status = phase.status === 'completed' ? '✅' :
+                   phase.status === 'skipped' ? '⏭️' : '❌'
+    const time = phase.actual_minutes ? `(${phase.actual_minutes}m)` : ''
+    output(`   ${status} ${phase.phase_number}. ${phaseId} ${time}`)
+  })
+
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`📁 FILES CREATED/MODIFIED`)
+  output(`═══════════════════════════════════════════════════════════════`)
+
+  // Collect all files from phase outputs
+  const allFiles = collectFilesFromPhases(flags.phases)
+  if (allFiles.created.length > 0) {
+    output(``)
+    output(`✨ Created (${allFiles.created.length}):`)
+    allFiles.created.forEach(f => output(`   • ${f}`))
+  }
+  if (allFiles.modified.length > 0) {
+    output(``)
+    output(`📝 Modified (${allFiles.modified.length}):`)
+    allFiles.modified.forEach(f => output(`   • ${f}`))
+  }
+
+  output(``)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(`🚀 NEXT STEPS`)
+  output(`═══════════════════════════════════════════════════════════════`)
+  output(``)
+  output(`1. Review changes:  /cview ${changeId}`)
+  output(`2. Test manually:   Verify the implementation works`)
+  output(`3. Mark complete:   Update tasks.md (mark all [x])`)
+  output(`4. Archive:         openspec archive ${changeId}`)
+  output(``)
+  output(`💡 Note: flags.json contains full execution history`)
+  output(`   Path: openspec/changes/${changeId}/.claude/flags.json`)
+  output(``)
 } else {
   const nextPhase = flags.phases[flags.current_phase]