autodoc-agent-kit 1.0.0

package/src/modules/engineering/skills/nextjs-15/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: nextjs-15
+description: Next.js 15 App Router patterns. Trigger when working in Next.js App Router (app/), Server Components vs Client Components, Server Actions, Route Handlers, caching/revalidation, and streaming/Suspense.
+---
+
+# Next.js 15 App Router Patterns
+
+Next.js 15 uses the App Router exclusively. Every file in `app/` is a Server Component by default. Understanding the server/client boundary is the core mental model.
+
+## Server vs Client Components
+
+### Default: Server Components
+
+```tsx
+// app/users/page.tsx — Server Component (no "use client")
+// Can: await data, access env vars, use server-only packages
+// Cannot: useState, useEffect, event handlers, browser APIs
+
+export default async function UsersPage() {
+  const users = await db.users.findMany(); // direct DB access
+  return <UserList users={users} />;
+}
+```
+
+### Client Components
+
+```tsx
+'use client';
+// app/components/counter.tsx
+// Can: useState, useEffect, event handlers, browser APIs
+// Cannot: async/await at component level, server-only imports
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### The Boundary Rule
+
+Push "use client" as deep as possible. Server Components can render Client Components, but not vice versa (without passing as props).
+
+```tsx
+// Good: Server Component renders Client Component leaf
+// app/dashboard/page.tsx (Server)
+export default async function Dashboard() {
+  const data = await fetchData();
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <InteractiveChart data={data} /> {/* Client Component */}
+    </div>
+  );
+}
+
+// Passing Server Components INTO Client Components via children
+function ClientShell({ children }: { children: React.ReactNode }) {
+  'use client';
+  const [open, setOpen] = useState(false);
+  return <div onClick={() => setOpen(!open)}>{children}</div>;
+}
+
+// Server Component passed as children — stays on server
+<ClientShell>
+  <ServerSideContent /> {/* This renders on the server */}
+</ClientShell>
+```
+
+## File Conventions
+
+| File | Purpose |
+|------|---------|
+| `layout.tsx` | Persistent UI wrapper, not re-rendered on navigation |
+| `page.tsx` | Route UI, receives `params` and `searchParams` |
+| `loading.tsx` | Suspense fallback for the route segment |
+| `error.tsx` | Error boundary for the route segment (must be `'use client'`) |
+| `not-found.tsx` | 404 UI for `notFound()` calls |
+| `route.ts` | API route handler (no UI) |
+| `template.tsx` | Like layout but re-renders on navigation |
+
+## Server Actions
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { redirect } from 'next/navigation';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+
+  // Validate
+  if (!title) throw new Error('Title required');
+
+  // Mutate
+  const post = await db.posts.create({ data: { title } });
+
+  // Revalidate cache
+  revalidatePath('/posts');
+
+  // Redirect
+  redirect(`/posts/${post.id}`);
+}
+
+// Use in a form
+export default function NewPostForm() {
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+## Data Fetching
+
+### Parallel Fetching
+
+```tsx
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+
+  // Fetch in parallel — don't await sequentially
+  const [user, posts] = await Promise.all([
+    getUser(id),
+    getUserPosts(id),
+  ]);
+
+  return <Profile user={user} posts={posts} />;
+}
+```
+
+### Streaming with Suspense
+
+```tsx
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Slow data doesn't block fast data */}
+      <Suspense fallback={<StatsLoading />}>
+        <SlowStats />
+      </Suspense>
+      <Suspense fallback={<FeedLoading />}>
+        <ActivityFeed />
+      </Suspense>
+    </div>
+  );
+}
+
+async function SlowStats() {
+  const stats = await getExpensiveStats(); // doesn't block the rest
+  return <StatsGrid stats={stats} />;
+}
+```
+
+## Caching and Revalidation
+
+### Route Segment Config
+
+```tsx
+// Force dynamic rendering (no cache)
+export const dynamic = 'force-dynamic';
+
+// Cache for 60 seconds
+export const revalidate = 60;
+
+// Static (build-time only)
+export const dynamic = 'force-static';
+```
+
+### On-Demand Revalidation
+
+```tsx
+'use server';
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+// Revalidate a path
+async function updatePost(id: string) {
+  await db.posts.update({ where: { id }, data: { ... } });
+  revalidatePath(`/posts/${id}`);
+  revalidatePath('/posts');
+}
+
+// Tag data when fetching
+const user = await fetch(`/api/users/${id}`, {
+  next: { tags: [`user-${id}`] }
+});
+
+// Revalidate by tag
+revalidateTag(`user-${id}`);
+```
+
+## Route Handlers
+
+```tsx
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const query = searchParams.get('q');
+
+  const users = await db.users.findMany({
+    where: query ? { name: { contains: query } } : undefined,
+  });
+
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const result = CreateUserSchema.safeParse(body);
+  if (!result.success) {
+    return NextResponse.json({ error: result.error.format() }, { status: 400 });
+  }
+  const user = await db.users.create({ data: result.data });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## Dynamic Routes
+
+```tsx
+// app/posts/[slug]/page.tsx
+export default async function PostPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params; // params is now async in Next.js 15
+  const post = await getPostBySlug(slug);
+  if (!post) notFound();
+  return <PostContent post={post} />;
+}
+
+// Generate static paths at build time
+export async function generateStaticParams() {
+  const posts = await getAllPosts();
+  return posts.map(post => ({ slug: post.slug }));
+}
+
+// Generate metadata
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const post = await getPostBySlug(slug);
+  return {
+    title: post?.title ?? 'Not Found',
+    description: post?.excerpt,
+  };
+}
+```
+
+## Middleware
+
+```tsx
+// middleware.ts (project root)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('auth-token');
+
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+## Error Handling
+
+```tsx
+// app/dashboard/error.tsx
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Key Next.js 15 Changes
+
+- `params` and `searchParams` in pages/layouts are now **Promises** — must be awaited
+- `cookies()` and `headers()` are now **async** — must be awaited
+- New `after()` API for post-response work (logging, analytics)
+- Turbopack is the default dev bundler

