stackfit 0.0.0-stage → 0.1.0

package/starter/skill-sources.json

@@ -0,0 +1,310 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/skill-sources.schema.json",
+  "schemaVersion": 2,
+  "skills": {
+    "animation-vocabulary": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/animation-vocabulary"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "apple-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/apple-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "baseline-ui": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/baseline-ui"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "emil-design-eng": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/emil-design-eng"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "fixing-accessibility": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/fixing-accessibility"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "fixing-motion-performance": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/fixing-motion-performance"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "frontend-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/anthropics/skills.git",
+        "path": "skills/frontend-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "grilling": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/mattpocock/skills.git",
+        "path": "skills/productivity/grilling"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "improve": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/shadcn/improve.git",
+        "path": "skills/improve"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "improve-animations": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/improve-animations"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "interface-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/Dammyjay93/interface-design.git",
+        "path": ".claude/skills/interface-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "make-interfaces-feel-better": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/jakubkrehel/make-interfaces-feel-better.git",
+        "path": "skills/make-interfaces-feel-better"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-bundle-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-bundle-optimizer"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-cache-components-adoption": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-cache-components-adoption"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-cache-components-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-cache-components-optimizer"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-dev-loop": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-dev-loop"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-partial-prefetching-adoption": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-partial-prefetching-adoption"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-partial-prefetching-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-partial-prefetching-optimizer"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-server-security": {
+      "kind": "custom",
+      "reviewed": "2026-10-26",
+      "note": "First-party stackfit starter skill."
+    },
+    "playwright-e2e-testing": {
+      "kind": "custom",
+      "reviewed": "2026-10-26",
+      "note": "First-party stackfit starter skill."
+    },
+    "react-doctor": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/millionco/react-doctor.git",
+        "path": "skills/react-doctor"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "review-animations": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/review-animations"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "shadcn": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/shadcn-ui/ui.git",
+        "path": "skills/shadcn"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "evals/evals.json"
+        ]
+      }
+    },
+    "stripe-best-practices": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/stripe-best-practices"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "stripe-projects": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/stripe-projects"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "ui-ux-pro-max": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
+        "path": ".claude/skills/ui-ux-pro-max"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "upgrade-stripe": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/upgrade-stripe"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "vercel-composition-patterns": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/composition-patterns"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ]
+      }
+    },
+    "vercel-react-best-practices": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/react-best-practices"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ]
+      }
+    },
+    "vercel-react-view-transitions": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/react-view-transitions"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ],
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "web-design-guidelines": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/web-design-guidelines"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": []
+      }
+    }
+  }
+}

