@champpaba/claude-agent-kit 3.0.3 → 3.2.0

package/.claude/CHANGELOG.md

@@ -5,6 +5,186 @@
 
 ---
 
+## v3.2.0: Consolidated Pre-Work Context
+
+**Problem Solved:** `/csetup` generated two separate pseudocode outputs (`research-checklist.md` and `INTEGRATION_RISKS.md`) that were never actually created. Agents had to discover context from multiple scattered sources.
+
+**Solution:** Consolidated all agent context into a single `pre-work-context.md` file with direct execution instructions. Merged Step 2.7 (Best Practices) into Step 2.6.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Step 2.6 | ~1000 lines of pseudocode | ~300 lines of direct instructions |
+| Step 2.7 | Separate best practices step | Merged into Step 2.6 |
+| Output files | research-checklist.md + INTEGRATION_RISKS.md + best-practices/*.md | Single `pre-work-context.md` |
+| Agent discovery | Multiple files to read | One file with all context |
+
+### Step 2.6 Structure (New - v3.2.0)
+
+```
+Step 2.6.1: Analyze Change Characteristics (type, complexity, risk)
+Step 2.6.2: Detect Libraries (from package files + specs)
+Step 2.6.3: Fetch Best Practices via Context7 (direct MCP calls)
+Step 2.6.4: Determine Research Layers (adaptive depth)
+Step 2.6.5: Detect Integration Warnings (cross-library)
+Step 2.6.6: Generate Critical Checklist Items (security/compliance)
+Step 2.6.7: Write pre-work-context.md (single consolidated file)
+Step 2.6.8: Output Summary
+Step 2.6.9: Skip Conditions
+```
+
+### pre-work-context.md Structure
+
+```markdown
+# Pre-Work Context: {changeId}
+
+## 1. Change Analysis (type, complexity, risk)
+## 2. Library Best Practices (from Context7)
+## 3. Research Findings (domain knowledge)
+## 4. Integration Warnings (cross-library concerns)
+## 5. Critical Checklist (security/compliance must-haves)
+## 6. Quick Reference (package manager, commands)
+```
+
+### Agent Pre-Work Checklist Update
+
+**Version:** 3.0.0 (Pre-Work Context Integration)
+
+- Step 0: Read pre-work-context.md (NEW - primary source)
+- Step 0.1: Library Requirements Check (fallback)
+- Step 0.2: Library Feasibility Validation (was 0.5)
+- Step 0.3: Memory Context Query (was 0.6)
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` | Rewrote Step 2.6 with direct execution |
+| `csetup.md` | Removed Step 2.7 (merged into 2.6) |
+| `csetup.md` | Renumbered Step 2.8 → Step 2.7 |
+| `pre-work-checklist.md` | Added Step 0 (read pre-work-context.md) |
+| `pre-work-checklist.md` | Renumbered steps (0.5→0.2, 0.6→0.3) |
+| `CLAUDE.md` | Updated to v3.2.0 |
+
+### Why This Matters
+
+**Before:**
+- Agents had to read 5+ files to get context
+- research-checklist.md was pseudocode that never executed
+- INTEGRATION_RISKS.md was pseudocode that never executed
+- Context was scattered and inconsistent
+
+**After:**
+- Agents read ONE file (`pre-work-context.md`) in STEP 0
+- All context is consolidated and actually generated
+- Main Claude follows direct instructions (not pseudocode)
+- Integration warnings + checklist items in one place
+
+---
+
+## v3.1.1: Direct Best Practices Execution
+
+**Problem Solved:** Step 2.7 (Auto-Setup Best Practices) was written as pseudocode with helper functions (`extractLibrariesSemantically`, `parseContext7Response`, etc.) that Main Claude never actually executed. Best practices files were documented but never created.
+
+**Solution:** Rewrote Step 2.7 as direct, executable instructions that Main Claude can follow. No more pseudocode - just clear steps with actual MCP tool names.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| Step 2.7 | ~1000 lines of pseudocode | ~130 lines of direct instructions |
+| Helper functions | 6 fake functions | Removed entirely |
+| MCP tool calls | Written as code syntax | Written as clear instructions |
+| Output format | Complex extraction logic | Simple template |
+
+### Step 2.7 Structure (New)
+
+```
+Step 2.7.1: Detect Libraries (from package.json, requirements.txt, spec files)
+Step 2.7.2: Resolve via Context7 (call MCP tools directly)
+Step 2.7.3: Create Best Practices Files (using template)
+Step 2.7.4: Create index.md (registry)
+Step 2.7.5: Output Summary
+Step 2.7.6: Skip Conditions
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `csetup.md` | Rewrote Step 2.7, removed ~1000 lines of pseudocode |
+| `csetup.md` | Removed helper functions (extractLibrariesSemantically, etc.) |
+| `csetup.md` | Updated detectAdditionalTech as REMOVED |
+| `CLAUDE.md` | Updated version to 3.1.1 |
+
+### Why This Matters
+
+Before: Main Claude would read Step 2.7 as documentation and skip it.
+After: Main Claude follows clear instructions and actually calls Context7.
+
+---
+
+## v3.1.0: TDD Classification + Development Principles Injection
+
+**Problem Solved:** TDD classification was a simple one-liner (`risk=HIGH || complexity>=7`) that missed critical patterns like auth, payment, and external integrations. Development principles (SOLID, DRY, KISS) were documented but never injected to agents.
+
+**Solution:** Comprehensive TDD classification based on `tdd-classification.md` patterns, integrated into `task-analyzer.md` Step 2.6. Development principles injected to ALL agents via `/cdev`.
+
+### Key Changes
+
+| Component | Before | After |
+|-----------|--------|-------|
+| TDD classification | 1-line in csetup.md | Full pattern matching in task-analyzer.md |
+| development-principles.md | Listed but not used | Injected to ALL agents via /cdev |
+| tdd-classifier.md | Duplicate file | Deleted (merged into tdd-classification.md) |
+
+### TDD Classification (Step 2.6)
+
+Now classifies based on:
+
+| Pattern | Examples | TDD Required |
+|---------|----------|--------------|
+| Security operations | auth, jwt, encrypt, permission | ✅ Always |
+| Financial operations | payment, stripe, calculate, tax | ✅ Always |
+| External integrations | webhook, sendgrid, twilio | ✅ Always |
+| Data transformations | serialize, parse, etl | ✅ Always |
+| Complex UI | multi-step, wizard, keyboard-nav | ✅ Always |
+| Simple CRUD reads | get, list, fetch | ❌ Test-alongside OK |
+| Presentational UI | button, card, modal | ❌ No TDD |
+| Database/Integration | schema, migration, validation | ❌ No TDD |
+
+### Development Principles Injection
+
+`/cdev` now injects to ALL agent prompts:
+
+```markdown
+## 🏛️ Development Principles (Level 1 - ALL Agents)
+
+**REQUIRED READING:** @.claude/contexts/patterns/development-principles.md
+
+| Principle | Summary |
+|-----------|---------|
+| **KISS** | Choose simple solutions over complex ones |
+| **YAGNI** | Build only what you need now |
+| **SRP** | One responsibility per module |
+| **DRY** | Single source of truth for all knowledge |
+| **Fail Fast** | Detect and raise errors immediately |
+| **Observability** | Log everything that matters |
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `task-analyzer.md` | Added Step 2.6 TDD Classification |
+| `csetup.md` | Updated phase generation to use TDD from tasks |
+| `cdev.md` | Added development-principles injection |
+| `tdd-classifier.md` | **DELETED** (merged) |
+| `CLAUDE.md` | Updated references and version |
+
+---
+
 ## v3.0.0: Template-Free Architecture (Task Analyzer v2.0)
 
 **Problem Solved:** Phase templates (`phase-templates.json`) were limiting and caused task loss. When `tasks.md` had 5 detailed phases but template had only 2, tasks disappeared. Templates overrode the single source of truth.

package/.claude/CLAUDE.md

@@ -1,8 +1,8 @@
 # CLAUDE.md
 
 > **Navigation Hub for AI Agents**
-> **Template Version:** 3.0.0 - Template-Free Architecture
-> **Latest:** Task Analyzer v2.0 - AI-driven analysis, no keyword matching, auto-add best practices
+> **Template Version:** 3.2.0 - Consolidated Pre-Work Context
+> **Latest:** Step 2.6 generates `pre-work-context.md` - single file with all agent context
 
 ---
 
@@ -26,6 +26,7 @@
 | `README.md` | **Visual design summary** (human-readable) | UI/Frontend phases |
 | `data.yaml` | Design tokens + psychology (~300 lines) | Quick UI reference |
 | `page-plan.md` | UI component layout + content strategy | uxui-frontend agent |
+| `pre-work-context.md` | **v3.2.0!** All agent context (best practices, warnings, checklist) | All agents - STEP 0 ✨ |
 | `phases.md` | Execution plan with agent assignments | All phases |
 | `flags.json` | Progress tracking | All phases |
 
@@ -75,6 +76,8 @@ Universal, framework-agnostic template for AI-assisted development.
 - `@/.claude/contexts/design/index.md` (General design principles - fallback)
 
 **Development:**
+- `@/.claude/contexts/patterns/development-principles.md` - **v3.1.0!** SOLID, DRY, KISS, Fail Fast (Level 1 - ALL agents) ✨
+- `@/.claude/contexts/patterns/tdd-classification.md` - TDD workflow classification patterns
 - `@/.claude/contexts/patterns/task-classification.md` (Agent selection guide)
 - `@/.claude/contexts/patterns/agent-coordination.md` (When to run agents parallel/sequential)
 - `@/.claude/contexts/patterns/error-recovery.md` (How agents handle errors & escalate)
@@ -86,7 +89,7 @@ Universal, framework-agnostic template for AI-assisted development.
 **Project Setup:**
 - `/extract https://site.com` - Extract design from reference sites
 - `/designsetup @prd.md` - Interactive design system setup
-- `/csetup` - **v3.0.0:** Template-free! AI-driven task analysis, auto-add best practices, incremental milestones
+- `/csetup` - **v3.2.0:** Generates `pre-work-context.md` with best practices, research, warnings, checklists
 
 **Page Planning (UI Tasks) - v2.0.0:**
 - `/pageplan @prd.md @brief.md` - Generate page structure with auto page type detection
@@ -122,30 +125,28 @@ Universal, framework-agnostic template for AI-assisted development.
 **Implementation Logic:**
 - `@/.claude/lib/README.md` - Implementation logic overview
 - `@/.claude/lib/agent-executor.md` - Agent retry & escalation logic (used by /cdev) + Incremental testing execution
-- `@/.claude/lib/tdd-classifier.md` - TDD classification logic (used by /csetup)
-- `@/.claude/lib/task-analyzer.md` - **v2.0!** Template-free AI-driven task analysis ✨
+- `@/.claude/lib/task-analyzer.md` - **v3.1.0!** Template-free task analysis with TDD classification (Step 2.6) ✨
 - `@/.claude/lib/flags-updater.md` - Progress tracking protocol (Main Claude updates flags.json)
 - `@/.claude/lib/agent-router.md` - Mandatory agent routing rules (enforce delegation)
 - `@/.claude/contexts/patterns/agent-discovery.md` - Shared agent discovery flow
 
 ---
 
-## 📚 Best Practices System (v2.5.0 - Smart Topic Query)
+## 📚 Best Practices System (v3.2.0 - Consolidated Pre-Work Context)
 
 **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 + integration risks before coding
+- `/csetup` generates **single `pre-work-context.md`** with ALL agent context
+- **Consolidates:** Best practices, research findings, integration warnings, critical checklists
+- **Context7 validates** each library and fetches best practices
+- **Agents read ONE file** instead of multiple scattered files
+- **File location:** `openspec/changes/{changeId}/pre-work-context.md`
 
 **Key Changes:**
 | Version | Change |
 |---------|--------|
 | v2.3.0 | NLP extraction + Context7 resolution (zero maintenance) |
 | v2.5.0 | Smart Topic Query + Integration Risk Detection |
+| v3.2.0 | **Consolidated `pre-work-context.md`** (single file for all agent context) |
 
 **Detection Sources:**
 | Source | Examples |
@@ -158,23 +159,22 @@ Universal, framework-agnostic template for AI-assisted development.
 | PHP | composer.json |
 | Ruby | Gemfile |
 
-**Flow (v2.5.0):**
+**Flow (v3.2.0):**
 ```
-/csetup → extract potential library names from ALL text sources
-        → Context7 resolve-library-id (validates if real library)
-        → 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
+/csetup → analyze change (type, complexity, risk)
+        → detect libraries from spec + package files
+        → Context7 resolve + fetch best practices
+        → determine research layers
+        → detect integration warnings
+        → generate critical checklist items
+        → write pre-work-context.md (single file)
+/cdev   → agents read pre-work-context.md in STEP 0
 ```
 
-**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 |
+**Output File:**
+| File | Sections |
+|------|----------|
+| `pre-work-context.md` | 1. Change Analysis, 2. Library Best Practices, 3. Research Findings, 4. Integration Warnings, 5. Critical Checklist, 6. Quick Reference |
 
 ---
 
@@ -310,6 +310,9 @@ User: "Build login system"
 **Recent versions:**
 | Version | Key Feature |
 |---------|-------------|
+| v3.2.0 | Consolidated Pre-Work Context (single `pre-work-context.md` for agents) |
+| v3.1.1 | Direct Best Practices Execution (Step 2.7 rewritten, no pseudocode) |
+| v3.1.0 | TDD Classification + Development Principles Injection |
 | v3.0.0 | Template-Free Architecture (AI-driven Task Analyzer v2.0) |
 | v2.8.0 | Critical Flow Injection (auto-inject security/compliance items) |
 | v2.7.0 | UX Testing Agent (persona-based, approval gate) |

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

@@ -1,6 +1,6 @@
 # Pre-Work Checklist (Shared by All Agents)
 
-> **Version:** 2.2.0 (Library Feasibility Validation)
+> **Version:** 3.0.0 (Pre-Work Context Integration)
 > **Purpose:** Single source of truth for pre-work validation
 
 ---
@@ -9,7 +9,40 @@
 
 Complete these steps before implementation to ensure alignment with project standards:
 
-### Step 0: Library Requirements Check
+### Step 0: Read Pre-Work Context (v3.2.0 - NEW)
+
+**FIRST: Check if pre-work-context.md exists:**
+
+```
+openspec/changes/{changeId}/pre-work-context.md
+```
+
+**If file exists, read it and extract:**
+1. **Change Analysis** - Type, complexity, risk level
+2. **Library Best Practices** - DO's and DON'Ts for each library
+3. **Research Findings** - Domain-specific considerations
+4. **Integration Warnings** - Cross-library concerns
+5. **Critical Checklist** - Security/compliance items to verify
+
+**Report:**
+```markdown
+Pre-Work Context: (Step 0)
+- [x] Read pre-work-context.md
+- Change Type: {type}
+- Complexity: {n}/10
+- Risk: {level}
+- Libraries: {list}
+- Critical Items: {count}
+```
+
+**If file doesn't exist:**
+- User may not have run `/csetup` with v3.2.0+
+- Fall back to Step 0.1 (Library Requirements Check)
+- Suggest: "Run /csetup to generate pre-work-context.md"
+
+---
+
+### Step 0.1: Library Requirements Check
 
 **Scan for required libraries before writing code:**
 
@@ -49,7 +82,7 @@ WHY not defaults? Design spec has project-specific security requirements.
 
 ---
 
-### Step 0.5: Library Feasibility Validation (v2.2.0)
+### Step 0.2: Library Feasibility Validation (v2.2.0)
 
 **Before implementing, verify the chosen library supports ALL spec requirements:**
 
@@ -131,7 +164,7 @@ Reporting to Main Claude...
 
 ---
 
-### Step 0.6: Memory Context Query (v2.2.0 - claude-mem Integration)
+### Step 0.3: Memory Context Query (v2.2.0 - claude-mem Integration)
 
 **Before implementation, query claude-mem for related past work:**
 
@@ -193,7 +226,17 @@ Result: #12345 - "Chose rotating refresh tokens with Redis storage"
 ```markdown
 Pre-Implementation Validation
 
-Library Requirements: (Step 0)
+Pre-Work Context: (Step 0 - v3.2.0)
+- [ ] Read pre-work-context.md (if exists)
+- Change Type: {type}
+- Complexity: {n}/10
+- Risk Level: {level}
+- Libraries: {list from pre-work-context.md}
+- Critical Checklist Items: {count}
+- Integration Warnings: {count}
+(OR: pre-work-context.md not found - using fallback steps)
+
+Library Requirements: (Step 0.1 - fallback)
 - [ ] Scanned tasks.md for "Install X" patterns
 - [ ] Scanned design.md for design decisions
 - Required libraries: {list from tasks.md/design.md}
@@ -205,7 +248,7 @@ Design Spec Implementation: (Step 5)
   - {requirement 1 from design.md}
   - {requirement 2 from design.md}
 
-Memory Context: (Step 0.6 - claude-mem)
+Memory Context: (Step 0.3 - claude-mem)
 - [ ] Queried claude-mem for related past work
 - Relevant observations:
   - {#ID: summary → will apply how}
@@ -214,7 +257,7 @@ Memory Context: (Step 0.6 - claude-mem)
 Project Context:
 - Project: {name}
 - Stack: {tech-stack}
-- Package Manager: {pm} (from tech-stack.md)
+- Package Manager: {pm} (from tech-stack.md or pre-work-context.md)
 
 Patterns Loaded:
 - [ ] error-handling.md
@@ -223,13 +266,18 @@ Patterns Loaded:
 - [ ] code-standards.md
 - [ ] {agent-specific patterns}
 
-Best Practices:
-- [ ] {framework} best practices loaded (from Context7)
+Best Practices: (from pre-work-context.md Section 2)
+- [ ] {framework} best practices loaded
+
+Critical Checklist: (from pre-work-context.md Section 5)
+- [ ] {critical item 1}
+- [ ] {critical item 2}
 
 Ready to Implement:
 - [ ] Task understood
 - [ ] Dependencies identified
 - [ ] Required libraries identified
+- [ ] Critical checklist reviewed
 - [ ] Memory context applied (if available)
 - [ ] Approach planned (using specified libraries)
 ```

package/.claude/commands/cdev.md

@@ -163,6 +163,42 @@ Design Spec Implementation:
 ---
 `
 
+  // v3.1.0: Add Level 1 Universal Patterns (development-principles.md) for ALL agents
+  // Source: context-loading-protocol.md - Level 1 patterns apply to ALL agents
+  const devPrinciplesPath = '.claude/contexts/patterns/development-principles.md'
+  if (fileExists(devPrinciplesPath)) {
+    prompt += `
+
+---
+
+## 🏛️ Development Principles (Level 1 - ALL Agents)
+
+**REQUIRED READING:** @${devPrinciplesPath}
+
+These principles apply to ALL code written by ALL agents:
+
+**Quick Reference:**
+| Principle | Summary |
+|-----------|---------|
+| **KISS** | Choose simple solutions over complex ones |
+| **YAGNI** | Build only what you need now |
+| **SRP** | One responsibility per module |
+| **DRY** | Single source of truth for all knowledge |
+| **Fail Fast** | Detect and raise errors immediately |
+| **Observability** | Log everything that matters |
+
+**Report format:**
+\`\`\`
+✅ Development Principles Applied
+   - KISS ✓ (simple implementation)
+   - DRY ✓ (no duplication)
+   - Separation of Concerns ✓
+\`\`\`
+
+---
+`
+  }
+
   // Add best-practices reference for ALL agents
   const bpDir = '.claude/contexts/domain/project/best-practices/'
   if (fileExists(bpDir)) {