package/src/modules/engineering/skills/perf-optimizer/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: perf-optimizer
+description: Performance profiling and optimization across the full stack. Use when you need to improve application speed, reduce bundle size, optimize database queries, or improve Core Web Vitals. Triggers on "this is slow", "optimize performance", "reduce bundle size", "improve LCP/CLS/INP", "this query takes too long", or "why is this app laggy".
+---
+
+You are a performance optimization specialist across the full stack.
+
+## Optimization Areas
+
+### Frontend Performance
+- **Bundle size**: Analyze imports, tree-shaking, dynamic imports, code splitting
+- **Rendering**: Identify unnecessary re-renders, missing memoization, heavy computations
+- **Assets**: Image optimization, font loading, lazy loading below-the-fold content
+- **Core Web Vitals**: LCP, FID/INP, CLS optimization strategies
+- **Network**: Request waterfall analysis, prefetching, caching headers
+
+### Backend Performance
+- **Database**: Query optimization with EXPLAIN, N+1 detection, index analysis
+- **Caching**: Identify cacheable operations, cache invalidation strategy
+- **Async**: Move heavy operations to background jobs/queues
+- **Memory**: Identify memory leaks, large allocations, streaming for large datasets
+- **Concurrency**: Connection pooling, worker threads, request queuing
+
+### API Performance
+- **Response time**: Identify bottlenecks in request lifecycle
+- **Payload size**: Minimize response payloads, use pagination
+- **Compression**: Enable gzip/brotli
+- **Batching**: Combine multiple requests where appropriate
+
+## Process
+
+### Step 1: Measure
+1. Identify the performance concern (what's slow, by how much)
+2. Read the relevant code paths
+3. Look for obvious anti-patterns first
+4. Establish baseline metrics where possible
+
+### Step 2: Identify Bottlenecks
+Priority order:
+1. **Algorithmic**: O(n²) or worse in hot paths
+2. **I/O bound**: Unnecessary or sequential database/network calls
+3. **Memory**: Large allocations, missing cleanup, unbounded growth
+4. **CPU**: Heavy computation on the main thread
+5. **Network**: Large payloads, missing compression, no caching
+
+### Step 3: Optimize
+- Fix one bottleneck at a time
+- Measure improvement after each change
+- Document the tradeoff (e.g., added memory cache = more RAM usage)
+
+### Step 4: Verify
+- Confirm the optimization doesn't break functionality
+- Quantify the improvement
+- Check for regressions in other areas
+
+## Rules
+- Measure before optimizing — never optimize based on assumptions
+- Target the biggest bottleneck first (Amdahl's law)
+- Simple optimizations first (caching, batching) before complex ones (architecture changes)
+- Document performance tradeoffs in code comments

package/src/modules/engineering/skills/react-19/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: react-19
+description: React 19 patterns with React Compiler. Trigger when writing React 19 components and hooks in .tsx — React Compiler rules, hook patterns, refs as props, Server Components, and the new APIs (use, useActionState, useOptimistic, useFormStatus).
+---
+
+# React 19 Patterns
+
+React 19 ships the React Compiler (no more manual memoization), new hooks, and ref-as-prop. Write components for the compiler, not against it.
+
+## React Compiler Rules
+
+The compiler automatically memoizes components and values — **do not add `useMemo`, `useCallback`, or `memo` manually** unless you have a profiler-confirmed performance issue.
+
+### What the Compiler Handles Automatically
+
+- Memoizing component renders when props haven't changed
+- Memoizing derived values (replaces most `useMemo`)
+- Memoizing callbacks (replaces most `useCallback`)
+- Stabilizing refs
+
+### Rules of Hooks (Stricter in React 19)
+
+```tsx
+// Rules the compiler enforces:
+// 1. Only call hooks at the top level
+// 2. Only call hooks from React functions
+// 3. Don't mutate props or state directly
+// 4. Don't read a ref during render (only in effects/handlers)
+
+// Bad: conditional hook
+function Component({ isAdmin }: { isAdmin: boolean }) {
+  if (isAdmin) {
+    const data = useData(); // compiler error
+  }
+}
+
+// Good: hook always called, condition inside
+function Component({ isAdmin }: { isAdmin: boolean }) {
+  const data = useData();
+  if (!isAdmin) return null;
+  return <View data={data} />;
+}
+```
+
+## New React 19 APIs
+
+### `use()` — Read Resources in Render
+
+```tsx
+import { use, Suspense } from 'react';
+
+// use() unwraps promises and context — works inside conditionals
+function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise); // suspends until resolved
+  return <div>{user.name}</div>;
+}
+
+// Wrap in Suspense at the boundary
+function App() {
+  const userPromise = fetchUser(userId);
+  return (
+    <Suspense fallback={<Spinner />}>
+      <UserProfile userPromise={userPromise} />
+    </Suspense>
+  );
+}
+```
+
+### `useActionState()` — Form Actions with State
+
+```tsx
+import { useActionState } from 'react';
+
+async function submitForm(prevState: FormState, formData: FormData): Promise<FormState> {
+  const name = formData.get('name') as string;
+  if (!name) return { error: 'Name is required', data: null };
+  const data = await createUser({ name });
+  return { error: null, data };
+}
+
+function CreateUserForm() {
+  const [state, formAction, isPending] = useActionState(submitForm, { error: null, data: null });
+
+  return (
+    <form action={formAction}>
+      <input name="name" />
+      {state.error && <p className="text-red-500">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create'}
+      </button>
+    </form>
+  );
+}
+```
+
+### `useOptimistic()` — Optimistic UI
+
+```tsx
+import { useOptimistic } from 'react';
+
+function MessageList({ messages }: { messages: Message[] }) {
+  const [optimisticMessages, addOptimistic] = useOptimistic(
+    messages,
+    (state, newMessage: Message) => [...state, newMessage]
+  );
+
+  async function handleSend(text: string) {
+    const tempMessage = { id: crypto.randomUUID(), text, pending: true };
+    addOptimistic(tempMessage); // immediate UI update
+    await sendMessage(text);    // actual request
+  }
+
+  return (
+    <>
+      {optimisticMessages.map(m => (
+        <div key={m.id} style={{ opacity: m.pending ? 0.5 : 1 }}>{m.text}</div>
+      ))}
+    </>
+  );
+}
+```
+
+### `useFormStatus()` — Form Submission State
+
+```tsx
+import { useFormStatus } from 'react-dom';
+
+// Must be used inside a <form> component
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return <button disabled={pending}>{pending ? 'Submitting...' : 'Submit'}</button>;
+}
+```
+
+## Ref as Prop (React 19)
+
+Refs are now regular props — no more `forwardRef`:
+
+```tsx
+// React 19: ref is just a prop
+function Input({ ref, ...props }: React.ComponentProps<'input'>) {
+  return <input ref={ref} {...props} />;
+}
+
+// Usage
+function Form() {
+  const inputRef = useRef<HTMLInputElement>(null);
+  return <Input ref={inputRef} placeholder="Name" />;
+}
+```
+
+## Document Metadata in Components
+
+React 19 renders `<title>`, `<meta>`, and `<link>` directly from components:
+
+```tsx
+function BlogPost({ post }: { post: Post }) {
+  return (
+    <>
+      <title>{post.title}</title>
+      <meta name="description" content={post.excerpt} />
+      <link rel="canonical" href={post.url} />
+      <article>{post.content}</article>
+    </>
+  );
+}
+```
+
+## Component Patterns
+
+### Compound Components with Context
+
+```tsx
+const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
+
+function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
+  const [active, setActive] = useState(defaultTab);
+  return (
+    <TabsContext value={{ active, setActive }}>
+      <div className="tabs">{children}</div>
+    </TabsContext>
+  );
+}
+
+function Tab({ id, children }: { id: string; children: ReactNode }) {
+  const ctx = use(TabsContext); // use() works with context too
+  if (!ctx) throw new Error('Tab must be inside Tabs');
+  return (
+    <button
+      onClick={() => ctx.setActive(id)}
+      className={ctx.active === id ? 'active' : ''}
+    >
+      {children}
+    </button>
+  );
+}
+
+Tabs.Tab = Tab;
+```
+
+### Error Boundaries
+
+```tsx
+// Use react-error-boundary for functional wrappers
+import { ErrorBoundary } from 'react-error-boundary';
+
+function App() {
+  return (
+    <ErrorBoundary fallback={<ErrorPage />} onError={logError}>
+      <MyFeature />
+    </ErrorBoundary>
+  );
+}
+```
+
+## Rules for Clean Components
+
+1. **One responsibility per component** — if a component needs a long comment to explain what it does, split it
+2. **Derive state, don't sync it** — compute values from existing state rather than creating parallel state
+3. **Lift state to the first common ancestor** — no lower
+4. **Co-locate state with the component that needs it** — no higher
+5. **Props down, events up** — callbacks are always prefixed with `on`
+
+```tsx
+// Derived state: don't useEffect + setState
+// Bad:
+const [filteredUsers, setFilteredUsers] = useState(users);
+useEffect(() => { setFilteredUsers(users.filter(u => u.active)); }, [users]);
+
+// Good:
+const filteredUsers = users.filter(u => u.active);
+```
+
+## TypeScript with React 19
+
+```tsx
+// Component props
+type ButtonProps = React.ComponentProps<'button'> & {
+  variant?: 'primary' | 'secondary';
+};
+
+// Generic components
+function List<T extends { id: string }>({
+  items,
+  renderItem,
+}: {
+  items: T[];
+  renderItem: (item: T) => ReactNode;
+}) {
+  return <ul>{items.map(item => <li key={item.id}>{renderItem(item)}</li>)}</ul>;
+}
+
+// Event handlers
+function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+  setValue(e.target.value);
+}
+```

package/src/modules/engineering/skills/refactorer/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: refactorer
+description: Safe, incremental code refactoring with verification. Use when you need to restructure code, extract functions, simplify logic, or improve code organization without changing behavior. Triggers on "refactor this", "clean up this code", "simplify this function", "extract this logic", or "this is too complex".
+---
+
+You are a refactoring specialist focused on improving code structure without changing behavior.
+
+## Core Principles
+- **No behavior changes** — refactoring must preserve existing functionality
+- **Incremental steps** — make small, verifiable changes, not big-bang rewrites
+- **Test-backed** — verify tests pass after each step; write tests first if none exist
+- **Reversible** — every change should be easy to revert
+
+## Process
+
+### Step 1: Assess
+1. Read the target code and all its callers/dependents
+2. Run existing tests to establish a green baseline
+3. Identify the specific code smells to address:
+   - Long functions (>50 lines)
+   - Deep nesting (>3 levels)
+   - Duplicated logic across files
+   - God classes/modules with too many responsibilities
+   - Shotgun surgery (changes requiring edits in many files)
+   - Feature envy (code using another module's data extensively)
+
+### Step 2: Plan
+Present a numbered refactoring plan with:
+- Each step as an atomic, testable change
+- What each step improves and why
+- Risk assessment for each step
+- Expected test impact
+
+### Step 3: Execute
+For each step:
+1. Make the change
+2. Run tests/lint/typecheck
+3. If tests fail, revert and reassess
+4. Move to next step only when green
+
+### Step 4: Verify
+- All original tests still pass
+- No new lint warnings or type errors
+- Code coverage hasn't decreased
+- The public API is unchanged (unless explicitly requested)
+
+## Common Refactoring Techniques
+- **Extract Function**: Pull a coherent block into a named function
+- **Extract Module**: Move related functions to their own file
+- **Simplify Conditional**: Replace nested if/else with early returns or strategy pattern
+- **Remove Duplication**: Extract shared logic into a utility
+- **Rename**: Improve naming for clarity (update all references)
+- **Inline**: Remove unnecessary indirection (single-use wrappers)
+- **Decompose Class**: Split responsibilities into focused modules
+
+## Safety Rules
+- Never refactor and add features in the same change
+- Never delete code without confirming it's unused (check all callers)
+- If no tests exist, write characterization tests before refactoring
+- Preserve all public interfaces unless the user explicitly approves breaking changes