class-ai-agent 1.2.0

package/.claude/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: Incremental Implementation
+description: Build features in thin vertical slices with continuous verification
+---
+
+# Incremental Implementation Skill
+
+## Philosophy
+
+> "The simplest thing that could work."
+
+Build in thin vertical slices. Each increment leaves the system working and testable.
+
+---
+
+## When to Apply
+
+**Use this skill when:**
+- Multi-file changes
+- New features
+- Refactoring work
+- Any change > 100 lines
+
+**Skip for:**
+- Single-file, small changes
+- Simple bug fixes
+- Configuration updates
+
+---
+
+## The Increment Cycle
+
+```
+┌─────────────────────────────────────────┐
+│  1. Pick smallest complete piece        │
+│                 ↓                       │
+│  2. Write failing test (RED)            │
+│                 ↓                       │
+│  3. Implement minimal code (GREEN)      │
+│                 ↓                       │
+│  4. Refactor if needed                  │
+│                 ↓                       │
+│  5. Run all tests                       │
+│                 ↓                       │
+│  6. Commit with clear message           │
+│                 ↓                       │
+│  7. Repeat for next piece               │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Vertical vs Horizontal Slicing
+
+### Vertical Slices (Correct)
+
+Each slice delivers end-to-end functionality:
+
+```
+Task 1: User can create a task
+        └── DB model + API route + UI component
+
+Task 2: User can view task list
+        └── DB query + API endpoint + List component
+
+Task 3: User can complete a task
+        └── DB update + API handler + Toggle UI
+```
+
+### Horizontal Slices (Anti-pattern)
+
+Layers completed separately:
+
+```
+Task 1: Create all DB models
+Task 2: Create all API routes
+Task 3: Create all UI components
+
+❌ Problem: Nothing works until everything is done
+```
+
+---
+
+## Slicing Strategies
+
+### 1. Happy Path First
+
+```
+Slice 1: Basic flow works
+Slice 2: Add validation
+Slice 3: Add error handling
+Slice 4: Add edge cases
+```
+
+### 2. Risk-First
+
+```
+Slice 1: Uncertain/complex piece (reduce risk early)
+Slice 2: Dependent pieces (build on verified foundation)
+Slice 3: Polish (now safe to invest time)
+```
+
+### 3. Contract-First
+
+```
+Slice 1: Define API contract (types, endpoints)
+Slice 2: Backend implements contract
+Slice 3: Frontend implements against contract
+```
+
+---
+
+## Rules
+
+### The 100-Line Rule
+
+> Test before writing more than ~100 lines.
+
+If you've written 100+ lines without running tests, stop and verify.
+
+### Touch Only What's Needed
+
+> Don't refactor adjacent code. Don't add unrequested features.
+
+Stay focused on the current task.
+
+### Keep It Building
+
+> Project must compile and tests must pass after each increment.
+
+Never leave the codebase broken between commits.
+
+### Feature Flags for Incomplete Work
+
+```javascript
+// Use flags when merging incomplete features
+if (featureFlags.newCheckout) {
+  return <NewCheckoutFlow />;
+}
+return <LegacyCheckout />;
+```
+
+### Safe Defaults
+
+New code defaults to conservative, disabled behavior:
+- New features off by default
+- New permissions denied by default
+- New validations strict by default
+
+### Rollback-Friendly
+
+Each increment should be independently revertable:
+
+```bash
+# If this commit breaks something, revert just this
+git revert HEAD
+```
+
+---
+
+## Red Flags
+
+**Stop and reassess if you're:**
+
+- Writing > 100 lines without testing
+- Mixing unrelated changes in one commit
+- Expanding scope mid-task
+- Breaking the build between increments
+- Creating abstractions "for later"
+- Touching files outside the task scope
+
+---
+
+## Commit Strategy
+
+Each increment = one commit:
+
+```bash
+# Good: Atomic, focused commits
+git commit -m "feat(tasks): add Task model with title and status"
+git commit -m "feat(tasks): add POST /api/tasks endpoint"
+git commit -m "feat(tasks): add CreateTaskForm component"
+
+# Bad: Large, unfocused commits
+git commit -m "Add task feature"  # 500 lines across 10 files
+```
+
+---
+
+## When Stuck
+
+If an increment fails:
+
+1. **Stop** — Don't push through
+2. **Diagnose** — What specifically failed?
+3. **Reduce scope** — Can you make a smaller increment?
+4. **Ask for help** — If truly blocked
+
+---
+
+## Verification Checklist
+
+After each increment:
+
+- [ ] Tests pass
+- [ ] Build succeeds
+- [ ] Code compiles
+- [ ] Feature works (manual check if UI)
+- [ ] Commit is atomic and focused
+- [ ] Message follows conventions

package/.claude/skills/security-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: security-review
+description: Skill to perform a thorough security audit of the codebase
+---
+
+# Security Review Skill
+
+## Purpose
+Systematically scan the codebase for security vulnerabilities and produce a prioritized report.
+
+## Checklist
+
+### 🔴 Critical (Check First)
+- [ ] Hardcoded secrets, API keys, passwords in source files
+  ```bash
+  grep -r "password\s*=\s*['\"]" src/
+  grep -r "api_key\s*=\s*['\"]" src/
+  ```
+- [ ] `.env` files accidentally committed
+  ```bash
+  git log --all --full-history -- .env
+  ```
+- [ ] SQL injection via string concatenation
+- [ ] `eval()` or `new Function()` with user input
+
+### 🟡 High Priority
+- [ ] Missing authentication on protected routes
+- [ ] Missing authorization (privilege escalation)
+- [ ] Passwords stored in plain text
+- [ ] JWT secrets too short or exposed
+- [ ] No rate limiting on auth endpoints
+- [ ] Missing input validation
+
+### 🟢 Medium Priority
+- [ ] Missing security headers (run Helmet scan)
+- [ ] CORS configured too broadly (`origin: *`)
+- [ ] Dependencies with known vulnerabilities
+  ```bash
+  npm audit
+  ```
+- [ ] Sensitive data in logs
+- [ ] Missing HTTPS enforcement
+
+### ℹ️ Low / Informational
+- [ ] Error messages revealing stack traces to client
+- [ ] Missing CSP headers
+- [ ] Cookie security flags (HttpOnly, Secure, SameSite)
+
+## Output Format
+```markdown
+# Security Review Report — [Date]
+
+## Critical Issues
+[List with file:line references]
+
+## High Priority Issues
+[List with file:line references]
+
+## Recommendations
+[Prioritized action items]
+```
+
+## Commands
+```bash
+# Dependency audit
+npm audit --audit-level=moderate
+
+# Check for secret patterns
+grep -rn --include="*.js" --include="*.ts" \
+  -E "(password|secret|api_key|token)\s*=\s*['\"][^'\"]{8,}" src/
+```

package/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: Test-Driven Development
+description: Write tests before code using RED-GREEN-REFACTOR cycle
+---
+
+# Test-Driven Development Skill
+
+## Overview
+
+TDD transforms testing from an afterthought into the foundation of development. Tests are proof that code works correctly.
+
+## When to Invoke
+
+- Writing new features
+- Fixing bugs (Prove-It pattern)
+- When asked to write tests
+- Before any implementation work
+
+---
+
+## Core Cycle: RED-GREEN-REFACTOR
+
+### RED Phase
+
+Write a test that describes expected behavior. **It must fail.**
+
+```javascript
+describe('calculateDiscount', () => {
+  it('should apply 10% discount for orders over $100', () => {
+    const result = calculateDiscount(150);
+    expect(result).toBe(15);
+  });
+});
+```
+
+Run: `npm test` → Should **FAIL**
+
+### GREEN Phase
+
+Write **minimal** code to pass the test. No extras.
+
+```javascript
+function calculateDiscount(amount) {
+  if (amount > 100) return amount * 0.1;
+  return 0;
+}
+```
+
+Run: `npm test` → Should **PASS**
+
+### REFACTOR Phase
+
+Improve code while keeping tests green.
+
+```javascript
+const DISCOUNT_THRESHOLD = 100;
+const DISCOUNT_RATE = 0.1;
+
+function calculateDiscount(amount) {
+  if (amount <= DISCOUNT_THRESHOLD) return 0;
+  return amount * DISCOUNT_RATE;
+}
+```
+
+Run: `npm test` → Should still **PASS**
+
+---
+
+## Prove-It Pattern (Bug Fixes)
+
+### Step 1: Write Failing Test
+
+```javascript
+it('should handle empty cart without error (bug #456)', () => {
+  const cart = new Cart([]);
+  expect(() => cart.getTotal()).not.toThrow();
+  expect(cart.getTotal()).toBe(0);
+});
+```
+
+### Step 2: Verify Failure
+
+Run test → Confirms bug exists
+
+### Step 3: Fix Bug
+
+```javascript
+getTotal() {
+  if (this.items.length === 0) return 0;  // Fix
+  return this.items.reduce((sum, item) => sum + item.price, 0);
+}
+```
+
+### Step 4: Verify Pass
+
+Run test → Confirms fix works
+
+### Step 5: Run Full Suite
+
+```bash
+npm test  # No regressions
+```
+
+---
+
+## Test Pyramid
+
+```
+         ┌─────────┐
+         │   E2E   │  5%  — Critical user flows
+         │  Tests  │       Full system, minutes
+         ├─────────┤
+         │ Integr. │  15% — API + DB interactions
+         │  Tests  │       Seconds
+         ├─────────┤
+         │  Unit   │  80% — Pure logic
+         │  Tests  │       Milliseconds
+         └─────────┘
+```
+
+---
+
+## Test Structure: AAA Pattern
+
+```javascript
+it('should calculate tax for California', () => {
+  // Arrange — Setup
+  const order = createOrder({ state: 'CA', subtotal: 100 });
+  
+  // Act — Execute
+  const tax = calculateTax(order);
+  
+  // Assert — Verify
+  expect(tax).toBe(7.25);
+});
+```
+
+---
+
+## DAMP > DRY in Tests
+
+Tests should be **Descriptive And Meaningful Phrases**.
+
+```javascript
+// ✅ DAMP — Self-contained and clear
+it('should reject password without uppercase letter', () => {
+  const result = validatePassword('lowercase123!');
+  
+  expect(result.valid).toBe(false);
+  expect(result.errors).toContain('Must contain uppercase letter');
+});
+
+// ❌ Too DRY — Requires reading shared context
+it('should reject invalid password', () => {
+  expect(validate(INVALID_PASSWORD_NO_UPPER)).toBe(false);
+});
+```
+
+---
+
+## Test Doubles (Preference Order)
+
+1. **Real implementations** — Best, but may be slow
+2. **Fakes** — In-memory DB, simplified implementations
+3. **Stubs** — Return canned responses
+4. **Mocks** — Verify interactions (use sparingly)
+
+```javascript
+// ✅ Prefer: Real or fake
+const db = createTestDatabase();
+const user = await userService.create(db, userData);
+
+// ⚠️ Use sparingly: Mocks
+const mockDb = { create: vi.fn().mockResolvedValue(user) };
+```
+
+---
+
+## Naming Conventions
+
+```javascript
+// Pattern: should [expected behavior] when [condition]
+
+// ✅ Good
+'should return empty array when no users exist'
+'should throw ValidationError when email is invalid'
+'should send welcome email after registration'
+
+// ❌ Bad
+'works correctly'
+'test user creation'
+'handles error'
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Testing internals | Breaks on refactor | Test behavior, not implementation |
+| Flaky tests | Erodes trust | Use deterministic data |
+| Over-mocking | False confidence | Prefer real implementations |
+| Snapshot abuse | Large diffs ignored | Use sparingly |
+| Shared mutable state | Tests affect each other | Reset in beforeEach |
+| Testing frameworks | Wasted effort | Only test your code |
+
+---
+
+## Verification Checklist
+
+- [ ] All new code has tests
+- [ ] Bug fixes have reproduction tests
+- [ ] Tests describe behavior (readable names)
+- [ ] No skipped tests
+- [ ] Coverage maintained/improved
+- [ ] Full suite passes

