@appsforgood/next-supabase-kit 0.3.0 → 0.4.1

package/examples/next-supabase-installed/.cursor/skills/frontend-design/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: frontend-design
+description: Use when building or reviewing user-facing UI. Commit one simple palette and type pairing. Reject default AI layouts, timid color spreads, and decoration that is not the task.
+---
+
+# Frontend Design
+
+Build or review a screen as if a stranger must name the product from the first viewport. Simple and specific beats decorated.
+
+Scan 2026-09-06 (structure only, no bodies copied): Anthropic `frontend-design` (updated 2026-06), addyosmani `frontend-ui-engineering`, `educlopez/ui-craft`, `funboy322/avoid-ai-design`, `superdesigndev/superdesign-skill`.
+
+## Use when
+
+Any user-facing layout, component, HTML page, or “it looks generic.” Required for `USER_GUIDE.html` and for app screens.
+
+## Ground in the subject
+
+Name the product, the user, and this screen’s job before CSS. Tokens come from the domain (materials, time of day, one real object) — not from a theme pack. A toy store and a ledger cannot share a palette.
+
+**This kit’s HTML** (`USER_GUIDE.html`): charcoal assignment desk.
+
+| Token | Value |
+| --- | --- |
+| Paper | `#10100e` |
+| Ink | `#eceae4` |
+| Frame | `#070706` |
+| Line | `#2a2823` |
+| Safelight | `#ff5a2a` (required / fail only) |
+| Pass | `#5ea37a` |
+| Type | `"Helvetica Neue", Helvetica, Arial, ui-sans-serif` |
+| Mono | `ui-monospace, Menlo, Consolas` |
+| Radius | `2px` |
+| Shadow | none |
+
+**Downstream Next.js apps:** do not paste the kit desk onto a product. Extract or invent **4–6 hex tokens** from *this* product’s job. Write them before CSS. Inside an existing design system, stay surgical — swap tells, do not invent a second brand.
+
+## Color — simple schemes that hold up
+
+One field, one ink, one accent, one line. That is enough.
+
+1. **Dominant field** (~80%): the page. Flat. Not a gradient, not a mesh.
+2. **Ink** (~15%): body text. Contrast ≥ 4.5:1 (3:1 for large type).
+3. **Accent** (~5%): one action or one required state. Recolor-as-decoration fails.
+4. **Line / well**: borders and code wells, one step off the field.
+
+Recipes (pick one that fits the product, then stop):
+
+| Scheme | Field | Ink | Accent | Use when |
+| --- | --- | --- | --- | --- |
+| Charcoal desk | `#10100e` | `#eceae4` | `#ff5a2a` | Tools, manuals, this kit |
+| Paper + ink | `#f4f4f1` | `#171717` | `#0b57d0` | Documents, settings, calm apps |
+| Night + signal | `#0e1116` | `#e6edf3` | `#3fb950` | Ops, status, pass/fail |
+| Warm shop | `#1c1916` | `#f3ece3` | `#e8a317` | Craft, commerce with real goods |
+
+Do not:
+
+- Spread six mid-chroma colors evenly.
+- Use purple→blue, default `blue-600`, or untouched shadcn `zinc` as the identity.
+- Use cream `#F4F1EA` + terracotta (the 2026 editorial default) unless the brief asks.
+- Use acid green or neon vermilion on near-black as decoration.
+- Treat Space Grotesk + slate, or any “tasteful” swap you used last week, as a new idea.
+
+Prefer CSS variables. Self-contained kit HTML: no Google Fonts, no CDN CSS.
+
+## Type
+
+One family, or two that are obviously different (display vs mono). Inter + system sans is not a pairing. Roboto, Space Grotesk, and “the last distinctive font you used” are second-order defaults.
+
+- Line length < 80 characters.
+- Tight display tracking on large sans. Do not italicize or recolor one word of a headline.
+- No tracked-out ALL-CAPS eyebrows, middle-dot meta (`A · B · C`), or `WORD — fragment` labels unless the content needs them.
+- Numbered tickets only when the content is a real sequence.
+
+## Layout
+
+- First viewport = the characteristic thing: command, table, form, named owner. Not a slogan over atmosphere.
+- Mobile (~390): the primary CTA still fits above the fold.
+- Hierarchy from size, weight, and space — not from cards.
+- Landing and marketing pages take a full direction. App chrome (settings, tables) stays quiet and dense.
+- Reject: centered hero + two pills + three icon cards; glass navbar; four-column empty footer; fake metrics; broadsheet hairlines + dense newsprint columns (that look is itself a 2026 default).
+
+## Motion
+
+None, or one moment that answers a click. Fade-and-slide on every section is generated. Respect `prefers-reduced-motion`.
+
+## Process
+
+1. Name the product, the user, and the job of this screen.
+2. Write the 4–6 tokens and one-sentence layout idea.
+3. Check the plan is not a 2026 default (cream editorial, neon-on-black decoration, SaaS card kit, newsprint desk, last week’s “tasteful” swap). If it is, change one axis: field, accent, or structure.
+4. Build. Spend boldness once. Remove one accessory.
+5. Screenshot desktop (~1280) and mobile (~390). Fix from pixels. Ask: would a stranger believe a person chose this?
+
+## Checks
+
+- A stranger can name the product from the first screen.
+- Loading, empty, error, disabled, success exist where the flow has them.
+- Focus visible, tap targets usable.
+- Copy on the screen is real. If words are public-facing, Copy runs `deslop` last.
+
+## Tools
+
+`browser` + `screenshot` + `image-review` first. Do not approve UI from TSX or HTML alone.
+
+## Done when
+
+Desktop and mobile images were read. Token list is in the change or in `DESIGN.md`. No P0 slop from `deslop` remains unless Design names it as an accepted exception.

