@champpaba/claude-agent-kit 2.4.0 → 2.6.0

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 2.4.0 - Adaptive Depth Research
-> **Latest:** Dynamic research layers (0-10+) per change + Zero-maintenance tech detection + Claude 4.5 optimized agents
+> **Template Version:** 2.5.0 - Smart Topic Query
+> **Latest:** Cross-library integration detection + Integration risk summary + Proactive error prevention
 
 ---
 
@@ -131,18 +131,22 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 📚 Best Practices System (v2.3.0 - Zero Maintenance)
+## 📚 Best Practices System (v2.5.0 - Smart Topic Query)
 
 **Quick Summary:**
 - `/csetup` **dynamically detects any library** from spec text + package files (no hardcoded mappings)
 - **Works with any language:** JavaScript, Python, Rust, Go, PHP, Ruby - automatically
 - **Context7 validates** each potential library name and resolves to official docs
+- **v2.5.0:** Smart Topic Query includes other library names for cross-library integration docs
+- **v2.5.0:** Auto-generates `INTEGRATION_RISKS.md` with detected concerns
 - Files created in `.claude/contexts/domain/project/best-practices/`
-- **Agents read** best practices before coding (validated by agent-executor)
+- **Agents read** best practices + integration risks before coding
 
-**Key Change in v2.3.0:**
-- ❌ Old: Hardcoded regex patterns + manual ID mappings (required maintenance)
-- ✅ New: NLP extraction + Context7 resolution (zero maintenance, any library)
+**Key Changes:**
+| Version | Change |
+|---------|--------|
+| v2.3.0 | NLP extraction + Context7 resolution (zero maintenance) |
+| v2.5.0 | Smart Topic Query + Integration Risk Detection |
 
 **Detection Sources:**
 | Source | Examples |
@@ -155,15 +159,24 @@ Universal, framework-agnostic template for AI-assisted development.
 | PHP | composer.json |
 | Ruby | Gemfile |
 
-**Flow:**
+**Flow (v2.5.0):**
 ```
 /csetup → extract potential library names from ALL text sources
         → Context7 resolve-library-id (validates if real library)
-        → Context7 get-library-docs (fetch best practices)
+        → Context7 get-library-docs (Smart Topic Query with other lib names)
+        → detect integration risks from docs content
         → generate .md files for each verified library
+        → generate INTEGRATION_RISKS.md if risks detected
 /cdev   → inject paths into prompt → agent reads → validation checks
 ```
 
+**Output Files:**
+| File | Content |
+|------|---------|
+| `{lib}.md` | Library best practices with integration info |
+| `INTEGRATION_RISKS.md` | Cross-library risks + checklist (if any detected) |
+| `index.md` | Registry of all best practices files |
+
 ---
 
 ## 🎨 Design System v2.0.0 (Interactive Setup)
@@ -305,6 +318,86 @@ User: "Build login system"
 
 ---
 
