@champpaba/claude-agent-kit 2.1.6 → 2.2.1

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 2.0.0 - Claude 4.5 Optimized + Design System v2.0
-> **Latest:** Full template refactored with Claude 4.5 best practices (agents ~65% smaller) + Interactive design setup with theme selection
+> **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
 
 ---
 
@@ -131,18 +131,36 @@ Universal, framework-agnostic template for AI-assisted development.
 
 ---
 
-## 📚 Best Practices System (v1.8.0)
+## 📚 Best Practices System (v2.3.0 - Zero Maintenance)
 
 **Quick Summary:**
-- `/csetup` **auto-detects tech stack** from: package.json → design.md → proposal/tasks (3 sources)
-- **Auto-generates best practices** from Context7 MCP (React, Next.js, Prisma, etc.)
+- `/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
 - Files created in `.claude/contexts/domain/project/best-practices/`
 - **Agents read** best practices before coding (validated by agent-executor)
-- `/cdev` **injects** relevant best-practices paths into agent prompts
+
+**Key Change in v2.3.0:**
+- ❌ Old: Hardcoded regex patterns + manual ID mappings (required maintenance)
+- ✅ New: NLP extraction + Context7 resolution (zero maintenance, any library)
+
+**Detection Sources:**
+| Source | Examples |
+|--------|----------|
+| Spec files | proposal.md, design.md, tasks.md |
+| JS/TS | package.json, import statements |
+| Python | requirements.txt, pyproject.toml, imports |
+| Rust | Cargo.toml, use statements |
+| Go | go.mod, import statements |
+| PHP | composer.json |
+| Ruby | Gemfile |
 
 **Flow:**
 ```
-/csetup → detect stack → query Context7 → generate best-practices
+/csetup → extract potential library names from ALL text sources
+        → Context7 resolve-library-id (validates if real library)
+        → Context7 get-library-docs (fetch best practices)
+        → generate .md files for each verified library
 /cdev   → inject paths into prompt → agent reads → validation checks
 ```
 
@@ -278,6 +296,54 @@ User: "Build login system"
 
 ---
 
+## 🆕 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.
+
+**Solution:** Dynamic detection that works with any library in any language without maintenance.
+
+### How It Works
+
+```
+1. Extract potential library names from ALL text sources:
+   - Spec files (proposal.md, design.md, tasks.md)
+   - Package files (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
+   - Import statements in code snippets
+   - Prose mentions ("using FastAPI", "with Prisma")
+
+2. Send each candidate to Context7 resolve-library-id:
+   - If Context7 recognizes it → confirmed library ✅
+   - If not recognized → not a library, skip ❌
+
+3. For confirmed libraries, fetch best practices:
+   - Context7 get-library-docs with "best practices" topic
+   - Generate .md file with patterns, anti-patterns, checklist
+
+4. Result: Best practices for ANY library, automatically!
+```
+
+### Benefits
+
+| Aspect | Before (v1.8.0) | After (v2.3.0) |
+|--------|-----------------|----------------|
+| New library support | Manual code change | Automatic |
+| Python stack | Partial (FastAPI, Django only) | Full (SQLAlchemy, Pydantic, Click, etc.) |
+| Rust support | None | Automatic |
+| Go support | None | Automatic |
+| Maintenance | Required for each library | Zero |
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` Step 2.7 | Complete rewrite with dynamic detection |
+| `extractPotentialLibraryNames()` | New helper for NLP extraction |
+| `parseContext7Response()` | New helper for Context7 response parsing |
+| `generateBestPracticesFile()` | Updated signature, includes Context7 ID |
+| `detectAdditionalTech()` | Deprecated, delegates to new system |
+
+---
+
 ## 🆕 v2.0.0: Claude 4.5 Optimization + Design System v2.0
 
 **Based on:** [Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)

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