@champpaba/claude-agent-kit 2.1.6 → 2.2.0

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

@@ -1,6 +1,6 @@
 # Pre-Work Checklist (Shared by All Agents)
 
-> **Version:** 2.1.3 (Design Spec Injection)
+> **Version:** 2.2.0 (Library Feasibility Validation)
 > **Purpose:** Single source of truth for pre-work validation
 
 ---
@@ -49,6 +49,88 @@ WHY not defaults? Design spec has project-specific security requirements.
 
 ---
 
+### Step 0.5: Library Feasibility Validation (v2.2.0)
+
+**Before implementing, verify the chosen library supports ALL spec requirements:**
+
+WHY: Implementing without verifying library capabilities leads to spec drift. Better to discover gaps early than during implementation.
+
+1. **List spec requirements from design.md:**
+
+   Extract specific technical requirements, for example:
+   - "JWT access token 15min expiry"
+   - "Redis refresh token 30d"
+   - "Refresh token rotation on each use"
+   - "Token revocation capability"
+
+2. **For each requirement, verify library support:**
+
+   - Check library documentation
+   - Query Context7 if available: "How to implement {requirement} with {library}?"
+   - Search for feature in library's plugin/extension list
+   - Check if feature is: built-in, plugin-available, or unsupported
+
+3. **Report feasibility in your validation:**
+
+   ```markdown
+   Library Feasibility Check:
+   - [ ] {requirement 1} → {library} supports: YES/PARTIAL/NO
+   - [ ] {requirement 2} → {library} supports: YES/PARTIAL/NO
+   - [ ] {requirement 3} → {library} supports: YES/PARTIAL/NO
+   ```
+
+4. **If ANY requirement is NOT FULLY supported:**
+
+   **STOP - Do not proceed with implementation**
+
+   Report to Main Claude using the Spec Deviation Protocol:
+
+   ```markdown
+   ⚠️ Library Capability Gap Detected
+
+   **Library:** {name}
+   **Requirement (from design.md):** {exact requirement text}
+   **Support Status:** NO / PARTIAL
+
+   **What library supports:** {alternative approach library offers}
+   **What spec requires:** {original requirement}
+
+   **Gap Analysis:**
+   {explain what cannot be implemented as specified}
+
+   **Options:**
+   A) Change library → {suggest alternative library that supports this}
+   B) Change spec → Update design.md to use what library supports
+   C) Custom implementation → Build missing feature on top of library
+
+   **My Recommendation:** {A/B/C} because {reasoning}
+
+   Awaiting decision before proceeding.
+   ```
+
+5. **Wait for explicit decision before implementing**
+
+   - Do NOT implement alternative approach silently
+   - Do NOT assume user would prefer simpler option
+   - Do NOT continue with "close enough" solution
+
+   WHY: Silent spec drift creates technical debt and user confusion. Explicit decisions create documented trade-offs.
+
+**Example Gap Detection:**
+```markdown
+Library Feasibility Check:
+- [x] JWT access token 15min → better-auth jwt plugin: YES ✅
+- [x] Refresh token → better-auth: PARTIAL ⚠️ (session-based, not separate token)
+- [ ] Refresh token rotation → better-auth: NO ❌
+- [ ] Redis session storage → better-auth: NO ❌
+
+⚠️ STOP - Gaps found in requirements 3 and 4
+
+Reporting to Main Claude...
+```
+
+---
+
 ### Step 1-4: Standard Checks
 
 1. **Context Discovery** - Load project context via agent-discovery.md

package/.claude/commands/csetup.md

@@ -249,6 +249,233 @@ Continue anyway? (yes/no)
 
 ---
 