+## 🆕 v2.5.0: Smart Topic Query + Integration Risk Detection
+
+**Problem Solved:** Context7 queries used static topic "best practices" which missed adapter/integration documentation. Example: Drizzle + Auth.js requires specific column naming (snake_case) but this wasn't detected, causing runtime errors.
+
+**Solution:** Smart Topic Query includes other library names in topic + automatic integration risk detection.
+
+### How Smart Topic Query Works
+
+```
+Old (v2.4.0):
+  topic: "best practices, patterns, anti-patterns, common mistakes"
+  → Misses adapter-specific docs
+
+New (v2.5.0):
+  topic: "best practices, patterns, adapter, integration, schema, {other-lib-names}"
+  → Gets cross-library integration docs automatically
+```
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Smart Topic** | Includes other detected library names in Context7 topic |
+| **Bidirectional Query** | Query BOTH libraries (Auth.js → Drizzle, Drizzle → Auth.js) |
+| **Risk Pattern Detection** | Scans docs for adapter, schema, column, sync, webhook patterns |
+| **INTEGRATION_RISKS.md** | Auto-generated summary of detected integration concerns |
+| **Zero Maintenance** | No hardcoded library pairs - works with any combination |
+
+### Integration Risk Patterns Detected
+
+| Pattern | Keywords | Example |
+|---------|----------|---------|
+| Adapter | adapter, drizzleadapter, prismaadapter | ORM + Auth integrations |
+| Schema | column, snake_case, camelcase, mapping | Column naming mismatches |
+| Sync | sync, migrate, syncurl, embedded replica | Mobile/Edge data sync |
+| Webhook | webhook, webhookendpoint | Payment/notification handlers |
+| Lifecycle | beforeall, aftereach, setup, teardown | Test configuration |
+
+### Output Files
+
+| File | Content |
+|------|---------|
+| `best-practices/{lib}.md` | Library-specific best practices (enhanced with integration docs) |
+| `best-practices/INTEGRATION_RISKS.md` | Cross-library risk summary + checklist |
+
+### Example Flow
+
+```
+Detected: [drizzle, auth.js, stripe]
+
+Query drizzle with topic: "best practices, adapter, integration, auth.js, stripe"
+  → Gets: Drizzle adapter patterns, column naming
+
+Query auth.js with topic: "best practices, adapter, integration, drizzle, stripe"
+  → Gets: DrizzleAdapter config, usersTable/accountsTable schema
+
+Query stripe with topic: "best practices, adapter, integration, drizzle, auth.js"
+  → Gets: Webhook patterns, payment integration
+
+Risk Detection:
+  → auth.js mentions "drizzleadapter", "userstable" → SCHEMA pattern
+  → stripe mentions "webhook", "webhooksecret" → WEBHOOK pattern
+
+Output:
+  → drizzle.md (with auth.js integration info)
+  → auth-js.md (with Drizzle adapter config)
+  → stripe.md (with webhook patterns)
+  → INTEGRATION_RISKS.md (summary of all detected risks)
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` Step 2.7 | Smart Topic Query implementation |
+| `detectIntegrationRisks()` | New: Pattern detection from docs |
+| `generateIntegrationRiskSummary()` | New: INTEGRATION_RISKS.md output |
+
+---
+
 ## 🆕 v2.4.0: Adaptive Depth Research
 
 **Problem Solved:** Previous feature detection was hardcoded (only 4 types: auth, payment, fileUpload, apiDesign) and used fixed standards. Missing domain-level best practices like "how to design a good database" or "healthcare compliance requirements."

package/.claude/commands/csetup.md

@@ -1045,6 +1045,7 @@ if (resolvedLibraries.length === 0) {
 }
 
 // 5. Generate best-practices files for resolved libraries
+// v2.5.0: Smart Topic Query - include other library names for cross-library integration docs
 const bpDir = '.claude/contexts/domain/project/best-practices/'
 const existingBp = fileExists(bpDir) ? listFiles(bpDir) : []
 
