class-ai-agent 1.2.3 → 1.3.0

package/.kiro/commands/resume.md

@@ -0,0 +1,107 @@
+---
+name: resume
+description: Start-of-session — load .agent/SESSION.md and continue prior work
+---
+
+# /resume — Continue prior work
+
+> "Read the map before you move."
+
+## Purpose
+
+Load cross-tool handoff state and continue work from a previous agent session without re-discovering context.
+
+## When to use
+
+- Starting a new chat on the same feature
+- Switching tools (Cursor ↔ Claude Code ↔ Kiro)
+- User says "continue", "pick up where we left off", or "resume"
+- After pulling a branch that includes an updated `.agent/SESSION.md`
+
+## Prerequisites
+
+- **`.agent/SESSION.md`** exists in the project root
+- If missing: run `npx class-ai-agent` or copy `.agent/SESSION.template.md` → `.agent/SESSION.md`
+
+## Workflow
+
+### Phase 1: Load handoff (read-only first)
+
+Read in this order:
+
+1. **`.agent/SESSION.md`** — goal, done, in progress, next, decisions, gotchas, pointers
+2. **`tasks/todo.md`** — if referenced in Pointers
+3. **`SPEC.md`** or path from Pointers — if in spec/plan/build phase
+
+> Do **not** edit code until Phase 3 plan is stated to the user.
+
+### Phase 2: Sanity check
+
+From SESSION **Gotchas** and **Pointers**, run quick checks when noted:
+
+- `git status` — uncommitted work matches SESSION?
+- Build/test commands listed in Gotchas — run if stale or uncertain
+- Branch matches Pointers
+
+If SESSION reports **blockers** or broken build, surface them before implementing.
+
+### Phase 3: State plan to user
+
+Reply with a short structured summary:
+
+```markdown
+## Resuming
+
+**Goal:** [from SESSION]
+**Phase:** [spec | plan | build | test | review | debug]
+**Last updated:** [Meta date] via [tool/persona]
+
+### Already done
+- ...
+
+### In progress
+- ...
+
+### Next (this session)
+1. ...
+
+### Risks / blockers
+- ...
+```
+
+Ask for confirmation only if SESSION is ambiguous or blockers need a decision.
+
+### Phase 4: Continue workflow
+
+| Phase in SESSION | Command to follow |
+|------------------|-------------------|
+| spec | `/spec` (refine) or `/plan` if spec is done |
+| plan | `/plan` or `/build` if plan exists |
+| build | `/build` |
+| test | `/test` |
+| review | `/review` |
+| debug | `/debug` |
+
+Update **Meta** in `.agent/SESSION.md` when you change phase or tool.
+
+### Phase 5: During work
+
+- After meaningful progress, update SESSION **Done** / **In progress** / **Next**
+- End session with **`/handoff`**
+
+## If SESSION is empty or stale
+
+1. Survey repo: `git log`, `tasks/todo.md`, open PRs
+2. Rebuild SESSION from evidence
+3. Ask user to confirm goal and next steps
+4. Run `/handoff` when aligned
+
+## Output
+
+- Resumption summary (Phase 3)
+- Explicit next action (first item from **Next**)
+- No code changes until plan is stated (unless user asked for a specific fix)
+
+## Next step
+
+Execute the first **Next** item using the appropriate workflow command (`/build`, etc.).

package/.kiro/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/.kiro/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.

package/.kiro/commands/spec.md

@@ -0,0 +1,96 @@
+---
+name: spec
+description: Spec before code — structured PRD creation for new features
+---
+
+# /spec — Specification-Driven Development
+
+> "Plan the work, then work the plan."
+
+## Purpose
+
+Create a comprehensive specification document **before** writing any code. This ensures alignment on requirements, constraints, and acceptance criteria.
+
+## Workflow
+
+### Phase 1: Discovery (Ask Questions)
+
+Before generating a spec, gather requirements by asking:
+
+**Scope**
+- What is the objective of this feature?
+- Who are the target users?
+- What problem does this solve?
+
+**Features**
+- What are the core features (MVP)?
+- What are the acceptance criteria for each?
+- What is explicitly out of scope?
+
+**Technical**
+- Any tech stack preferences or constraints?
+- Integration points with existing systems?
+- Performance requirements?
+
+### Phase 2: Generate Specification
+
+After discovery, produce `SPEC.md` with these sections:
+
+```markdown
+# Feature: [Name]
+
+## Objective
+[1-2 sentences describing the goal]
+
+## Target Users
+[Who will use this and why]
+
+## Core Features
+1. [Feature A] — [Acceptance criteria]
+2. [Feature B] — [Acceptance criteria]
+3. [Feature C] — [Acceptance criteria]
+
+## Out of Scope
+- [What we're NOT building in this iteration]
+
+## Technical Approach
+- Tech stack decisions
+- Data models
+- API contracts (if applicable)
+- Integration points
+
+## Code Style
+- Follow rules in `.claude/rules/`
+- [Any feature-specific conventions]
+
+## Testing Strategy
+- Unit tests for: [areas]
+- Integration tests for: [areas]
+- E2E tests for: [critical paths]
+
+## Boundaries
+### Always Do
+- [Non-negotiables]
+
+### Ask First
+- [Decisions requiring approval]
+
+### Never Do
+- [Hard constraints]
+```
+
+### Phase 3: Review & Confirm
+
+- Present the spec to the user
+- Confirm before proceeding to `/plan`
+- Save as `SPEC.md` in project root or `docs/specs/[feature].md`
+
+## Output
+
+- `SPEC.md` — The specification document
+- Clear alignment on what to build
+- **`.agent/SESSION.md`** — Initialize or update: set Meta `phase` to `plan`, **Goal**, **Pointers** → spec path, **Next** → run `/plan`
+
+## Next Step
+
+After spec is approved, run `/plan` to decompose into tasks. Run `/handoff` if ending the session before planning.