+### Step 2.6: Feature Best Practice Analysis (v2.2.0)
+
+> **NEW:** Validate spec against industry standards BEFORE checking stack best practices
+> **Reference:** `.claude/lib/feature-best-practices.md`
+
+WHY: Stack best practices tell you "how to use React well", but Feature best practices tell you "what a good auth system needs". The feature layer is higher-level and informs whether your spec is complete.
+
+```typescript
+output(`\n🔍 Analyzing Feature Best Practices...`)
+
+// 1. Detect features from proposal/tasks/design
+const combined = (proposalContent + ' ' + tasksContent + ' ' + designContent).toLowerCase()
+
+const featureDetection = {
+  authentication: {
+    keywords: ['login', 'auth', 'register', 'password', 'session', 'jwt', 'token', 'oauth'],
+    tier: 1, // Blocking
+    standards: [
+      { name: 'Short-lived access token', keywords: ['jwt', 'access', '15', '30', 'min'], priority: 'required' },
+      { name: 'Refresh token rotation', keywords: ['refresh', 'rotation', 'rotate'], priority: 'required' },
+      { name: 'Secure token storage', keywords: ['httponly', 'cookie', 'secure'], priority: 'required' },
+      { name: 'Token revocation', keywords: ['revoke', 'invalidate', 'logout'], priority: 'required' },
+      { name: 'Rate limiting', keywords: ['rate', 'limit', 'throttle', 'attempt'], priority: 'required' },
+      { name: 'Account lockout', keywords: ['lockout', 'lock', 'failed attempt'], priority: 'recommended' }
+    ]
+  },
+  payment: {
+    keywords: ['payment', 'stripe', 'checkout', 'billing', 'subscription'],
+    tier: 1,
+    standards: [
+      { name: 'No card data on server', keywords: ['elements', 'checkout', 'client-side'], priority: 'required' },
+      { name: 'Webhook signature verification', keywords: ['webhook', 'signature', 'verify'], priority: 'required' },
+      { name: 'Idempotency keys', keywords: ['idempotency', 'idempotent'], priority: 'required' }
+    ]
+  },
+  fileUpload: {
+    keywords: ['upload', 'file', 'image', 's3', 'storage'],
+    tier: 1,
+    standards: [
+      { name: 'File type validation', keywords: ['mime', 'type', 'validation', 'allowed'], priority: 'required' },
+      { name: 'File size limits', keywords: ['size', 'limit', 'max'], priority: 'required' },
+      { name: 'Filename sanitization', keywords: ['sanitize', 'filename', 'path'], priority: 'required' }
+    ]
+  },
+  apiDesign: {
+    keywords: ['api', 'endpoint', 'rest', 'graphql'],
+    tier: 2, // Warning
+    standards: [
+      { name: 'Rate limiting', keywords: ['rate', 'limit'], priority: 'required' },
+      { name: 'Input validation', keywords: ['validate', 'validation', 'zod', 'schema'], priority: 'required' },
+      { name: 'Pagination', keywords: ['pagination', 'page', 'limit', 'offset'], priority: 'recommended' }
+    ]
+  }
+}
+
+// 2. Find detected features
+const detectedFeatures = []
+for (const [featureName, config] of Object.entries(featureDetection)) {
+  if (config.keywords.some(kw => combined.includes(kw))) {
+    detectedFeatures.push({ name: featureName, ...config })
+  }
+}
+
+if (detectedFeatures.length > 0) {
+  output(`\n📋 Features Detected:`)
+  detectedFeatures.forEach(f => {
+    output(`   - ${f.name} (Tier ${f.tier}: ${f.tier === 1 ? 'Blocking' : 'Warning'})`)
+  })
+
+  // 3. For each Tier 1/2 feature, check spec against standards
+  const allGaps = []
+
+  for (const feature of detectedFeatures) {
+    output(`\n🔍 Checking ${feature.name} against industry standards...`)
+
+    const gaps = []
+    const matches = []
+
+    for (const standard of feature.standards) {
+      const isMentioned = standard.keywords.some(kw =>
+        designContent.toLowerCase().includes(kw)
+      )
+
+      if (isMentioned) {
+        matches.push(standard.name)
+      } else if (standard.priority === 'required') {
+        gaps.push({
+          feature: feature.name,
+          requirement: standard.name,
+          priority: standard.priority,
+          tier: feature.tier
+        })
+      }
+    }
+
+    if (matches.length > 0) {
+      output(`   ✅ Matches: ${matches.join(', ')}`)
+    }
+
+    if (gaps.length > 0) {
+      output(`   ❌ Gaps: ${gaps.map(g => g.requirement).join(', ')}`)
+      allGaps.push(...gaps)
+    }
+  }
+
+  // 4. Handle gaps based on tier
+  const tier1Gaps = allGaps.filter(g => g.tier === 1)
+  const tier2Gaps = allGaps.filter(g => g.tier === 2)
+
+  if (tier1Gaps.length > 0) {
+    output(`\n⚠️ Security-Critical Gaps Found (Tier 1)`)
+    output(``)
+    output(`Your spec is missing these industry-standard requirements:`)
+    output(``)
+
+    // Group by feature
+    const byFeature = {}
+    tier1Gaps.forEach(g => {
+      if (!byFeature[g.feature]) byFeature[g.feature] = []
+      byFeature[g.feature].push(g.requirement)
+    })
+
+    for (const [feature, reqs] of Object.entries(byFeature)) {
+      output(`   ${feature}:`)
+      reqs.forEach(r => output(`     - ${r}`))
+    }
+
+    output(``)
+    output(`Options:`)
+    output(`   A) Update spec - Add missing requirements to design.md`)
+    output(`   B) Document skip - Record why these aren't needed (requires justification)`)
+    output(`   C) Continue anyway - Proceed with security gap (not recommended)`)
+    output(``)
+
+    const decision = await askUserQuestion({
+      questions: [{
+        question: 'How would you like to handle the security gaps?',
+        header: 'Spec Gaps',
+        options: [
+          { label: 'A) Update spec', description: 'Add missing requirements to design.md (recommended)' },
+          { label: 'B) Document skip', description: 'Record justification for skipping' },
+          { label: 'C) Continue anyway', description: 'Proceed with gap (security risk)' }
+        ],
+        multiSelect: false
+      }]
+    })
+
+    if (decision.includes('A')) {
+      // Generate suggested additions
+      output(`\n📝 Add this to design.md:\n`)
+      output(`\`\`\`markdown`)
+      output(`### D{n}: Security Requirements (Industry Standard Alignment)`)
+      output(``)
+      output(`**Added based on industry best practices:**`)
+      output(``)
+      for (const [feature, reqs] of Object.entries(byFeature)) {
+        output(`#### ${feature}`)
+        reqs.forEach(r => output(`- ${r}`))
+      }
+      output(``)
+      output(`**Source:** Feature Best Practice Validation`)
+      output(`**Added:** ${new Date().toISOString().split('T')[0]}`)
+      output(`\`\`\``)
+      output(``)
+      output(`Please update design.md and re-run /csetup.`)
+      return
+    } else if (decision.includes('B')) {
+      // Document conscious skip
+      output(`\n📝 Add this to design.md to document the skip:\n`)
+      output(`\`\`\`markdown`)
+      output(`### D{n}: Conscious Security Trade-offs`)
+      output(``)
+      output(`**Skipped requirements (with justification):**`)
+      output(``)
+      output(`| Requirement | Why Skipped | Risk Level | Mitigation |`)
+      output(`|-------------|-------------|------------|------------|`)
+      for (const gap of tier1Gaps) {
+        output(`| ${gap.requirement} | [YOUR REASON] | [LOW/MED/HIGH] | [YOUR MITIGATION] |`)
+      }
+      output(``)
+      output(`**Acknowledged by:** User decision in /csetup`)
+      output(`**Date:** ${new Date().toISOString().split('T')[0]}`)
+      output(`\`\`\``)
+      output(``)
+
+      const confirm = await askUserQuestion({
+        questions: [{
+          question: 'Confirm you will document this in design.md?',
+          header: 'Confirm',
+          options: [
+            { label: 'Yes, continue', description: 'I will add documentation' },
+            { label: 'Cancel', description: 'Go back and update spec' }
+          ],
+          multiSelect: false
+        }]
+      })
+
+      if (confirm.includes('Cancel')) {
+        output(`\n❌ Setup cancelled. Please update design.md first.`)
+        return
+      }
+    }
+    // If C, just continue with warning logged
+  }
+
+  if (tier2Gaps.length > 0) {
+    output(`\n⚠️ Recommendations (Tier 2 - Non-blocking):`)
+    tier2Gaps.forEach(g => {
+      output(`   - ${g.feature}: ${g.requirement}`)
+    })
+    output(`   Continuing with setup...`)
+  }
+} else {
+  output(`\n✅ No security-critical features detected`)
+}
+
+// Store feature analysis for later use
+const featureAnalysis = {
+  detected: detectedFeatures.map(f => f.name),
+  tier1Gaps: tier1Gaps || [],
+  tier2Gaps: tier2Gaps || [],
+  validated: true
+}
+```
+
+---
+
 ### Step 2.7: Auto-Setup Best Practices (v1.8.0)
 
 > **NEW:** Auto-detect tech stack and generate best-practices (replaces /psetup and /agentsetup)
@@ -419,6 +646,243 @@ const stackForContext = {
 }
 ```
 
