@appsforgood/next-supabase-kit 0.1.0

package/templates/next-supabase/DESIGN.md

@@ -0,0 +1,171 @@
+# Design Direction
+
+This file is the persistent visual identity and content-direction contract for coding agents, design agents, and human reviewers.
+
+Use it before designing or changing any user-facing screen. If the project already has a mature brand or design system, keep that system and record the override in `.agent-kit/overrides.json`.
+
+## Brand And Content Inputs
+
+Define the real product context before UI work starts.
+
+| Area | Required Decision |
+| --- | --- |
+| Product category | SaaS, admin, marketplace, content, tool, ecommerce, portfolio, venue, education, community, AI workflow, or other |
+| Primary audience | Who uses the product and what they already understand |
+| User needs | Jobs users are trying to complete, written in the user's language |
+| Content inventory | Real nouns, labels, data types, records, assets, and domain terms available to the UI |
+| Brand personality | 3-5 traits that should be visible in layout, typography, imagery, and interaction tone |
+| Visual constraints | Existing logo, colors, fonts, imagery, accessibility constraints, and platform conventions |
+| Competitive context | Category references to learn from and avoid copying |
+| Non-goals | Visual tropes, copy patterns, or interaction styles that must not be used |
+
+## Reference Set And Anti-References
+
+Use references for learning, not copying. Record what the project should absorb and what it must avoid.
+
+| Reference | What To Learn | What Not To Copy | Source-Safety Notes |
+| --- | --- | --- | --- |
+| Reference A | TBD | TBD | No brand marks, protected layout signatures, proprietary assets, or exact copy |
+| Reference B | TBD | TBD | TBD |
+| Reference C | Optional | Optional | Optional |
+
+Anti-references:
+
+- TBD: pattern, palette, layout, copy, or interaction style to avoid.
+- TBD: another explicit non-goal.
+
+## Creative Direction
+
+Before implementation, produce at least two distinct visual directions and choose one.
+
+| Direction | What Makes It Distinct | Best For | Risks |
+| --- | --- | --- | --- |
+| Direction A | TBD | TBD | TBD |
+| Direction B | TBD | TBD | TBD |
+| Direction C | Optional | Optional | Optional |
+
+Chosen direction:
+
+- Name: TBD
+- Rationale: TBD
+- Rejected alternatives: TBD
+
+## Design Tokens
+
+Tokens are the normative values. Prose explains how to apply them.
+
+| Token Area | Required Decisions |
+| --- | --- |
+| Color | Semantic colors, surface colors, text colors, state colors, contrast notes |
+| Typography | Font family, scale, weights, line height, heading/body relationship |
+| Spacing | Base unit, dense/admin spacing, section spacing, responsive spacing |
+| Radius | Component radius defaults and exceptions |
+| Motion | Duration, easing, reduced-motion behavior |
+| Shadow/Depth | When elevation is allowed and when it is prohibited |
+| Imagery | Product, place, person, object, or workflow asset rules |
+
+## Information Architecture
+
+The first screen must show the real product, task, object, or workflow.
+
+Document:
+
+- Primary workflow.
+- Secondary workflows.
+- Navigation model.
+- Data hierarchy.
+- Empty, loading, error, disabled, success, and permission-denied states.
+- Mobile-first layout changes.
+
+## Design Critique Gate
+
+Run `.agent-kit/prompts/design-critique-gate.md` before accepting significant frontend work.
+
+| Area | Verdict |
+| --- | --- |
+| First-screen specificity | TBD |
+| Product/content fit | TBD |
+| Distinctiveness | Weak, adequate, or strong |
+| Generic AI-site risk | TBD |
+| Accessibility risk | TBD |
+| Required changes | TBD |
+
+## Frontend Distinctiveness Benchmark
+
+Run `.agent-kit/prompts/frontend-distinctiveness-benchmark.md` before accepting significant frontend work. This benchmark proves the UI is specific to the product, not just polished.
+
+| Area | Required Evidence |
+| --- | --- |
+| First-screen proof | The first viewport shows the real product object, task, workflow, content, or decision |
+| Content fingerprint | Product nouns, labels, data shapes, records, actions, edge cases, and domain terms visible in the UI |
+| Reference benchmark | 3-5 references with lessons to learn and 2-3 anti-references with tropes to avoid |
+| Creative divergence | At least two plausible directions compared before implementation |
+| Asset provenance | Real, generated, licensed, and placeholder assets identified with usage constraints |
+| State proof | Loading, empty, error, disabled, success, permission, and focus states captured where relevant |
+| Visual QA proof | Desktop, mobile, and high-risk state evidence reviewed for the change risk |
+
+Distinctiveness verdict:
+
+- Verdict: Reject, adequate, or distinctive
+- Generic-AI-site risk: TBD
+- Source-safety risks: TBD
+- Required changes before acceptance: TBD
+
+## Product Quality Scorecard
+
+Run `.agent-kit/prompts/frontend-product-quality-scorecard.md` before accepting significant frontend work. Score each dimension as `0`, `1`, or `2`.
+
+| Dimension | Score | Evidence |
+| --- | --- | --- |
+| User/task fit | TBD | Does the first screen show the real product task, object, workflow, or content? |
+| Content specificity | TBD | Are real nouns, labels, data shapes, assets, and domain terms visible? |
+| Visual identity | TBD | Does the visual direction belong to this product instead of a generic category? |
+| Information architecture | TBD | Are primary and secondary workflows clear and scannable? |
+| Component states | TBD | Are loading, empty, error, disabled, success, permission, and focus states handled where relevant? |
+| Accessibility and interaction | TBD | Are keyboard path, focus, contrast, labels, motion, and error feedback covered? |
+| Source safety | TBD | Did references teach decisions without copied brand marks, layouts, copy, assets, or visual signatures? |
+
+Total score:
+
+- Score: TBD / 14
+- Verdict: Reject, adequate, or strong
+- Critical zeroes: TBD
+- Required changes before acceptance: TBD
+
+Acceptance threshold:
+
+- Reject if user/task fit, content specificity, accessibility and interaction, or source safety scores `0`.
+- Reject if total score is below `10`.
+- Treat `10-11` as adequate and `12-14` as strong.
+- Best-practice frontend evidence requires at least `12`, no critical zeroes, desktop/mobile review, and visual QA evidence for the change risk.
+
+## Component Direction
+
+List product-specific components and the states they require.
+
+| Component | Purpose | States | Accessibility Notes |
+| --- | --- | --- | --- |
+| Primary action surface | TBD | Default, hover, focus, disabled, loading, success, error | TBD |
+
+## Asset Rules
+
+- Use real product, object, place, person, gameplay, workflow, or generated imagery when visual inspection matters.
+- Avoid generic abstract gradients, vague device mockups, fake metrics, and stock-like decoration.
+- If no assets exist, document the missing asset need and use a purposeful placeholder with clear dimensions.
+- Keep image alt text specific to the content or empty only when the image is decorative.
+
+## Acceptance Evidence
+
+Frontend work is not accepted until the following evidence exists:
+
+- Brand and content inputs are filled or explicitly marked as not applicable.
+- Reference set, anti-references, and source-safety notes are filled.
+- A creative-direction matrix was considered.
+- The chosen direction is reflected in tokens, layout, copy, and imagery.
+- A design critique verdict records product fit, distinctiveness, generic-risk, and required changes.
+- A frontend distinctiveness benchmark records first-screen proof, content fingerprint, reference benchmark, creative divergence, asset provenance, state proof, visual QA proof, generic-risk, and source-safety risks.
+- A product-quality scorecard records user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, source safety, total score, and verdict.
+- Desktop and mobile screenshots were reviewed.
+- Accessibility risks and component states were reviewed.
+- Visual QA tier is documented in `TESTING.md` for high-risk UI changes.
+- Baseline visual changes are approved intentionally when visual regression tooling exists.