package/examples/next-supabase-installed/.cursor/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: nextjs-app-router
+description: Use for Next.js App Router, Server Components, Client Components, Route Handlers, Server Actions, caching, forms, and metadata.
+---
+
+# Next.js App Router
+
+## Use when
+
+Routes, layouts, Server Components, Client Components, Server Actions, Route Handlers, data loading, caching, or revalidation.
+
+## Checks
+
+- Server Components are the default. Client Components are only for browser-only behavior.
+- Secrets never enter client bundles.
+- User-specific data is not stored in shared caches.
+- Route params, query params, forms, and API bodies are validated.
+- Loading, error, empty, and success states exist.
+- Authorization is enforced on the server and in RLS, not only in the UI.
+
+## Done when
+
+The server/client boundary is explicit and the changed route can be opened in the browser.

package/examples/next-supabase-installed/.cursor/skills/owasp-security-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: owasp-security-review
+description: Use when reviewing auth, APIs, Server Actions, uploads, webhooks, dependencies, secrets, or data mutations.
+---
+
+# OWASP Security Review
+
+## Use when
+
+Auth, APIs, Server Actions, external fetches, uploads, webhooks, dependencies, or mutations.
+
+## Checks
+
+- Broken access control and IDOR are tested.
+- Inputs are validated with safe schemas.
+- Outputs are encoded; secrets are not logged or bundled.
+- SSRF risk is addressed for server-side fetches.
+- Dependencies are reviewed for known critical CVEs.
+- Errors are explicit without leaking internals.
+
+## Done when
+
+Each finding has severity, affected behavior, and a concrete fix. User-visible auth failures were seen in the browser.

package/examples/next-supabase-installed/.cursor/skills/planning/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: planning
+description: Classify work, pick an owner, and name the evidence QA must capture. Use when the request is ambiguous, cross-layer, or needs a specialist.
+---
+
+# Planning
+
+## Use when
+
+Planning, roadmaps, “what should we do,” or any request that needs an owner.
+
+## Steps
+
+1. Read enough of the repo to name affected routes and data.
+2. Pick one owner: `app-engineer`, `security`, `design`, `qa`, or `copy`.
+3. Add Security for auth/data/secrets, Design for UI, QA for behavior/UI, Copy for public words.
+4. If the change is user-visible, list the desktop and mobile screenshots QA must capture.
+
+## Done when
+
+Owner, extra reviewers, preserved behavior, and required screenshots are explicit. No product code was written.
+
+## Reject
+
+Implementing in the planning pass. Asking one chat to play every role.

package/examples/next-supabase-installed/.cursor/skills/postgres-migrations/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: postgres-migrations
+description: Use for schema changes, migrations, constraints, indexes, and rollback risk.
+---
+
+# Postgres Migrations
+
+## Use when
+
+Creating or changing tables, constraints, indexes, functions, triggers, or seed data.
+
+## Checks
+
+- Migrations are additive or have an explicit rollback path.
+- Constraints protect integrity; indexes match real query paths.
+- RLS is planned in the same change when the table holds user or tenant data.
+- Generated types are refreshed after schema changes.
+
+## Done when
+
+Migration order and rollback risk are named. User data is not left unprotected.

