@vpxa/aikit 0.1.54 → 0.1.56

package/scaffold/general/skills/react/SKILL.md

@@ -1,309 +1,309 @@
----
-name: react
-description: "Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization."
-metadata:
-  category: domain
-  domain: react
-  applicability: on-demand
-  inputs: [codebase, requirements]
-  outputs: [component-patterns, code]
-  relatedSkills: [typescript, frontend-design]
----
-
-# React
-
-> Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization. Synthesized from react-dev patterns, react-patterns (React 19), and Vercel React best practices.
-
-## When to Use
-
-**MANDATORY** for the Frontend agent on every React task. Also use when:
-- Building React components, hooks, or pages
-- Working with Server Components or Server Actions
-- Optimizing React performance (re-renders, bundle size, data fetching)
-- Reviewing React code for correctness and best practices
-
-## React 19 Quick Reference
-
-| API | Use Case | Key Change |
-|-----|----------|------------|
-| `ref` as prop | Access DOM/component instance | No more `forwardRef` wrapper |
-| `use()` | Read promises/context in render | Replaces `useContext`, enables async |
-| `useActionState` | Form submission state + error | Replaces `useFormState` |
-| `useOptimistic` | Instant UI feedback | Optimistic updates before server confirms |
-| `useTransition` | Non-urgent state updates | `isPending` for loading states |
-| `<form action>` | Server Actions in forms | Direct server function binding |
-| Server Components | Zero-bundle components | Default in App Router, no `"use client"` |
-| Server Actions | Server mutations | `"use server"` functions, form actions |
-
-## Component Patterns
-
-### Extend Native Elements
-```tsx
-type ButtonProps = React.ComponentProps<"button"> & {
-  variant?: "primary" | "secondary" | "ghost";
-  size?: "sm" | "md" | "lg";
-};
-
-function Button({ variant = "primary", size = "md", className, ...props }: ButtonProps) {
-  return <button className={cn(variants[variant], sizes[size], className)} {...props} />;
-}
-```
-
-### Discriminated Union Props
-```tsx
-type ModalProps =
-  | { variant: "alert"; message: string; onConfirm: () => void }
-  | { variant: "form"; children: React.ReactNode; onSubmit: (data: FormData) => void };
-
-function Modal(props: ModalProps) {
-  switch (props.variant) {
-    case "alert": return <AlertModal {...props} />;
-    case "form": return <FormModal {...props} />;
-  }
-}
-```
-
-### Generic Components
-```tsx
-type TableProps<T> = {
-  data: T[];
-  columns: { key: keyof T; header: string; render?: (value: T[keyof T], row: T) => React.ReactNode }[];
-  onRowClick?: (row: T) => void;
-};
-
-function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }: TableProps<T>) {
-  // ...
-}
-```
-
-### Children Typing
-```tsx
-// Specific children
-type Props = { children: React.ReactElement<TabProps>[] };
-
-// Render function children
-type Props = { children: (data: T) => React.ReactNode };
-
-// String only
-type Props = { children: string };
-```
-
-## Ref as Prop (React 19)
-
-```tsx
-// React 19: pass ref directly, no forwardRef needed
-function Input({ ref, ...props }: React.ComponentProps<"input">) {
-  return <input ref={ref} {...props} />;
-}
-
-// Cleanup function (new in React 19)
-function MeasuredDiv({ ref, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      ref={(node) => {
-        if (node) measureElement(node);
-        return () => cleanupMeasurement(); // cleanup on unmount
-      }}
-      {...props}
-    />
-  );
-}
-```
-
-## Server Components & Actions
-
-### Server Component (default — no directive needed)
-```tsx
-// app/users/page.tsx — Server Component (default)
-import { db } from "@/lib/db";
-
-export default async function UsersPage() {
-  const users = await db.query.users.findMany();  // Direct DB access
-  return <UserList users={users} />;  // Pass data to client
-}
-```
-
-### Client Component (explicit opt-in)
-```tsx
-"use client";
-import { useState, useOptimistic, useTransition } from "react";
-
-export function Counter({ initialCount }: { initialCount: number }) {
-  const [count, setCount] = useState(initialCount);
-  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
-}
-```
-
-### Server Action with Form
-```tsx
-// actions.ts
-"use server";
-import { z } from "zod";
-
-const schema = z.object({ name: z.string().min(1), email: z.string().email() });
-
-export async function createUser(_prev: unknown, formData: FormData) {
-  const result = schema.safeParse(Object.fromEntries(formData));
-  if (!result.success) return { error: result.error.flatten().fieldErrors };
-  await db.insert(users).values(result.data);
-  return { success: true };
-}
-```
-
-```tsx
-"use client";
-import { useActionState } from "react";
-import { createUser } from "./actions";
-
-export function CreateUserForm() {
-  const [state, action, isPending] = useActionState(createUser, null);
-  return (
-    <form action={action}>
-      <input name="name" required />
-      {state?.error?.name && <p className="text-red-500">{state.error.name}</p>}
-      <input name="email" type="email" required />
-      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}
-      <button disabled={isPending}>{isPending ? "Creating..." : "Create"}</button>
-    </form>
-  );
-}
-```
-
-### Optimistic Updates
-```tsx
-"use client";
-import { useOptimistic } from "react";
-
-function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) => Promise<void> }) {
-  const [optimisticTodos, addOptimistic] = useOptimistic(
-    todos,
-    (state, newTodo: string) => [...state, { id: "temp", text: newTodo, pending: true }]
-  );
-
-  async function handleAdd(formData: FormData) {
-    const text = formData.get("text") as string;
-    addOptimistic(text);
-    await addTodo(text);
-  }
-
-  return (
-    <form action={handleAdd}>
-      <input name="text" />
-      <button type="submit">Add</button>
-      <ul>
-        {optimisticTodos.map(t => (
-          <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}</li>
-        ))}
-      </ul>
-    </form>
-  );
-}
-```
-
-## Event Handler Types
-
-```tsx
-// Always use specific event types
-onClick:    (e: React.MouseEvent<HTMLButtonElement>) => void
-onChange:   (e: React.ChangeEvent<HTMLInputElement>) => void
-onSubmit:   (e: React.FormEvent<HTMLFormElement>) => void
-onKeyDown:  (e: React.KeyboardEvent<HTMLInputElement>) => void
-onFocus:    (e: React.FocusEvent<HTMLInputElement>) => void
-onDrag:     (e: React.DragEvent<HTMLDivElement>) => void
-```
-
-## Hooks Typing
-
-```tsx
-// useState with union
-const [status, setStatus] = useState<"idle" | "loading" | "error">("idle");
-
-// useRef for DOM — pass null, get RefObject
-const inputRef = useRef<HTMLInputElement>(null);
-
-// useRef for mutable value — no null, get MutableRefObject
-const intervalRef = useRef<number>(0);
-
-// useReducer with discriminated actions
-type Action = { type: "increment" } | { type: "set"; payload: number };
-const [count, dispatch] = useReducer((state: number, action: Action) => {
-  switch (action.type) {
-    case "increment": return state + 1;
-    case "set": return action.payload;
-  }
-}, 0);
-
-// Custom hook: return as const for tuple types
-function useToggle(initial = false) {
-  const [value, setValue] = useState(initial);
-  const toggle = useCallback(() => setValue(v => !v), []);
-  return [value, toggle] as const;
-}
-
-// useContext with null guard
-const ctx = useContext(ThemeContext);
-if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
-```
-
-## Performance Rules
-
-### Prevent Async Waterfalls
-```tsx
-// BAD — sequential fetching
-const user = await getUser(id);
-const posts = await getPosts(user.id);  // Waits for user first
-const comments = await getComments(posts[0].id);  // Waits for posts
-
-// GOOD — parallel where possible
-const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
-```
-
-### Bundle Size
-- `dynamic(() => import("./HeavyComponent"))` — lazy load below-fold components
-- Tree-shake: use named exports, avoid `import *`
-- Analyze bundle: `@next/bundle-analyzer` to find bloat
-- Code-split by route — each page loads only its own JS
-- Avoid importing entire libraries: `import { debounce } from "lodash-es"` not `import _ from "lodash"`
-
-### Server-Side Performance
-- Default to Server Components — zero JS shipped to client
-- Stream with Suspense: wrap slow data fetchers in `<Suspense fallback={<Skeleton />}>`
-- Cache expensive computations with `"use cache"` directive
-- Avoid serializing large objects across server/client boundary
-
-### Client-Side Data Fetching
-- Use SWR or React Query — automatic caching, revalidation, error retry
-- Stale-while-revalidate: show cached data instantly, refresh in background
-- Error boundaries: `<ErrorBoundary>` wrapping data-dependent trees
-- Prefetch on hover/viewport for likely next navigations
-
-### Re-render Optimization
-- React Compiler (React 19): auto-memoizes — try this first before manual `useMemo`/`useCallback`
-- If no compiler: `useMemo` for expensive computations, `useCallback` for stable function references
-- Extract static JSX outside components — constants don't re-create
-- Split context: separate frequently-changing state from rarely-changing state
-- `React.memo()` on components receiving only primitive props
-
-### Rendering Performance
-- **Virtualize** lists > 100 items: `@tanstack/react-virtual`, `react-window`
-- Defer heavy computations with `useDeferredValue`
-- Batch state updates (React 18+ does this automatically in event handlers)
-- Avoid reading DOM layout during renders (force sync layout = jank)
-
-### Advanced Patterns
-- Progressive hydration: load and hydrate components as they enter viewport
-- Concurrent features: `useTransition` for non-blocking state updates
-- Suspense caching: combine `<Suspense>` with data cache for instant page transitions
-- React Compiler adoption: enable gradually, check for unsafe patterns first
-
-## Decision Flow
-
-When implementing a React feature:
-
-1. **Server or Client?** → If it uses browser APIs, event handlers, or useState → Client. Everything else → Server.
-2. **Data fetching?** → Server Component for initial data. SWR/React Query for client-side mutations.
-3. **Form?** → Server Action + `useActionState` + Zod validation.
-4. **Optimistic?** → `useOptimistic` for instant feedback.
-5. **Loading?** → `<Suspense>` with skeleton fallback.
-6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
-7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.
+---
+name: react
+description: "Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization."
+metadata:
+  category: domain
+  domain: react
+  applicability: on-demand
+  inputs: [codebase, requirements]
+  outputs: [component-patterns, code]
+  relatedSkills: [typescript, frontend-design]
+---
+
+# React
+
+> Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization. Synthesized from react-dev patterns, react-patterns (React 19), and Vercel React best practices.
+
+## When to Use
+
+**MANDATORY** for the Frontend agent on every React task. Also use when:
+- Building React components, hooks, or pages
+- Working with Server Components or Server Actions
+- Optimizing React performance (re-renders, bundle size, data fetching)
+- Reviewing React code for correctness and best practices
+
+## React 19 Quick Reference
+
+| API | Use Case | Key Change |
+|-----|----------|------------|
+| `ref` as prop | Access DOM/component instance | No more `forwardRef` wrapper |
+| `use()` | Read promises/context in render | Replaces `useContext`, enables async |
+| `useActionState` | Form submission state + error | Replaces `useFormState` |
+| `useOptimistic` | Instant UI feedback | Optimistic updates before server confirms |
+| `useTransition` | Non-urgent state updates | `isPending` for loading states |
+| `<form action>` | Server Actions in forms | Direct server function binding |
+| Server Components | Zero-bundle components | Default in App Router, no `"use client"` |
+| Server Actions | Server mutations | `"use server"` functions, form actions |
+
+## Component Patterns
+
+### Extend Native Elements
+```tsx
+type ButtonProps = React.ComponentProps<"button"> & {
+  variant?: "primary" | "secondary" | "ghost";
+  size?: "sm" | "md" | "lg";
+};
+
+function Button({ variant = "primary", size = "md", className, ...props }: ButtonProps) {
+  return <button className={cn(variants[variant], sizes[size], className)} {...props} />;
+}
+```
+
+### Discriminated Union Props
+```tsx
+type ModalProps =
+  | { variant: "alert"; message: string; onConfirm: () => void }
+  | { variant: "form"; children: React.ReactNode; onSubmit: (data: FormData) => void };
+
+function Modal(props: ModalProps) {
+  switch (props.variant) {
+    case "alert": return <AlertModal {...props} />;
+    case "form": return <FormModal {...props} />;
+  }
+}
+```
+
+### Generic Components
+```tsx
+type TableProps<T> = {
+  data: T[];
+  columns: { key: keyof T; header: string; render?: (value: T[keyof T], row: T) => React.ReactNode }[];
+  onRowClick?: (row: T) => void;
+};
+
+function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }: TableProps<T>) {
+  // ...
+}
+```
+
+### Children Typing
+```tsx
+// Specific children
+type Props = { children: React.ReactElement<TabProps>[] };
+
+// Render function children
+type Props = { children: (data: T) => React.ReactNode };
+
+// String only
+type Props = { children: string };
+```
+
+## Ref as Prop (React 19)
+
+```tsx
+// React 19: pass ref directly, no forwardRef needed
+function Input({ ref, ...props }: React.ComponentProps<"input">) {
+  return <input ref={ref} {...props} />;
+}
+
+// Cleanup function (new in React 19)
+function MeasuredDiv({ ref, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      ref={(node) => {
+        if (node) measureElement(node);
+        return () => cleanupMeasurement(); // cleanup on unmount
+      }}
+      {...props}
+    />
+  );
+}
+```
+
+## Server Components & Actions
+
+### Server Component (default — no directive needed)
+```tsx
+// app/users/page.tsx — Server Component (default)
+import { db } from "@/lib/db";
+
+export default async function UsersPage() {
+  const users = await db.query.users.findMany();  // Direct DB access
+  return <UserList users={users} />;  // Pass data to client
+}
+```
+
+### Client Component (explicit opt-in)
+```tsx
+"use client";
+import { useState, useOptimistic, useTransition } from "react";
+
+export function Counter({ initialCount }: { initialCount: number }) {
+  const [count, setCount] = useState(initialCount);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### Server Action with Form
+```tsx
+// actions.ts
+"use server";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string().min(1), email: z.string().email() });
+
+export async function createUser(_prev: unknown, formData: FormData) {
+  const result = schema.safeParse(Object.fromEntries(formData));
+  if (!result.success) return { error: result.error.flatten().fieldErrors };
+  await db.insert(users).values(result.data);
+  return { success: true };
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { createUser } from "./actions";
+
+export function CreateUserForm() {
+  const [state, action, isPending] = useActionState(createUser, null);
+  return (
+    <form action={action}>
+      <input name="name" required />
+      {state?.error?.name && <p className="text-red-500">{state.error.name}</p>}
+      <input name="email" type="email" required />
+      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}
+      <button disabled={isPending}>{isPending ? "Creating..." : "Create"}</button>
+    </form>
+  );
+}
+```
+
+### Optimistic Updates
+```tsx
+"use client";
+import { useOptimistic } from "react";
+
+function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) => Promise<void> }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (state, newTodo: string) => [...state, { id: "temp", text: newTodo, pending: true }]
+  );
+
+  async function handleAdd(formData: FormData) {
+    const text = formData.get("text") as string;
+    addOptimistic(text);
+    await addTodo(text);
+  }
+
+  return (
+    <form action={handleAdd}>
+      <input name="text" />
+      <button type="submit">Add</button>
+      <ul>
+        {optimisticTodos.map(t => (
+          <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.text}</li>
+        ))}
+      </ul>
+    </form>
+  );
+}
+```
+
+## Event Handler Types
+
+```tsx
+// Always use specific event types
+onClick:    (e: React.MouseEvent<HTMLButtonElement>) => void
+onChange:   (e: React.ChangeEvent<HTMLInputElement>) => void
+onSubmit:   (e: React.FormEvent<HTMLFormElement>) => void
+onKeyDown:  (e: React.KeyboardEvent<HTMLInputElement>) => void
+onFocus:    (e: React.FocusEvent<HTMLInputElement>) => void
+onDrag:     (e: React.DragEvent<HTMLDivElement>) => void
+```
+
+## Hooks Typing
+
+```tsx
+// useState with union
+const [status, setStatus] = useState<"idle" | "loading" | "error">("idle");
+
+// useRef for DOM — pass null, get RefObject
+const inputRef = useRef<HTMLInputElement>(null);
+
+// useRef for mutable value — no null, get MutableRefObject
+const intervalRef = useRef<number>(0);
+
+// useReducer with discriminated actions
+type Action = { type: "increment" } | { type: "set"; payload: number };
+const [count, dispatch] = useReducer((state: number, action: Action) => {
+  switch (action.type) {
+    case "increment": return state + 1;
+    case "set": return action.payload;
+  }
+}, 0);
+
+// Custom hook: return as const for tuple types
+function useToggle(initial = false) {
+  const [value, setValue] = useState(initial);
+  const toggle = useCallback(() => setValue(v => !v), []);
+  return [value, toggle] as const;
+}
+
+// useContext with null guard
+const ctx = useContext(ThemeContext);
+if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
+```
+
+## Performance Rules
+
+### Prevent Async Waterfalls
+```tsx
+// BAD — sequential fetching
+const user = await getUser(id);
+const posts = await getPosts(user.id);  // Waits for user first
+const comments = await getComments(posts[0].id);  // Waits for posts
+
+// GOOD — parallel where possible
+const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
+```
+
+### Bundle Size
+- `dynamic(() => import("./HeavyComponent"))` — lazy load below-fold components
+- Tree-shake: use named exports, avoid `import *`
+- Analyze bundle: `@next/bundle-analyzer` to find bloat
+- Code-split by route — each page loads only its own JS
+- Avoid importing entire libraries: `import { debounce } from "lodash-es"` not `import _ from "lodash"`
+
+### Server-Side Performance
+- Default to Server Components — zero JS shipped to client
+- Stream with Suspense: wrap slow data fetchers in `<Suspense fallback={<Skeleton />}>`
+- Cache expensive computations with `"use cache"` directive
+- Avoid serializing large objects across server/client boundary
+
+### Client-Side Data Fetching
+- Use SWR or React Query — automatic caching, revalidation, error retry
+- Stale-while-revalidate: show cached data instantly, refresh in background
+- Error boundaries: `<ErrorBoundary>` wrapping data-dependent trees
+- Prefetch on hover/viewport for likely next navigations
+
+### Re-render Optimization
+- React Compiler (React 19): auto-memoizes — try this first before manual `useMemo`/`useCallback`
+- If no compiler: `useMemo` for expensive computations, `useCallback` for stable function references
+- Extract static JSX outside components — constants don't re-create
+- Split context: separate frequently-changing state from rarely-changing state
+- `React.memo()` on components receiving only primitive props
+
+### Rendering Performance
+- **Virtualize** lists > 100 items: `@tanstack/react-virtual`, `react-window`
+- Defer heavy computations with `useDeferredValue`
+- Batch state updates (React 18+ does this automatically in event handlers)
+- Avoid reading DOM layout during renders (force sync layout = jank)
+
+### Advanced Patterns
+- Progressive hydration: load and hydrate components as they enter viewport
+- Concurrent features: `useTransition` for non-blocking state updates
+- Suspense caching: combine `<Suspense>` with data cache for instant page transitions
+- React Compiler adoption: enable gradually, check for unsafe patterns first
+
+## Decision Flow
+
+When implementing a React feature:
+
+1. **Server or Client?** → If it uses browser APIs, event handlers, or useState → Client. Everything else → Server.
+2. **Data fetching?** → Server Component for initial data. SWR/React Query for client-side mutations.
+3. **Form?** → Server Action + `useActionState` + Zod validation.
+4. **Optimistic?** → `useOptimistic` for instant feedback.
+5. **Loading?** → `<Suspense>` with skeleton fallback.
+6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
+7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.

package/scaffold/general/skills/requirements-clarity/SKILL.md

@@ -2,12 +2,12 @@
 name: requirements-clarity
 description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
 metadata:
-   category: cross-cutting
-   domain: general
-   applicability: on-demand
-   inputs: [requirements]
-   outputs: [scored-requirements, clarifications]
-   relatedSkills: [brainstorming]
+  category: cross-cutting
+  domain: general
+  applicability: on-demand
+  inputs: [requirements]
+  outputs: [scored-requirements, clarifications]
+  relatedSkills: [brainstorming]
 ---
 
 # Requirements Clarity Skill

package/scaffold/general/skills/session-handoff/SKILL.md

@@ -2,13 +2,13 @@
 name: session-handoff
 description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
 metadata:
-    category: cross-cutting
-    domain: general
-    applicability: always
-    inputs: [session-state, decisions]
-    outputs: [handoff-document]
-    requires: [aikit]
-    relatedSkills: [lesson-learned]
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [session-state, decisions]
+  outputs: [handoff-document]
+  requires: [aikit]
+  relatedSkills: [lesson-learned]
 ---
 
 # Handoff