class-ai-agent 1.2.2 → 1.3.0

package/.kiro/references/testing-patterns.md

@@ -0,0 +1,183 @@
+# Testing Patterns Reference
+
+> Quick reference for test patterns. See `.claude/rules/testing.md` for full rules.
+
+## Test Pyramid
+
+```
+         ┌─────────┐
+         │   E2E   │  5%   Critical user flows
+         ├─────────┤
+         │  Integ  │  15%  API + DB interactions
+         ├─────────┤
+         │  Unit   │  80%  Pure logic, fast
+         └─────────┘
+```
+
+## Test Structure (AAA)
+
+```javascript
+it('should [expected behavior] when [condition]', () => {
+  // Arrange — Setup
+  const user = createTestUser({ role: 'admin' });
+  
+  // Act — Execute
+  const result = checkPermission(user, 'delete');
+  
+  // Assert — Verify
+  expect(result).toBe(true);
+});
+```
+
+## Unit Test Example
+
+```javascript
+describe('calculateDiscount', () => {
+  it('should return 10% for orders over $100', () => {
+    expect(calculateDiscount(150)).toBe(15);
+  });
+
+  it('should return 0 for orders under $100', () => {
+    expect(calculateDiscount(50)).toBe(0);
+  });
+
+  it('should handle edge case at exactly $100', () => {
+    expect(calculateDiscount(100)).toBe(0);
+  });
+});
+```
+
+## Integration Test Example
+
+```javascript
+describe('POST /api/users', () => {
+  it('should create user and return 201', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ email: 'test@example.com', name: 'Test' })
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(response.status).toBe(201);
+    expect(response.body.data.email).toBe('test@example.com');
+    
+    // Verify in database
+    const user = await db.user.findUnique({ 
+      where: { email: 'test@example.com' } 
+    });
+    expect(user).toBeDefined();
+  });
+});
+```
+
+## E2E Test Example (Playwright)
+
+```javascript
+test('user can complete checkout flow', async ({ page }) => {
+  // Login
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'user@example.com');
+  await page.fill('[name="password"]', 'password');
+  await page.click('button[type="submit"]');
+
+  // Add to cart
+  await page.goto('/products/1');
+  await page.click('button:has-text("Add to Cart")');
+
+  // Checkout
+  await page.goto('/checkout');
+  await page.fill('[name="card"]', '4242424242424242');
+  await page.click('button:has-text("Pay")');
+
+  // Verify
+  await expect(page.locator('.success-message')).toBeVisible();
+});
+```
+
+## React Component Test
+
+```javascript
+import { render, screen, fireEvent } from '@testing-library/react';
+
+describe('Counter', () => {
+  it('should increment count when button clicked', () => {
+    render(<Counter initialCount={0} />);
+    
+    const button = screen.getByRole('button', { name: /increment/i });
+    fireEvent.click(button);
+    
+    expect(screen.getByText('Count: 1')).toBeInTheDocument();
+  });
+});
+```
+
+## Test Doubles
+
+```javascript
+// 1. Real (preferred)
+const db = createTestDatabase();
+
+// 2. Fake (in-memory)
+const fakeUserRepo = {
+  users: [],
+  create(user) { this.users.push(user); return user; },
+  findById(id) { return this.users.find(u => u.id === id); }
+};
+
+// 3. Stub (canned response)
+const stubbedApi = {
+  getUser: () => Promise.resolve({ id: '1', name: 'Test' })
+};
+
+// 4. Mock (verify interactions — use sparingly)
+const mockLogger = vi.fn();
+```
+
+## Naming Convention
+
+```javascript
+// Pattern: should [expected] when [condition]
+
+// ✅ Good
+'should return null when user not found'
+'should throw ValidationError when email invalid'
+'should emit event when order placed'
+
+// ❌ Bad
+'works'
+'test user'
+'error handling'
+```
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Testing internals | Breaks on refactor | Test behavior |
+| Shared state | Tests affect each other | Reset in beforeEach |
+| Flaky tests | Random failures | Deterministic data |
+| Over-mocking | False confidence | Real implementations |
+| No assertions | Test always passes | Assert outcomes |
+| Magic numbers | Hard to understand | Named constants |
+
+## Coverage Thresholds
+
+```javascript
+// vitest.config.js
+coverage: {
+  thresholds: {
+    lines: 80,
+    branches: 80,
+    functions: 80,
+    statements: 80
+  }
+}
+```
+
+## Commands
+
+```bash
+npm test                  # Run all tests
+npm test -- --watch       # Watch mode
+npm test -- --coverage    # Coverage report
+npm run test:e2e          # E2E tests
+```

package/.kiro/settings/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp",
+        "--path",
+        "${workspaceFolder}"
+      ]
+    }
+  }
+}