+---
+
+### Step 2.8: Library Capability Validation (v2.2.0)
+
+> **NEW:** Verify chosen libraries support ALL spec requirements before proceeding
+> **WHY:** Prevents spec drift - discovering during implementation that library doesn't support requirements
+
+```typescript
+output(`\n🔍 Validating Library Capabilities...`)
+
+// 1. Extract spec requirements from design.md
+const designPath = `openspec/changes/${changeId}/design.md`
+if (!fileExists(designPath)) {
+  output(`   ⚠️ No design.md found - skipping library validation`)
+} else {
+  const designContent = Read(designPath)
+
+  // 2. Find library mentions in spec
+  const libraryPatterns = {
+    'better-auth': {
+      patterns: ['better-auth', 'betterauth'],
+      context7Id: null, // No Context7 mapping yet
+      knownLimitations: [
+        { feature: 'refresh token rotation', supported: false },
+        { feature: 'redis session storage', supported: false },
+        { feature: 'jwt plugin', supported: true },
+        { feature: 'bearer plugin', supported: true },
+        { feature: 'session-based auth', supported: true }
+      ]
+    },
+    'nextauth': {
+      patterns: ['next-auth', 'nextauth', 'authjs'],
+      context7Id: '/nextauthjs/next-auth',
+      knownLimitations: []
+    },
+    'lucia': {
+      patterns: ['lucia', 'lucia-auth'],
+      context7Id: '/lucia-auth/lucia',
+      knownLimitations: []
+    },
+    'prisma': {
+      patterns: ['prisma'],
+      context7Id: '/prisma/prisma',
+      knownLimitations: []
+    },
+    'drizzle': {
+      patterns: ['drizzle'],
+      context7Id: '/drizzle-team/drizzle-orm',
+      knownLimitations: []
+    }
+  }
+
+  // 3. Detect which libraries are mentioned
+  const detectedLibraries = []
+  for (const [libName, config] of Object.entries(libraryPatterns)) {
+    if (config.patterns.some(p => designContent.toLowerCase().includes(p))) {
+      detectedLibraries.push({ name: libName, ...config })
+    }
+  }
+
+  if (detectedLibraries.length > 0) {
+    output(`\n📚 Libraries in Spec:`)
+    detectedLibraries.forEach(lib => output(`   - ${lib.name}`))
+
+    // 4. Extract requirements from design.md
+    // Look for patterns like: "JWT 15min", "refresh token", "rotation"
+    const requirementPatterns = [
+      { name: 'JWT access token', pattern: /jwt.*(?:access|token).*(\d+\s*min)/i },
+      { name: 'Refresh token', pattern: /refresh\s*token/i },
+      { name: 'Token rotation', pattern: /(?:token\s*)?rotation|rotate/i },
+      { name: 'Redis session', pattern: /redis.*session|session.*redis/i },
+      { name: 'Bearer token', pattern: /bearer\s*(?:token|auth)/i },
+      { name: 'OAuth providers', pattern: /oauth|google|github|social\s*login/i },
+      { name: 'Rate limiting', pattern: /rate\s*limit/i },
+      { name: 'Account lockout', pattern: /lockout|lock\s*account/i }
+    ]
+
+    const specRequirements = []
+    for (const rp of requirementPatterns) {
+      if (rp.pattern.test(designContent)) {
+        specRequirements.push(rp.name)
+      }
+    }
+
+    if (specRequirements.length > 0) {
+      output(`\n📋 Spec Requirements Found:`)
+      specRequirements.forEach(r => output(`   - ${r}`))
+
+      // 5. Check each library's capability
+      const capabilityGaps = []
+
+      for (const lib of detectedLibraries) {
+        output(`\n🔍 Checking ${lib.name} capabilities...`)
+
+        for (const req of specRequirements) {
+          // Check known limitations first
+          const known = lib.knownLimitations.find(l =>
+            req.toLowerCase().includes(l.feature.toLowerCase()) ||
+            l.feature.toLowerCase().includes(req.toLowerCase())
+          )
+
+          if (known && !known.supported) {
+            output(`   ❌ ${req} - NOT SUPPORTED`)
+            capabilityGaps.push({
+              library: lib.name,
+              requirement: req,
+              supported: false,
+              note: `${lib.name} does not have built-in support for ${req}`
+            })
+          } else if (known && known.supported) {
+            output(`   ✅ ${req} - Supported`)
+          } else {
+            // Unknown - query Context7 if available
+            if (lib.context7Id) {
+              output(`   🔍 ${req} - Checking Context7...`)
+              // Note: In actual implementation, this would call Context7
+              // For now, mark as unknown
+              output(`   ⚠️ ${req} - Verify manually`)
+            } else {
+              output(`   ⚠️ ${req} - Verify manually (no Context7 mapping)`)
+            }
+          }
+        }
+      }
+
+      // 6. Report gaps if any
+      if (capabilityGaps.length > 0) {
+        output(`\n⚠️ Library Capability Gaps Detected!`)
+        output(``)
+        output(`The following spec requirements are NOT supported by chosen libraries:`)
+        output(``)
+
+        // Group by library
+        const byLibrary = {}
+        capabilityGaps.forEach(g => {
+          if (!byLibrary[g.library]) byLibrary[g.library] = []
+          byLibrary[g.library].push(g.requirement)
+        })
+
+        for (const [library, reqs] of Object.entries(byLibrary)) {
+          output(`   ${library}:`)
+          reqs.forEach(r => output(`     - ${r}`))
+        }
+
+        output(``)
+        output(`This will cause spec drift during implementation!`)
+        output(``)
+        output(`Options:`)
+        output(`   A) Change library - Use a library that supports these features`)
+        output(`   B) Downgrade spec - Remove unsupported requirements (must document trade-off)`)
+        output(`   C) Custom implementation - Build missing features on top of library`)
+        output(`   D) Continue anyway - Proceed and let agent handle at implementation time`)
+        output(``)
+
+        const decision = await askUserQuestion({
+          questions: [{
+            question: 'How would you like to handle the capability gaps?',
+            header: 'Lib Gaps',
+            options: [
+              { label: 'A) Change library', description: 'Switch to a library that supports requirements' },
+              { label: 'B) Downgrade spec', description: 'Update design.md to use what library supports' },
+              { label: 'C) Custom implementation', description: 'Build on top of library (more work)' },
+              { label: 'D) Continue anyway', description: 'Let agent handle during implementation' }
+            ],
+            multiSelect: false
+          }]
+        })
+
+        if (decision.includes('A')) {
+          output(`\n📝 Suggested alternative libraries:`)
+          for (const [library, reqs] of Object.entries(byLibrary)) {
+            if (library === 'better-auth') {
+              output(`   Instead of ${library}, consider:`)
+              output(`   - lucia-auth (supports custom session storage)`)
+              output(`   - NextAuth.js (supports refresh token rotation with JWT strategy)`)
+              output(`   - Custom implementation with jose + Redis`)
+            }
+          }
+          output(``)
+          output(`Please update design.md with new library choice and re-run /csetup.`)
+          return
+        } else if (decision.includes('B')) {
+          output(`\n📝 Update design.md to remove unsupported requirements:`)
+          output(``)
+          output(`\`\`\`markdown`)
+          output(`### D{n}: Library Capability Alignment`)
+          output(``)
+          output(`**Changed requirements to match ${Object.keys(byLibrary).join(', ')} capabilities:**`)
+          output(``)
+          for (const gap of capabilityGaps) {
+            output(`- ~~${gap.requirement}~~ → Use ${gap.library}'s default approach instead`)
+          }
+          output(``)
+          output(`**Reason:** Library limitation`)
+          output(`**Trade-off:** ${capabilityGaps.map(g => g.requirement).join(', ')} not available`)
+          output(`**Date:** ${new Date().toISOString().split('T')[0]}`)
+          output(`\`\`\``)
+          output(``)
+          output(`Please update design.md and re-run /csetup.`)
+          return
+        } else if (decision.includes('C')) {
+          output(`\n📝 Custom implementation notes for agents:`)
+          output(``)
+          output(`Add to context.md:`)
+          output(`\`\`\`markdown`)
+          output(`## Custom Implementation Required`)
+          output(``)
+          output(`The following features need custom implementation:`)
+          for (const gap of capabilityGaps) {
+            output(`- ${gap.requirement} (not supported by ${gap.library})`)
+          }
+          output(``)
+          output(`Agents should implement these on top of the base library.`)
+          output(`\`\`\``)
+
+          // Store for context.md generation
+          customImplementationRequired = capabilityGaps
+        }
+        // If D, continue with gaps logged for agent awareness
+      } else {
+        output(`\n✅ All spec requirements supported by chosen libraries`)
+      }
+    }
+  } else {
+    output(`   ℹ️ No specific libraries detected in spec`)
+  }
+}
+
+// Store capability analysis
+const capabilityAnalysis = {
+  libraries: detectedLibraries || [],
+  requirements: specRequirements || [],
+  gaps: capabilityGaps || [],
+  customRequired: customImplementationRequired || []
+}
+```
+
 **Helper: generateBestPracticesFile()**
 ```typescript
 function generateBestPracticesFile(tech: string, context7Docs: string): string {

package/.claude/contexts/patterns/validation-framework.md

@@ -228,12 +228,56 @@ logger.warning("login_failed", extra={"email": email, "reason": "invalid_credent
 logger.error("login_error", extra={"error": str(e)})
 ```
 
-### F. Ready to Implement ✓
+### F. Library Feasibility Check ✓ (v2.2.0)
+**From:** design.md + library documentation
+
+**Spec Requirements:**
+- JWT access token 15min expiry
+- Refresh token with rotation
+- Redis session storage
+- Token revocation capability
+
+**Library Capability Verification:**
+- [x] JWT 15min → better-auth jwt plugin: YES ✅
+- [x] Refresh token → better-auth: PARTIAL ⚠️ (session-based, not separate token)
+- [ ] Token rotation → better-auth: NO ❌
+- [ ] Redis storage → better-auth: NO ❌
+
+**IF ALL SUPPORTED:**
+```
+✅ Library Feasibility Validated
+All spec requirements are supported by chosen library.
+Proceeding with implementation...
+```
+
+**IF GAPS FOUND:**
+```
+⚠️ Library Capability Gap Detected
+
+Library: better-auth
+Requirement: Refresh token rotation
+Support Status: NO
+
+What library supports: Session-based auth with auto-refresh
+What spec requires: Explicit refresh token rotation on each use
+
+Options:
+A) Change library → lucia-auth (supports custom session storage)
+B) Change spec → Use session-based approach instead
+C) Custom implementation → Build rotation on top of better-auth
+
+My Recommendation: B (simplest, meets core security needs)
+
+Awaiting decision before proceeding.
+```
+
+### G. Ready to Implement ✓
 ✅ Patterns loaded
 ✅ Existing endpoints searched
 ✅ TDD workflow planned
 ✅ Error handling pattern identified
 ✅ Logging pattern identified
+✅ Library feasibility validated
 
 **Proceeding with TDD (RED phase first)...**
 ```
