agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/frontend-developer/references/react-rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+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 Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/template/agent/skills/frontend-developer/references/react-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/template/agent/skills/frontend-developer/references/svelte-sveltekit.md

@@ -0,0 +1,220 @@
+# Svelte + SvelteKit Reference
+
+> **Philosophy:** Write less code. No virtual DOM. Compiled framework.
+> Reactivity is built into the language, not bolted on.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `svelte.config.js`, `package.json` with `svelte` or `@sveltejs/kit` dependency.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `svelte.config.js` | SvelteKit configuration (adapter, preprocess) |
+| `vite.config.ts` | Vite bundler configuration |
+| `tsconfig.json` | TypeScript configuration |
+| `.env` | Environment variables (prefixed `PUBLIC_` for client) |
+
+**Recommended project structure (SvelteKit):**
+
+```
+src/
+  routes/
+    +layout.svelte              # Root layout
+    +page.svelte                # Home page
+    +error.svelte               # Error page
+    about/
+      +page.svelte              # /about
+    users/
+      [id]/
+        +page.svelte            # /users/:id
+        +page.server.ts         # Server load function
+    api/
+      posts/
+        +server.ts              # API endpoint
+  lib/
+    components/                 # Reusable components
+    stores/                     # Svelte stores
+    server/                     # Server-only code ($lib/server/)
+    utils.ts                    # Shared utilities
+  app.html                      # HTML template
+  app.css                       # Global styles
+static/                         # Static assets
+```
+
+---
+
+## Architecture Patterns
+
+### Svelte 5 Runes (Default)
+
+```svelte
+<script lang="ts">
+  let count = $state(0)
+  let doubled = $derived(count * 2)
+
+  function increment() {
+    count++
+  }
+</script>
+
+<button onclick={increment}>{count} ({doubled})</button>
+```
+
+| Rune | Purpose |
+|------|---------|
+| `$state` | Reactive state declaration |
+| `$derived` | Computed value (replaces `$:` reactive statements) |
+| `$effect` | Side effect (replaces `$:` for effects) |
+| `$props` | Component props |
+| `$bindable` | Two-way binding capability |
+
+### Data Loading (SvelteKit)
+
+| Pattern | Use When |
+|---------|----------|
+| **`+page.server.ts` `load()`** | SSR data — runs on server only |
+| **`+page.ts` `load()`** | Universal — runs on server AND client |
+| **`+server.ts`** | API endpoints |
+| **Form actions** | Mutations (POST/PUT/DELETE) |
+
+```ts
+// src/routes/posts/+page.server.ts
+export async function load({ fetch }) {
+  const posts = await fetch('/api/posts').then(r => r.json())
+  return { posts }
+}
+
+// src/routes/posts/+page.svelte
+<script>
+  let { data } = $props()
+</script>
+
+{#each data.posts as post}
+  <article>{post.title}</article>
+{/each}
+```
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **`$state` (rune)** | Component-local state |
+| **Svelte stores (`writable`)** | Shared state across components |
+| **`$page.url.searchParams`** | URL state (filters, pagination) |
+| **Context API** | Scoped dependency injection |
+
+---
+
+## Performance Optimization
+
+### Why Svelte is Fast by Default
+
+- **No virtual DOM** — compiles to direct DOM manipulation
+- **No runtime framework** — smaller bundle (Svelte ~2KB vs React ~40KB)
+- **Granular reactivity** — only updates exactly what changed
+- **Automatic code splitting** — SvelteKit splits by route
+
+### Key Optimizations
+
+1. **`{#key}`** — force re-create a component when key changes.
+
+2. **`{#await}`** — built-in async rendering.
+
+```svelte
+{#await fetchData()}
+  <Spinner />
+{:then data}
+  <DataView {data} />
+{:catch error}
+  <ErrorMessage {error} />
+{/await}
+```
+
+3. **Enhanced image** — `@sveltejs/enhanced-img` for automatic optimization.
+
+4. **Streaming** — SvelteKit supports streaming SSR with nested `load` functions.
+
+5. **Preloading** — `data-sveltekit-preload-data="hover"` preloads links on hover.
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **UI** | `shadcn-svelte` | `skeleton`, `melt-ui` |
+| **Styling** | `tailwindcss` | `unocss` |
+| **Forms** | `superforms` + `zod` | `felte` |
+| **Auth** | `lucia` | `authjs-sveltekit` |
+| **Database** | `prisma` / `drizzle` | `kysely` |
+| **Testing** | `vitest` + `@testing-library/svelte` | — |
+| **E2E** | `playwright` | `cypress` |
+| **Icons** | `lucide-svelte` | `svelte-icons` |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| Svelte 4 `$:` reactive statements | Legacy (Svelte 5 uses runes) | `$derived`, `$effect` |
+| `onMount` for data fetching | Runs only on client, no SSR | `load()` in `+page.server.ts` |
+| Mutating `$state` arrays without reassignment | May not trigger reactivity | Push then reassign: `items = [...items, newItem]` |
+| `$effect` for derived state | Extra update cycle | Use `$derived` |
+| `PUBLIC_` prefix missing for client env | Variable not available in client | Prefix with `PUBLIC_` |
+| Importing `$lib/server` in client code | Server secrets leak to bundle | Use `$lib/server/` only in `.server.ts` |
+| Missing form `use:enhance` | Full page reload on submit | Add `use:enhance` for progressive enhancement |
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | Vitest + `@testing-library/svelte` | Components, stores |
+| **E2E** | Playwright | Full user flows |
+
+```ts
+import { render, screen } from '@testing-library/svelte'
+import Counter from '$lib/components/Counter.svelte'
+
+test('increments count', async () => {
+  render(Counter)
+  const button = screen.getByRole('button')
+  await button.click()
+  expect(button.textContent).toBe('1')
+})
+```
+
+---
+
+## Deployment & Distribution
+
+### Adapters
+
+SvelteKit uses adapters for different deployment targets:
+
+```bash
+npm run build
+```
+
+| Adapter | Platform |
+|---------|----------|
+| `@sveltejs/adapter-auto` | Auto-detect (Vercel, Netlify, Cloudflare) |
+| `@sveltejs/adapter-vercel` | Vercel |
+| `@sveltejs/adapter-node` | Node.js server |
+| `@sveltejs/adapter-static` | Static site (SSG) |
+| `@sveltejs/adapter-cloudflare` | Cloudflare Pages/Workers |
+
+```js
+// svelte.config.js
+import adapter from '@sveltejs/adapter-auto'
+
+export default {
+  kit: { adapter: adapter() }
+}
+```