package/.kiro/settings.json

@@ -0,0 +1,8 @@
+{
+  "steering_dir": ".kiro/steering",
+  "commands_dir": ".kiro/commands",
+  "skills_dir": ".kiro/skills",
+  "agents_dir": ".kiro/agents",
+  "references_dir": ".kiro/references",
+  "note": "Parallels .cursor/settings.json. Kiro loads .kiro/steering/*.md and .kiro/settings/mcp.json."
+}

package/.kiro/skills/agent-continuity/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: Agent Continuity
+description: Cross-tool session handoff and resume via .agent/SESSION.md
+---
+
+# Agent Continuity Skill
+
+## Purpose
+
+Keep **Cursor**, **Claude Code**, and **Kiro** aligned on the same in-flight work using committed **`.agent/SESSION.md`**.
+
+---
+
+## When to apply
+
+| Situation | Action |
+|-----------|--------|
+| New chat, same feature | **Resume** — read SESSION first |
+| End of session | **Handoff** — update SESSION |
+| Switch IDE/tool | **Handoff** then **Resume** in new tool |
+| Switch persona | Update Meta `persona`; handoff notes for next role |
+| Phase change (plan → build) | Update Meta `phase` |
+
+---
+
+## Handoff checklist
+
+- [ ] Meta: date, phase, tool, persona
+- [ ] Goal still accurate (one paragraph)
+- [ ] Done: bullets with paths/commits
+- [ ] In progress + blockers
+- [ ] Next: numbered for next agent
+- [ ] Decisions: non-obvious choices
+- [ ] Gotchas: failures, test commands, env
+- [ ] Pointers: spec, tasks, branch, key files
+- [ ] `tasks/todo.md` synced
+- [ ] No secrets or PII in SESSION
+
+---
+
+## Resume checklist
+
+- [ ] Read `.agent/SESSION.md`
+- [ ] Read `tasks/todo.md` if linked
+- [ ] Read SPEC if linked
+- [ ] `git status` vs SESSION expectations
+- [ ] Run sanity build/test if Gotchas say so
+- [ ] Post resumption summary to user
+- [ ] Execute first **Next** step via workflow command
+
+---
+
+## SESSION schema
+
+See **`.agent/SESSION.template.md`** for the canonical sections.
+
+---
+
+## Commands
+
+| Command | File |
+|---------|------|
+| `/handoff` | `.cursor/commands/handoff.md` (`.claude/`, `.kiro/`) |
+| `/resume` | `.cursor/commands/resume.md` |
+
+---
+
+## Optional history
+
+Copy SESSION to `.agent/history/YYYY-MM-DD-slug.md` at milestones; commit for audit trail.