package/.cursor/CURSOR.md

@@ -0,0 +1,112 @@
+# Cursor AI agent configuration
+
+## Overview
+
+This project uses **Cursor** with the same structured workflows, specialized agent personas, and coding standards as the Claude-oriented **`.claude/`** tree. Cursor-specific files live under **`.cursor/`**.
+
+---
+
+## Development workflow
+
+Follow this workflow for feature development:
+
+```
+/spec  →  /plan  →  /build  →  /test  →  /review  →  Ship
+```
+
+| Phase | Prompt source | Purpose |
+|-------|----------------|--------|
+| **Define** | `.cursor/commands/spec.md` | PRD: objectives, scope, boundaries |
+| **Plan** | `.cursor/commands/plan.md` | Vertical slices, acceptance criteria |
+| **Build** | `.cursor/commands/build.md` | Incremental implementation, TDD |
+| **Verify** | `.cursor/commands/test.md` | Tests and verification |
+| **Review** | `.cursor/commands/review.md` | Five-axis review before merge |
+| **Ship** | `.cursor/commands/deploy.md` | Build, test, deploy |
+
+### Supporting prompts
+
+| File | Purpose |
+|------|---------|
+| `commands/debug.md` | Systematic diagnosis |
+| `commands/simplify.md` | Reduce complexity, same behavior |
+| `commands/fix-issue.md` | Analyze and fix reported issues |
+
+**How to use:** Open the markdown file, copy the section you need, or **@ mention** the file in Chat/Composer so the model loads it.
+
+---
+
+## Core principles
+
+- **TDD** — Failing tests first, then implementation (`.cursor/skills/tdd/`)
+- **Incremental implementation** — Small vertical slices (`.cursor/skills/incremental-implementation/`)
+- **Five-axis review** — Correctness, readability, architecture, security, performance (`.cursor/skills/code-review/`)
+
+---
+
+## Mandatory rules (Cursor)
+
+Project rules are **`.cursor/rules/*.mdc`**. They use YAML frontmatter:
+
+- **`alwaysApply: true`** — Included in every relevant session (`cursor-overview.mdc`, `security.mdc`)
+- **`alwaysApply: false`** + **`globs`** — Applied when files matching the pattern are in context
+
+| Topic | Rule file |
+|-------|-----------|
+| Clean code, style, errors | `clean-code`, `code-style`, `error-handling` |
+| Stack, structure, APIs | `tech-stack`, `project-structure`, `api-conventions` |
+| Data & naming | `naming-conventions`, `database` |
+| Ops & quality | `security`, `monitoring`, `testing`, `git-workflow`, `system-design` |
+
+---
+
+## Agent personas
+
+Instructions live in **`.cursor/agents/`**. Invoke by **@ mentioning** the file (e.g. `@.cursor/agents/backend.md`).
+
+| Area | File |
+|------|------|
+| Frontend, backend, architecture | `frontend.md`, `backend.md`, `systems-architect.md` |
+| Quality | `code-reviewer.md`, `test-engineer.md`, `qa.md`, `security-auditor.md` |
+| Product & content | `project-manager.md`, `ui-ux-designer.md`, `copywriter-seo.md` |
+
+---
+
+## Skills
+
+Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files where present).
+
+| Skill | Use for |
+|-------|---------|
+| `tdd` | Red–green–refactor |
+| `code-review` | Five-axis review |
+| `incremental-implementation` | Vertical slices |
+| `deploy` | Deployment pipeline |
+| `security-review` | Security audit |
+
+---
+
+## Reference checklists
+
+**`.cursor/references/`**
+
+| File | Use for |
+|------|---------|
+| `security-checklist.md` | Pre-deploy security |
+| `testing-patterns.md` | Test structure |
+| `performance-checklist.md` | Performance |
+| `accessibility-checklist.md` | WCAG-oriented checks |
+
+---
+
+## Config parity
+
+**`.cursor/settings.json`** lists directories (mirrors `.claude/settings.json` for Claude Code). Cursor natively loads **`.cursor/rules/*.mdc`**; other paths are documentation for humans and for `@` includes.
+
+---
+
+## Agent behavior
+
+1. Follow the workflow and use the command prompts when starting a phase.
+2. Apply **`.cursor/rules/`**; treat **`security.mdc`** as non-negotiable.
+3. Prefer tests first and small, buildable changes.
+4. **@ mention** the right **`.cursor/agents/`** file when the task matches that role.