class-ai-agent 1.2.0

package/.claude/commands/debug.md

@@ -0,0 +1,242 @@
+---
+name: debug
+description: Systematic debugging and error recovery — find root cause, not symptoms
+---
+
+# /debug — Debugging & Error Recovery
+
+> "Fix root causes, not symptoms."
+
+## Purpose
+
+Systematically diagnose and fix errors. Stop feature work, preserve evidence, find root cause, add guards, then resume.
+
+## The Stop-the-Line Rule
+
+When unexpected failures occur:
+
+1. **STOP** — Halt feature work immediately
+2. **PRESERVE** — Save error messages, logs, stack traces
+3. **DIAGNOSE** — Follow the 6-step triage process
+4. **FIX** — Address root cause, not symptoms
+5. **GUARD** — Add tests to prevent recurrence
+6. **RESUME** — Only continue after verification
+
+---
+
+## 6-Step Triage Process
+
+### Step 1: Reproduce
+
+Make the failure happen reliably.
+
+```bash
+# Run the failing test
+npm test -- --grep "failing test name"
+
+# Or reproduce manually with specific steps
+```
+
+**If not reproducible**, investigate:
+- Timing/race conditions
+- Environment differences (dev vs CI)
+- State leakage between tests
+- Random/flaky behavior
+
+### Step 2: Localize
+
+Identify which layer fails:
+
+| Layer | Symptoms |
+|-------|----------|
+| **UI/Frontend** | Render errors, missing elements, wrong display |
+| **API/Backend** | HTTP errors, wrong responses, timeout |
+| **Database** | Query errors, constraint violations, missing data |
+| **Build** | Compilation errors, missing dependencies |
+| **External** | Third-party API failures, network issues |
+| **Test itself** | Flaky assertion, wrong expectations |
+
+**Use `git bisect` for regressions:**
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good <last-known-good-commit>
+# Git will guide you to the breaking commit
+```
+
+### Step 3: Reduce
+
+Strip away unrelated elements:
+
+```javascript
+// Original complex failing code
+const result = await complexFunction(
+  await getConfig(),
+  await fetchData(),
+  processOptions(opts)
+);
+
+// Reduced to find the problem
+const config = await getConfig();
+console.log('config:', config);  // Check each step
+
+const data = await fetchData();
+console.log('data:', data);
+
+const result = await complexFunction(config, data, opts);
+```
+
+### Step 4: Fix Root Cause
+
+**Fix the actual problem, not the symptom:**
+
+| Symptom | Bad Fix | Good Fix |
+|---------|---------|----------|
+| Duplicate list items | Dedupe in UI | Fix query returning duplicates |
+| Null reference error | Add `?.` everywhere | Ensure data is loaded before access |
+| Slow API response | Increase timeout | Optimize the query |
+| Flaky test | Add retry logic | Fix the race condition |
+
+### Step 5: Guard Against Recurrence
+
+Write a test that catches this specific failure:
+
+```javascript
+it('should not return duplicate items (regression #123)', async () => {
+  // Setup that caused the original bug
+  await createOrder({ items: [item, item] });
+  
+  // The query that was returning duplicates
+  const result = await getOrderItems();
+  
+  // Guard: ensure no duplicates
+  const ids = result.map(r => r.id);
+  expect(ids).toEqual([...new Set(ids)]);
+});
+```
+
+### Step 6: Verify End-to-End
+
+```bash
+# Run the specific test
+npm test -- --grep "regression"
+
+# Run full test suite
+npm test
+
+# Run build
+npm run build
+
+# Manual verification if needed
+```
+
+---
+
+## Error-Specific Triage Trees
+
+### Test Failure
+
+```
+Test fails
+├── Assertion error
+│   ├── Expected value wrong → Check test expectation
+│   └── Actual value wrong → Debug implementation
+├── Runtime error
+│   ├── ReferenceError → Check imports, variable names
+│   ├── TypeError → Check types, null checks
+│   └── NetworkError → Check test setup, mocks
+└── Timeout
+    ├── Async not awaited → Add missing await
+    └── Infinite loop → Check loop conditions
+```
+
+### Build Error
+
+```
+Build fails
+├── TypeScript error
+│   ├── Type mismatch → Fix types or add assertion
+│   └── Missing import → Add import statement
+├── Module not found
+│   ├── Package missing → npm install
+│   └── Path wrong → Fix import path
+└── Syntax error
+    └── Check recent changes → git diff
+```
+
+### Runtime Error
+
+```
+Runtime error
+├── API returns error
+│   ├── 4xx → Client issue, check request
+│   └── 5xx → Server issue, check logs
+├── CORS error
+│   └── Check server CORS config
+├── Undefined/null
+│   └── Add loading state or null check
+└── Network timeout
+    └── Check connectivity, increase timeout
+```
+
+---
+
+## Debugging Tools
+
+### Console Logging (Temporary)
+
+```javascript
+// Add strategic logs
+console.log('[DEBUG] Input:', input);
+console.log('[DEBUG] After transform:', result);
+
+// Remove all debug logs before commit
+git diff | grep console.log
+```
+
+### Node Inspector
+
+```bash
+# Debug Node.js
+node --inspect-brk src/index.js
+
+# Debug tests
+node --inspect-brk node_modules/.bin/vitest
+```
+
+### Git Bisect
+
+```bash
+git bisect start
+git bisect bad                    # Current commit is broken
+git bisect good abc123            # This commit was working
+# Test each commit git suggests
+git bisect good  # or  git bisect bad
+git bisect reset                  # When done
+```
+
+---
+
+## Common Rationalizations (Avoid These)
+
+| Excuse | Reality |
+|--------|---------|
+| "It works on my machine" | Environment differences are bugs |
+| "It's just flaky" | Flaky tests have root causes |
+| "Let's just retry" | Retries hide real problems |
+| "It's a third-party issue" | Still need to handle gracefully |
+| "We'll fix it later" | Tech debt compounds |
+
+---
+
+## Output
+
+- Root cause identified and fixed
+- Regression test added
+- All tests passing
+- Clear commit message explaining the fix
+
+## Next Step
+
+After fixing, continue with `/build` or run `/review` for verification.

package/.claude/commands/deploy.md

@@ -0,0 +1,40 @@
+# Deploy Command
+
+## Description
+Deploy the application to the target environment.
+
+## Usage
+Tell Claude: "Run the deploy command" or "Deploy to [environment]"
+
+## Steps
+
+### 1. Pre-deploy Checklist
+- [ ] All tests pass (`npm test`)
+- [ ] No linting errors (`npm run lint`)
+- [ ] Environment variables are configured
+- [ ] Database migrations are ready
+
+### 2. Build
+```bash
+npm run build
+```
+
+### 3. Deploy
+```bash
+# Development
+npm run deploy:dev
+
+# Production
+npm run deploy:prod
+```
+
+### 4. Post-deploy Verification
+- Check application health endpoint
+- Verify logs for errors
+- Run smoke tests
+
+## Rollback
+If deployment fails:
+```bash
+npm run rollback
+```

package/.claude/commands/fix-issue.md

@@ -0,0 +1,42 @@
+# Fix Issue Command
+
+## Description
+Analyze and fix a reported bug or issue systematically.
+
+## Usage
+Tell Claude: "Fix issue: [describe the issue]" or "Fix bug in [file/module]"
+
+## Process
+
+### 1. Understand the Issue
+- Read the error message or bug description carefully
+- Identify the affected component(s)
+- Reproduce the issue locally if possible
+
+### 2. Root Cause Analysis
+- Check recent git changes: `git log --oneline -20`
+- Review affected files
+- Look for related tests that may reveal expected behavior
+
+### 3. Plan the Fix
+- Identify the minimal change needed
+- Consider side effects on other components
+- Update or add tests to cover the fix
+
+### 4. Implement
+- Make the targeted fix
+- Ensure code follows `.claude/rules/code-style.md`
+- Handle errors per `.claude/rules/error-handling.md`
+
+### 5. Verify
+- Run relevant tests: `npm test -- --testPathPattern=[affected]`
+- Run full test suite: `npm test`
+- Check linting: `npm run lint`
+
+### 6. Commit
+Follow `.claude/rules/git-workflow.md`:
+```
+fix: [short description of the fix]
+
+Closes #[issue-number]
+```

package/.claude/commands/plan.md

@@ -0,0 +1,125 @@
+---
+name: plan
+description: Decompose specs into small, verifiable tasks with dependency ordering
+---
+
+# /plan — Planning & Task Breakdown
+
+> "Vertical slices, not horizontal layers."
+
+## Purpose
+
+Transform a specification into an ordered list of small, verifiable tasks. Each task delivers end-to-end functionality.
+
+## Prerequisites
+
+- A specification exists (`SPEC.md` or described requirements)
+- Understanding of the codebase structure
+
+## Workflow
+
+### Phase 1: Analysis (Read-Only)
+
+1. **Read the spec** — Understand objectives and acceptance criteria
+2. **Survey the codebase** — Identify relevant files, patterns, and integration points
+3. **Map dependencies** — Which components depend on which?
+
+> **Do NOT modify code during planning.**
+
+### Phase 2: Vertical Slicing
+
+Break work into **vertical slices** — each slice delivers complete functionality through all layers:
+
+```
+❌ Horizontal (anti-pattern):
+   Task 1: Create all DB models
+   Task 2: Create all API routes
+   Task 3: Create all UI components
+
+✅ Vertical (correct):
+   Task 1: User can create a task (DB + API + UI)
+   Task 2: User can view task list (DB + API + UI)
+   Task 3: User can mark task complete (DB + API + UI)
+```
+
+### Phase 3: Task Definition
+
+Each task must include:
+
+```markdown
+## Task: [Short description]
+
+**Objective**: [What this achieves]
+
+**Files to modify**:
+- `src/models/task.ts`
+- `src/routes/tasks.ts`
+- `src/components/TaskList.tsx`
+
+**Acceptance Criteria**:
+- [ ] User can [action]
+- [ ] [Validation] is enforced
+- [ ] Test covers [scenario]
+
+**Dependencies**: [Task IDs this depends on]
+
+**Verification**:
+- [ ] Unit tests pass
+- [ ] Integration test added
+- [ ] Manual verification: [steps]
+```
+
+### Phase 4: Ordering
+
+Order tasks by:
+1. **Foundation first** — DB models, types, shared utilities
+2. **Risk-first** — Tackle uncertain/complex items early
+3. **Dependencies** — Respect the dependency graph
+4. **Quick wins** — Early momentum with smaller tasks
+
+### Phase 5: Checkpoints
+
+Insert checkpoints between major phases:
+
+```markdown
+---
+## Checkpoint: Core CRUD Complete
+
+**Verify before proceeding**:
+- [ ] All CRUD operations work
+- [ ] Test coverage > 80%
+- [ ] No console errors
+- [ ] Performance acceptable
+
+---
+```
+
+## Output
+
+Save to `tasks/` directory:
+
+- `tasks/plan.md` — Full planning document with context
+- `tasks/todo.md` — Actionable task checklist
+
+```markdown
+# TODO: [Feature Name]
+
+## Phase 1: Foundation
+- [ ] Task 1.1: [Description]
+- [ ] Task 1.2: [Description]
+
+## Checkpoint: Foundation Complete
+
+## Phase 2: Core Features
+- [ ] Task 2.1: [Description]
+- [ ] Task 2.2: [Description]
+
+## Checkpoint: Core Complete
+
+## Phase 3: Polish
+- [ ] Task 3.1: [Description]
+```
+
+## Next Step
+
+After plan is approved, run `/build` to implement tasks incrementally.

package/.claude/commands/review.md

@@ -0,0 +1,50 @@
+# Review Command
+
+## Description
+Perform a thorough code review of specified files or a pull request.
+
+## Usage
+Tell Claude: "Review [file/PR/feature]" or "Do a code review of [changes]"
+
+## Review Checklist
+
+### Code Quality
+- [ ] Code follows style guide (`.claude/rules/code-style.md`)
+- [ ] No unnecessary complexity or duplication
+- [ ] Functions are small and focused (single responsibility)
+- [ ] Variable and function names are descriptive
+
+### Security
+- [ ] No hardcoded secrets or credentials
+- [ ] Input validation is present
+- [ ] Authentication/authorization checks in place
+- [ ] See `.claude/rules/security.md` for full checklist
+
+### Error Handling
+- [ ] Errors are properly caught and handled
+- [ ] Meaningful error messages
+- [ ] No swallowed exceptions
+- [ ] See `.claude/rules/error-handling.md`
+
+### Testing
+- [ ] Unit tests cover new logic
+- [ ] Edge cases are tested
+- [ ] Tests are readable and maintainable
+- [ ] See `.claude/rules/testing.md`
+
+### Database
+- [ ] Queries are optimized (no N+1)
+- [ ] Transactions used where appropriate
+- [ ] See `.claude/rules/database.md`
+
+### API
+- [ ] Endpoints follow REST conventions
+- [ ] Request/response schemas are documented
+- [ ] See `.claude/rules/api-conventions.md`
+
+## Output Format
+Provide feedback as:
+- 🔴 **Critical** — Must fix before merge
+- 🟡 **Warning** — Should fix, potential issue
+- 🟢 **Suggestion** — Nice to have improvement
+- ✅ **Good** — Highlight what's done well

package/.claude/commands/simplify.md

@@ -0,0 +1,222 @@
+---
+name: simplify
+description: Reduce complexity without changing behavior — code simplification
+---
+
+# /simplify — Code Simplification
+
+> "Complexity is the enemy of execution."
+
+## Purpose
+
+Simplify code for clarity and maintainability. Reduce complexity **without changing behavior**.
+
+## When to Use
+
+- After `/review` identifies complexity issues
+- When code is hard to understand
+- Before adding new features to tangled code
+- During tech debt cleanup sprints
+
+## Principles
+
+### Chesterton's Fence
+
+> Before removing something, understand why it exists.
+
+Don't delete code just because it looks unnecessary. Investigate:
+- Git history: `git log -p -- path/to/file`
+- Related tests
+- Comments or documentation
+- Ask team members if unsure
+
+### Rule of 500
+
+If a function, file, or class exceeds ~500 lines, it likely needs splitting.
+
+---
+
+## Workflow
+
+### Step 1: Identify Target
+
+```bash
+# Recently modified complex code
+git diff --stat HEAD~10
+
+# Or specify scope
+# "Simplify the OrderService class"
+```
+
+### Step 2: Understand Before Changing
+
+1. **Read the code** — What does it do?
+2. **Check tests** — What behaviors are verified?
+3. **Trace callers** — Who uses this code?
+4. **Note edge cases** — Any special handling?
+
+### Step 3: Identify Opportunities
+
+| Pattern | Simplification |
+|---------|---------------|
+| Deep nesting (> 3 levels) | Guard clauses, extract helpers |
+| Long functions (> 30 lines) | Split by responsibility |
+| Nested ternaries | `if/else` or `switch` |
+| Unclear names | Rename for clarity |
+| Duplicated code | Extract shared function |
+| Dead code | Remove entirely |
+| Complex conditionals | Extract to named function |
+| Magic numbers | Named constants |
+
+### Step 4: Apply Incrementally
+
+**One change at a time:**
+
+```javascript
+// Before: Deep nesting
+function processOrder(order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.status === 'pending') {
+        // ... actual logic buried here
+      }
+    }
+  }
+}
+
+// After: Guard clauses
+function processOrder(order) {
+  if (!order) return;
+  if (order.items.length === 0) return;
+  if (order.status !== 'pending') return;
+
+  // ... actual logic at top level
+}
+```
+
+**Run tests after each change.**
+
+### Step 5: Validate
+
+```bash
+# All tests pass
+npm test
+
+# Build succeeds
+npm run build
+
+# Behavior unchanged (manual check if needed)
+```
+
+### Step 6: If Tests Fail
+
+**Revert immediately.** Don't debug while mid-simplification.
+
+```bash
+git checkout -- .
+```
+
+Then:
+1. Reassess the change
+2. Make a smaller change
+3. Or add missing tests first
+
+---
+
+## Common Simplifications
+
+### Extract Guard Clauses
+
+```javascript
+// Before
+function getDiscount(user) {
+  if (user) {
+    if (user.membership === 'premium') {
+      return 0.2;
+    } else {
+      return 0.1;
+    }
+  }
+  return 0;
+}
+
+// After
+function getDiscount(user) {
+  if (!user) return 0;
+  if (user.membership === 'premium') return 0.2;
+  return 0.1;
+}
+```
+
+### Extract Named Functions
+
+```javascript
+// Before
+const eligibleUsers = users.filter(u => 
+  u.age >= 18 && u.verified && !u.banned && u.subscription !== 'free'
+);
+
+// After
+const isEligible = (user) =>
+  user.age >= 18 && 
+  user.verified && 
+  !user.banned && 
+  user.subscription !== 'free';
+
+const eligibleUsers = users.filter(isEligible);
+```
+
+### Replace Nested Ternary
+
+```javascript
+// Before
+const status = isPaid ? (isShipped ? 'complete' : 'processing') : 'pending';
+
+// After
+function getOrderStatus(isPaid, isShipped) {
+  if (!isPaid) return 'pending';
+  if (!isShipped) return 'processing';
+  return 'complete';
+}
+```
+
+### Remove Dead Code
+
+```javascript
+// Before
+function calculate(a, b) {
+  // const oldResult = legacyCalculate(a, b);  // Commented out
+  const result = a + b;
+  // console.log('Debug:', result);  // Debug log
+  return result;
+}
+
+// After
+function calculate(a, b) {
+  return a + b;
+}
+```
+
+---
+
+## Red Flags
+
+Stop if you find yourself:
+
+- Changing behavior while "simplifying"
+- Unable to explain why code exists
+- Simplifying without tests
+- Making changes across unrelated files
+- Creating new abstractions
+
+---
+
+## Output
+
+- Simpler, clearer code
+- All tests still passing
+- Atomic commits with clear messages
+
+## Next Step
+
+Run `/review` to verify improvements.