package/template/agent/skills/frontend-developer/references/vanilla.md

@@ -0,0 +1,275 @@
+# Vanilla JS/TS + Web Components Reference
+
+> **Philosophy:** Zero dependencies. Platform APIs first.
+> The best framework is the one you don't need.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** No framework dependency in `package.json`. Plain `index.html` + `<script>` tags, or Vite with no framework plugin.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `index.html` | Entry point |
+| `vite.config.ts` | Build tool (if using Vite) |
+| `tsconfig.json` | TypeScript configuration |
+| `package.json` | Dependencies (minimal or none) |
+
+**Recommended project structure:**
+
+```
+src/
+  components/
+    header.ts                   # Custom elements / component modules
+    modal.ts
+  services/
+    api.ts                      # Fetch wrapper
+    storage.ts                  # localStorage abstraction
+  utils/
+    dom.ts                      # DOM utility functions
+    events.ts                   # Event system
+  styles/
+    main.css                    # Global styles
+    components/                 # Component-scoped CSS
+  main.ts                       # Entry point
+  router.ts                     # Client-side router (if SPA)
+index.html
+```
+
+---
+
+## Architecture Patterns
+
+### Web Components (Custom Elements)
+
+```ts
+class MyCounter extends HTMLElement {
+  #count = 0
+  #shadow: ShadowRoot
+
+  constructor() {
+    super()
+    this.#shadow = this.attachShadow({ mode: 'open' })
+  }
+
+  connectedCallback() {
+    this.render()
+  }
+
+  render() {
+    this.#shadow.innerHTML = `
+      <style>
+        button { font-size: 1rem; padding: 0.5rem 1rem; cursor: pointer; }
+      </style>
+      <button>${this.#count}</button>
+    `
+    this.#shadow.querySelector('button')!
+      .addEventListener('click', () => { this.#count++; this.render() })
+  }
+}
+
+customElements.define('my-counter', MyCounter)
+```
+
+### Module Pattern
+
+```ts
+// services/api.ts
+const BASE_URL = '/api'
+
+export async function get<T>(path: string): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`)
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json()
+}
+
+export async function post<T>(path: string, body: unknown): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  return res.json()
+}
+```
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **Module-level variables** | Simple state, single module access |
+| **Custom EventTarget** | Pub/sub across modules |
+| **Proxy-based reactivity** | Automatic DOM updates |
+| **URL state** (`URLSearchParams`) | Shareable, bookmarkable state |
+
+**Proxy-based reactivity:**
+
+```ts
+function createStore<T extends object>(initial: T, onChange: () => void): T {
+  return new Proxy(initial, {
+    set(target, prop, value) {
+      Reflect.set(target, prop, value)
+      onChange()
+      return true
+    }
+  })
+}
+```
+
+---
+
+## Performance Optimization
+
+### Modern Browser APIs to Use
+
+| API | Purpose |
+|-----|---------|
+| `fetch` | Network requests (replaces XMLHttpRequest) |
+| `IntersectionObserver` | Lazy loading, infinite scroll |
+| `ResizeObserver` | Responsive components |
+| `MutationObserver` | DOM change detection |
+| `requestIdleCallback` | Defer non-critical work |
+| `requestAnimationFrame` | Smooth animations |
+| `Web Workers` | Offload heavy computation |
+| `AbortController` | Cancel fetch requests |
+| `structuredClone` | Deep clone objects |
+| `URLPattern` | URL matching/routing |
+| `View Transitions API` | Page transition animations |
+| `Popover API` | Native popovers (no JS library) |
+| `<dialog>` | Native modal dialogs |
+
+### Key Optimizations
+
+1. **Event delegation** — one listener on parent, not N listeners on children.
+
+```ts
+// ❌ Bad: N listeners
+items.forEach(item => item.addEventListener('click', handler))
+
+// ✅ Good: 1 listener with delegation
+list.addEventListener('click', (e) => {
+  const item = (e.target as HTMLElement).closest('[data-id]')
+  if (item) handleClick(item.dataset.id!)
+})
+```
+
+2. **`DocumentFragment`** — batch DOM insertions.
+
+```ts
+const fragment = document.createDocumentFragment()
+items.forEach(item => {
+  const li = document.createElement('li')
+  li.textContent = item.name
+  fragment.appendChild(li)
+})
+list.appendChild(fragment) // single reflow
+```
+
+3. **CSS `content-visibility: auto`** — skip rendering off-screen content.
+
+4. **`<link rel="modulepreload">`** — preload ES modules.
+
+5. **`loading="lazy"`** on images and iframes — native lazy loading.
+
+---
+
+## Common Libraries (Minimal Dependencies)
+
+| Category | Lightweight Pick | Why Not Full Framework |
+|----------|-----------------|----------------------|
+| **Routing** | `navigo` / custom History API | 2KB vs router libraries |
+| **HTTP** | `fetch` (built-in) | No library needed |
+| **Templating** | `lit-html` | Tagged templates, 5KB |
+| **State** | `nanostores` | Framework-agnostic, 1KB |
+| **Build** | `vite` | Fast, ESM-native |
+| **Testing** | `vitest` | Fast, compatible |
+| **E2E** | `playwright` | Cross-browser |
+| **CSS** | CSS custom properties | Native variables |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| `innerHTML` with user input | XSS vulnerability | `textContent` or sanitize |
+| `document.write()` | Blocks parsing, destroys page | DOM manipulation methods |
+| jQuery for new projects | Unnecessary, browser APIs suffice | Native `querySelector`, `fetch` |
+| Sync XHR | Blocks main thread | `fetch` with async/await |
+| `var` declarations | Hoisting bugs, no block scope | `const` / `let` |
+| `==` loose equality | Type coercion bugs | `===` strict equality |
+| Missing `type="module"` on scripts | No ES module support | `<script type="module">` |
+| Global variables | Namespace pollution | ES modules |
+| Polling for DOM changes | Wasteful | `MutationObserver` |
+| `setTimeout` for animations | Inconsistent frame rate | `requestAnimationFrame` |
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | Vitest | Functions, modules |
+| **DOM** | Vitest + `happy-dom` | Component rendering |
+| **E2E** | Playwright | Full browser flows |
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { createStore } from '../src/store'
+
+describe('Store', () => {
+  it('notifies on change', () => {
+    let called = false
+    const store = createStore({ count: 0 }, () => { called = true })
+    store.count = 1
+    expect(called).toBe(true)
+  })
+})
+```
+
+---
+
+## Deployment & Distribution
+
+### Static Hosting (Most Common)
+
+```bash
+# Build (Vite)
+vite build
+
+# Output: dist/
+```
+
+Deploy `dist/` to any static host: Cloudflare Pages, Netlify, Vercel, GitHub Pages, S3 + CloudFront.
+
+### No-Build Option
+
+For simple projects, no build step needed:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="styles/main.css">
+</head>
+<body>
+  <script type="module" src="src/main.ts"></script>
+</body>
+</html>
+```
+
+Modern browsers support ES modules natively. Use import maps for bare specifiers:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "lit-html": "https://esm.sh/lit-html"
+  }
+}
+</script>
+```