cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/testing-strategist/references/typescript.md

@@ -0,0 +1,328 @@
+# TypeScript Testing Patterns
+
+Language-specific patterns for the `testing-strategist` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Framework Stack
+
+| Level | Tool | Purpose |
+|-------|------|---------|
+| Unit | **Jest** or **Vitest** | Test runner, assertions, mocking |
+| Component | **React Testing Library** | User-centric component testing |
+| Integration | **Supertest** | HTTP API testing |
+| E2E | **Playwright** | Browser automation |
+
+## Commands
+
+```bash
+npm test                    # Run tests
+npm test -- --watch         # Watch mode
+npm run test:coverage       # Coverage report
+npx playwright test         # E2E tests
+open coverage/lcov-report/index.html  # View HTML report
+```
+
+---
+
+## Unit Test: Business Logic
+
+```typescript
+// src/lib/pricing.ts
+export function calculateTotal(items: { price: number; quantity: number }[]) {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+}
+
+export function applyDiscount(total: number, discountPercent: number) {
+  if (discountPercent < 0 || discountPercent > 100) {
+    throw new Error('Invalid discount percentage')
+  }
+  return total * (1 - discountPercent / 100)
+}
+
+// src/lib/pricing.test.ts
+import { calculateTotal, applyDiscount } from './pricing'
+
+describe('calculateTotal', () => {
+  it('calculates total for single item', () => {
+    const items = [{ price: 10, quantity: 2 }]
+    expect(calculateTotal(items)).toBe(20)
+  })
+
+  it('calculates total for multiple items', () => {
+    const items = [
+      { price: 10, quantity: 2 },
+      { price: 5, quantity: 3 }
+    ]
+    expect(calculateTotal(items)).toBe(35)
+  })
+
+  it('returns 0 for empty array', () => {
+    expect(calculateTotal([])).toBe(0)
+  })
+})
+
+describe('applyDiscount', () => {
+  it('applies discount correctly', () => {
+    expect(applyDiscount(100, 20)).toBe(80)
+  })
+
+  it('throws error for invalid discount', () => {
+    expect(() => applyDiscount(100, -10)).toThrow('Invalid discount')
+    expect(() => applyDiscount(100, 150)).toThrow('Invalid discount')
+  })
+})
+```
+
+## Unit Test: React Components
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('applies primary variant by default', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByRole('button')).toHaveClass('btn-primary')
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click me</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+})
+```
+
+## Unit Test: Custom Hooks
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+import { useCounter } from './useCounter'
+
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { result } = renderHook(() => useCounter())
+    expect(result.current.count).toBe(0)
+  })
+
+  it('increments count', () => {
+    const { result } = renderHook(() => useCounter())
+    act(() => { result.current.increment() })
+    expect(result.current.count).toBe(1)
+  })
+
+  it('resets to initial value', () => {
+    const { result } = renderHook(() => useCounter(10))
+    act(() => {
+      result.current.increment()
+      result.current.reset()
+    })
+    expect(result.current.count).toBe(10)
+  })
+})
+```
+
+---
+
+## Integration Test: API Routes
+
+```typescript
+import { testClient } from '@/lib/test-utils'
+
+describe('POST /api/posts', () => {
+  beforeEach(async () => {
+    await db.post.deleteMany()
+  })
+
+  it('creates a new post', async () => {
+    const response = await testClient
+      .post('/api/posts')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ title: 'Test Post', content: 'This is a test post' })
+
+    expect(response.status).toBe(201)
+    expect(response.body).toMatchObject({
+      title: 'Test Post',
+      content: 'This is a test post'
+    })
+
+    // Verify in database
+    const posts = await db.post.findMany()
+    expect(posts).toHaveLength(1)
+    expect(posts[0].title).toBe('Test Post')
+  })
+
+  it('returns 400 for invalid data', async () => {
+    const response = await testClient
+      .post('/api/posts')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ title: '' })
+
+    expect(response.status).toBe(400)
+    expect(response.body.errors).toBeDefined()
+  })
+
+  it('returns 401 for unauthenticated request', async () => {
+    const response = await testClient.post('/api/posts')
+      .send({ title: 'Test', content: 'Test' })
+
+    expect(response.status).toBe(401)
+  })
+})
+```
+
+## Integration Test: Database Operations
+
+```typescript
+describe('userRepository', () => {
+  beforeEach(async () => { await db.user.deleteMany() })
+  afterAll(async () => { await db.$disconnect() })
+
+  describe('createUser', () => {
+    it('creates user with hashed password', async () => {
+      const user = await createUser({
+        email: 'test@example.com',
+        password: 'password123'
+      })
+
+      expect(user.email).toBe('test@example.com')
+      expect(user.password).not.toBe('password123')
+      expect(user.password).toMatch(/^\$2[aby]/) // bcrypt hash
+    })
+
+    it('throws error for duplicate email', async () => {
+      await createUser({ email: 'test@example.com', password: 'pass' })
+      await expect(createUser({ email: 'test@example.com', password: 'pass' }))
+        .rejects.toThrow()
+    })
+  })
+})
+```
+
+---
+
+## E2E Test: Playwright
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test.describe('Authentication', () => {
+  test('user can sign up and log in', async ({ page }) => {
+    await page.goto('/signup')
+    await page.fill('input[name="email"]', 'test@example.com')
+    await page.fill('input[name="password"]', 'SecurePass123!')
+    await page.fill('input[name="confirmPassword"]', 'SecurePass123!')
+    await page.click('button[type="submit"]')
+
+    await expect(page).toHaveURL('/dashboard')
+    await expect(page.locator('h1')).toContainText('Welcome')
+  })
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/login')
+    await page.fill('input[name="email"]', 'wrong@example.com')
+    await page.fill('input[name="password"]', 'wrongpassword')
+    await page.click('button[type="submit"]')
+
+    await expect(page.locator('[role="alert"]')).toContainText('Invalid credentials')
+    await expect(page).toHaveURL('/login')
+  })
+})
+```
+
+---
+
+## Mocking
+
+```typescript
+// Mock external API
+import { fetchUserData } from '@/lib/api'
+
+jest.mock('@/lib/api')
+const mockFetchUserData = fetchUserData as jest.MockedFunction<typeof fetchUserData>
+
+it('displays user data', async () => {
+  mockFetchUserData.mockResolvedValue({
+    id: '1', name: 'John Doe', email: 'john@example.com'
+  })
+
+  render(<UserProfile userId="1" />)
+
+  await waitFor(() => {
+    expect(screen.getByText('John Doe')).toBeInTheDocument()
+  })
+})
+
+// Mock Date
+beforeAll(() => {
+  jest.useFakeTimers()
+  jest.setSystemTime(new Date('2024-01-01'))
+})
+afterAll(() => { jest.useRealTimers() })
+
+// Mock Math.random
+const mockRandom = jest.spyOn(Math, 'random')
+mockRandom.mockReturnValue(0.5)
+// ... assertions ...
+mockRandom.mockRestore()
+```
+
+---
+
+## Coverage Configuration
+
+```javascript
+// jest.config.js
+module.exports = {
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/*.stories.tsx',
+    '!src/types/**'
+  ],
+  coverageThresholds: {
+    global: {
+      branches: 70, functions: 70, lines: 70, statements: 70
+    },
+    './src/lib/auth/**': {
+      branches: 90, functions: 90, lines: 90
+    }
+  }
+}
+```
+
+## CI/CD
+
+```yaml
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Assertion Examples
+
+### ❌ Shallow (BANNED)
+```typescript
+expect(result).toBeDefined()
+expect(result).toBeTruthy()
+```
+
+### ✅ Deep (REQUIRED)
+```typescript
+expect(result).toEqual({
+  id: expect.any(String),
+  name: 'Test',
+  items: expect.arrayContaining([
+    expect.objectContaining({ amount: 100 })
+  ])
+})
+```

package/template/.claude/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: verification-before-completion
+description: "Use when about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before claims, always."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# Verification Before Completion
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this response, you cannot claim it passes. Period.
+
+## When to Apply
+
+**Before ANY of these:**
+- Claiming tests pass, build succeeds, or linter is clean
+- Expressing satisfaction ("Great!", "Done!", "All good!")
+- Committing, pushing, or creating a PR
+- Moving to the next task or slice
+- Reporting completion to the user
+
+## The Gate
+
+```
+1. IDENTIFY → What command proves this claim?
+2. RUN     → Execute it. Fresh. Complete. Not a cached result.
+3. READ    → Full output. Check exit code. Count failures.
+4. VERIFY  → Does the output support the claim?
+5. CLAIM   → Only now may you state the result.
+```
+
+Skip any step = the claim is unverified.
+
+## Evidence Standards
+
+| Claim | Required Evidence | Not Sufficient |
+|-------|-------------------|----------------|
+| "Tests pass" | Full test output showing 0 failures | Previous run, "should pass", partial suite |
+| "Build succeeds" | Build command output, exit code 0 | Linter passing (linter ≠ compiler) |
+| "Lint clean" | Linter output showing 0 errors/warnings | Build passing (build ≠ lint) |
+| "Bug fixed" | Reproduce original symptom → now passes | "I changed the code" |
+| "Regression test works" | Red-green cycle: fail → fix → pass | Test passes once without verifying it can fail |
+| "Requirements met" | Line-by-line checklist against acceptance criteria | "Tests pass" (tests may not cover requirements) |
+| "Migration works" | Run migration up AND down successfully | "Schema looks correct" |
+
+## Red-Green Verification (TDD)
+
+When claiming a regression test is valid:
+
+```
+1. Write test
+2. Run test → MUST FAIL (Red)
+3. Implement fix
+4. Run test → MUST PASS (Green)
+5. Revert fix temporarily
+6. Run test → MUST FAIL AGAIN (proves test is meaningful)
+7. Restore fix
+8. Run test → Passes (final confirmation)
+```
+
+If the test never fails, it proves nothing.
+
+## Red Flags — Stop and Verify
+
+Catch yourself if you're about to say:
+
+| Phrase | What to Do Instead |
+|--------|-------------------|
+| "Should work now" | Run the command |
+| "I'm confident this is correct" | Confidence ≠ evidence |
+| "Looks like it should pass" | Looks ≠ verified |
+| "Just this once I'll skip" | No exceptions |
+| "The linter passed so the build should too" | They check different things |
+| "I changed the right file" | Run the test |
+| "The agent said it succeeded" | Verify independently |
+
+## Integration with Pipeline
+
+This skill reinforces the pipeline's `completion-checklist` rule:
+
+1. **Code** — implementation meets the contract ← verified by tests
+2. **Tests** — all pass ← verified by running them RIGHT NOW
+3. **Tracking** — progress files updated ← verified by reading them
+4. **Locks** — claims removed ← verified by checking
+
+## The Bottom Line
+
+**Run the command. Read the output. Count the failures. THEN make the claim.**
+
+This is non-negotiable. The cost of verification is 30 seconds. The cost of a false claim is broken trust, shipped bugs, and wasted debugging time downstream.

package/template/.claude/skills/workflow-automation/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: workflow-automation
+description: "Architect durable, event-driven workflows using step functions, retry strategies, idempotency, fan-out patterns, and the critical differences between orchestration approaches."
+version: 2.0.0
+---
+
+# Workflow Automation
+
+You are a workflow architect who understands the fundamental tradeoff: **simplicity vs. correctness**. Every workflow platform sits somewhere on that spectrum. Your job is to pick the right point for the user's situation and implement it correctly.
+
+## When to Use
+
+- Background jobs that must complete even if the server restarts
+- Multi-step processes where partial completion is worse than failure (payments, onboarding)
+- Event-driven architectures where one event triggers multiple independent reactions
+- Scheduled/recurring tasks that need observability and retry guarantees
+- Any process where "it probably ran" is not acceptable
+
+## When NOT to Use
+
+- Simple fire-and-forget tasks (use a queue or a delay)
+- Synchronous request-response flows
+- Tasks under 100ms that don't involve external services
+
+## Ecosystem-Specific References
+
+After reading the methodology below, read the reference matching your orchestration platform:
+
+| Platform | Reference | Best For |
+|----------|-----------|----------|
+| Inngest | `references/inngest.md` | Serverless, event-driven, fast shipping |
+| Temporal | `references/temporal.md` | Complex orchestration, human-in-the-loop |
+| BullMQ | `references/bullmq.md` | Simple job queues, rate limiting, Redis stack |
+
+---
+
+## Core Concept: Durable Execution
+
+**Wrap each unit of work in a step, so the system can retry, resume, and checkpoint independently.**
+
+```
+Without durable execution:
+  fetch data → process → save → send email
+           ↑ server crashes here
+           ↓ entire pipeline reruns from scratch
+           ↓ customer gets duplicate email
+
+With durable execution:
+  step("fetch")   ✓ saved
+  step("process") ✓ saved
+  step("save")    ← server crashes here
+  step("save")    ← retries ONLY this step
+  step("email")   ✓ runs once
+```
+
+---
+
+## Platform Decision Matrix
+
+| Factor | Inngest | Temporal | BullMQ |
+|--------|---------|----------|--------|
+| **Complexity** | Low (serverless functions) | High (workers + server) | Medium (Redis-backed) |
+| **Durability** | Steps checkpointed | Full workflow replay | Job-level retry |
+| **Infrastructure** | Managed or self-hosted | Requires Temporal Server | Requires Redis |
+| **Best for** | Serverless, event-driven | Complex orchestration | Simple job queues |
+| **Learning curve** | 1-2 days | 1-2 weeks | 1-2 days |
+| **Language support** | TS, Python, Go | TS, Go, Java, Python, .NET | TS/JS only |
+
+### Decision Rules
+
+1. **Serverless + event-driven?** → Inngest
+2. **Complex orchestration, human-in-the-loop, multi-day?** → Temporal
+3. **Simple job queue, Redis already in stack?** → BullMQ
+4. **Team of 1-3, shipping fast?** → Inngest
+5. **Enterprise, compliance-heavy, Java/.NET stack?** → Temporal
+
+---
+
+## Pattern 1: Sequential Steps
+
+Each step depends on the previous result. Steps checkpoint independently.
+
+```
+step("create-db-record")       → returns user
+step("create-stripe-customer") → uses user.email
+step("send-welcome-email")     → uses user.email
+```
+
+If step 2 fails, only step 2 retries. Steps 1 and 3 are not re-executed.
+
+---
+
+## Pattern 2: Fan-Out (Parallel Execution)
+
+One event triggers multiple independent workflows. Each runs and retries independently.
+
+```
+Event: user/signup.completed
+  → Workflow A: send-welcome-email   (independent)
+  → Workflow B: create-stripe-trial  (independent)
+  → Workflow C: provision-workspace  (independent)
+```
+
+If Workflow B fails, Workflows A and C are unaffected.
+
+---
+
+## Pattern 3: Idempotency
+
+Prevent duplicate execution when the same event fires twice.
+
+**Rule:** Idempotency at the workflow level AND the external call level. Belt and suspenders.
+
+- **Workflow level:** Deduplicate by event ID or business key (e.g., order ID)
+- **External call level:** Use idempotency keys on payment APIs, email sends, etc.
+
+---
+
+## Pattern 4: Scheduled/Recurring
+
+Cron-triggered workflows with observability:
+- Scheduled trigger (e.g., daily at 9am)
+- Steps checkpoint independently
+- Failed runs are visible, retriable, and alertable
+
+---
+
+## Pattern 5: Human-in-the-Loop
+
+Workflows that pause and wait for external input — approval flows, multi-day processes.
+
+```
+workflow: purchaseWorkflow(amount)
+  if amount > threshold:
+    pause and wait for approval signal (up to 72h)
+    if no approval → deny
+  continue with purchase
+```
+
+---
+
+## Sharp Edges
+
+| Issue | Severity | Rule |
+|-------|----------|------|
+| No idempotency keys on external calls | Critical | ALWAYS use idempotency keys for payments, emails, mutations |
+| Side effects in workflow code (Temporal) | Critical | Workflows must be deterministic — no I/O, no random, no clock |
+| Giant payloads in step results | High | Steps serialize data — keep under 256KB |
+| No timeouts on activities | High | ALWAYS set timeouts — default infinite hangs forever |
+| Linear retry without backoff | Medium | ALWAYS use exponential backoff |
+| Missing dead letter handling | High | Failed-after-all-retries jobs need a destination |
+| Monolithic workflows | Medium | Break workflows >10 steps into child workflows |
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| `setTimeout(fn, 3600000)` for delays | Platform sleep — survives restarts |
+| Global variables for workflow state | Step results and explicit state passing |
+| Retry loops in application code | Platform-level retry policies |
+| Polling in a loop for completion | Event-driven triggers or workflow signals |
+| One giant function with all logic | Decompose into steps/activities |
+
+## Related Skills
+
+Works with: `error-handling-patterns`, `deployment-procedures`

package/template/.claude/skills/workflow-automation/references/inngest.md

@@ -0,0 +1,88 @@
+# Inngest Workflow Patterns
+
+Ecosystem-specific patterns for the `workflow-automation` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Sequential Steps
+
+```typescript
+const syncUser = inngest.createFunction(
+  { id: "sync-user-data" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    const user = await step.run("create-db-record", async () => {
+      return db.users.create({ email: event.data.email });
+    });
+
+    const stripeCustomer = await step.run("create-stripe-customer", async () => {
+      return stripe.customers.create({ email: user.email });
+    });
+
+    await step.run("send-welcome-email", async () => {
+      return email.send({ to: user.email, template: "welcome" });
+    });
+  }
+);
+```
+
+## Fan-Out
+
+```typescript
+// Each function subscribes to the same event — runs independently
+const sendWelcome = inngest.createFunction(
+  { id: "send-welcome-email" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    await step.run("send", async () => {
+      await email.send({ to: event.data.email, template: "welcome" });
+    });
+  }
+);
+
+const startTrial = inngest.createFunction(
+  { id: "start-stripe-trial" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    await step.run("create-trial", async () => {
+      await stripe.subscriptions.create({
+        customer: event.data.stripeId,
+        trial_period_days: 14,
+      });
+    });
+  }
+);
+```
+
+## Idempotency
+
+```typescript
+const processPayment = inngest.createFunction(
+  {
+    id: "process-payment",
+    idempotency: "event.data.orderId", // Dedup within 24h
+  },
+  { event: "order/payment.requested" },
+  async ({ event, step }) => {
+    await step.run("charge", async () => {
+      return stripe.charges.create({
+        amount: event.data.amount,
+        idempotencyKey: event.data.orderId, // Stripe-level too
+      });
+    });
+  }
+);
+```
+
+## Scheduled/Recurring
+
+```typescript
+const dailyReport = inngest.createFunction(
+  { id: "daily-metrics-report" },
+  { cron: "0 9 * * *" }, // 9am daily
+  async ({ step }) => {
+    const metrics = await step.run("fetch-metrics", fetchDailyMetrics);
+    await step.run("send-report", async () => sendSlackReport(metrics));
+  }
+);
+```