package/templates/next-supabase/DOCS.md

@@ -0,0 +1,62 @@
+# Developer Docs
+
+## Setup
+
+Document local setup:
+
+```bash
+npm install
+npm run dev
+```
+
+Add required environment variables in `.env.example`. Never place real secrets in docs.
+
+## Architecture Overview
+
+Document:
+
+- Agent council routing in `.agent-kit/agent-roster.json`
+- Assistant activation surfaces in `ASSISTANT_ADAPTERS.md`
+- Model profile routing in `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`
+- Council-session evidence in `COUNCIL.md`
+- Agent, council-session, model-routing, and audit-report schemas in `.agent-kit/schemas/`
+- Quality gate maturity model in `QUALITY_GATES.md`
+- Upgrade lifecycle in `UPGRADE.md`
+- Design identity and content-direction contract in `DESIGN.md`
+- Messaging, positioning, proof, objections, voice, and CTA contract in `MESSAGING.md`
+- Application routes
+- Shared components
+- Server-only modules
+- Supabase client creation
+- Auth middleware
+- Migrations and seed data
+- Test setup
+
+## Key Workflows
+
+Document primary workflows, including:
+
+- Planning and core-change handoffs from `AGENT_ROSTER.md`
+- Tool-specific assistant activation from `ASSISTANT_ADAPTERS.md`
+- Model-selection setup, enforcement status, and limitations from `MODEL_ROUTING.md`
+- Council-session evidence capture from `COUNCIL.md`
+- Upgrade review, conflict handling, migration review, and rollback evidence from `UPGRADE.md`
+- Baseline, strong, and best-practice evidence review from `QUALITY_GATES.md`
+- Brand/content intake and creative-direction selection before frontend implementation
+- Reference-led design critique, anti-references, source-safety notes, and distinctiveness verdict from `DESIGN.md`
+- Frontend product-quality scorecard from `DESIGN.md`
+- Marketing-copy workflow, proof mapping, objection handling, and CTA hierarchy from `MESSAGING.md`
+- Visual QA tier and baseline approval workflow for high-risk UI changes
+- Sign up, login, logout, and session refresh
+- Main user workflow
+- Admin workflow
+- Data creation and update workflow
+- Deployment workflow
+
+## Integration Points
+
+Document external APIs, webhooks, storage buckets, cron jobs, email providers, analytics, and monitoring.
+
+## Troubleshooting
+
+Record known issues, expected logs, and operational checks.

