@pageai/ralph-loop 1.0.0

package/.agent/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md

@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

package/.agent/skills/vercel-react-best-practices/rules/rerender-memo.md

@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.

package/.agent/skills/vercel-react-best-practices/rules/rerender-transitions.md

@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```

package/.agent/skills/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

package/.agent/skills/vercel-react-best-practices/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/.agent/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,26 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.

package/.agent/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,79 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Layout({ children }: { children: ReactNode }) {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      {children}
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/.agent/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/.agent/skills/vitest-best-practices/AGENTS.md

@@ -0,0 +1,84 @@
+# Vitest Best Practices
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring vitest tests. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive guide for testing with `vitest`, designed for AI agents and LLMs. Each rule includes one-line summaries here, with links to detailed examples in the `references/` folder. Load reference files only when you need detailed implementation guidance for a specific rule.
+
+Use the `vitest` testing framework. Design tests to be short, simple, flat, and instantly understandable.
+
+---
+
+## How to Use This Guide
+
+1. **Start here**: Scan the rule summaries to identify relevant patterns
+2. **Load references as needed**: Click through to detailed examples only when implementing
+3. **Progressive loading**: Each reference file is self-contained with examples
+
+This structure minimizes context usage while providing complete implementation guidance when needed.
+
+---
+
+## General Test Structure
+
+Use `it()` with sentence-style descriptions:
+
+**✅ Correct: appropriate structure**
+```ts
+describe('ProductsService', () => {
+  describe('Add new product', () => {
+    it('should have status "pending approval" when no price is specified', () => {
+      const newProduct = new ProductService().add(/*...*/);
+      expect(newProduct.status).toEqual('pendingApproval');
+    });
+  });
+});
+```
+
+---
+
+## 1. General
+
+### 1.1 Organization
+Place test files next to implementation; one test file per module.
+[View detailed examples](references/organization.md)
+
+### 1.2 AAA Pattern
+Structure tests as Arrange, Act, Assert for clarity.
+[View detailed examples](references/aaa-pattern.md)
+
+### 1.3 Parameterized Tests
+Use `it.each` for variations; one behavior per test.
+[View detailed examples](references/parameterized-tests.md)
+
+### 1.4 Error Handling
+Test negative cases, fault injection, and recovery thoroughly.
+[View detailed examples](references/error-handling.md)
+
+### 1.5 Assertions
+Use strict assertions (`toEqual`, `toStrictEqual`) over loose ones.
+[View detailed examples](references/assertions.md)
+
+### 1.6 Test Doubles
+Prefer fakes > stubs > spies/mocks; avoid over-mocking.
+[View detailed examples](references/test-doubles.md)
+
+### 1.7 Async Testing
+Test promises, async/await, and timers correctly.
+[View detailed examples](references/async-testing.md)
+
+### 1.8 Performance
+Keep tests fast through efficient setup and avoiding expensive operations.
+[View detailed examples](references/performance.md)
+
+### 1.9 Vitest Features
+Use coverage, watch mode, benchmarking, and other vitest-specific features.
+[View detailed examples](references/vitest-features.md)
+
+### 1.10 Snapshot Testing
+Use snapshots for appropriate cases; avoid common pitfalls.
+[View detailed examples](references/snapshot-testing.md)

package/.agent/skills/vitest-best-practices/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: vitest-best-practices
+description: Comprehensive vitest testing patterns covering test structure, AAA pattern, parameterized tests, assertions, mocking, test doubles, error handling, async testing, and performance optimization. Use when writing, reviewing, or refactoring vitest tests, or when user mentions vitest, testing, TDD, test coverage, mocking, assertions, or test files (*.test.ts, *.spec.ts).
+compatibility: Requires vitest testing framework
+---
+
+# Vitest Best Practices
+
+## When to Apply This Skill
+
+Use this skill when you encounter any of these scenarios:
+
+### File Patterns
+
+- Working with `*.test.ts`, `*.spec.ts`, or similar test files
+- Creating new test files for TypeScript/JavaScript modules
+- Reviewing existing vitest test suites
+
+### User Intent Keywords
+
+- User mentions: vitest, testing, TDD, BDD, unit tests, integration tests
+- User asks to: write tests, add test coverage, fix failing tests, refactor tests
+- User discusses: mocking, stubbing, assertions, test performance, test organization
+
+### Code Context
+
+- Files importing from `vitest` (`describe`, `it`, `expect`, `vi`)
+- Test setup/teardown code (`beforeEach`, `afterEach`, `beforeAll`, `afterAll`)
+- Mock/spy implementations using `vi.mock()`, `vi.spyOn()`, `vi.fn()`
+- Assertion chains (`expect(...).toEqual()`, `.toBe()`, `.toThrow()`, etc.)
+
+### Common Tasks
+
+- Writing new test cases for existing functionality
+- Refactoring tests for better clarity or performance
+- Debugging flaky or failing tests
+- Improving test coverage or maintainability
+- Reviewing test code for best practices compliance
+
+## Do NOT Use This Skill When
+
+- Writing end-to-end tests with Playwright/Cypress (different scope)
+- The task is purely about implementation code, not tests
+
+## What This Skill Covers
+
+This skill provides comprehensive guidance on:
+
+1. **Test Organization**: File placement, naming conventions, grouping strategies
+2. **AAA Pattern**: Arrange, Act, Assert structure for clarity
+3. **Parameterized Tests**: Using `it.each()` for testing variations
+4. **Error Handling**: Testing exceptions, edge cases, and fault injection
+5. **Assertions**: Choosing strict assertions (`toEqual`, `toStrictEqual`, `toThrow`)
+6. **Test Doubles**: Fakes, stubs, mocks, spies - when to use each
+7. **Async Testing**: Promises, async/await, timers, and concurrent tests
+8. **Performance**: Fast tests, avoiding expensive operations, cleanup patterns
+9. **Vitest-Specific Features**: Coverage, watch mode, benchmarking, type testing, setup files
+10. **Snapshot Testing**: When and how to use snapshots effectively
+
+## How to Use
+
+This skill uses a **progressive disclosure** structure to minimize context usage:
+
+### 1. Start with the Overview (AGENTS.md)
+
+Read [AGENTS.md](AGENTS.md) for a concise overview of all rules with one-line summaries.
+
+### 2. Load Specific Rules as Needed
+
+When you identify a relevant optimization, load the corresponding reference file for detailed implementation guidance:
+
+**Core Patterns:**
+- [organization.md](references/organization.md)
+- [aaa-pattern.md](references/aaa-pattern.md)
+- [parameterized-tests.md](references/parameterized-tests.md)
+- [error-handling.md](references/error-handling.md)
+- [assertions.md](references/assertions.md)
+- [test-doubles.md](references/test-doubles.md)
+
+**Advanced Topics:**
+- [async-testing.md](references/async-testing.md)
+- [performance.md](references/performance.md)
+- [vitest-features.md](references/vitest-features.md)
+- [snapshot-testing.md](references/snapshot-testing.md)
+
+### 3. Apply the Pattern
+
+Each reference file contains:
+- ❌ Incorrect examples showing the anti-pattern
+- ✅ Correct examples showing the optimal implementation
+- Explanations of why the pattern matters
+
+## Quick Example
+
+This skill helps you transform unclear tests into clear, maintainable ones:
+
+**Before (unclear):**
+```ts
+test('product test', () => {
+  const p = new ProductService().add({name: 'Widget'});
+  expect(p.status).toBe('pendingApproval');
+});
+```
+
+**After (optimized with this skill):**
+```ts
+describe('ProductService', () => {
+  describe('Add new product', () => {
+    it('should have status "pending approval" when no price is specified', () => {
+      // Arrange
+      const productService = new ProductService();
+
+      // Act
+      const newProduct = productService.add({name: 'Widget'});
+
+      // Assert
+      expect(newProduct.status).toEqual('pendingApproval');
+    });
+  });
+});
+```
+
+## Key Principles
+
+- **Clarity over cleverness**: Tests should be instantly understandable
+- **Flat structure**: Avoid deep nesting in describe blocks
+- **One assertion per concept**: Focus tests on single behaviors
+- **Strict assertions**: Prefer `toEqual` over `toBe`, `toStrictEqual` when needed
+- **Minimal mocking**: Use real implementations when practical
+- **Fast execution**: Keep tests quick through efficient setup/teardown