package/.kiro/skills/code-review/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: Code Review & Quality
+description: Five-axis code review for comprehensive quality assessment
+---
+
+# Code Review & Quality Skill
+
+## Philosophy
+
+> "Approve a change when it definitely improves overall code health, even if it isn't perfect."
+
+Progress over perfection. Continuous incremental improvement.
+
+---
+
+## Five-Axis Review Framework
+
+### Axis 1: Correctness
+
+**Questions to ask:**
+- Does the implementation match the specification?
+- Are edge cases handled?
+- Are error paths covered?
+- Are there potential runtime issues?
+  - Off-by-one errors
+  - Race conditions
+  - Null/undefined access
+  - Resource leaks
+
+**Test adequacy:**
+- Do tests verify the claimed behavior?
+- Are negative cases tested?
+- Would a bug slip through?
+
+---
+
+### Axis 2: Readability & Simplicity
+
+**Questions to ask:**
+- Can another engineer understand this without explanation?
+- Are names clear and descriptive?
+- Is control flow straightforward?
+- Is the code organized logically?
+
+**Complexity checks:**
+- Deep nesting (> 3 levels)?
+- Long functions (> 30 lines)?
+- Clever tricks that obscure intent?
+- Unnecessary abstractions?
+
+---
+
+### Axis 3: Architecture
+
+**Questions to ask:**
+- Does this follow existing patterns in the codebase?
+- Are module boundaries respected?
+- Is there code duplication that should be extracted?
+- Is the abstraction level appropriate?
+- Do dependencies flow in the right direction?
+
+**Over-engineering checks:**
+- Is this simpler than it needs to be?
+- Are there abstractions "for future use"?
+- Would a simpler approach work?
+
+---
+
+### Axis 4: Security
+
+**Input validation:**
+- Is user input validated and sanitized?
+- Are queries parameterized?
+- Is output properly encoded?
+
+**Authentication & Authorization:**
+- Are auth checks in place?
+- Is ownership verified for resources?
+- Are permissions enforced?
+
+**Secrets management:**
+- No hardcoded secrets?
+- Sensitive data excluded from logs?
+- External data treated as untrusted?
+
+---
+
+### Axis 5: Performance
+
+**Common issues:**
+- N+1 query patterns?
+- Unbounded operations (loops, queries)?
+- Missing pagination?
+- Unnecessary re-renders (React)?
+- Objects created in hot paths?
+- Missing indexes for queries?
+
+**Async handling:**
+- Are async operations properly awaited?
+- Could operations be parallelized?
+
+---
+
+## Change Sizing Guidelines
+
+| Size | Lines | Guidance |
+|------|-------|----------|
+| **Ideal** | ~100 | Easy to review thoroughly |
+| **Acceptable** | ~300 | Requires focused review |
+| **Too Large** | 1000+ | Split into smaller PRs |
+
+Each PR should be **one logical change**, not an entire feature.
+
+---
+
+## Comment Severity Labels
+
+Use prefixes to clarify intent:
+
+| Label | Meaning | Action Required |
+|-------|---------|-----------------|
+| (none) | Required change | Must fix before merge |
+| `Critical:` | Merge blocker | Must fix before merge |
+| `Nit:` | Minor/style | Optional, author's choice |
+| `Optional:` | Suggestion | Consider, not required |
+| `FYI:` | Informational | No action needed |
+
+**Examples:**
+```
+Critical: This allows SQL injection via the `name` parameter.
+
+Nit: Consider renaming `data` to `userData` for clarity.
+
+Optional: You could use `Array.from()` here instead of spread.
+
+FYI: We have a shared utility for this in `src/utils/format.ts`.
+```
+
+---
+
+## Review Process
+
+### Step 1: Understand Context
+
+- What is this PR trying to achieve?
+- Is there a linked issue or spec?
+- What's the scope of changes?
+
+### Step 2: Review Tests First
+
+Tests reveal:
+- What behavior is expected
+- What edge cases are considered
+- Whether coverage is adequate
+
+### Step 3: Examine Implementation
+
+Walk through changes with the 5 axes in mind.
+
+### Step 4: Categorize Findings
+
+- **Must fix** — Correctness, security, critical bugs
+- **Should fix** — Readability, architecture concerns
+- **Consider** — Suggestions, style preferences
+
+### Step 5: Provide Actionable Feedback
+
+```
+❌ "This is confusing"
+
+✅ "This nested conditional is hard to follow. Consider extracting 
+    the inner logic to a named function like `isEligibleForDiscount()`"
+```
+
+---
+
+## Review Output Format
+
+```markdown
+## Review: [PR Title]
+
+### Summary
+[1-2 sentences on overall assessment]
+
+### Critical Issues
+- **[file:line]** [Issue description]
+
+### Important
+- **[file:line]** [Issue description]
+
+### Suggestions
+- **[file:line]** [Suggestion]
+
+### Verdict
+- [ ] Approve
+- [ ] Request changes
+- [ ] Needs discussion
+```
+
+---
+
+## Rules
+
+- **Don't accept "I'll clean it up later"** — It won't happen
+- **Remove dead code** — Don't comment it out
+- **Review within 1 business day** — Faster is better
+- **Be kind, not nice** — Honest feedback helps everyone
+- **One approval minimum** — Before any merge

package/.kiro/skills/deploy/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: deploy
+description: Skill to automate the full deployment process including build, test, and release steps
+---
+
+# Deploy Skill
+
+## Purpose
+Automate the deployment pipeline: build → test → deploy → verify.
+
+## Prerequisites
+- All tests passing
+- Environment variables configured
+- Access to deployment target
+
+## Steps
+
+### 1. Verify Clean State
+```bash
+git status
+git pull origin main
+```
+
+### 2. Run Tests
+```bash
+npm test
+```
+If tests fail → STOP. Report failures.
+
+### 3. Build
+```bash
+npm run build
+```
+
+### 4. Deploy by Environment
+
+**Development:**
+```bash
+docker-compose -f docker-compose.dev.yml up -d --build
+```
+
+**Production:**
+```bash
+docker-compose -f docker-compose.prod.yml pull
+docker-compose -f docker-compose.prod.yml up -d
+```
+
+### 5. Health Check
+```bash
+curl -f http://localhost:3000/health || echo "Health check failed"
+```
+
+### 6. Tail Logs (first 30 seconds)
+```bash
+docker-compose logs --tail=50 -f app
+```
+
+## Rollback
+```bash
+git revert HEAD --no-edit
+git push origin main
+# Redeploy previous version
+```
+
+## Success Criteria
+- Health endpoint returns 200
+- No error logs in initial 30 seconds
+- All smoke tests pass