package/examples/next-supabase-installed/.cursor/skills/product-copy/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: product-copy
+description: Use for headlines, CTAs, empty states, and conversion copy. Review rendered screenshots, not only strings in source.
+---
+
+# Product Copy
+
+## Use when
+
+Landing pages, CTAs, positioning, onboarding, empty states, pricing copy, or the public user guide (`USER_GUIDE.html`).
+
+## Audience
+
+Engineers and coding agents on a Next.js + Supabase repo who already have Cursor, Claude, Codex, Copilot, or Antigravity. They do not need a manifesto. They need to know **who to @**, **what to paste**, and **what “done” looks like**.
+
+## Positioning (this product)
+
+Name the specialist. Prove the screen. Six agents, twelve skills, five IDEs. QA is two screenshots, not a file diff.
+
+Do not describe this as an “agent operating system,” a copilot marketplace, or “AI-powered delivery.”
+
+## Voice
+
+Direct, specific, slightly dry. Prefer verbs: ask, paste, open, capture, reject.
+
+Use: specialist, owner, screenshot, desktop, mobile, fail-closed, paste, Planner, browser-qa.  
+Avoid: supercharge, seamless, unlock, copilot for X, 10x, enterprise-grade, magic, revolutionize.
+
+## Headline test
+
+If the headline could sell GitHub Copilot, Cursor, or any agent marketplace, rewrite it.
+
+Good: `Ask one specialist. Then open the running UI.`  
+Bad: `Supercharge your AI workflow with agents and skills.`
+
+## CTA test
+
+A CTA is a command or a pasteable prompt, not “Get started.”
+
+Good: `Paste this to Planner` followed by the plan prompt.  
+Good: `npx --yes @appsforgood/next-supabase-kit init --activate all`  
+Bad: `Start building today`.
+
+## Checks
+
+- Audience, pain, and outcome are specific to this product.
+- Claims are backed or marked as assumptions. Do not invent user counts or “best-in-class.”
+- Headlines could not fit any competitor.
+- CTAs say what happens next.
+- Review the words on a screenshot for truncation, wrapping, and hierarchy. Copy that only exists in markdown is not approved for a public HTML page.
+
+## Done when
+
+Copy is specific and the rendered screenshot shows the key line and CTA clearly on desktop and mobile. Copy then runs `deslop` as the last pass — this skill is not the end of the run.

package/examples/next-supabase-installed/.cursor/skills/ship/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ship
+description: Use before release. Check env vars, migration order, smoke, and rollback. User-visible releases still need browser-qa evidence.
+---
+
+# Ship
+
+## Use when
+
+Preparing to deploy, promote, or roll back.
+
+## Checks
+
+- Production-critical env vars are named.
+- Migration order and rollback are explicit.
+- Smoke of the primary path passed.
+- User-visible changes have desktop and mobile screenshot evidence from `browser-qa`.
+- Secrets are not in the repo or client bundle.
+
+## Done when
+
+Go / no-go is explicit, with commands run and rollback named.

package/examples/next-supabase-installed/.cursor/skills/supabase-auth-rls/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: supabase-auth-rls
+description: Use for Supabase Auth, SSR clients, middleware, sessions, Row Level Security, Storage policies, and service-role usage.
+---
+
+# Supabase Auth And RLS
+
+## Use when
+
+Supabase Auth, SSR clients, middleware, sessions, tables, policies, Storage, or service-role operations.
+
+## Checks
+
+- RLS is enabled on user-owned and tenant-owned tables.
+- Policies enforce ownership and tenant boundaries.
+- Service-role keys stay server-only.
+- Auth middleware refreshes sessions safely.
+- Storage buckets have explicit policies.
+- IDOR is considered and tested at the policy boundary.
+
+## Done when
+
+A table that stores user data cannot be read or written across users without a failing policy. UI checks are not treated as authorization.

package/examples/next-supabase-installed/.cursor/skills/testing-qa/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: testing-qa
+description: Use when adding unit, regression, or smoke tests. Visual proof of a screen always also uses browser-qa.
+---
+
+# Testing QA
+
+## Use when
+
+Adding or reviewing tests, smoke checks, or regression coverage.
+
+## Checks
+
+- Core logic has unit tests.
+- Preserved behavior has regression tests.
+- Critical flows have Playwright or equivalent smoke tests.
+- Auth and mutation paths are prioritized.
+- Network failure, empty, and error behavior is covered.
+- Gaps are named when infrastructure is missing.
+
+## Visual proof
+
+User-visible screens also require `browser-qa`. This skill does not replace screenshots.
+
+## Done when
+
+Commands run, results, and residual gaps are listed.

package/examples/next-supabase-installed/.github/copilot-instructions.md