package/templates/next-supabase/MESSAGING.md

@@ -0,0 +1,81 @@
+# Messaging And Copy
+
+This file is the persistent positioning, value proposition, voice, and copy-evidence contract for agents and reviewers.
+
+Use it before writing or changing public-facing pages, onboarding, empty states, pricing, upgrade prompts, CTAs, lifecycle emails, notifications, or conversion-critical UX copy.
+
+## Discovery Questions
+
+Answer these before final copy is accepted. If an answer is unknown, mark it as `TBD` and treat the copy as provisional.
+
+| Question | Current Answer | Evidence |
+| --- | --- | --- |
+| Who is the primary audience? | TBD | User research, customer notes, analytics, brief, or stakeholder input |
+| What painful, expensive, slow, risky, or annoying problem do they need solved? | TBD | Customer language, support notes, interviews, or domain research |
+| What outcome do they want? | TBD | Success metric, workflow completion, time saved, risk reduced, revenue gained, or quality improved |
+| What alternatives do they use today? | TBD | Competitors, spreadsheets, manual work, agencies, internal tools, or doing nothing |
+| Why is this product meaningfully different? | TBD | Feature, workflow, data, quality, speed, trust, price, integration, or niche focus |
+| What proof supports the claim? | TBD | Demo, shipped feature, customer quote, case study, benchmark, integration, certification, or domain expertise |
+| What objections could stop signup, activation, or purchase? | TBD | Trust, cost, time, migration, privacy, compliance, risk, support, or switching cost |
+| What action should the user take next? | TBD | Signup, book demo, start workflow, invite team, connect account, import data, or contact support |
+
+## Positioning
+
+One-sentence positioning statement:
+
+> For `TBD audience` who need `TBD outcome`, this product is a `TBD category` that `TBD differentiator`, unlike `TBD alternative`.
+
+Primary value proposition:
+
+- TBD
+
+Secondary value propositions:
+
+- TBD
+- TBD
+
+Non-goals and claims to avoid:
+
+- TBD
+
+## Proof And Objections
+
+| Claim | Proof Required | Current Proof | Status |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | Missing, partial, or proven |
+
+| Objection | Response | Evidence Or Product Support |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Voice And Tone
+
+| Area | Decision |
+| --- | --- |
+| Voice traits | 3-5 traits, such as direct, expert, calm, playful, premium, practical, editorial, or technical |
+| Words to use | Product nouns, customer terms, category language, and approved phrases |
+| Words to avoid | Vague SaaS claims, unsupported AI claims, hype, jargon, or legally risky terms |
+| Error tone | Clear cause, useful recovery, no blame |
+| Security/privacy tone | Specific, factual, no invented guarantees |
+| Pricing/upgrade tone | Transparent, no hidden conditions or forced urgency |
+
+## Page And Flow Copy Inventory
+
+| Surface | Goal | Primary Message | Primary CTA | Secondary CTA | Proof | Objections |
+| --- | --- | --- | --- | --- | --- | --- |
+| Homepage hero | TBD | TBD | TBD | TBD | TBD | TBD |
+| Signup or onboarding | TBD | TBD | TBD | TBD | TBD | TBD |
+| Empty state | TBD | TBD | TBD | TBD | TBD | TBD |
+| Pricing or upgrade | Optional | Optional | Optional | Optional | Optional | Optional |
+
+## Acceptance Evidence
+
+Copy work is not accepted until:
+
+- Discovery questions are answered or explicitly marked unknown.
+- Audience, pain, outcome, differentiator, proof, objections, voice, and conversion goal are documented.
+- Claims are tied to proof or marked as assumptions.
+- CTA hierarchy has one primary action and clear secondary actions.
+- Onboarding, empty, error, permission, and upgrade copy provides a useful next step.
+- Marketing Copy Lead has handed off public-facing pages to Frontend Design Lead for layout and hierarchy review.
+- Risky claims are reviewed before release.