@@ -244,8 +288,14 @@ logger.error("login_error", extra={"error": str(e)})
 - IF TDD: Contains "TDD Workflow" + "RED-GREEN-REFACTOR"
 - Contains: "Error Handling Pattern ✓"
 - Contains: "Logging Pattern ✓"
+- Contains: "Library Feasibility" (either "Validated" or "Gap Detected")
 - Contains: "Ready to Implement ✓"
 
+**Spec Deviation Markers (triggers workflow pause):**
+- "⚠️ Library Capability Gap"
+- "Awaiting decision"
+- "Support Status: NO"
+
 ---
 
 ### 3️⃣ **frontend Agent**

package/.claude/lib/agent-executor.md

@@ -318,6 +318,155 @@ Please provide complete output including:
 
 ---
 
+## 🔄 Spec Deviation Protocol (v2.2.0)
+
+When an agent discovers that implementation cannot match spec exactly, this protocol ensures proper handling.
+
+WHY: Silent spec drift creates technical debt and user confusion. Explicit decisions create documented trade-offs.
+
+### Detection Triggers
+
+Agent discovers:
+- Library doesn't support a spec feature
+- Technical constraint prevents exact implementation
+- Better alternative exists than what spec describes
+- Dependency conflict with existing code
+
+### Required Actions
+
+**Agent should NOT:**
+- Implement alternative approach silently
+- Change the approach without user knowledge
+- Continue with "close enough" solution
+- Assume user would prefer the simpler option
+
+**Agent MUST:**
+1. Document the gap clearly
+2. Stop implementation immediately
+3. Report to Main Claude with options
+4. Wait for explicit decision
+
+### Spec Deviation Report Format
+
+```markdown
+⚠️ Spec Deviation Required
+
+**Phase:** {current phase}
+**Agent:** {agent type}
+
+---
+
+**Spec Requirement:** (exact text from design.md)
+{paste the exact requirement from design.md}
+
+**Library/Technical Constraint:**
+{what the library/system actually supports}
+
+**Gap Analysis:**
+{explain what cannot be implemented as specified}
+
+---
+
+**Options:**
+
+A) **Change Approach** - Use what library supports
+   - Implementation: {alternative approach}
+   - Benefit: {what you gain}
+   - Trade-off: {what you lose vs spec}
+
+B) **Change Library** - Switch to alternative
+   - Alternative: {library name}
+   - Benefit: Matches spec exactly
+   - Trade-off: {migration effort, learning curve}
+
+C) **Custom Implementation** - Build on top of library
+   - Implementation: {what needs to be built}
+   - Benefit: Matches spec, uses existing library
+   - Trade-off: {maintenance burden, complexity}
+
+---
+
+**My Recommendation:** {A/B/C}
+**Reasoning:** {why this option is best}
+
+Awaiting decision before proceeding.
+```
+
+### Main Claude Response Protocol
+
+When receiving a spec deviation report:
+
+1. **Pause workflow** - Do not auto-proceed to next phase
+2. **Show report to user** - Present options clearly
+3. **Get explicit decision** - User must choose A, B, or C
+4. **Document decision** in design.md:
+
+   ```markdown
+   ### D{n}: {Decision Title}
+
+   **Context:** Agent found {library} doesn't support {feature}
+   **Decision:** Option {A/B/C} - {brief description}
+   **Reason:** {user's reasoning}
+   **Trade-off Accepted:** {what we're giving up}
+   **Date:** {date}
+   ```
+
+5. **Update spec if needed:**
+   - If Option A: Add "Library Capability Alignment" section to design.md
+   - If Option B: Update library references in design.md and tasks.md
+   - If Option C: Add "Custom Implementation Required" section
+
+6. **Resume workflow** with clear, documented direction
+
+### Spec Deviation Validation
+
+**Check agent output for spec deviation markers:**
+
+| Marker | Meaning |
+|--------|---------|
+| "⚠️ Spec Deviation" | Agent found gap, needs decision |
+| "Library Capability Gap" | Library doesn't support requirement |
+| "Awaiting decision" | Agent stopped, waiting for response |
+
+**Main Claude should:**
+- Pause workflow when seeing these markers
+- Present options to user
+- Record decision before resuming
+
+### Example Flow
+
+```
+Agent: Backend implementing auth
+  ↓
+Agent: Reads design.md "JWT + Redis refresh + rotation"
+  ↓
+Agent: Checks better-auth capabilities
+  ↓
+Agent: Finds "rotation" not supported
+  ↓
+Agent: ⚠️ STOPS - Sends Spec Deviation Report
+  ↓
+Main Claude: Pauses workflow, shows user options
+  ↓
+User: Chooses Option B (change library to lucia-auth)
+  ↓
+Main Claude: Updates design.md with decision
+  ↓
+Main Claude: Resumes workflow with new library
+  ↓
+Agent: Implements with lucia-auth (supports rotation)
+```
+
+### Benefits of Spec Deviation Protocol
+
+- **Prevents silent drift** - User knows about every deviation
+- **Documented trade-offs** - All decisions recorded in design.md
+- **Early detection** - Gaps found at pre-work, not during implementation
+- **Clear options** - User can make informed choice
+- **Audit trail** - Design decisions are traceable
+
+---
+
 ## 🎯 Benefits
 
 ✅ **Auto-recovery** - Transient errors handled automatically

