@champpaba/claude-agent-kit 2.3.0 → 2.5.0

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 2.3.0 - Zero-Maintenance Tech Detection
-> **Latest:** Dynamic library detection via Context7 (any language, no hardcoded mappings) + 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)
@@ -185,19 +198,31 @@ Universal, framework-agnostic template for AI-assisted development.
 - 📜 **Scroll Patterns:** stacking-cards, parallax, fade-in, slide-in
 - 🖼️ **Decorative Direction:** USE/AVOID elements for theme consistency
 
-**Flow:**
+**Flow (v2.4.0):**
 ```
 /extract → .claude/extractions/*.json
            ↓
 /designsetup → tokens.json + patterns/*.md + STYLE_GUIDE.md
            ↓
-/pageplan → page-plan.md (reads tokens.json, auto-detects page type)
+/pageplan → page-plan.md (VISUAL: layout, components, animations, assets)
            ↓
-/csetup → phases.md (reads page-plan.md)
+/csetup → research-checklist.md (RESEARCH: best practices, content, UX)
+        → best-practices/*.md (Stack: Context7)
+        → phases.md
            ↓
-/cdev → uxui-frontend (reads tokens.json + patterns/*.md selectively)
+/cdev → uxui-frontend reads:
+        - tokens.json (design tokens)
+        - patterns/*.md (code patterns)
+        - page-plan.md (visual structure)
+        - research-checklist.md (content & UX)
 ```
 
+**Separation of Concerns:**
+| Command | Focus | Output |
+|---------|-------|--------|
+| `/pageplan` | Visual (layout, wireframe, animations) | `page-plan.md` |
+| `/csetup` | Research (best practices, content, UX) | `research-checklist.md` |
+
 ---
 
 ## ⚡ Context Optimization (v2.0.0)
@@ -218,33 +243,30 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 📋 Page Planning System (v2.0.0 - Auto Page Type Detection)
+## 📋 Page Planning System (v2.4.0 - Visual Planning Only)
 
 **→ See:** `@/.claude/lib/detailed-guides/page-planning.md` for complete guide
 
 **Quick Summary:**
-- **Problem:** Agents duplicate components (Navbar 3x), use random colors, lorem ipsum content, wrong decorations for page type
-- **Solution:** `/pageplan @prd.md @brief.md` → Generates `openspec/changes/{id}/page-plan.md` with:
-  - **Auto page type detection** (landing/dashboard/auth from proposal.md/tasks.md)
-  - **tokens.json integration** (style, theme, animations, decorative direction)
-  - **Selective pattern loading** (only load patterns relevant to page type)
+- **Problem:** Agents duplicate components (Navbar 3x), wrong layout structure
+- **Solution:** `/pageplan` → Generates `openspec/changes/{id}/page-plan.md` with:
   - Component reuse plan ✅ (prevent duplicates)
-  - Buyer avatar analysis (Eugene Schwartz framework) **for marketing pages only**
-  - Conversion-optimized content (pain → promise → CTA) **for marketing pages only**
+  - Layout wireframe (ASCII art for Desktop/Tablet/Mobile)
+  - Animation blueprint (hover, focus, transition patterns)
   - Asset checklist ✅ (performance-optimized)
 
-**Page Type Handling:**
-| Page Type | Decorations | Scroll Anims | Buyer Avatar | Patterns Loaded |
-|-----------|-------------|--------------|--------------|-----------------|
-| Landing/Marketing | ✅ Full | ✅ Enabled | ✅ Enabled | buttons, cards, scroll-anims, decorations |
-| Dashboard/Admin | ❌ Minimal | ❌ Disabled | ❌ Skipped | buttons, cards, forms |
-| Auth (Login/Register) | ❌ None | ❌ Disabled | ❌ Skipped | buttons, forms |
+> **Note:** Content strategy and conversion copy moved to `/csetup` (Adaptive Depth Research)
+
+**What Goes Where:**
+| Concern | Command | Output File |
+|---------|---------|-------------|
+| Components, Layout, Animations | `/pageplan` | `page-plan.md` |
+| Content, Conversion, UX Research | `/csetup` | `research-checklist.md` |
 
 **Benefits:**
-- Auto-detects page type from context (no manual config)
-- Theme + decorations from tokens.json applied consistently
-- 84% token reduction (selective pattern loading)
-- Conversion-optimized only where needed (marketing pages)
+- Clear separation of Visual vs Research
+- No duplication between commands
+- Agents know exactly which file has which information
 
 ---
 