@@ -0,0 +1,23 @@
+# Copilot instructions
+
+This repo uses a small agent and skill pack. Read `AGENTS.md` and `USER_GUIDE.md`.
+
+When the user names a role, act as that agent:
+
+- planner
+- app-engineer
+- security
+- design
+- qa
+- copy
+
+A user-visible change is not done until someone opened the running UI, captured desktop and mobile screenshots, and reviewed those images.
+
+Do not review user-visible work from code alone. Use the browser-qa skill: open the app, capture desktop and mobile screenshots, read the images, then give accept / accept-with-nits / reject.
+
+If you cannot open a browser, use Playwright:
+
+```bash
+npx playwright screenshot --viewport-size=1280,720 "$URL" qa-evidence/<slug>/desktop.png
+npx playwright screenshot --viewport-size=390,844 "$URL" qa-evidence/<slug>/mobile.png
+```

package/examples/next-supabase-installed/AGENTS.md

@@ -0,0 +1,30 @@
+# Agents
+
+This repo uses a small specialist pack. **Agent** = who. **Skill** = how. **Tool** = what they must use.
+
+Read `USER_GUIDE.md` for how to invoke these in Cursor, Claude, Codex, Copilot, and Antigravity.
+
+## Screenshot rule
+
+A user-visible change is not done until someone opened the running UI, captured desktop and mobile screenshots, and reviewed those images. Reading TSX is not QA.
+
+## Who to ask
+
+| Ask | Agent |
+| --- | --- |
+| Plan, scope, who owns this | `@planner` |
+| Implement Next.js or Supabase | `@app-engineer` |
+| Auth, RLS, secrets, OWASP | `@security` |
+| UI looks wrong / generic | `@design` |
+| Is this done? | `@qa` |
+| Headlines, CTAs, empty states | `@copy` |
+
+Do not ask one chat to be all six.
+
+## Handoff
+
+Planner names the owner. Security joins auth/data/secret work. Design joins user-facing screens. QA joins any behavior or UI change and **must use the browser**. Copy joins public/conversion copy. Stop there.
+
+## Skills
+
+Default skills live in `.cursor/skills/*/SKILL.md` (and the matching Claude/Codex/Antigravity copies). QA of a screen always uses `browser-qa`, not `testing-qa` alone. Copy finishes public words with `deslop`. Planner uses `planning` and names owners; it does not run the other agents. Each agent file points at `catalog.json` for the full skill list.

package/examples/next-supabase-installed/CLAUDE.md

@@ -0,0 +1,7 @@
+# Claude Code
+
+This repo uses a small agent and skill pack. Read `AGENTS.md` and `USER_GUIDE.md`.
+
+Subagents live in `.claude/agents/`. Use the matching subagent instead of one generic thread.
+
+A user-visible change is not done until someone opened the running UI, captured desktop and mobile screenshots, and reviewed those images. If you cannot open a browser, use the Playwright fallback in `skills/browser-qa/SKILL.md`.

package/examples/next-supabase-installed/README.md

@@ -1,15 +1,3 @@
-# Example Installed Output
+# Example install
 
-This directory shows the expected shape after running:
-
-```bash
-npx @appsforgood/next-supabase-kit init --stack next-supabase
-npx @appsforgood/next-supabase-kit audit --json
-npx @appsforgood/next-supabase-kit audit --min-readiness baseline-setup
-```
-
-The example is intentionally compact. It documents the generated structure, representative manifest metadata, Cursor adapter rules under `.cursor/rules/`, and expected audit shape without duplicating every template file. `npm run examples:check` verifies that these committed example files still match a clean install from the current built CLI.
-
-The installed `.agent-kit/agent-roster.json` is the machine-readable default council contract used by agents and validated by `agent-kit audit`. New installs also include `COUNCIL.md`, `ASSISTANT_ADAPTERS.md`, `MODEL_ROUTING.md`, `UPGRADE.md`, `.agent-kit/model-routing.json`, `.agent-kit/assistant-adapters/`, `.agent-kit/schemas/`, `DESIGN.md`, and `QUALITY_GATES.md` so handoffs, tool-specific assistant activation, model selection, upgrade review, frontend brand/content intake, reference-led critique, product-quality scoring, creative direction, visual QA, and maturity evidence are explicit before implementation is accepted. Optional `.agent-kit/council-sessions/*.json` records are validated when present.
-
-The sample audit intentionally reports `readiness.level: baseline-setup` with two warnings. A fresh install still contains starter placeholders and unverified assistant/model-selection rows; downstream projects should replace those with real project evidence before claiming strong or best-practice maturity.
+This tree is what `agent-kit init --activate all` writes.