@kood/claude-code 0.3.11 → 0.3.14

package/templates/.claude/skills/tanstack-start-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/templates/.claude/skills/tanstack-start-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/templates/.claude/skills/tanstack-start-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/templates/.claude/skills/tanstack-start-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/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-deferred-data.md

@@ -0,0 +1,67 @@
+---
+title: Use Deferred Data for Non-Critical Content
+impact: HIGH
+impactDescription: faster initial page render
+tags: server, streaming, suspense, deferred-data, ux
+---
+
+## Use Deferred Data for Non-Critical Content
+
+Load critical data with `await`, but return non-critical data as Promises for streaming. This allows the page to render immediately while slow queries complete in the background.
+
+**Incorrect (blocks on slow query):**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { getPost, getComments } from '@/functions/data'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    const post = await getPost(params.postId) // Fast: 50ms
+    const comments = await getComments(params.postId) // Slow: 3s
+    return { post, comments }
+  }
+})
+// Total wait: 3.05s before page renders
+```
+
+**Correct (stream slow data):**
+
+```typescript
+import { createFileRoute, Await } from '@tanstack/react-router'
+import { getPost, getComments } from '@/functions/data'
+import { Suspense } from 'react'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    // Critical: await immediately
+    const post = await getPost(params.postId)
+
+    // Non-critical: return Promise (don't await)
+    const deferredComments = getComments(params.postId)
+
+    return { post, deferredComments }
+  },
+  component: PostPage
+})
+
+function PostPage() {
+  const { post, deferredComments } = Route.useLoaderData()
+
+  return (
+    <div>
+      <PostContent post={post} /> {/* Renders immediately */}
+
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Await promise={deferredComments}>
+          {(comments) => <Comments comments={comments} />}
+        </Await>
+      </Suspense>
+    </div>
+  )
+}
+```
+
+Page renders in 50ms instead of 3s. Comments stream in when ready. Use for: analytics, recommendations, user activity, social features.
+
+Reference: [TanStack Router Deferred Data Loading](https://tanstack.com/router/v1/docs/framework/react/guide/deferred-data-loading)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,60 @@
+---
+title: Restructure Components for Parallel Server Function Calls
+impact: HIGH
+impactDescription: eliminates component-level waterfalls
+tags: server, parallelization, architecture, server-functions
+---
+
+## Restructure Components for Parallel Server Function Calls
+
+Avoid nested component structures that force sequential server function calls. Move data fetching to parent loader when possible.
+
+**Incorrect (sequential: User → Posts → Comments):**
+
+```tsx
+// routes/dashboard.tsx
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => ({ user: await getUser() }),
+  component: Dashboard
+})
+
+function Dashboard() {
+  const { user } = Route.useLoaderData()
+  return <UserPosts userId={user.id} />
+}
+
+// components/UserPosts.tsx
+function UserPosts({ userId }) {
+  const posts = await getPosts(userId) // Blocks until loaded
+  return posts.map(p => <PostComments postId={p.id} />)
+}
+
+function PostComments({ postId }) {
+  const comments = await getComments(postId) // Sequential waterfall
+  return <CommentList comments={comments} />
+}
+```
+
+**Correct (parallel fetching in loader):**
+
+```tsx
+// routes/dashboard.tsx
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const user = await getUser()
+    const [posts, comments] = await Promise.all([
+      getPosts(user.id),
+      getComments(user.id)
+    ])
+    return { user, posts, comments }
+  },
+  component: Dashboard
+})
+
+function Dashboard() {
+  const { user, posts, comments } = Route.useLoaderData()
+  return <PostList posts={posts} comments={comments} />
+}
+```
+
+Centralizing data fetching in the loader reduces waterfalls and enables parallel execution.

package/templates/.claude/skills/tanstack-start-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/templates/.claude/skills/vs-design-diverge/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: vs-design-diverge
+description: Create high-entropy frontend interfaces using Verbalized Sampling (VS). Break mode collapse, avoid AI-slop aesthetics. Use for distinctive design work.
+---
+
+<context>
+
+**Purpose:** Mitigate Mode Collapse (tendency to produce generic AI output) and create production-grade frontend interfaces
+
+**Principle:** Verbalized Sampling (VS) - Verbalize typical design (P ≈ 0.95), then deliberately select Low-T (low typicality) alternatives
+
+</context>
+
+---
+
+<workflow>
+
+## Execution Flow
+
+```
+Phase 0: Context Discovery
+  ↓ (AskUserQuestion - probe 4 dimensions)
+Phase 1: Identify the Mode
+  ↓ (verbalize P ≈ 0.95 baseline, avoid it)
+Phase 2: Sample the Long-Tail
+  ↓ (3 directions + T-Score justification)
+Phase 3: Commit to Low-Typicality
+  ↓ (lowest T-Score + pass Guardrails)
+Phase 4: Implementation
+  ↓ (production-grade code)
+Phase 5: Surprise Validation
+  ↓ (AI-typical? → refactor)
+```
+
+### Phase 0: Context Discovery
+
+**Probe these dimensions using AskUserQuestion tool:**
+
+| Dimension | Question Examples |
+|-----------|-------------------|
+| **Emotional Tone** | "Trustworthy", "edgy", "playful", "luxurious" - which atmosphere? |
+| **Target Audience** | Who will see this? Technical sophistication? Expectations? |
+| **Reference Points / Anti-References** | Benchmark examples? Styles to explicitly avoid? |
+| **Business Context** | Problem this UI solves? Usage scenario? |
+
+**Additional signals:**
+- Existing code: Extract style patterns, color schemes, component conventions
+- User prompt: Parse keywords (landing page, dashboard, portfolio, SaaS, etc.)
+- Follow-up questions: Surface full vision even for simple prompts
+
+Gather sufficient context before proceeding to Phase 1.
+
+### Phase 1: Identify the Mode
+
+**Verbalize the highest-probability (P ≈ 0.95) design:**
+
+AI-slop markers:
+- Inter/Roboto/System fonts
+- Rounded blue/purple buttons
+- Standard F-pattern layouts
+- White backgrounds with gradient accents
+- Generic hero sections with stock imagery
+
+**Avoid this baseline.**
+
+### Phase 2: Sample the Long-Tail
+
+**Generate 3 directions with T-Score (Typicality Score, 0~1.0):**
+
+| Direction | T-Score | Characteristics |
+|-----------|---------|-----------------|
+| **A** | ≈ 0.7 | Modern/Clean, safe |
+| **B** | ≈ 0.4 | Distinctive/Characterful (specific niche style) |
+| **C** | < 0.2 | Experimental/Bold (high-entropy, unexpected) |
+
+**T-Score justification required:** Explain WHY each direction has that score. Reference specific design choices.
+
+### Phase 3: Commit to Low-Typicality
+
+**Select lowest T-Score that meets:**
+1. Functional requirements from Phase 0
+2. All Quality Guardrails
+
+Deliberate and intentional choice, not accidental.
+
+</workflow>
+
+---
+
+<guardrails>
+
+## Quality Principles
+
+Experimental designs must satisfy these principles. If violated, increase T-Score until compliance.
+
+| Principle | Description |
+|-----------|-------------|
+| **Visual Hierarchy** | Clear priority ordering (1st → 2nd → 3rd) |
+| **Contrast & Legibility** | Text readable against background (WCAG AA minimum) |
+| **Internal Consistency** | Design follows its own logic (not random) |
+| **Functional Clarity** | Interactive elements recognizable, affordances clear |
+
+</guardrails>
+
+---
+
+<anti_patterns>
+
+## Failure Patterns
+
+| Pattern | Symptoms | Validation |
+|---------|----------|------------|
+| **Accidental Design** | Differentiation without intent, randomness | "Why this color/font/layout?" → must have coherent answer |
+| **Frankenstein Style** | Incompatible aesthetics mixed, no unity | "Describe this design's personality in one sentence?" → must be possible |
+
+</anti_patterns>
+
+---
+
+<aesthetics>
+
+## Frontend Aesthetics Guidelines (VS-Enhanced)
+
+**Inversion Principle:** If a choice feels "obvious," it has too much probability mass → consider lower-probability, higher-impact alternatives (when context-appropriate).
+
+### Typography
+
+| Category | Content |
+|----------|---------|
+| ❌ **AI-slop** | Inter, Roboto, Arial, System fonts, Space Grotesk (default usage) |
+| ✅ **Low-T** | High-character display faces + refined, unexpected body typefaces. Variable fonts, unusual weights. |
+| **Context-dependent** | Brutalist portfolio → industrial sans-serifs / Luxury brand → refined serifs |
+
+### Color & Theme
+
+| Principle | Description |
+|-----------|-------------|
+| ✅ **Uneven distribution** | Cohesive but "dissonant-yet-beautiful" palette |
+| ✅ **CSS Variables** | Systematic theming |
+| ✅ **Texture-first** | Sophisticated noise/lighting over flat fills (when context-appropriate) |
+
+### Spatial Composition
+
+| Condition | Approach |
+|-----------|----------|
+| **Standard grid (P=0.9)** | Consider asymmetry, overlapping elements, diagonal flows, editorial whitespace (P=0.1) |
+| **Data-heavy UIs** | Dashboards, tables → conventional grids may be needed (usability priority) |
+
+### Motion
+
+| Principle | Description |
+|-----------|-------------|
+| ✅ **Micro-delights** | Staggered reveals, scroll-bound transformations, custom easing |
+| ❌ **Purposeless motion** | Every animation must have purpose |
+
+</aesthetics>
+
+---
+
+<frameworks>
+
+## AIDA Framework (Conditional)
+
+**Apply only for persuasion/conversion goals (landing pages, marketing sites, product showcases):**
+
+| Stage | Goal | Design Application |
+|-------|------|-------------------|
+| **A**ttention | Stop scroll, create immediate visual impact | Bold typography, unexpected imagery, striking color contrast |
+| **I**nterest | Build curiosity, encourage exploration | Progressive information reveal, visual storytelling, highlight unique value |
+| **D**esire | Create emotional connection, make them want it | Social proof, benefits visualization, aspirational imagery, micro-interactions |
+| **A**ction | Drive conversion with clear next steps | High-contrast CTAs, reduced friction, urgency cues (when appropriate) |
+
+### Application Conditions
+
+| Apply ✅ | Don't Apply ❌ |
+|---------|----------------|
+| Landing/marketing pages | Dashboards, data-heavy UIs (usability priority) |
+| Product launch pages | Documentation/content-focused sites (readability priority) |
+| Client-attracting portfolios | Internal tools (efficiency priority) |
+
+**VS + AIDA Integration:** Apply Low-T aesthetics to EACH AIDA stage. Generic hero → Attention failure / Predictable CTA → Action failure. AIDA = "what", VS = "how".
+
+</frameworks>
+
+---
+
+<implementation>
+
+## Implementation Standards
+
+| Standard | Description |
+|----------|-------------|
+| **Production-Grade** | Functional, accessible (A11y), performant |
+| **Complexity-Typicality Balance** | Low-T design → implementation complexity increases proportionally (maintain quality) |
+| **No Complexity Refusal** | Pursue extraordinary work, don't simplify vision |
+
+</implementation>
+
+---
+
+<validation>
+
+## Final Validation
+
+Pre-delivery checklist:
+
+1. **Intentionality**: Can you justify every major design decision?
+2. **Consistency**: Does the design follow its own internal logic?
+3. **Guardrails**: Are hierarchy, legibility, consistency, and clarity preserved?
+4. **Surprise**: Would this stand out in a lineup of AI-generated designs?
+
+**Goal:** Maximize "Surprise Score" while maintaining "Production Quality." Deliberate disruption.
+
+</validation>
+
+---
+
+<examples>
+
+## Practical Examples
+
+### Phase 2: T-Score Justification
+
+```markdown
+**Direction A (T ≈ 0.7): Modern Minimal**
+- Inter font, white background, blue buttons
+- High typicality: 2020s SaaS standard pattern
+
+**Direction B (T ≈ 0.4): Brutalist Style**
+- Space Mono font, grid background, angular black buttons
+- Lower typicality: Specific niche, non-mainstream choice
+
+**Direction C (T < 0.2): Neo-Baroque**
+- Fraunces Display font, irregular layout, animated gradients
+- Very low probability: Rarely seen on web
+```
+
+### Typography Code
+
+```css
+/* ❌ AI-slop */
+font-family: 'Inter', system-ui, sans-serif;
+
+/* ✅ Low-T (Brutalist portfolio) */
+@import url('https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&display=swap');
+font-family: 'Space Mono', monospace;
+font-variation-settings: 'wght' 650;
+
+/* ✅ Low-T (Luxury brand) */
+@import url('https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@300;500&display=swap');
+font-family: 'Cormorant Garamond', serif;
+letter-spacing: 0.05em;
+```
+
+### Color System
+
+```css
+/* ❌ AI-slop (even distribution) */
+:root {
+  --primary: #3b82f6; /* blue */
+  --secondary: #a855f7; /* purple */
+  --accent: #10b981; /* green */
+}
+
+/* ✅ Low-T (uneven, cohesive) */
+:root {
+  --dominant: #0a0908; /* near-black (60%) */
+  --support: #8d99ae; /* neutral blue (30%) */
+  --punch: #ef233c; /* intense red (10%) */
+  --texture: url('data:image/svg+xml,...'); /* noise overlay */
+}
+```
+
+### AIDA + Low-T Integration
+
+```tsx
+// Hero Section (Attention stage + Low-T)
+<section className="hero">
+  <h1 style={{
+    fontFamily: 'Fraunces',
+    fontSize: 'clamp(3rem, 10vw, 8rem)',
+    fontVariationSettings: '"SOFT" 100, "WONK" 1',
+    background: 'linear-gradient(135deg, #0a0908, #ef233c)',
+    backgroundClip: 'text',
+    WebkitTextFillColor: 'transparent',
+  }}>
+    Disruptive Product Name
+  </h1>
+  {/* Unexpected imagery treatment */}
+</section>
+
+// CTA (Action stage + Low-T)
+<button style={{
+  background: '#ef233c',
+  color: '#0a0908',
+  border: '2px solid #0a0908',
+  padding: '1.5rem 3rem',
+  fontSize: '1.25rem',
+  fontWeight: 700,
+  clipPath: 'polygon(5% 0, 100% 0, 95% 100%, 0 100%)', // asymmetric
+  transition: 'clip-path 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+}}>
+  Get Started →
+</button>
+```
+
+</examples>