@@ -296,6 +318,208 @@ 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."
+
+**Solution:** Dynamic research layers that adapt to each change's complexity (0 to 10+ layers).
+
+### Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| L1 = Best Practice (ALWAYS) | "คนอื่นทำกันยังไง?" (How do others do it?) for ALL non-trivial changes |
+| Dynamic Depth | No fixed min/max - truly adaptive (0-10+ layers) |
+| Separation of Concerns | Visual (/designsetup) is STATIC, Strategy (research) is DYNAMIC |
+| Per-Change Output | Generates `research-checklist.md` for each change |
+| Design Conflict Warnings | Warns if industry practice conflicts with user's design choices |
+
+### Layer Examples by Change Type
+
+| Change Type | Layers | Example Layers |
+|-------------|--------|----------------|
+| Typo fix, debug log | 0 | None needed |
+| Simple API endpoint | 2 | Best Practice, API Design |
+| Auth system | 4 | Best Practice, Security, API Design, Testing |
+| E-commerce checkout | 7 | Best Practice, Security, UX, Payment, Integration, Performance, Testing |
+| Healthcare portal | 10 | Best Practice, Security, Compliance (HIPAA), UX, Data Architecture, API, Performance, Testing, Integration, Audit |
+
+### Knowledge Sources (Separated)
+
+| Step | Knowledge Type | Source | Example |
+|------|----------------|--------|---------|
+| **2.6** | Domain (HOW to design) | Claude's Knowledge | Normalization, UX patterns, Security |
+| **2.7** | Stack (HOW to use tool) | Context7 | Prisma, React, Next.js |
+
+### How It Works
+
+```
+1. Analyze change from proposal.md, tasks.md, design.md
+   → Detect: primaryType, complexity, riskLevel, domains, features
+
+2. Determine research layers dynamically:
+   - Trivial (complexity ≤ 1, no UI/API/DB) → 0 layers
+   - Non-trivial → L1 Best Practice + context-specific layers
+
+3. Execute research per layer using Claude's knowledge:
+   - Claude knows: UX (Nielsen Norman, Baymard), DB (Codd), Security (OWASP)
+   - No static files needed - Claude reasons from training
+   - No WebSearch needed - domain knowledge is stable
+
+4. Generate research-checklist.md with:
+   - Key questions per layer
+   - Best practices (from Claude's knowledge)
+   - Anti-patterns to avoid
+   - Trade-offs explained
+   - Recommendations specific to THIS change
+
+5. Agents read research-checklist.md before implementing
+```
+
+**WHY Claude's Knowledge?**
+- Domain principles rarely change (Normalization = 50 years, REST = 20 years)
+- No maintenance needed (no static files to update)
+- Context-aware (Claude applies principles to YOUR specific change)
+- Stack knowledge goes to Context7 (Step 2.7) which has live docs
+
+### Available Research Layers
+
+| Layer | Triggered By |
+|-------|--------------|
+| Best Practice / Industry Standard | Always (non-trivial changes) |
+| Security Requirements | hasAuth, hasPayment, hasSensitiveData |
+| {Industry} Compliance | healthcare, fintech, or other regulated industries |
+| User Experience Patterns | isExternalFacing + hasUI |
+| Conversion Psychology | marketing/sales pages |
+| Content Strategy | marketing/content pages |
+| Data Architecture | hasDatabase, data-intensive |
+| API Design | hasAPI |
+| Multi-tenancy Patterns | SaaS with tenant isolation |
+| Real-time Architecture | WebSocket, collaboration features |
+| Performance Optimization | external-facing OR complexity ≥ 6 |
+| Integration Patterns | external APIs, webhooks |
+| Testing Strategy | HIGH risk OR complexity ≥ 7 |
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` Step 2.6 | Complete rewrite - Adaptive Depth Research |
+| `analyzeChangeCharacteristics()` | New: semantic analysis of change context |
+| `determineResearchLayers()` | New: dynamic layer selection |
+| `executeLayerResearch()` | New: Context7 + semantic research |
+| `generateResearchChecklist()` | New: markdown output per change |
+| `checkDesignConflicts()` | New: warns on design vs industry fit |
+
+### Output Example
+
+```markdown
+# Research Checklist: healthcare-portal
+
+> Generated by Adaptive Depth Research (v2.4.0)
+> Complexity: 9/10 | Risk: HIGH
+
+## Summary
+
+| Layer | Focus | Status |
+|-------|-------|--------|
+| L1: Best Practice | How do others implement healthcare? | ⏳ Pending |
+| L2: Security Requirements | What security measures? | ⏳ Pending |
+| L3: Healthcare Compliance | What HIPAA regulations? | ⏳ Pending |
+...
+
+## L1: Best Practice / Industry Standard
+
+**Focus:** How do others implement healthcare portals?
+
+### Key Questions
+- [ ] What is the industry standard for healthcare portals?
+- [ ] What are common patterns and anti-patterns?
+...
+```
+
+---
+
 ## 🆕 v2.3.0: Zero-Maintenance Tech Stack Detection
 
 **Problem Solved:** Previously, `/csetup` required hardcoded regex patterns and Context7 ID mappings for each library. Adding support for new libraries (like SQLAlchemy, Pydantic, Rust crates) required code changes.