agent-skill-kit 3.9.135

package/.agent/skills/nextjs-pro/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: nextjs-pro
+description: >-
+  Next.js App Router patterns, Server Components, data fetching, routing, and caching.
+  Use when working with Next.js projects, SSR/SSG/ISR, App Router files, or server actions.
+  NOT for plain React SPA (use react-pro) or CSS styling (use tailwind-kit).
+category: frontend-architect
+triggers: ["Next.js", "App Router", "RSC", "React", "frontend", "SSR"]
+coordinates_with: ["react-architect", "tailwind-kit", "perf-optimizer", "problem-checker", "code-craft"]
+success_metrics: ["100% CWV Targets Met", "0 Server/Client Boundaries Errors", "0 IDE/Lint Errors"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Next.js Pro — App Router & React Performance
+
+> Server-first. 3 data strategies. 4 route files. 57 rules. 8 categories. CWV targets.
+
+**Philosophy:** Performance is a feature. Waterfalls are the enemy. Server first.
+
+---
+
+## 5 Must-Ask Questions (Before Any Development)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Rendering Strategy? | SSR, SSG, ISR, CSR |
+| 2 | Data Volatility? | Static, Periodic, Real-time |
+| 3 | Authentication? | Middleware, Server Actions, Client |
+| 4 | SEO/Metadata? | Dynamic metadata, sitemap |
+| 5 | Interactivity Level? | Mostly static vs Highly interactive |
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Building React frontend | Use App Router patterns |
+| Server vs Client decision | Use component decision tree |
+| Data fetching strategy | Route by volatility |
+| Performance patterns | Read rules/ by category |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Server/Client component decision | React architecture (→ react-architect) |
+| Data fetching strategy (3 options) | CSS/styling (→ tailwind-kit) |
+| Routing conventions (4 files) | Design system (→ design-system) |
+| 57 performance rules (8 categories) | Performance profiling (→ perf-optimizer) |
+
+**Expert decision skill:** Produces patterns and rule references. Does not write code.
+
+---
+
+## Server vs Client Decision (Binary)
+
+```
+Need useState / useEffect / event handlers?
+├── YES → 'use client'
+└── NO  → Server Component (default, no directive)
+```
+
+| Type | Use For |
+|------|---------|
+| **Server** | Data fetching, layouts, static content |
+| **Client** | Forms, buttons, interactive UI |
+
+---
+
+## Data Fetching (3 Strategies — Fixed)
+
+| Volatility | Strategy | Cache Config | Use Case |
+|-----------|----------|-------------|----------|
+| Static | Default | `cache: 'force-cache'` | Content pages |
+| Periodic | ISR | `revalidate: 60` | Dynamic but cacheable |
+| Real-time | Dynamic | `cache: 'no-store'` | Live data |
+
+---
+
+## Route Conventions (4 Files — Fixed)
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `page.tsx` | Route UI | Yes |
+| `layout.tsx` | Shared layout | Yes (root) |
+| `loading.tsx` | Loading state (Suspense) | Recommended |
+| `error.tsx` | Error boundary | Recommended |
+
+---
+
+## Core Web Vitals Targets (Fixed)
+
+| Metric | Target |
+|--------|--------|
+| LCP | < 2,500 ms |
+| INP | < 200 ms |
+| CLS | < 0.1 |
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `architecture_decision` | `{"component_type": "server|client", "reason": "..."}` | `INFO` |
+| `data_fetching_audit` | `{"strategy": "static|isr|dynamic", "volatility": "..."}` | `INFO` |
+| `build_verification` | `{"status": "pass|fail", "cwv_metrics_met": true}` | `INFO` |
+
+All executions MUST emit the `build_verification` span before reporting completion.
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_UNKNOWN_CATEGORY` | Yes | Rule category not one of 8 |
+| `ERR_INVALID_VOLATILITY` | Yes | Data volatility not recognized |
+
+**Zero internal retries.** Deterministic; same context = same pattern.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `'use client'` everywhere | Server Component by default |
+| Fetch data in Client Components | Fetch in Server Components |
+| Barrel imports (`index.js`) | Direct imports |
+| Nested awaits (waterfall) | `Promise.all()` (parallel) |
+| Skip loading/error states | Use loading.tsx + error.tsx |
+| Ignore IDE warnings/errors | Call `problem-checker` to auto-fix |
+
+
+## 📑 Content Map
+
+| Category | Files | Focus | When to Read |
+|----------|-------|-------|--------------|
+| `rules/async-*.md` | 5 | Waterfalls, parallel fetch | Data fetching |
+| `rules/bundle-*.md` | 5 | Tree-shaking, lazy loading | Bundle size |
+| `rules/server-*.md` | 7 | RSC, caching, actions | Server Components |
+| `rules/client-*.md` | 4 | Events, SWR, localStorage | Client Components |
+| `rules/rendering-*.md` | 9 | Hydration, transitions | Rendering issues |
+| `rules/rerender-*.md` | 12 | Memo, state, effects | Re-render prevention |
+| `rules/js-*.md` | 12 | Micro-patterns | JS performance |
+| `rules/advanced-*.md` | 3 | Event refs, init-once, useLatest | Advanced patterns |
+| `rules/_*.md, schema.json` | 3 | Section catalog, template, schema | Rule authoring |
+| [engineering-spec.md](rules/engineering-spec.md) | 1 | Full engineering spec | Architecture review |
+
+**Selective reading:** Read ONLY the category relevant to current task.
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `react-architect` | Skill | React patterns |
+| `tailwind-kit` | Skill | Styling |
+| `perf-optimizer` | Skill | Performance profiling |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/_sections.md

@@ -0,0 +1,50 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/advanced-event-handler-refs.md

@@ -0,0 +1,59 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/advanced-init-once.md

@@ -0,0 +1,46 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/advanced-use-latest.md

@@ -0,0 +1,43 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/async-api-routes.md

@@ -0,0 +1,42 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/async-defer-await.md

@@ -0,0 +1,84 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/async-dependencies.md

@@ -0,0 +1,55 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nextjs-pro/rules/async-parallel.md

@@ -0,0 +1,32 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+---
+
+⚡ PikaKit v3.9.134