package/.claude/lib/feature-best-practices.md

@@ -0,0 +1,386 @@
+# Feature Best Practices Detection & Validation
+
+> **Version:** 1.0.0
+> **Purpose:** Detect features from spec and validate against industry standards
+> **Used by:** `/csetup` Step 2.6
+
+---
+
+## Overview
+
+Before querying stack-level best practices (React, Next.js, etc.), we first need to:
+1. Detect what features the change involves (Auth, Payment, etc.)
+2. Query industry best practices for each feature
+3. Compare spec against industry standards
+4. Report gaps and get user decision
+
+WHY: Stack best practices tell you "how to use React well", but Feature best practices tell you "what a good auth system needs". The feature layer is higher-level and informs whether your spec is complete.
+
+---
+
+## Feature Detection
+
+### Keyword Mapping
+
+| Keywords in proposal/tasks/design | Feature Type | Security Tier |
+|-----------------------------------|--------------|---------------|
+| login, auth, register, password, session, jwt, token, oauth | Authentication | Tier 1 (Blocking) |
+| payment, stripe, checkout, billing, subscription, invoice | Payment | Tier 1 (Blocking) |
+| upload, file, image, s3, storage, attachment | File Upload | Tier 1 (Blocking) |
+| admin, role, permission, rbac, acl, access control | Authorization | Tier 1 (Blocking) |
+| api, endpoint, rest, graphql, webhook | API Design | Tier 2 (Warning) |
+| realtime, websocket, notification, push, sse | Real-time | Tier 2 (Warning) |
+| email, smtp, sendgrid, notification, mailer | Email/Notification | Tier 2 (Warning) |
+| search, elasticsearch, algolia, filter, query | Search | Tier 2 (Warning) |
+| cache, redis, memcached, cdn | Caching | Tier 2 (Warning) |
+| crud, list, table, form, dashboard | CRUD/UI | Tier 3 (Info) |
+| landing, hero, marketing, seo | Marketing Page | Tier 3 (Info) |
+
+### Security Tiers
+
+**Tier 1 (Blocking):** Security-critical features
+- Validation against industry standard is required
+- User must explicitly approve if skipping requirements
+- Gaps are documented in design.md
+
+**Tier 2 (Warning):** Important but not security-critical
+- Show warning if gaps found
+- Allow continue without blocking
+- Log decision
+
+**Tier 3 (Info):** Nice-to-have
+- Suggest best practices
+- No blocking or warning
+- Optional to follow
+
+---
+
+## Industry Standard Queries
+
+### Authentication
+
+**Query Topics:**
+```
+- "JWT authentication best practices 2024"
+- "refresh token rotation security"
+- "session management security best practices"
+- "OAuth 2.0 implementation best practices"
+```
+
+**Expected Standards:**
+
+| Requirement | Description | Priority |
+|-------------|-------------|----------|
+| Short-lived access token | JWT 15-60 minutes max | Required |
+| Refresh token rotation | New refresh token on each use | Required |
+| Secure token storage | httpOnly cookies, not localStorage | Required |
+| Token revocation | Ability to invalidate tokens immediately | Required |
+| Rate limiting | 5-10 attempts per minute on auth endpoints | Required |
+| Account lockout | Lock after N failed attempts | Recommended |
+| Password requirements | Min length, complexity | Required |
+| Secure password storage | bcrypt/argon2, never plain text | Required |
+| HTTPS only | All auth endpoints over TLS | Required |
+| CSRF protection | For cookie-based auth | Required |
+
+---
+
+### Payment
+
+**Query Topics:**
+```
+- "payment integration security best practices"
+- "PCI DSS compliance requirements"
+- "Stripe integration best practices"
+```
+
+**Expected Standards:**
+
+| Requirement | Description | Priority |
+|-------------|-------------|----------|
+| No card data on server | Use Stripe Elements/Checkout | Required |
+| Webhook signature verification | Validate Stripe webhook signatures | Required |
+| Idempotency keys | Prevent duplicate charges | Required |
+| Amount validation | Server-side price validation | Required |
+| Audit logging | Log all payment events | Required |
+| Error handling | Graceful failure, no sensitive data in errors | Required |
+| Test mode separation | Clear separation of test/live keys | Required |
+
+---
+
+### File Upload
+
+**Query Topics:**
+```
+- "file upload security best practices"
+- "image upload validation security"
+- "S3 presigned URL best practices"
+```
+
+**Expected Standards:**
+
+| Requirement | Description | Priority |
+|-------------|-------------|----------|
+| File type validation | Server-side MIME type check | Required |
+| File size limits | Configurable max size | Required |
+| Filename sanitization | Remove path traversal, special chars | Required |
+| Virus scanning | For user-uploaded files | Recommended |
+| Presigned URLs | For direct-to-S3 uploads | Recommended |
+| Access control | Private by default, signed URLs for access | Required |
+| Content-Disposition | Force download, prevent XSS | Required |
+
+---
+
+### Authorization (RBAC)
+
+**Query Topics:**
+```
+- "role based access control best practices"
+- "RBAC implementation patterns"
+- "authorization security best practices"
+```
+
+**Expected Standards:**
+
+| Requirement | Description | Priority |
+|-------------|-------------|----------|
+| Deny by default | No access unless explicitly granted | Required |
+| Server-side checks | Never trust client-side only | Required |
+| Principle of least privilege | Minimal permissions needed | Required |
+| Role hierarchy | Clear inheritance if needed | Recommended |
+| Audit logging | Log access decisions | Required |
+| Separation of duties | Critical actions need multiple roles | Recommended |
+
+---
+
+### API Design
+
+**Query Topics:**
+```
+- "REST API design best practices 2024"
+- "API security best practices"
+- "API rate limiting best practices"
+```
+
+**Expected Standards:**
+
+| Requirement | Description | Priority |
+|-------------|-------------|----------|
+| Consistent naming | Resource-based URLs, proper HTTP methods | Required |
+| Versioning | URL or header-based versioning | Recommended |
+| Rate limiting | Per-user/IP rate limits | Required |
+| Input validation | Validate all inputs server-side | Required |
+| Error format | Consistent error response structure | Required |
+| Pagination | For list endpoints | Required |
+| CORS configuration | Proper origin restrictions | Required |
+
+---
+
+## Spec Comparison Logic
+
+### Extracting Spec Requirements
+
+From `design.md`, look for:
+1. **Decision sections** (### D1, ### D2, etc.)
+2. **Technical specs** (tables, bullet points)
+3. **Architecture descriptions**
+
+### Comparison Algorithm
+
+```typescript
+interface SpecComparison {
+  feature: string
+  industryRequirements: Requirement[]
+  specRequirements: string[]
+  gaps: Gap[]
+  matches: Match[]
+}
+
+interface Gap {
+  requirement: string
+  priority: 'required' | 'recommended'
+  securityImpact: 'high' | 'medium' | 'low'
+  suggestion: string
+}
+
+function compareSpecToIndustry(
+  featureType: string,
+  specContent: string,
+  industryStandards: Requirement[]
+): SpecComparison {
+  const gaps = []
+  const matches = []
+
+  for (const standard of industryStandards) {
+    // Check if spec mentions this requirement
+    const mentioned = checkIfMentioned(specContent, standard.keywords)
+
+    if (mentioned) {
+      matches.push({ requirement: standard.name, specText: mentioned })
+    } else if (standard.priority === 'required') {
+      gaps.push({
+        requirement: standard.name,
+        priority: standard.priority,
+        securityImpact: standard.securityImpact,
+        suggestion: standard.suggestion
+      })
+    }
+  }
+
+  return { feature: featureType, industryRequirements, specRequirements, gaps, matches }
+}
+```
+
+---
+
+## Gap Report Format
+
+### For Tier 1 (Blocking) Features
+
+```markdown
+## Feature Best Practice Validation
+
+### Feature: Authentication
+**Security Tier:** 1 (Blocking)
+
+### Spec vs Industry Standard
+
+| Requirement | Industry Standard | Your Spec | Status |
+|-------------|------------------|-----------|--------|
+| Access token expiry | 15-60 min | 15 min | ✅ Match |
+| Refresh token rotation | Required | Not specified | ❌ Gap |
+| Token revocation | Required | Redis-based | ✅ Match |
+| Rate limiting | 5-10/min | Not specified | ❌ Gap |
+| Account lockout | Recommended | Not specified | ⚠️ Missing |
+
+### Gaps Found: 2 Required, 1 Recommended
+
+**Security Impact:** HIGH
+
+⚠️ Your spec is missing security-critical requirements.
+
+### Options:
+
+**A) Update spec (Recommended)**
+   Add missing requirements to design.md:
+   - Refresh token rotation on each use
+   - Rate limiting: 5 attempts per minute
+
+**B) Document conscious skip**
+   Record why these aren't needed for your use case.
+   (Requires justification for security review)
+
+**C) Continue anyway**
+   Proceed without these requirements.
+   ⚠️ Security risk - not recommended for production
+
+Which option? [A/B/C]
+```
+
+### For Tier 2 (Warning) Features
+
+```markdown
+## Feature Best Practice Validation
+
+### Feature: API Design
+**Security Tier:** 2 (Warning)
+
+### Recommendations
+
+Your spec could be improved with:
+- [ ] API versioning strategy
+- [ ] Pagination for list endpoints
+- [ ] Consistent error format
+
+These are recommended but not blocking.
+Continuing with implementation...
+```
+
+---
+
+## Suggested Spec Updates
+
+When user chooses Option A (Update spec), generate:
+
+```markdown
+### D{n}: Security Requirements (Industry Standard Alignment)
+
+**Added based on industry best practices:**
+
+#### Authentication Security
+- Refresh token rotation: Generate new refresh token on each use
+- Rate limiting: Max 5 login attempts per minute per IP
+- Account lockout: Lock account for 15 minutes after 5 failed attempts
+
+#### Rationale
+These requirements align with OWASP Authentication Guidelines and
+industry standard security practices for production applications.
+
+**Source:** Feature Best Practice Validation in /csetup
+**Added:** {date}
+```
+
+---
+
+## Conscious Skip Documentation
+
+When user chooses Option B (Document skip):
+
+```markdown
+### D{n}: Conscious Security Trade-offs
+
+**Skipped requirements (with justification):**
+
+| Requirement | Why Skipped | Risk Level | Mitigation |
+|-------------|-------------|------------|------------|
+| Refresh token rotation | Internal tool, 3 users only | Low | Short session timeout (1 hour) |
+| Rate limiting | Behind VPN, no public access | Low | VPN already rate-limits |
+
+**Acknowledged by:** User decision in /csetup
+**Date:** {date}
+**Review reminder:** Re-evaluate if app becomes public-facing
+```
+
+---
+
+## Integration with /csetup
+
+This file is used in Step 2.6 of `/csetup`:
+
+```typescript
+// In csetup.md Step 2.6
+
+// 1. Detect features
+const features = detectFeatures(proposalContent, tasksContent, designContent)
+
+// 2. For each Tier 1/2 feature, validate
+for (const feature of features) {
+  const industryStandards = loadIndustryStandards(feature.type)
+  const comparison = compareSpecToIndustry(feature.type, designContent, industryStandards)
+
+  if (comparison.gaps.length > 0 && feature.tier <= 2) {
+    // Show gap report and get user decision
+    const decision = await showGapReport(comparison)
+
+    if (decision === 'A') {
+      // Generate spec update suggestions
+      await updateSpec(changeId, comparison.gaps)
+    } else if (decision === 'B') {
+      // Document conscious skip
+      await documentSkip(changeId, comparison.gaps)
+    }
+  }
+}
+```
+
+---
+
+## Best Practice Sources
+
+When querying, use these sources in order:
+1. **Context7** - For library-specific best practices
+2. **OWASP** - For security best practices
+3. **Industry standards** - PCI DSS, OAuth 2.0 RFC, etc.
+
+---
+
+This feature-first validation ensures specs are complete before we check if libraries support them.

package/README.md

@@ -29,10 +29,24 @@ cak init
 
 ## Features
 
+- **4-Layer Validation (v2.2.0)** - Feature BP → Spec Alignment → Library Capability → Stack BP
+- **Spec Drift Prevention** - Validates library supports spec before implementation
 - **Instruction-based Library Detection** - Agents scan `tasks.md`/`design.md` for required libraries
 - **Cross-session Context** - `PROJECT_STATUS.yml` maintains state across sessions
 - **Design System v2.0** - Interactive setup with theme selection
 
+## Validation Flow (v2.2.0)
+
+```
+/csetup
+  ├── Step 2.6: Feature Best Practice (Auth, Payment, etc. vs industry standard)
+  ├── Step 2.7: Stack Best Practice (React, Next.js, etc.)
+  └── Step 2.8: Library Capability (verify library supports spec)
+
+/cdev
+  └── Agent Step 0.5: Double-check feasibility before implement
+```
+
 ## Commands
 
 **CLI:** `cak init` | `cak update`

package/package.json

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