@champpaba/claude-agent-kit 1.4.1 → 1.5.0

package/.claude/CLAUDE.md

@@ -52,7 +52,7 @@ Universal, framework-agnostic template for AI-assisted development.
 
 **Page Planning (UI Tasks):**
 - `/pageplan @prd.md @brief.md` - **NEW!** Generate page structure & content plan for UI tasks
-- Output: `.changes/{id}/page-plan.md` (component reuse, content draft, asset checklist)
+- Output: `openspec/changes/{id}/page-plan.md` (component reuse, content draft, asset checklist)
 - Used by: uxui-frontend agent (auto-reads in STEP 0.5)
 
 **OpenSpec Multi-Agent Workflow:**
@@ -121,7 +121,7 @@ Universal, framework-agnostic template for AI-assisted development.
 
 **Quick Summary:**
 - **Problem:** Agents duplicate components (Navbar 3x), use random colors, lorem ipsum content
-- **Solution:** `/pageplan @prd.md @brief.md` → Generates `.changes/{id}/page-plan.md` with component reuse plan, AI-drafted content, asset checklist
+- **Solution:** `/pageplan @prd.md @brief.md` → Generates `openspec/changes/{id}/page-plan.md` with component reuse plan, AI-drafted content, asset checklist
 - **Benefits:** Prevents duplicates, ensures design consistency, real content from PRD, 25% faster (search done once upfront)
 - **Use for:** Landing pages, dashboards, multi-section UI pages (skip for backend/database work)
 

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

@@ -78,7 +78,7 @@ After completing standard discovery, check for project-specific resources:
 Read: design-system/STYLE_GUIDE.md
 
 # Check if page plan exists (from /pageplan command)