package/.kiro/commands/test.md

@@ -0,0 +1,214 @@
+---
+name: test
+description: Write tests using TDD patterns — tests are proof of correctness
+---
+
+# /test — Test-Driven Development
+
+> "Tests are proof, not afterthought."
+
+## Purpose
+
+Write tests that prove code works correctly. Use the RED-GREEN-REFACTOR cycle for new features and the Prove-It pattern for bug fixes.
+
+## For New Features: RED-GREEN-REFACTOR
+
+### RED: Write Failing Test First
+
+```javascript
+describe('UserService.findById', () => {
+  it('should return user when found', async () => {
+    // Arrange
+    const userId = 'user-123';
+    
+    // Act
+    const user = await userService.findById(userId);
+    
+    // Assert
+    expect(user).toBeDefined();
+    expect(user.id).toBe(userId);
+  });
+
+  it('should throw NotFoundError when user does not exist', async () => {
+    await expect(userService.findById('non-existent'))
+      .rejects.toThrow(NotFoundError);
+  });
+});
+```
+
+Run tests — **they should fail** (proves nothing is implemented yet).
+
+### GREEN: Write Minimal Code to Pass
+
+```javascript
+async findById(id: string): Promise<User> {
+  const user = await this.db.user.findUnique({ where: { id } });
+  if (!user) throw new NotFoundError('User not found');
+  return user;
+}
+```
+
+Run tests — **they should pass**.
+
+### REFACTOR: Improve While Green
+
+Clean up code while keeping tests passing:
+- Better naming
+- Extract helpers
+- Remove duplication
+
+---
+
+## For Bug Fixes: Prove-It Pattern
+
+### Step 1: Write Test That Reproduces the Bug
+
+```javascript
+it('should not duplicate items when adding to cart twice', async () => {
+  // This test should FAIL with the current buggy code
+  await cart.addItem('product-1', 1);
+  await cart.addItem('product-1', 1);
+  
+  expect(cart.items).toHaveLength(1);
+  expect(cart.items[0].quantity).toBe(2);
+});
+```
+
+### Step 2: Verify Test Fails
+
+Run the test — confirm it **fails** (proving the bug exists).
+
+### Step 3: Fix the Bug
+
+```javascript
+async addItem(productId: string, quantity: number) {
+  const existing = this.items.find(i => i.productId === productId);
+  if (existing) {
+    existing.quantity += quantity;  // Fix: increment instead of duplicate
+  } else {
+    this.items.push({ productId, quantity });
+  }
+}
+```
+
+### Step 4: Verify Test Passes
+
+Run the test — confirm it **passes** (proving the fix works).
+
+### Step 5: Run Full Suite
+
+```bash
+npm test  # Ensure no regressions
+```
+
+---
+
+## Test Pyramid
+
+| Level | Percentage | Speed | Scope |
+|-------|------------|-------|-------|
+| **Unit** | 80% | ms | Single function, no I/O |
+| **Integration** | 15% | seconds | API + DB, component interactions |
+| **E2E** | 5% | minutes | Full user flows |
+
+---
+
+## Writing Good Tests
+
+### Arrange-Act-Assert Pattern
+
+```javascript
+it('should calculate total with discount', () => {
+  // Arrange — setup
+  const cart = new Cart();
+  cart.addItem({ price: 100 });
+  cart.applyDiscount(10);
+
+  // Act — execute
+  const total = cart.calculateTotal();
+
+  // Assert — verify
+  expect(total).toBe(90);
+});
+```
+
+### DAMP Over DRY
+
+Tests should be **Descriptive And Meaningful Phrases**. Each test reads independently:
+
+```javascript
+// ✅ DAMP — clear and independent
+it('should reject password shorter than 8 characters', () => {
+  const result = validatePassword('short');
+  expect(result.valid).toBe(false);
+  expect(result.error).toBe('Password must be at least 8 characters');
+});
+
+// ❌ Too DRY — requires reading shared setup
+it('should reject short password', () => {
+  expect(validate(shortPassword)).toBe(false);
+});
+```
+
+### Descriptive Test Names
+
+```javascript
+// ✅ Good — describes behavior
+'should return 404 when user is not found'
+'should increment quantity when adding existing product'
+'should send welcome email after registration'
+
+// ❌ Bad — vague
+'works correctly'
+'handles error'
+'test user'
+```
+
+### One Behavior Per Test
+
+```javascript
+// ✅ Good — focused
+it('should validate email format', () => { ... });
+it('should require email field', () => { ... });
+
+// ❌ Bad — testing multiple things
+it('should validate email', () => {
+  expect(validate('')).toBe(false);      // required
+  expect(validate('bad')).toBe(false);   // format
+  expect(validate('a@b.c')).toBe(true);  // valid
+});
+```
+
+---
+
+## Test Doubles Preference
+
+```
+1. Real implementations (best)
+2. In-memory fakes (test DB, fake filesystem)
+3. Stubs (canned responses)
+4. Mocks (verify interactions — use sparingly)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Testing internals | Breaks on refactor | Test inputs/outputs only |
+| Flaky tests | Erodes trust | Use deterministic data, isolate state |
+| Over-mocking | False confidence | Prefer real implementations |
+| Snapshot abuse | Large diffs ignored | Use for rare cases only |
+| Shared state | Tests affect each other | Reset state in beforeEach |
+
+---
+
+## Verification Checklist
+
+- [ ] All new behaviors have tests
+- [ ] Bug fixes have reproduction tests
+- [ ] Test names describe behavior
+- [ ] No skipped or disabled tests
+- [ ] Coverage maintained or improved
+- [ ] Full test suite passes