package/templates/next-supabase/MODEL_ROUTING.md

@@ -0,0 +1,109 @@
+# Model Routing
+
+Use this file to choose the right model profile for each agent and to record how the active AI coding tools apply those choices.
+
+Canonical source of truth:
+
+- `.agent-kit/model-routing.json`
+- `.agent-kit/schemas/model-routing.schema.json`
+- `.agent-kit/agent-roster.json`
+- `ASSISTANT_ADAPTERS.md`
+
+## Policy
+
+- Keep role behavior in `AGENTS.md`, `AGENT_ROSTER.md`, and `.agent-kit/agent-roster.json`.
+- Keep reusable skills in `SKILLS.md` and `.agent-kit/skills/`.
+- Keep model choice as a dated, reviewable routing layer.
+- Do not store secrets, API keys, billing notes, private model entitlement details, or workspace-only vendor terms in this file.
+- If an IDE cannot enforce per-agent model choice, document the limitation honestly and use the closest manual or advisory setup.
+
+## Agent Profiles
+
+| Agent | Default profile | Effort | Escalate when |
+| --- | --- | --- | --- |
+| Planner | `balanced-reasoning` | Medium | Scope affects architecture, auth, data, release, or package behavior. |
+| Lead Architect | `deep-reasoning-large-context` | High | Always for core-change council review. |
+| Supabase/Postgres Engineer | `deep-reasoning-large-context` | High | Schema, RLS, migration order, rollback, or authorization impact exists. |
+| Next.js Engineer | `coding-large-context` | Medium | Server/client boundary, caching, auth, or mutation behavior is uncertain. |
+| Frontend Design Lead | `creative-vision-large-context` | High | Significant UI, screenshots, references, content strategy, or visual QA is involved. |
+| Marketing Copy Lead | `creative-vision-large-context` | High | Positioning, value proposition, conversion copy, voice/tone, proof review, or public-facing copy handoff is involved. |
+| Security Reviewer | `deep-reasoning-large-context` | High | OWASP, IDOR, SSRF, injection, broken auth, dependency, secret, or release risk exists. |
+| QA Engineer | `balanced-reasoning` | Medium | Flaky tests, concurrency, auth flows, visual regression, or hard-to-reproduce bugs exist. |
+| Documentation Maintainer | `fast-targeted` | Low | Docs encode architecture, migrations, security, or release decisions. |
+| Deployment/Observability Engineer | `fast-targeted` | Low | Production release, rollback, env vars, logs, or incident review is involved. |
+
+## Tool Setup
+
+| Tool | Instruction surface | Model-selection status | Enforcement | Evidence |
+| --- | --- | --- | --- | --- |
+| Codex | `AGENTS.md`, `.codex/config.toml`, optional `.codex/agents/*.toml` | Unverified | Partial | Record date, owner, command/session, and active model settings. |
+| Claude Code | `CLAUDE.md`, `.claude/agents/*.md` | Unverified | Partial | Record date, owner, subagent files, and model frontmatter behavior. |
+| Cursor | `.cursor/rules/*.mdc` | Unverified | Advisory | Record date, owner, model picker/team setting, and loaded rule evidence. |
+| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Unverified | Advisory | Record date, owner, selected chat/coding-agent model, and loaded instruction evidence. |
+
+## June 2026 Commented Recommendations
+
+These are setup comments, not permanent guarantees. Verify against the active IDE and provider docs before enabling.
+
+### Codex
+
+```toml
+# ~/.codex/config.toml or trusted project .codex/config.toml
+# June 2026 Agent Kit suggestion:
+# model = "gpt-5.5"
+# model_reasoning_effort = "medium"
+#
+# For custom Codex agents, pin only where the role needs it:
+# model = "gpt-5.5"
+# model_reasoning_effort = "high"
+```
+
+### Claude Code
+
+```md
+---
+name: lead-architect
+description: Use for architecture, cross-layer changes, and core-change council review.
+# June 2026 Agent Kit suggestion:
+# model: opus
+# effort: high
+---
+```
+
+### Cursor
+
+```mdc
+---
+description: Agent Kit model-selection reminder.
+alwaysApply: true
+---
+
+<!--
+June 2026 Agent Kit suggestion:
+- Use the model picker or team model policy for the active task.
+- Prefer a deep reasoning model for Lead Architect, Security Reviewer, and Supabase/Postgres Engineer.
+- Prefer a fast/balanced coding model for Docs, Deployment, and low-risk QA passes.
+- Cursor rules advise model choice; they should not be treated as hard enforcement.
+-->
+```
+
+### GitHub Copilot
+
+```md
+<!--
+June 2026 Agent Kit suggestion:
+- Select the strongest available model for architecture, security, RLS, and release-risk review.
+- Use a faster model for docs-only or low-risk mechanical changes.
+- Repository instructions advise model choice; Copilot model selection remains tool/user controlled.
+-->
+```
+
+## Acceptance Evidence
+
+Before claiming strong or best-practice maturity, record:
+
+- Active IDE/tool and version or environment.
+- Model picker or config location.
+- Which agent profiles are enforced, partial, advisory, or manual.
+- Screenshot, command, session transcript, or PR evidence that instructions loaded.
+- Date and owner of the verification.