@@ -1056,22 +1057,53 @@ const newLibraries = resolvedLibraries.filter(lib => {
 
 if (newLibraries.length > 0) {
   output(`\n📚 Generating Best Practices from Context7...`)
+  output(`   💡 Using Smart Topic Query for cross-library integration docs`)
 
   // Create directory if needed
   if (!fileExists(bpDir)) {
     mkdir(bpDir)
   }
 
+  // Collect all integration risks for summary
+  const integrationRisks = []
+
   for (const lib of newLibraries) {
     output(`   📖 Fetching ${lib.title} best practices...`)
 
     try {
+      // v2.5.0: Smart Topic Query - include other library names in topic
+      // WHY: This captures integration docs (e.g., "drizzle adapter" in auth.js docs)
+      const otherLibNames = resolvedLibraries
+        .filter(l => l.name !== lib.name)
+        .map(l => l.name.toLowerCase())
+        .slice(0, 5) // Limit to 5 to avoid topic overflow
+        .join(', ')
+
+      const smartTopic = [
+        'best practices',
+        'patterns',
+        'anti-patterns',
+        'common mistakes',
+        'adapter',        // Key for ORM + Auth integrations
+        'integration',    // Key for multi-library setups
+        'schema',         // Key for database + auth column naming
+        'configuration',  // Key for setup requirements
+        otherLibNames     // Include other detected libraries
+      ].filter(Boolean).join(', ')
+
       const docs = await mcp__context7__get_library_docs({
         context7CompatibleLibraryID: lib.context7Id,
-        topic: 'best practices, patterns, anti-patterns, common mistakes',
+        topic: smartTopic,
         mode: 'code'
       })
 
+      // v2.5.0: Detect integration risks from docs content
+      const risks = detectIntegrationRisks(docs, lib.name, resolvedLibraries)
+      if (risks.length > 0) {
+        integrationRisks.push(...risks)
+        output(`   ⚠️ Found ${risks.length} integration pattern(s) to review`)
+      }
+
       const bpContent = generateBestPracticesFile(lib.title, docs, lib.context7Id)
       const safeName = lib.name.toLowerCase().replace(/[^a-z0-9]/g, '-')
       Write(`${bpDir}${safeName}.md`, bpContent)
@@ -1082,6 +1114,13 @@ if (newLibraries.length > 0) {
     }
   }
 
+  // v2.5.0: Generate integration risk summary if any found
+  if (integrationRisks.length > 0) {
+    generateIntegrationRiskSummary(integrationRisks, bpDir, resolvedLibraries)
+    output(`\n⚠️ Integration Risk Summary generated (${integrationRisks.length} items)`)
+    output(`   📄 ${bpDir}INTEGRATION_RISKS.md`)
+  }
+
   // Generate/update index.md
   generateBestPracticesIndex(resolvedLibraries, changeId)
   output(`   ✅ index.md updated`)
@@ -1771,6 +1810,228 @@ function extractChecklist(docs: string): string {
 
 ---
 
+### Helper: detectIntegrationRisks() - v2.5.0
+
+> **Smart Risk Detection:** Scans Context7 docs for integration patterns that require attention.
+> **WHY:** Proactively catch integration requirements BEFORE implementation, not at runtime.
+
+```typescript
+function detectIntegrationRisks(
+  docs: string,
+  currentLib: string,
+  allLibs: Array<{ name: string; title: string }>
+): Array<{ library: string; risk: string; pattern: string; recommendation: string }> {
+  const risks = []
+  const docsLower = docs.toLowerCase()
+
+  // Integration risk patterns to detect
+  const riskPatterns = [
+    // Adapter patterns (ORM + Auth)
+    {
+      keywords: ['adapter', 'drizzleadapter', 'prismaadapter'],
+      risk: 'Database adapter configuration required',
+      pattern: 'adapter',
+      recommendation: 'Verify adapter schema matches expected column names'
+    },
+    // Column naming patterns
+    {
+      keywords: ['column', 'columnname', 'snake_case', 'camelcase', 'mapping'],
+      risk: 'Column naming convention mismatch possible',
+      pattern: 'schema',
+      recommendation: 'Check column naming between ORM schema and library expectations'
+    },
+    // Schema patterns
+    {
+      keywords: ['userstable', 'accountstable', 'sessionstable', 'schema'],
+      risk: 'Custom table schema required',
+      pattern: 'schema',
+      recommendation: 'Ensure table schemas match library documentation exactly'
+    },
+    // Sync/Migration patterns
+    {
+      keywords: ['sync', 'migrate', 'migration', 'syncurl', 'embedded replica'],
+      risk: 'Data synchronization setup required',
+      pattern: 'sync',
+      recommendation: 'Configure sync intervals and handle offline scenarios'
+    },
+    // Webhook patterns
+    {
+      keywords: ['webhook', 'webhookendpoint', 'webhooksecret'],
+      risk: 'Webhook endpoint configuration required',
+      pattern: 'webhook',
+      recommendation: 'Set up webhook endpoints and verify signatures'
+    },
+    // API Key patterns
+    {
+      keywords: ['apikey', 'secretkey', 'authtoken', 'bearer'],
+      risk: 'API credentials setup required',
+      pattern: 'credentials',
+      recommendation: 'Store credentials securely in environment variables'
+    },
+    // Lifecycle patterns
+    {
+      keywords: ['beforeall', 'afterall', 'beforeeach', 'aftereach', 'setup', 'teardown'],
+      risk: 'Test lifecycle hooks required',
+      pattern: 'lifecycle',
+      recommendation: 'Implement proper setup/teardown in test configuration'
+    }
+  ]
+
+  for (const rp of riskPatterns) {
+    const found = rp.keywords.some(kw => docsLower.includes(kw.toLowerCase()))
+    if (found) {
+      // Check if this risk involves other detected libraries
+      const involvedLibs = allLibs
+        .filter(l => l.name !== currentLib)
+        .filter(l => docsLower.includes(l.name.toLowerCase()))
+        .map(l => l.name)
+
+      risks.push({
+        library: currentLib,
+        risk: rp.risk,
+        pattern: rp.pattern,
+        recommendation: rp.recommendation,
+        involvedLibraries: involvedLibs
+      })
+    }
+  }
+
+  return risks
+}
+```
+
+---
+
+### Helper: generateIntegrationRiskSummary() - v2.5.0
+
+> **Risk Summary Output:** Creates INTEGRATION_RISKS.md with all detected cross-library concerns.
+> **WHY:** Agents can review this BEFORE implementation to avoid common integration mistakes.
+
+```typescript
+function generateIntegrationRiskSummary(
+  risks: Array<{
+    library: string
+    risk: string
+    pattern: string
+    recommendation: string
+    involvedLibraries?: string[]
+  }>,
+  bpDir: string,
+  allLibs: Array<{ name: string; title: string }>
+): void {
+  // Group risks by pattern type
+  const byPattern = {}
+  for (const r of risks) {
+    if (!byPattern[r.pattern]) byPattern[r.pattern] = []
+    byPattern[r.pattern].push(r)
+  }
+
+  const content = `# Integration Risk Summary
+
+> **Generated:** ${new Date().toISOString().split('T')[0]}
+> **Template Version:** 2.5.0 - Smart Topic Query
+> **Detected Libraries:** ${allLibs.map(l => l.name).join(', ')}
+
+---
+
+## ⚠️ Review Before Implementation
+
+The following integration patterns were detected from library documentation.
+**Agents should review these items in STEP 0 before writing code.**
+
+---
+
+${Object.entries(byPattern).map(([pattern, patternRisks]) => `
+### ${pattern.toUpperCase()} Patterns
+
+| Library | Risk | Recommendation |
+|---------|------|----------------|
+${patternRisks.map(r => `| ${r.library} | ${r.risk} | ${r.recommendation} |`).join('\n')}
+${patternRisks.some(r => r.involvedLibraries?.length > 0) ? `
+**Cross-library concerns:**
+${patternRisks.filter(r => r.involvedLibraries?.length > 0).map(r => `- ${r.library} ↔ ${r.involvedLibraries.join(', ')}: ${r.risk}`).join('\n')}
+` : ''}
+`).join('\n')}
+
+---
+
+## Quick Checklist
+
+Before implementing integrations:
+
+${[...new Set(risks.map(r => r.recommendation))].map(rec => `- [ ] ${rec}`).join('\n')}
+
+---
+
+**This file is auto-generated by /csetup v2.5.0**
+**Agents read this in STEP 0 alongside best-practices files**
+`
+
+  Write(`${bpDir}INTEGRATION_RISKS.md`, content)
+}
+```
+
+---
+
+### Helper: generateBestPracticesIndex() - v2.5.0
+
+> **Index File:** Creates index.md registry of all best practices files.
+> **v2.5.0:** Now includes INTEGRATION_RISKS.md if present.
+
+```typescript
+function generateBestPracticesIndex(
+  resolvedLibraries: Array<{ name: string; title: string; context7Id: string }>,
+  changeId: string
+): void {
+  const bpDir = '.claude/contexts/domain/project/best-practices/'
+  const hasIntegrationRisks = fileExists(`${bpDir}INTEGRATION_RISKS.md`)
+
+  const content = `# Best Practices Index
+
+> **Generated:** ${new Date().toISOString().split('T')[0]}
+> **Template Version:** 2.5.0 - Smart Topic Query
+> **Change:** ${changeId}
+
+---
+
+## 📚 Library Best Practices
+
+| Library | File | Context7 ID |
+|---------|------|-------------|
+${resolvedLibraries.map(lib => {
+  const safeName = lib.name.toLowerCase().replace(/[^a-z0-9]/g, '-')
+  return `| ${lib.title} | [${safeName}.md](./${safeName}.md) | \`${lib.context7Id}\` |`
+}).join('\n')}
+
+---
+
+${hasIntegrationRisks ? `## ⚠️ Integration Risks
+
+Cross-library integration concerns detected. **Review before implementation.**
+
+→ [INTEGRATION_RISKS.md](./INTEGRATION_RISKS.md)
+
+---
+
+` : ''}## Usage
+
+Agents read these files in **STEP 0** before implementation:
+
+1. Read \`index.md\` (this file) for overview
+2. Read relevant \`{library}.md\` files for specific best practices
+${hasIntegrationRisks ? '3. Read `INTEGRATION_RISKS.md` for cross-library concerns' : ''}
+
+---
+
+**Auto-generated by /csetup v2.5.0**
+`
+
+  Write(`${bpDir}index.md`, content)
+}
+```
+
+---
+
 ### Step 3: Analyze Tasks
 
 **Parse tasks.md content and detect keywords:**
@@ -2348,33 +2609,91 @@ contextTemplate = contextTemplate
 
 Write to: `openspec/changes/{change-id}/.claude/context.md`
 
-### Step 8: Output Summary
+### Step 8: Output Summary (ENHANCED v2.6.0)
 
-```
+```typescript
+// Check if UI work was detected (from Step 2.5/Step 3)
+const hasUIWork = hasFrontend || (hasDatabase && lower.includes('ui'))
+
+// Check for existing page-plan.md
+const pagePlanPath = `openspec/changes/${changeId}/page-plan.md`
+const hasPagePlan = fileExists(pagePlanPath)
+
+// Build output
+let output = `
 ✅ Change setup complete!
 
-📦 Change: {change-id}
-📋 Template: {template-name} ({total-phases} phases)
-🛠️ Detected: {detected-categories}
+📦 Change: ${changeId}
+📋 Template: ${templateName} (${totalPhases} phases)
+🛠️ Detected: ${detectedCategories.join(', ')}
 
 📁 Files created:
-✓ openspec/changes/{change-id}/.claude/phases.md
-✓ openspec/changes/{change-id}/.claude/flags.json
-✓ openspec/changes/{change-id}/.claude/context.md
+✓ openspec/changes/${changeId}/.claude/phases.md
+✓ openspec/changes/${changeId}/.claude/flags.json
+✓ openspec/changes/${changeId}/.claude/context.md
 
 📊 Workflow:
-   Phase 1: {first-phase-name} ({agent} agent, {estimated} min)
+   Phase 1: ${firstPhaseName} (${firstPhaseAgent} agent, ${firstPhaseMin} min)
    ...
-   Phase {n}: {last-phase-name}
+   Phase ${totalPhases}: ${lastPhaseName}
 
-⏱️ Total estimated time: ~{hours}h {minutes}m
+⏱️ Total estimated time: ~${hours}h ${minutes}m
+`
 
+// 🆕 v2.6.0: Recommend /pageplan if UI work detected
+if (hasUIWork) {
+  if (hasPagePlan) {
+    output += `
+✅ page-plan.md found: ${pagePlanPath}
+   → uxui-frontend will use this for component planning
+`
+  } else {
+    output += `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎨 UI Work Detected!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phases with UI work:
+${uiPhases.map(p => \`   • Phase \${p.number}: \${p.name} (\${p.agent})\`).join('\\n')}
+
+💡 RECOMMENDED: Run /pageplan before /cdev
+
+   Why?
+   ├── Content variants (3 options per element - user picks A/B/C)
+   ├── Component index (auto-generated, prevents duplicates)
+   ├── Asset checklist (images, icons with specs)
+   └── Approval process (user reviews before implementation)
+
+📝 Recommended Steps:
+   1. /pageplan @prd.md           ← Generate page plan
+   2. Edit page-plan.md           ← Pick A/B/C content, prepare assets
+   3. Mark APPROVED in Section 6  ← Sign-off before implementation
+   4. /cdev ${changeId}           ← Implement with real content
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`
+  }
+}
+
+output += `
 🚀 Ready to start development!
 
-Next steps:
-1. Review generated workflow: openspec/changes/{change-id}/.claude/phases.md
-2. Start development: /cdev {change-id}
-3. View progress: /cview {change-id}
+Next steps:`
+
+if (hasUIWork && !hasPagePlan) {
+  output += `
+1. (Recommended) Run: /pageplan @prd.md
+2. Edit page-plan.md (content, assets, approval)
+3. Review workflow: openspec/changes/${changeId}/.claude/phases.md
+4. Start development: /cdev ${changeId}
+5. View progress: /cview ${changeId}`
+} else {
+  output += `
+1. Review workflow: openspec/changes/${changeId}/.claude/phases.md
+2. Start development: /cdev ${changeId}
+3. View progress: /cview ${changeId}`
+}
+
+console.log(output)
 ```
 
 ---