-Read: .changes/{change-id}/page-plan.md
+Read: openspec/changes/{change-id}/page-plan.md
 ```
 
 **If STYLE_GUIDE.md exists:**
@@ -104,6 +104,62 @@ Read: .changes/{change-id}/page-plan.md
 - **OPTIMIZATION:** Skip STEP 3 (component search) - page-plan already did this!
 - **CRITICAL:** If Section 2.6 exists, animations are **pre-designed** - follow blueprint exactly
 
+---
+
+### 🚨 MANDATORY COMPLIANCE (When page-plan.md exists)
+
+**YOU MUST implement ALL sections listed in page-plan.md Section 2 (Page Structure).**
+
+**Before writing ANY code:**
+
+1. **Count sections** in page-plan.md Section 2 (Page Structure)
+2. **Create implementation checklist:**
+   ```
+   Sections to implement (from page-plan.md):
+   - [ ] Section 1: {ComponentName} - {purpose}
+   - [ ] Section 2: {ComponentName} - {purpose}
+   - [ ] Section 3: {ComponentName} - {purpose}
+   ...
+   ```
+
+**After completing implementation:**
+
+3. **Verify ALL sections** are implemented
+4. **Report compliance:**
+   ```
+   ✅ Page Structure Compliance:
+      Sections required: {count}
+      Sections implemented: {count}
+      Status: ✅ COMPLETE (or ❌ INCOMPLETE)
+   ```
+
+**⚠️ CRITICAL RULES:**
+
+- ❌ If you implement LESS than ALL sections → Your work will be **REJECTED**
+- ❌ You CANNOT skip sections (even if tasks.md says "4-5 components")
+- ✅ You MUST implement EVERY section in page-plan.md Section 2
+- ✅ If confused, page-plan.md takes PRIORITY over tasks.md
+
+**Example:**
+
+If page-plan.md Section 2 lists:
+```
+<Layout>
+  <LandingNavBar />     {/* 1 */}
+  <HeroSection />       {/* 2 */}
+  <ProblemSection />    {/* 3 */}
+  <FeatureGrid />       {/* 4 */}
+  <ComparisonTable />   {/* 5 */}
+  <TestimonialCards />  {/* 6 */}
+  <CTASection />        {/* 7 */}
+  <Footer />            {/* 8 */}
+</Layout>
+```
+
+You MUST create ALL 8 sections, NOT just Hero + FeatureGrid + Footer (3/8).
+
+---
+
 **If page-plan.md does NOT exist:**
 - ℹ️ No page plan - will search for components manually in STEP 3
 - ⚠️ No animation blueprint - fallback to `.claude/contexts/patterns/animation-patterns.md`
@@ -309,6 +365,63 @@ const TOKENS = {
 - Bundle size: -30-40% (code splitting)
 - Image size: -80% (WebP + compression)
 
+### 📋 Step 4.6: Page Plan Compliance Checklist (IF page-plan.md exists)
+
+**Only complete this step if page-plan.md was loaded in STEP 0.5:**
+
+**Purpose:** Ensure you implement ALL sections from page-plan.md, not a subset.
+
+**Instructions:**
+
+1. **Re-read** page-plan.md Section 2 (Page Structure)
+2. **Extract** all components listed in the structure
+3. **Count** total sections required
+4. **Create** implementation checklist:
+
+```
+📋 Page Structure Implementation Checklist
+Total sections: {count}
+
+Sections to implement (from page-plan.md Section 2):
+- [ ] {Component 1} - {description/purpose}
+- [ ] {Component 2} - {description/purpose}
+- [ ] {Component 3} - {description/purpose}
+...
+
+Verification:
+- [ ] All sections from page-plan.md are listed above
+- [ ] No sections are skipped
+- [ ] I will implement ALL sections (not a subset)
+```
+
+**Report when complete:**
+```
+✅ Page Plan Compliance Checklist Created
+   Total sections: {count}
+   Ready to implement FULL page structure
+
+   Example:
+   - Section 1: LandingNavBar (sticky navigation)
+   - Section 2: HeroSection (above fold)
+   - Section 3: ProblemSection (pain points)
+   - ...
+   - Section 10: Footer (links + social)
+
+   Status: ✅ Checklist verified - will implement all 10 sections
+```
+
+**⚠️ CRITICAL:**
+- This checklist is MANDATORY - if you skip it, you'll likely implement only 4-5 sections instead of all 10
+- If page-plan.md lists 10 sections, you MUST create 10 components
+- tasks.md may say "create 4-5 components" - IGNORE this if page-plan.md exists
+- page-plan.md takes PRIORITY over tasks.md
+
+**If page-plan.md does NOT exist:**
+- Skip this step
+- Proceed to Step 5
+
+---
+
 ### 📋 Step 5: Pre-Implementation Report (REQUIRED)
 
 Provide complete analysis covering steps 1-4 BEFORE writing code.
@@ -343,7 +456,7 @@ Provide complete analysis covering steps 1-4 BEFORE writing code.
 ### Project-Specific (If Exists)
 - `design-system/STYLE_GUIDE.md` (Priority #1 - loaded in STEP 0.5)
 - `design-system/STYLE_TOKENS.json` (lightweight tokens)
-- `.changes/{change-id}/page-plan.md` (from /pageplan command)
+- `openspec/changes/{change-id}/page-plan.md` (from /pageplan command)
 
 ### Framework Docs (Context7)
 **Topic:** "components, hooks, state management, routing, styling"

package/.claude/commands/cdev.md

@@ -269,6 +269,93 @@ See `.claude/contexts/patterns/validation-framework.md` for complete checklist p
 
 ---
 
+### Step 4.7: Validate Page Plan Compliance (uxui-frontend only)
+
+**Only runs for uxui-frontend agent when page-plan.md exists:**
+
+**Purpose:** Verify agent implemented ALL sections from page-plan.md, not a subset.
+
+```typescript
+// Check if page-plan.md exists
+const pagePlanPath = `openspec/changes/${changeId}/page-plan.md`
+const hasPagePlan = fileExists(pagePlanPath)
+
+if (phase.agent === 'uxui-frontend' && hasPagePlan) {
+  output(`\n🔍 Validating page-plan.md compliance...`)
+
+  // Extract sections from page-plan.md Section 2 (Page Structure)
+  const pagePlan = Read(pagePlanPath)
+  const section2Match = pagePlan.match(/## 2\. Page Structure[\s\S]*?(?=## 3\.|## 2\.5|## 2\.6|$)/)
+
+  if (section2Match) {
+    // Count expected sections (extract component names from JSX)
+    const componentMatches = section2Match[0].match(/<([A-Z]\w+)/g) || []
+    const expectedComponents = componentMatches
+      .map(m => m.replace('<', ''))
+      .filter(name => name !== 'Layout' && name !== 'div') // Exclude wrappers
+
+    const uniqueComponents = [...new Set(expectedComponents)] // Remove duplicates
+
+    output(`\n📋 Page Plan Analysis:`)
+    output(`   Expected sections: ${uniqueComponents.length}`)
+    output(`   Components: ${uniqueComponents.join(', ')}`)
+
+    // Prompt user to verify agent compliance
+    output(`\n⚠️ VALIDATION REQUIRED:`)
+    output(`\nDid the agent implement ALL ${uniqueComponents.length} sections?`)
+    output(`\nPlease verify the implementation includes:`)
+    uniqueComponents.forEach(c => output(`   - ${c}`))
+
+    output(`\nOptions:`)
+    output(`  [yes]   - All sections implemented ✓`)
+    output(`  [retry] - Agent skipped sections, retry with strict enforcement`)
+    output(`  [skip]  - Skip validation (not recommended)`)
+
+    const answer = await askUser(`\nConfirm all sections implemented?`)
+
+    if (answer === 'retry') {
+      output(`\n🔄 Retrying phase with enhanced enforcement...`)
+      output(`Agent will be explicitly instructed to implement all ${uniqueComponents.length} sections`)
+
+      // Restart phase with enhanced prompt
+      return executePhaseAgain(changeId, phase, {
+        enforce_page_plan: true,
+        required_sections: uniqueComponents
+      })
+    } else if (answer === 'skip') {
+      warn(`\n⚠️ Skipping validation - proceed with caution`)
+      warn(`   This may result in incomplete implementation`)
+    } else {
+      output(`\n✅ Page plan compliance confirmed`)
+      output(`   All ${uniqueComponents.length} sections implemented`)
+    }
+  } else {
+    warn(`\n⚠️ Could not parse page-plan.md Section 2`)
+    warn(`   Skipping compliance validation`)
+  }
+} else {
+  // Not uxui-frontend or no page-plan.md - skip validation
+  output(`\nℹ️ Page plan validation: N/A (agent: ${phase.agent}, has plan: ${hasPagePlan})`)
+}
+```
+
+**When to use:**
+- ✅ Agent: uxui-frontend
+- ✅ page-plan.md exists
+- ✅ Phase completed successfully
+
+**Common issues caught:**
+- Agent implemented 5/10 sections (missing ProblemSection, ComparisonTable, etc.)
+- Agent followed tasks.md ("4-5 components") instead of page-plan.md (10 sections)
+- Agent skipped sections they thought were "optional"
+
+**Remediation:**
+- If validation fails → Retry with `enforce_page_plan: true`
+- Agent will receive enhanced prompt with explicit section list
+- Validation runs again after retry
+
+---
+
 ### Step 5: Post-Execution (🆕 MANDATORY FLAGS UPDATE)
 
 **⚠️ CRITICAL: Main Claude MUST update flags.json after EVERY phase completion**

package/.claude/commands/pageplan.md

@@ -7,7 +7,7 @@
 # With context files
 /pageplan @proposal.md @prd.md @project_brief.md
 
-# Current change only (uses proposal.md in .changes/)
+# Current change only (uses proposal.md in openspec/changes/)
 /pageplan
 
 # Specify change ID
@@ -20,7 +20,7 @@
 
 1. **Reads User-Specified Context:**
    - Only reads files that user mentions with `@` prefix
-   - Always reads `.changes/{change-id}/proposal.md` (if exists)
+   - Always reads `openspec/changes/{change-id}/proposal.md` (if exists)
    - **Always reads `design-system/STYLE_TOKENS.json`** (lightweight, ~500 tokens) ✅
    - Validates `design-system/STYLE_GUIDE.md` exists (doesn't load full content)
 
@@ -36,7 +36,7 @@
    - Asset checklist (user must prepare)
    - Rationale (why this structure)
 
-4. **Outputs to:** `.changes/{change-id}/page-plan.md`
+4. **Outputs to:** `openspec/changes/{change-id}/page-plan.md`
 
 ---
 
@@ -46,7 +46,7 @@
 
 ```typescript
 // Detect current change ID
-const changesDir = '.changes/'
+const changesDir = 'openspec/changes/'
 const changeId = detectCurrentChange() // or from command arg
 
 if (!changeId) {
@@ -54,7 +54,7 @@ if (!changeId) {
   return
 }
 
-const outputPath = `.changes/${changeId}/page-plan.md`
+const outputPath = `openspec/changes/${changeId}/page-plan.md`
 ```
 
 ### STEP 2: Read Context Files
@@ -64,7 +64,7 @@ const outputPath = `.changes/${changeId}/page-plan.md`
 const userFiles = extractMentionedFiles(userMessage) // @prd.md, @brief.md
 
 // Always read (if exists)
-const proposalPath = `.changes/${changeId}/proposal.md`
+const proposalPath = `openspec/changes/${changeId}/proposal.md`
 const tokensPath = `design-system/STYLE_TOKENS.json` // 🆕 Lightweight tokens
 const styleGuidePath = `design-system/STYLE_GUIDE.md` // Validate only, don't load
 

package/.claude/contexts/patterns/animation-patterns.md

@@ -17,7 +17,7 @@
 ## 📘 How to Use This File
 
 **Priority:**
-1. **Page-specific plan:** `.changes/{id}/page-plan.md` Section 2.6 (if exists)
+1. **Page-specific plan:** `openspec/changes/{id}/page-plan.md` Section 2.6 (if exists)
 2. **Project tokens:** `design-system/STYLE_TOKENS.json` (animation tokens)
 3. **General guidelines:** This file (fallback when above don't exist)
 

package/.claude/lib/context-loading-protocol.md

@@ -252,7 +252,7 @@ Each agent loads additional contexts based on their role.
 **Project-specific (if exists):**
 - `design-system/STYLE_GUIDE.md` (17 sections, ~5K tokens)
 - `design-system/STYLE_TOKENS.json` (lightweight, ~500 tokens)
-- `.changes/{change-id}/page-plan.md` (from /pageplan command)
+- `openspec/changes/{change-id}/page-plan.md` (from /pageplan command)
 
 **Loading strategy:**
 ```
@@ -334,7 +334,7 @@ Each agent loads additional contexts based on their role.
    → Loading: design/*.md ✓
    → Loading: patterns/ui-component-consistency.md ✓
    → Loading: design-system/STYLE_TOKENS.json ✓
-   → Loading: .changes/landing-page/page-plan.md ✓
+   → Loading: openspec/changes/landing-page/page-plan.md ✓
    ✅ Design contexts loaded
 
 ✅ Context Loading Complete!

package/.claude/lib/detailed-guides/page-planning.md

@@ -36,7 +36,7 @@ Main Claude:
 2. Reads proposal.md (technical architecture)
 3. Reads STYLE_GUIDE.md (visual design)
 4. Searches existing components (Glob/Grep)
-5. Generates: .changes/{id}/page-plan.md
+5. Generates: openspec/changes/{id}/page-plan.md
    - 🔄 Reuse: Navbar, Footer (found)
    - ✅ New: HeroSection, FeatureGrid (create)
    - 📝 Content draft (AI-generated from PRD)

package/.claude/lib/task-analyzer.md

@@ -219,7 +219,7 @@ function generateMitigation(risk: RiskLevel, task: Task): string[] {
 ```typescript
 function detectResearchNeeds(task: Task, changeContext: any): ResearchRequirement | null {
   // Check if page-plan.md exists (skip UX/accessibility research)
-  const hasPagePlan = fileExists(`.changes/${changeContext.changeId}/page-plan.md`)
+  const hasPagePlan = fileExists(`openspec/changes/${changeContext.changeId}/page-plan.md`)
 
   const researchIndicators = {
     // Technical research (always check)

package/README.md

@@ -110,7 +110,7 @@ Users need secure login functionality...
 ```bash
 # Step 1: OpenSpec generates tasks
 User: "Build landing page for TOEIC app"
-→ Creates: .changes/landing-page/proposal.md + tasks.md
+→ Creates: openspec/changes/landing-page/proposal.md + tasks.md
 
 # Step 2: Generate page plan (NEW!)
 User: /pageplan @prd.md @project_brief.md
@@ -121,7 +121,7 @@ User: /pageplan @prd.md @project_brief.md
 # 3. Reads STYLE_GUIDE.md (visual design)
 # 4. Searches existing components (Navbar, Footer, etc.)
 # 5. AI drafts real content from PRD
-# 6. Generates: .changes/landing-page/page-plan.md
+# 6. Generates: openspec/changes/landing-page/page-plan.md
 ```
 
 ### page-plan.md Output
@@ -257,7 +257,7 @@ cd my-app
 
 # Draft a change proposal (OpenSpec handles this)
 "I want to build a landing page for my TOEIC app"
-# → Generates: .changes/landing-page/proposal.md + tasks.md
+# → Generates: openspec/changes/landing-page/proposal.md + tasks.md
 ```
 
 ### Step 2: Initialize Claude Agent Kit
@@ -277,7 +277,7 @@ cak init
 # In Claude Code:
 /pageplan @prd.md @project_brief.md
 
-# → Generates: .changes/landing-page/page-plan.md
+# → Generates: openspec/changes/landing-page/page-plan.md
 # → Review content, prepare assets
 ```
 
@@ -288,9 +288,9 @@ cak init
 ```
 
 **What happens:**
-- Reads `.changes/landing-page/proposal.md` (business context)
-- Reads `.changes/landing-page/tasks.md` (implementation checklist)
-- Reads `.changes/landing-page/page-plan.md` (if exists - content plan)
+- Reads `openspec/changes/landing-page/proposal.md` (business context)
+- Reads `openspec/changes/landing-page/tasks.md` (implementation checklist)
+- Reads `openspec/changes/landing-page/page-plan.md` (if exists - content plan)
 - Classifies tasks by agent (database, backend, frontend, etc.)
 - Generates `workflow.md` (execution plan)
 

package/lib/helpers.js

@@ -28,16 +28,52 @@ async function promptUser(question) {
 }
 
 /**
- * Merge template files into target directory
- * - Overwrites files with same name
+ * Merge template files into target directory with smart comparison
+ * - Only overwrites if content actually differs
  * - Keeps existing files that don't exist in template
+ * - Skips identical files (prevents Git showing unnecessary changes)
  * @param {string} templatePath - Source template directory
  * @param {string} targetPath - Target directory
  */
 async function mergeTemplateFiles(templatePath, targetPath) {
+  const crypto = require('crypto');
+
+  // Helper: Calculate file hash
+  function getFileHash(filePath) {
+    try {
+      const content = fs.readFileSync(filePath);
+      return crypto.createHash('md5').update(content).digest('hex');
+    } catch (error) {
+      return null;
+    }
+  }
+
+  // Custom filter function
+  const filter = (src, dest) => {
+    const srcStat = fs.statSync(src);
+
+    // Always copy directories
+    if (srcStat.isDirectory()) {
+      return true;
+    }
+
+    // If destination doesn't exist, copy it
+    if (!fs.existsSync(dest)) {
+      return true;
+    }
+
+    // Compare file hashes (content-based comparison)
+    const srcHash = getFileHash(src);
+    const destHash = getFileHash(dest);
+
+    // Only copy if content differs
+    return srcHash !== destHash;
+  };
+
   await fs.copy(templatePath, targetPath, {
     overwrite: true,
-    errorOnExist: false
+    errorOnExist: false,
+    filter: filter
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champpaba/claude-agent-kit",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Universal multi-agent template for Claude Code - AI-assisted development with specialized agents",
   "main": "bin/cli.js",
   "bin": {