package/templates/next-supabase/QUALITY_GATES.md

@@ -0,0 +1,87 @@
+# Quality Gates
+
+This file defines the project maturity model. Use it to decide whether a change is merely working, strong enough for normal delivery, or best-practice ready.
+
+## Maturity Levels
+
+`agent-kit audit --json` reports one readiness verdict:
+
+- `needs-setup`: required install or council contract checks are failing.
+- `baseline-setup`: setup is valid, but starter evidence placeholders remain.
+- `needs-improvement`: no blocking failures, but warnings remain.
+- `best-practice-candidate`: static audit found no failures or warnings.
+
+Use `agent-kit audit --min-readiness <level>` in CI when the project wants a merge or release threshold. New projects usually start at `baseline-setup`; mature projects should move toward `best-practice-candidate`.
+
+### Baseline
+
+Baseline means the project is usable and the agent kit can audit it.
+
+- `AGENTS.md`, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `COUNCIL.md`, `SPEC.md`, `DECISIONS.md`, `DOCS.md`, `DESIGN.md`, `MESSAGING.md`, `MODEL_ROUTING.md`, `STYLE_GUIDE.md`, `SECURITY.md`, `TESTING.md`, `DEPLOYMENT.md`, and `UPGRADE.md` exist.
+- `.agent-kit/agent-roster.json`, `.agent-kit/model-routing.json`, and `.agent-kit/schemas/` exist.
+- `.agent-kit/assistant-adapters/` exists.
+- Agent Studio schemas for project context, correction rules, session events, and studio sessions exist when the installed kit version includes them.
+- Planner is the default planning route.
+- Lead Architect reviews core changes.
+- Security Reviewer reviews auth, RLS, dependency, secret, external-call, and release-risk changes.
+- Marketing Copy Lead reviews public-facing or conversion-facing copy, positioning, proof, objections, voice, and CTA hierarchy.
+- QA evidence is recorded before behavior changes are accepted.
+
+### Strong
+
+Strong means the project is safe for repeated team or agent delivery.
+
+- Council sessions record workflow, decision, risk, next handoff, required outputs, and evidence.
+- `.agent-kit/project-context.json` and `.agent-kit/project-context.md` capture product intent, users, workflows, auth/data assumptions, integrations, design direction, quality target, and open questions.
+- Active project and agent corrections are reviewed before implementation and are reflected in future session behavior.
+- Agent Studio sessions render current `index.md` and `transcript.md` files after visible decisions, handoffs, artifacts, corrections, or verification change.
+- Optional static Studio exports are regenerated from local files after session evidence changes and are checked for secret leakage.
+- `ASSISTANT_ADAPTERS.md` records active AI tool surfaces, model-selection status, enforcement level, and verification evidence.
+- `MODEL_ROUTING.md` records active model-selection status, dated recommendations, enforcement limits, and known IDE limitations.
+- `MESSAGING.md` captures audience, pain, desired outcome, alternatives, differentiator, proof, objections, voice, conversion goal, and copy inventory.
+- `SPEC.md` documents affected architecture, behavioral contracts, data model, RLS inventory, and critical workflows.
+- `SECURITY.md` covers OWASP Top 10, Supabase RLS, service-role isolation, secrets, IDOR prevention, dependency risk, and external-call risk.
+- `DESIGN.md` captures audience, user needs, real content, brand constraints, reference set, anti-references, creative direction, design critique verdict, distinctiveness benchmark, product-quality scorecard, design tokens, and visual QA tier.
+- `STYLE_GUIDE.md` defines component patterns, states, responsive behavior, accessibility, and anti-generic AI-site rules.
+- `TESTING.md` defines unit, regression, smoke, visual QA, accessibility, and release checks.
+- `DEPLOYMENT.md` documents environments, migrations, env vars, observability, rollback, and post-release verification.
+- `UPGRADE.md` documents diff/update flow, release notes, migration review, generated types, and rollback evidence.
+
+### Best-Practice
+
+Best-practice means evidence can survive handoff, release, and later audit.
+
+- Every meaningful change maps affected layers: data, business logic, presentation, auth, deployment, docs, and tests.
+- Multi-agent work has local Agent Studio evidence: context loaded, corrections considered, decisions and handoffs recorded, required outputs tracked, artifacts linked, verification captured, and rendered Markdown current.
+- Supabase RLS policies are inventory-backed, least-privilege, and tested for cross-user or cross-tenant access.
+- Production readiness covers Next.js routing/rendering, caching, error boundaries, metadata, accessibility, performance, security headers, and Core Web Vitals evidence.
+- Frontend work starts from brand/content intake, reference-set review, anti-references, and creative-direction options, then proves first-screen proof, content fingerprint, asset provenance, product-quality scorecard, distinctiveness, desktop, mobile, key states, keyboard flow, and visual QA evidence.
+- Public-facing and conversion-facing copy starts from discovery questions, audience, pain, outcome, differentiator, proof, objections, voice/tone, and CTA hierarchy, with unsupported claims marked as assumptions.
+- Test evidence includes the smallest useful unit/regression checks plus critical-path smoke coverage.
+- Release evidence includes install or production smoke, migration order, dependency audit, package or deployment verification, logs, and rollback notes.
+- Repo health includes issue/PR templates, CODEOWNERS, dependency updates, CodeQL or equivalent scanning, dependency review, provenance expectations, support, conduct, and governance.
+- Public or shared package releases use Trusted Publishing or equivalent identity-bound release provenance.
+
+## Change Acceptance Matrix
+
+| Change Type | Required Council | Required Evidence |
+| --- | --- | --- |
+| Planning or roadmap | Planner, Documentation Maintainer | Updated roadmap or checklist with owner, status, and acceptance evidence |
+| Core architecture | Planner, Lead Architect, QA, Docs | Affected-layer map, preserved contracts, tests, updated `SPEC.md` or `DECISIONS.md` |
+| Supabase/Auth/RLS | Lead Architect, Supabase/Postgres Engineer, Security Reviewer, QA | Migration notes, RLS inventory, negative authorization test, rollback risk |
+| Frontend/UI | Frontend Design Lead, QA, Docs | Brand/content intake, reference-set evidence, design critique verdict, distinctiveness benchmark, product-quality scorecard, creative direction, component states, accessibility, desktop/mobile visual QA |
+| Marketing/copy | Marketing Copy Lead, Frontend Design Lead, QA, Docs | `MESSAGING.md`, audience and pain, value proposition, proof, objections, voice/tone, CTA hierarchy, risky-claim review |
+| Security-sensitive | Security Reviewer, Lead Architect, QA | OWASP review, boundary validation, dependency/secret review, regression or smoke evidence |
+| Release/package | Deployment/Observability Engineer, Security Reviewer, QA, Docs | Release gate output, dependency audit, install/deploy smoke, provenance or publish identity evidence |
+| Upgrade/dependency | Planner, Lead Architect, Security Reviewer, QA, Docs, Deployment/Observability Engineer | Release notes, codemods or migration guide, `agent-kit diff`, conflict review, audit output, rollback notes |
+
+## Evidence Rules
+
+- A checklist item is not done until the evidence is linked or named.
+- A test is not evidence unless it covers the behavior, risk, or contract being claimed.
+- A screenshot is not visual QA unless it covers the important viewport, state, and content.
+- A research finding is not a best practice until it is promoted into templates, skills, checklists, audit checks, tests, release gates, or documented decisions.
+- A fresh install can be baseline setup while still warning on `TBD`, example rows, or starter instruction text; those placeholders must be replaced before claiming strong or best-practice maturity.
+- A local customization is acceptable only when `.agent-kit/overrides.json` explains why and when it was reviewed.
+- A human correction is not durable until it is stored in `.agent-kit/corrections/`, remains secret-safe, has a clear scope, and is visible to future agents through installed instructions.
+- An upgrade is not complete until `UPGRADE.md` records version changes, migration impact, rollback process, and verification evidence.