package/starter/skills/next-server-security/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: next-server-security
+description: Next.js App Router server-side security - Server Actions as public endpoints, data access layer and DTOs, authz in proxy.ts vs at the data, Cache Components with user data, route handler CSRF, secrets and client-boundary leaks. Use when writing or reviewing Server Actions, route.ts, proxy/middleware, auth, data fetching, or caching of user-specific data.
+---
+
+# Next.js server security
+
+Next.js-specific failure modes that generic OWASP checklists miss. For the general OWASP pass, also use `owasp-security-check`. Canonical reference: https://nextjs.org/docs/app/guides/data-security.
+
+## Entry points (audit every one)
+
+| Entry point | Why it is public |
+| --- | --- |
+| Every exported function in a `"use server"` file that the app uses | Reachable by direct `POST`, not only through your UI. Encrypted action IDs and dead-code elimination reduce exposure; they are not access control. |
+| Inline `"use server"` functions in components | Same. A page-level auth check or `redirect()` does **not** protect the actions defined on that page. |
+| `route.ts` handlers | Plain HTTP. No built-in Origin check (unlike Server Actions). |
+| `proxy.ts` (Next 16; `middleware.ts` before) | Runs on matched requests only and is easy to bypass or mis-match. |
+| `[param]` segments, `searchParams`, headers, cookies | User input. |
+
+## Rules
+
+1. **Authorize at the data, not the route.** Put auth + authorization in a server-only data access layer (DAL): `import "server-only"`, a `cache()`d `getCurrentUser()`, then ownership checks before every read or write. `proxy.ts` is for optimistic redirects only. (CVE-2025-29927 let attackers skip middleware entirely with one header; apps that also checked in the DAL were safe.)
+2. **Every Server Action re-verifies.** Inside the action (or the DAL function it calls): authenticate, authorize the specific resource (IDOR), then mutate. Identity comes from the session, never from an argument, a hidden input, or a `.bind()` value.
+3. **Validate every action argument at runtime.** TypeScript types are erased; parse `FormData` and arguments with a schema (`z.safeParse` or the repo's validator) and return a typed error state instead of throwing raw errors.
+4. **Return DTOs, not records.** Action return values and props passed to Client Components are serialized to the browser (RSC payload / HTML). Select only the fields the UI needs. Never pass a full ORM row, user object, or session to a `"use client"` component. For defense in depth enable `experimental.taint` and use `experimental_taintObjectReference` / `experimental_taintUniqueValue` on secrets and raw records.
+5. **Secrets stay in the DAL.** Only server-only modules read `process.env` secrets and DB clients. Anything prefixed `NEXT_PUBLIC_` ships in the client bundle; never put keys there. Validate env at startup with a schema.
+6. **Cache Components and user data.**
+   - `"use cache"` output is shared across users and requests. `cookies()`, `headers()`, and `searchParams` are not allowed inside it; pass values in as arguments, and they become part of the cache key.
+   - A cached function that takes `userId` returns that user's data to *any* caller who passes the id: authorize **before** calling it, outside the cache boundary.
+   - Per-user personalized results: `"use cache: private"` (never stored in a server cache across requests) or no cache.
+   - After a mutation, invalidate what you changed: `updateTag(tag)` inside the action for read-your-own-writes, `revalidateTag(tag, "max")` for stale-while-revalidate, or `revalidatePath`.
+7. **Route handlers that mutate with cookie auth need CSRF protection.** Prefer Server Actions (Next checks `Origin` against `Host`). Otherwise verify the `Origin` header, require a non-simple content type or a CSRF token, and keep session cookies `SameSite=Lax` or stricter, `HttpOnly`, `Secure`. Behind a reverse proxy or alternate domain, set `serverActions.allowedOrigins` instead of disabling checks.
+8. **No mutations during render.** Logging out, writing, or revalidating from a page because of a `searchParams` value is a GET side effect. Use an action.
+9. **Redirects.** `redirect(searchParams.callbackUrl)` is an open redirect. Allow only same-origin relative paths (starts with `/`, not `//`).
+10. **Headers.** Static security headers go in `next.config` `headers()`. A nonce-based CSP is generated in `proxy.ts` and forces dynamic rendering for those routes; choose that trade-off deliberately.
+11. **Self-hosting multiple instances:** set a stable `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` so closure encryption works across instances. Encryption of closed-over values is not a reason to close over secrets.
+12. **Rate-limit expensive actions** (email, signup, AI calls, uploads) by user and IP.
+13. **Stay on the latest patch of your Next.js and React line.** RSC protocol bugs are critical (React2Shell, CVE-2025-55182, was unauthenticated RCE in Next 15.x/16.0 App Router apps). Check the repo's audit command and https://github.com/vercel/next.js/security/advisories when touching dependencies.
+
+## Server Action shape
+
+```ts
+// app/posts/actions.ts
+"use server";
+
+import { z } from "zod";
+import { updateTag } from "next/cache";
+import { deletePost } from "@/data/posts"; // server-only DAL: auth + ownership inside
+
+const Input = z.object({ postId: z.string().uuid() });
+
+export async function deletePostAction(_prev: unknown, formData: FormData) {
+  const parsed = Input.safeParse({ postId: formData.get("postId") });
+  if (!parsed.success) return { ok: false as const, error: "Invalid input" };
+  await deletePost(parsed.data.postId); // throws/returns forbidden if not the owner
+  updateTag(`posts`);
+  return { ok: true as const }; // minimal result, no DB row
+}
+```
+
+## Review output
+
+For each finding: entry point, file:line, what an attacker sends, impact, fix. Check the repo's actual auth library and DAL location first; do not assume paths.

package/starter/skills/playwright-e2e-testing/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: playwright-e2e-testing
+description: Write, fix, or review Playwright end-to-end tests, especially for Next.js apps - locators, auth via storageState, flaky waits, server-side fetch mocking, CI against a production build. Use for *.spec.ts / e2e/ / playwright.config changes or flaky browser tests. For unit and component tests use frontend-testing.
+---
+
+# Playwright E2E
+
+## Start from repository evidence
+
+1. Read `AGENTS.md` and the testing page linked from `docs/agent/index.md`.
+2. Read `playwright.config.*` (`testDir`, `projects`, `webServer`, `use.baseURL`, `testIdAttribute`), existing fixtures, page objects, and the auth setup project.
+3. Use the repo's package manager and scripts. Match existing file names, tags, and fixture style; do not introduce page objects or new fixtures if the suite does not use them.
+
+## Rules that prevent flaky tests
+
+- **Locators:** `getByRole` with `name`, then `getByLabel`, `getByText`, then `getByTestId` (respect a configured `testIdAttribute`). No CSS chains, XPath, or `.nth()` on unstable lists.
+- **Waiting:** only web-first assertions (`await expect(locator).toBeVisible()`, `toHaveURL`, `toHaveText`). Never `waitForTimeout`. Avoid `waitForLoadState("networkidle")`: Next.js prefetching and streaming keep the network busy. After navigation use `await expect(page).toHaveURL(...)` or `page.waitForURL`.
+- **Hydration:** a click on a server-rendered button before hydration can be lost. Assert the result of the interaction (a visible state change), not just that the click ran; if the suite has a hydration-ready helper, use it.
+- **Server Actions / forms:** assert on the UI that the action produces (toast, updated row, redirect URL), not on internal network calls.
+- **Isolation:** every test creates the data it needs (API or DB fixture) and can run in parallel and in any order. No dependence on a previous test.
+- **Auth:** log in once in a setup project and save `storageState` per role; tests reuse it. Do not log in through the UI in every test.
+
+## Next.js specifics
+
+- **CI runs against a production build** (`next build` then `next start`) through `webServer`; `next dev` compiles routes on first hit and causes timeouts. Use `reuseExistingServer: !process.env.CI` locally.
+- **`page.route` only intercepts browser requests.** Fetches made by Server Components, Route Handlers, or Server Actions run on the server and are not intercepted. Point the server at a test backend/database via env, or use the repo's existing server-side mocking (MSW in the server, or `next/experimental/testmode/playwright` if already set up).
+- **Instant navigation / static shell guards** under Cache Components: use the `next-cache-components-optimizer` skill (`@next/playwright` `instant()`).
+- **Visual snapshots:** fixed viewport, `animations: "disabled"`, mask dynamic regions (dates, avatars). Snapshots are per OS/browser; only update them on the platform CI uses.
+
+## Run and debug
+
+- Narrow first: `<pm> playwright test <file> -g "<title>" --project=chromium`.
+- Flaky: `--repeat-each=10 --workers=1`, then `--trace on` and `playwright show-trace`.
+- Report the exact command, pass/fail, and any test you could not run (for example missing env or seed data).

package/starter/stackfit.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/stackfit.schema.json",
+  "schemaVersion": 3,
+  "skills": [
+    "animation-vocabulary",
+    "apple-design",
+    "baseline-ui",
+    "emil-design-eng",
+    "fixing-accessibility",
+    "fixing-motion-performance",
+    "frontend-design",
+    "grilling",
+    "improve",
+    "improve-animations",
+    "interface-design",
+    "make-interfaces-feel-better",
+    "next-bundle-optimizer",
+    "next-cache-components-adoption",
+    "next-cache-components-optimizer",
+    "next-dev-loop",
+    "next-partial-prefetching-adoption",
+    "next-partial-prefetching-optimizer",
+    "next-server-security",
+    "playwright-e2e-testing",
+    "react-doctor",
+    "review-animations",
+    "shadcn",
+    "stripe-best-practices",
+    "stripe-projects",
+    "ui-ux-pro-max",
+    "upgrade-stripe",
+    "vercel-composition-patterns",
+    "vercel-react-best-practices",
+    "vercel-react-view-transitions",
+    "web-design-guidelines"
+  ],
+  "packs": {
+    "core": {
+      "description": "Every repository: codebase review planning and decision grilling.",
+      "always": true,
+      "skills": [
+        "grilling",
+        "improve"
+      ]
+    },
+    "react": {
+      "description": "React performance, composition, and diagnostics.",
+      "detect": {
+        "dependencies": [
+          "react"
+        ]
+      },
+      "skills": [
+        "react-doctor",
+        "vercel-composition-patterns",
+        "vercel-react-best-practices"
+      ]
+    },
+    "nextjs": {
+      "description": "Next.js App Router: server security, runtime verification, bundle and navigation workflows (manual-only ones cost no context). Framework reference knowledge comes from node_modules/next/dist/docs (16.2+).",
+      "detect": {
+        "dependencies": [
+          "next"
+        ]
+      },
+      "skills": [
+        "next-bundle-optimizer",
+        "next-cache-components-adoption",
+        "next-cache-components-optimizer",
+        "next-dev-loop",
+        "next-partial-prefetching-adoption",
+        "next-partial-prefetching-optimizer",
+        "next-server-security",
+        "vercel-react-view-transitions"
+      ]
+    },
+    "e2e": {
+      "description": "Playwright browser tests.",
+      "detect": {
+        "dependencies": [
+          "@playwright/test",
+          "playwright"
+        ]
+      },
+      "skills": [
+        "playwright-e2e-testing"
+      ]
+    },
+    "ui": {
+      "description": "Interface design, accessibility, and polish.",
+      "detect": {
+        "dependencies": [
+          "react-dom",
+          "vue",
+          "svelte",
+          "tailwindcss",
+          "@angular/core",
+          "solid-js"
+        ]
+      },
+      "skills": [
+        "baseline-ui",
+        "fixing-accessibility",
+        "frontend-design",
+        "interface-design",
+        "make-interfaces-feel-better",
+        "web-design-guidelines"
+      ]
+    },
+    "shadcn": {
+      "description": "shadcn/ui components and registries.",
+      "detect": {
+        "files": [
+          "components.json"
+        ]
+      },
+      "skills": [
+        "shadcn"
+      ]
+    },
+    "motion": {
+      "description": "Animation craft, review, and performance. Auto-detected from motion libraries; add it by hand for CSS-only motion work.",
+      "detect": {
+        "dependencies": [
+          "motion",
+          "framer-motion",
+          "gsap",
+          "@react-spring/web"
+        ]
+      },
+      "skills": [
+        "animation-vocabulary",
+        "apple-design",
+        "emil-design-eng",
+        "fixing-motion-performance",
+        "improve-animations",
+        "review-animations"
+      ]
+    },
+    "design-research": {
+      "description": "Large searchable UI/UX database (about 1.7 MB). Opt-in only.",
+      "skills": [
+        "ui-ux-pro-max"
+      ]
+    },
+    "stripe": {
+      "description": "Stripe integrations and upgrades.",
+      "detect": {
+        "dependencies": [
+          "stripe",
+          "@stripe/stripe-js",
+          "@stripe/react-stripe-js"
+        ]
+      },
+      "skills": [
+        "stripe-best-practices",
+        "stripe-projects",
+        "upgrade-stripe"
+      ]
+    }
+  },
+  "adapters": {
+    "agents": [],
+    "commands": [],
+    "rules": [
+      "defaults.mdc"
+    ]
+  }
+}

package/starter/stackfit.local.example.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/stackfit.local.schema.json",
+  "schemaVersion": 1,
+  "machines": [
+    {
+      "id": "mac",
+      "match": { "platform": "darwin" },
+      "roots": ["~/code"],
+      "projects": [
+        "my-next-app",
+        { "name": "client-site", "scaffold": false, "packs": ["motion"] }
+      ]
+    },
+    {
+      "id": "windows",
+      "match": { "platform": "win32" },
+      "roots": ["C:/Users/you/code"]
+    }
+  ]
+}