package/templates/next-supabase/SECURITY.md

@@ -0,0 +1,54 @@
+# Security
+
+Security review is required for every auth, API, data access, upload, webhook, external request, or dependency change.
+
+## OWASP Top 10 Checklist
+
+- Broken access control: verify RLS, ownership checks, admin checks, and tenant boundaries.
+- Cryptographic failures: never expose secrets or sensitive tokens.
+- Injection: validate inputs and use parameterized queries or safe client APIs.
+- Insecure design: document abuse cases before implementation.
+- Security misconfiguration: verify env vars, CORS, headers, and deployment settings.
+- Vulnerable components: review dependency additions and audit results.
+- Identification and authentication failures: test login, logout, refresh, and protected routes.
+- Software and data integrity failures: protect CI, package installs, and migrations.
+- Security logging and monitoring failures: log privileged actions and operational failures.
+- SSRF: restrict server-side fetches and validate external URLs.
+
+## Supabase Requirements
+
+- RLS must be enabled for user-owned, tenant-owned, or privileged tables.
+- RLS policies must enforce ownership and tenant boundaries.
+- UI checks are not authorization.
+- Service-role keys must never be exposed to browser code.
+- Storage buckets require explicit access policies.
+- Migrations that change authorization must include review notes.
+- `SPEC.md` must include an RLS policy inventory for every protected table and bucket.
+
+## Security Control Inventory
+
+Track project controls explicitly.
+
+| Control | Location | Owner | Verification |
+| --- | --- | --- | --- |
+| Auth middleware | TBD | TBD | Protected-route smoke test |
+| RLS policies | Supabase migrations | TBD | SQL/policy review |
+| Input validation | Forms, Server Actions, Route Handlers | TBD | Unit/integration tests |
+| Rate limiting | Public mutations and auth-sensitive routes | TBD | Abuse-case review |
+| Service-role isolation | Server-only modules | TBD | Bundle and code review |
+
+## Input And Output Boundaries
+
+- Validate form, API, webhook, query string, and route param inputs.
+- Encode or safely render user-controlled output.
+- Do not leak stack traces, tokens, SQL, or internal IDs in user-facing errors.
+
+## Secrets
+
+- Store secrets in environment configuration, not source code.
+- Keep `.env.example` documented with placeholder values only.
+- Rotate secrets after suspected exposure.
+
+## Review Notes
+
+Add security-sensitive decisions and exceptions to `DECISIONS.md`.