@appsforgood/next-supabase-kit 0.1.0

package/skills/reference-led-design-critique.md

@@ -0,0 +1,48 @@
+# Reference-Led Design Critique Skill
+
+## Use When
+
+Reviewing or designing a user-facing screen, component system, marketing surface, dashboard, tool, onboarding flow, marketplace, content page, ecommerce flow, portfolio, venue page, community surface, education product, or AI workflow UI where visual quality and product specificity matter.
+
+## Goal
+
+Prevent generic AI-looking UI by grounding design decisions in a small reference set, explicit anti-references, product content, accessibility, and a written critique verdict before implementation is accepted.
+
+## Required Inputs
+
+- `DESIGN.md` brand/content inputs and selected creative direction.
+- 3-5 category references to learn from without copying.
+- 2-3 anti-references that show what the product must not look like.
+- Real content, assets, data examples, and workflow constraints.
+- Screenshots or preview links for desktop and mobile when implementation exists.
+
+## Critique Workflow
+
+1. Identify what each reference teaches: density, hierarchy, navigation, content treatment, typography, imagery, motion, or interaction behavior.
+2. State what must not be copied: brand marks, layouts, proprietary components, exact copy, visual signatures, or protected assets.
+3. Compare the proposed UI against the chosen creative direction and product content.
+4. Score distinctiveness as `weak`, `adequate`, or `strong`.
+5. Apply the frontend product-quality scorecard for user/task fit, content specificity, visual identity, IA, states, accessibility, and source safety.
+6. Reject the work if the first screen could fit any generic product in the same category.
+7. Require the smallest useful visual QA evidence for the risk: screenshot review, Playwright screenshots, Storybook states, visual-regression baseline, or equivalent.
+
+## Reject By Default
+
+- References used as permission to copy a brand, layout, or source design.
+- One-reference design direction.
+- A UI that has tokens and states but no product-specific point of view.
+- Designs that hide missing content behind abstract gradients, fake dashboards, generic illustrations, or vague copy.
+- Screenshot evidence that omits mobile, empty, error, loading, or permission states when those states affect the workflow.
+
+## Review Output
+
+Return:
+
+- Reference set and anti-references used.
+- What was learned from each reference without copying.
+- Product-specific details that make the UI belong to this project.
+- Generic or AI-slop risks that remain.
+- Distinctiveness verdict: weak, adequate, or strong.
+- Frontend product-quality scorecard verdict and total score.
+- Required design changes before implementation or release.
+- Required screenshot, accessibility, and visual QA evidence.

package/skills/supabase-auth-rls.md

@@ -0,0 +1,20 @@
+# Supabase Auth And RLS Skill
+
+## Use When
+
+Working on Supabase Auth, SSR clients, middleware, sessions, tables, policies, Storage, or service-role operations.
+
+## Checklist
+
+- RLS is enabled on user-owned and tenant-owned tables.
+- Policies enforce ownership and tenant boundaries.
+- Service-role key is never exposed to client code.
+- Auth middleware handles session refresh safely.
+- Storage buckets have explicit policies.
+- IDOR attempts are considered and tested.
+- `SPEC.md` contains an RLS policy inventory.
+- Security-sensitive policy assumptions are recorded in `DECISIONS.md`.
+
+## Safe Default
+
+If a table stores user-specific data, assume it needs RLS before it is queried from application code.

package/skills/testing-qa.md

@@ -0,0 +1,15 @@
+# Testing And QA Skill
+
+## Use When
+
+Adding or reviewing tests, smoke checks, regression coverage, or acceptance evidence.
+
+## Checklist
+
+- Core logic has unit tests.
+- Preserved behavior has regression tests.
+- Critical user flows have Playwright smoke tests.
+- High-risk UI changes have screenshot or visual-regression evidence.
+- Auth and data mutation paths are prioritized.
+- Network failure, empty state, and error state behavior is covered.
+- Test gaps are documented when infrastructure is missing.

package/skills/upgrade-maintenance.md

@@ -0,0 +1,32 @@
+# Upgrade Maintenance Skill
+
+## Use When
+
+Upgrading Agent Kit, Next.js, Supabase, UI libraries, testing tools, release workflows, assistant adapters, or any shared package that can change project behavior.
+
+## Goal
+
+Make upgrades repeatable, reviewable, reversible, and evidence-backed.
+
+## Required Checks
+
+- Read `UPGRADE.md`, `CHANGELOG.md`, `ROADMAP.md`, and `DECISIONS.md` before changing versioned behavior.
+- Run `agent-kit diff` before accepting template changes.
+- Use `agent-kit update` only on a branch where conflicts can be reviewed.
+- Preserve valid local overrides in `.agent-kit/overrides.json`.
+- For Next.js upgrades, check official upgrade guidance and codemods.
+- For Supabase upgrades, verify migration history, RLS impact, service-role exposure, generated types, and rollback risk.
+- Run `agent-kit audit --min-readiness baseline-setup` after the upgrade.
+- Use `agent-kit audit --min-readiness best-practice-candidate` only after project-specific evidence is complete.
+- Record package versions, migration order, rollback notes, verification commands, owner, and date.
+
+## Output
+
+Return:
+
+- Upgrade scope.
+- Files and templates changed.
+- Conflicts accepted, deferred, or rejected.
+- Migration and rollback risk.
+- Verification commands and results.
+- Remaining warnings before best-practice readiness.

package/skills/visual-regression-qa.md

@@ -0,0 +1,42 @@
+# Visual Regression QA Skill
+
+## Use When
+
+Reviewing or changing user-facing UI, reusable components, app shells, dashboards, marketing pages, visual design tokens, responsive layouts, image-heavy pages, or any screen where appearance is part of the acceptance criteria.
+
+## Goal
+
+Turn visual quality from subjective review into repeatable evidence. Capture important UI states, compare them across changes, and require intentional approval for visual diffs.
+
+## Coverage Tiers
+
+- Baseline: desktop and mobile screenshots reviewed with `prompts/screenshot-review.md`.
+- Strong: Playwright screenshot checks for primary workflows and responsive breakpoints.
+- Mature: Storybook stories for reusable component states plus visual regression in CI through a tool such as Chromatic, Argos, Loki, or Playwright snapshots.
+
+## Required Checks
+
+- Primary screens have screenshot evidence for desktop and mobile.
+- Reusable components have meaningful state coverage: default, hover/focus where practical, loading, empty, error, disabled, success, permission-denied, and mobile.
+- Dynamic data, animations, dates, avatars, ads, third-party widgets, and generated media are stabilized, mocked, or masked before visual comparison.
+- Baseline updates are reviewed as product changes, not accepted automatically.
+- Visual diffs are linked in PRs, CI artifacts, or review notes.
+- Accessibility and interaction tests still run; visual diffs do not replace semantic checks.
+
+## Reject By Default
+
+- A single happy-path screenshot as final UI evidence.
+- Visual baselines updated without rationale.
+- Full-page visual snapshots that are flaky because dynamic content is uncontrolled.
+- Screenshot tests that ignore mobile, long text, empty data, or error states.
+- Treating a visual testing service as proof of good design without `DESIGN.md` and screenshot review.
+
+## Review Output
+
+Return:
+
+- Visual surfaces covered and missing.
+- Component states covered and missing.
+- Baseline/diff evidence and where it can be reviewed.
+- Flake risks and stabilization strategy.
+- Whether the visual QA tier is appropriate for the change risk.

package/templates/next-supabase/AGENTS.md

@@ -0,0 +1,138 @@
+# Agent Setup
+
+This project uses explicit agent roles so implementation, security, quality, and documentation do not collapse into one vague assistant.
+
+Use `.agent-kit/agent-roster.json` as the default council contract. Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` to choose model profiles for each agent. Before meaningful work, read `.agent-kit/project-context.json` and `.agent-kit/project-context.md` when present, then apply active corrections from `.agent-kit/corrections/project-rules.json` and `.agent-kit/corrections/agent-rules.json`. When a request is ambiguous, planning-oriented, or cross-layer, start with Planner and follow the matching workflow in `AGENT_ROSTER.md`. Use `ASSISTANT_ADAPTERS.md` to confirm which AI coding tools load these instructions and how model selection is handled. Record meaningful council sessions in `COUNCIL.md` or the local Agent Studio files under `.agent-kit/council-sessions/`.
+
+## Planner
+
+Owns planning, scope breakdown, sequencing, and council routing before implementation starts.
+
+Responsibilities:
+- Convert requests into phased, checkable work.
+- Decide whether the work is planning-only, frontend-only, security-sensitive, release-related, or a core change.
+- Select or confirm the model profile from `MODEL_ROUTING.md` before delegating complex work.
+- Route core changes to Lead Architect before implementation.
+- Name required handoffs and acceptance evidence.
+- Record council-session workflow, decision, risk, next handoff, and evidence for meaningful multi-agent work.
+- Compare proposed work against `QUALITY_GATES.md` and name the required evidence level.
+- Keep roadmap and delivery status current.
+
+## Lead Architect
+
+Owns system design, affected-layer mapping, tradeoffs, and final implementation direction.
+
+Responsibilities:
+- Confirm existing behavior before changing it.
+- Map each change across data, business logic, presentation, auth, and deployment.
+- Decide whether logic belongs in Supabase SQL/RLS, Route Handlers, Server Actions, Server Components, or client state.
+- Keep changes scoped and preserve behavioral contracts.
+
+## Next.js Engineer
+
+Owns App Router implementation, Server Components, Client Components, Route Handlers, Server Actions, forms, data loading, caching, and UI state.
+
+Responsibilities:
+- Keep server/client boundaries explicit.
+- Avoid exposing secrets or privileged data to client bundles.
+- Provide loading, error, empty, and success states.
+- Preserve accessibility and responsive behavior.
+
+## Supabase/Postgres Engineer
+
+Owns schema, migrations, RLS policies, Auth integration, Storage policies, SQL functions, triggers, indexes, and seed data.
+
+Responsibilities:
+- Enforce authorization in Postgres RLS, not only in UI code.
+- Keep service-role access server-only.
+- Add constraints and indexes that protect data integrity and performance.
+- Document migration order and rollback risks.
+
+## Security Reviewer
+
+Owns OWASP Top 10 review, auth boundary review, IDOR prevention, input validation, output encoding, SSRF prevention, dependency risk, and secret handling.
+
+Responsibilities:
+- Review all data mutations and privileged reads.
+- Verify least privilege for Supabase, API routes, automation tokens, and storage.
+- Flag unsafe dependencies or misconfiguration.
+- Ensure every failure path is explicit and observable.
+
+## Frontend Design Lead
+
+Owns content-first creative direction, visual quality, design systems, accessibility, and prevention of generic AI-looking UI.
+
+Responsibilities:
+- Maintain `DESIGN.md` as the project visual identity and content-direction contract.
+- Require audience, user needs, content inventory, brand constraints, and creative-direction options before implementation.
+- Require reference-set evidence, anti-references, source-safety notes, and a design critique verdict before accepting significant frontend work.
+- Require a frontend product-quality scorecard before accepting significant frontend work.
+- Reject generic gradient heroes, vague SaaS copy, card soup, and fake dashboard metrics.
+- Prefer task-first screens, domain-specific hierarchy, real workflow affordances, and reusable components.
+- Require visual QA evidence for important responsive screens and reusable component states.
+- Maintain WCAG 2.1 AA, keyboard navigation, focus states, and mobile-first behavior.
+- Use design adapters for Stitch, Claude, Figma, or human review when visual direction is weak.
+
+## Marketing Copy Lead
+
+Owns positioning, value proposition, conversion copy, product voice, and UX copy for public-facing or conversion-facing surfaces.
+
+Responsibilities:
+- Maintain `MESSAGING.md` as the positioning, value proposition, voice, proof, objection, and CTA contract.
+- Ask discovery questions when audience, pain, outcome, differentiator, proof, objections, voice, or conversion goal is unclear.
+- Reject vague SaaS copy, unsupported AI claims, invented proof, and headlines that could fit any competitor.
+- Translate product facts into specific headlines, CTAs, onboarding copy, empty states, pricing copy, and objection handling.
+- Handoff public-facing copy to Frontend Design Lead so layout, hierarchy, imagery, and interaction tone reinforce the message.
+- Flag risky pricing, security, privacy, compliance, financial, legal, medical, or performance claims before release.
+
+## QA Engineer
+
+Owns tests, regression coverage, smoke checks, and acceptance evidence.
+
+Responsibilities:
+- Add unit coverage for core logic and edge cases.
+- Add regression tests for preserved behavior.
+- Add Playwright smoke coverage for auth and primary workflows.
+- Add screenshot or visual-regression evidence for high-risk UI changes.
+- Report test gaps explicitly when infrastructure is missing.
+
+## Documentation Maintainer
+
+Owns living markdown docs.
+
+Responsibilities:
+- Validate handoff evidence against `COUNCIL.md` and `.agent-kit/schemas/`.
+- Update `SPEC.md`, `DECISIONS.md`, `DOCS.md`, `ASSISTANT_ADAPTERS.md`, `MODEL_ROUTING.md`, `QUALITY_GATES.md`, `DESIGN.md`, `MESSAGING.md`, `STYLE_GUIDE.md`, `SECURITY.md`, `TESTING.md`, `DEPLOYMENT.md`, and `UPGRADE.md`.
+- Record decisions with context, decision, and consequences.
+- Keep docs actionable for another engineer or agent to continue safely.
+
+## Deployment/Observability Engineer
+
+Owns deployment config, environment variables, migrations, logs, monitoring, and rollback guidance.
+
+Responsibilities:
+- Verify production-critical env vars.
+- Confirm migration and release order.
+- Ensure errors are visible through logs or monitoring.
+- Define rollback and recovery steps for risky changes.
+
+## Default Handoff
+
+Use this order for feature work:
+
+1. Planner classifies the request, maps the workflow, and names the council.
+2. Planner starts or updates an Agent Studio session with `agent-kit session start` when the work is meaningful, risky, or cross-agent, then records fallback notes in `COUNCIL.md` if CLI tooling is unavailable.
+3. Lead Architect maps affected layers and preserved behavior.
+4. Supabase/Postgres Engineer handles schema, RLS, and migrations when data/auth changes are involved.
+5. Next.js Engineer implements runtime behavior and UI.
+6. Frontend Design Lead owns content-first creative direction and reviews UX quality/accessibility when user-facing screens change.
+7. Marketing Copy Lead owns positioning, value proposition, conversion copy, product voice, and UX copy when public-facing or conversion-facing copy changes.
+8. Security Reviewer checks OWASP, auth, data boundaries, dependencies, external calls, and secrets.
+9. QA Engineer adds and runs tests.
+10. Documentation Maintainer updates living docs and council evidence.
+11. Deployment/Observability Engineer verifies release and upgrade readiness.
+12. The active agent records decisions, handoffs, corrections, artifacts, required-output status, verification, and status with `agent-kit session ...` commands, then runs `agent-kit session render` so `index.md` and `transcript.md` are current. Run `agent-kit studio export` when the user needs a local visual session view.
+
+## Council Rule
+
+Core changes cannot skip Planner or Lead Architect. Frontend changes cannot skip content/brand intake, creative-direction rationale, reference-led critique, product-quality scorecard, visual QA evidence, and Frontend Design Lead review. Public-facing or conversion-facing copy changes cannot skip Marketing Copy Lead discovery questions, value proposition, proof, objection, voice/tone, and CTA review. Auth, RLS, data mutation, dependency, secret, external-call, and release-risk changes cannot skip Security Reviewer. Behavior changes cannot skip QA evidence. Significant changes cannot skip Documentation Maintainer. Meaningful multi-agent work cannot skip a decision, risk, next-handoff, required-output status, and evidence record. Human corrections must be recorded before continuing work, and durable project or agent corrections must be applied in future sessions. Work is not best-practice ready until it satisfies the relevant `QUALITY_GATES.md` evidence level.

package/templates/next-supabase/AGENT_ROSTER.md

@@ -0,0 +1,98 @@
+# Agent Roster
+
+This project uses `.agent-kit/agent-roster.json` as the default council contract. Agents should use it before planning, implementation, review, and handoff. Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` to select model profiles for each agent. The roster contract is backed by `.agent-kit/schemas/agent-roster.schema.json`.
+
+## Default Rule
+
+Planner handles planning by default. Lead Architect reviews core changes before implementation. Frontend Design Lead owns content-first creative direction, reference-led critique, frontend distinctiveness benchmarking, product-quality scoring, and visual QA before significant frontend implementation is accepted. Marketing Copy Lead owns positioning, value proposition, public-facing copy, proof, objections, voice, and CTA hierarchy before conversion-facing copy is accepted. Security Reviewer, QA Engineer, Documentation Maintainer, and Deployment/Observability Engineer join when their trigger areas are touched. Meaningful multi-agent work records council-session evidence in `COUNCIL.md` or a structured record that follows `.agent-kit/schemas/council-session.schema.json`.
+
+## Default Workflows
+
+### Planning
+
+Use when the request asks for a plan, roadmap, phases, scope, or a breakdown.
+
+Handoff order:
+
+1. Planner
+2. Lead Architect
+3. QA Engineer
+4. Documentation Maintainer
+
+### Core Change
+
+Use when the request touches schema, auth, RLS, API behavior, Server Actions, Route Handlers, dependency changes, package behavior, upgrade workflows, release workflows, or cross-layer architecture.
+
+Handoff order:
+
+1. Planner
+2. Lead Architect
+3. Supabase/Postgres Engineer
+4. Next.js Engineer
+5. Security Reviewer
+6. QA Engineer
+7. Documentation Maintainer
+8. Deployment/Observability Engineer
+
+### Frontend Change
+
+Use when the request touches screens, components, layout, visual design, accessibility, responsiveness, or screenshot review.
+
+Handoff order:
+
+1. Planner
+2. Frontend Design Lead
+3. Marketing Copy Lead when the surface is public-facing or conversion-facing
+4. Next.js Engineer
+5. QA Engineer
+6. Documentation Maintainer
+
+Required outputs:
+
+- Brand/content intake
+- Copy/value-proposition brief when public-facing or conversion-facing
+- Creative-direction rationale
+- Reference-set evidence
+- Frontend distinctiveness benchmark
+- Design critique verdict
+- Frontend product-quality scorecard
+- Domain-specific UI rationale
+- Visual QA evidence
+- State coverage
+- Accessibility checks
+- Desktop/mobile verification
+
+### Marketing Copy
+
+Use when the request touches copy, copywriting, marketing, positioning, messaging, value proposition, landing pages, headlines, CTAs, conversion, onboarding, empty states, or pricing.
+
+Handoff order:
+
+1. Planner
+2. Marketing Copy Lead
+3. Frontend Design Lead
+4. QA Engineer
+5. Documentation Maintainer
+
+Required outputs:
+
+- Discovery questions answered or explicitly marked unknown
+- Audience and segment assumptions
+- Problem, pain, desired outcome, and value proposition
+- Differentiators, proof points, objections, and counter-messaging
+- Voice/tone guidance
+- Page or flow copy inventory
+- CTA and conversion hypothesis
+- Handoff notes for design and implementation
+
+## Handoff Rules
+
+- Each agent must state its decision, risk, and required next handoff.
+- Each meaningful council session must record workflow, affected layers, required outputs, handoff decisions, risks, evidence, and verification status.
+- Core changes cannot skip Lead Architect.
+- Frontend changes cannot skip content/brand intake, creative-direction rationale, reference-set evidence, distinctiveness benchmark, design critique verdict, product-quality scorecard, visual QA evidence, or Frontend Design Lead review.
+- Public-facing or conversion-facing copy cannot skip Marketing Copy Lead discovery questions, value proposition, proof, objection, voice/tone, and CTA review.
+- Auth, data mutation, dependency, external-call, secret, and release-risk changes cannot skip Security Reviewer.
+- Behavior changes cannot skip QA evidence.
+- Significant changes cannot skip living docs.
+- Upgrade changes cannot skip `UPGRADE.md`, conflict review, audit evidence, and rollback notes.

package/templates/next-supabase/ASSISTANT_ADAPTERS.md

@@ -0,0 +1,82 @@
+# Assistant Adapters
+
+Use this file to record how the agent council is activated in the AI coding tools used by this project.
+
+Canonical source of truth:
+
+- `AGENTS.md`
+- `AGENT_ROSTER.md`
+- `.agent-kit/agent-roster.json`
+- `MODEL_ROUTING.md`
+- `.agent-kit/model-routing.json`
+- `.agent-kit/project-context.json`
+- `.agent-kit/project-context.md`
+- `.agent-kit/corrections/project-rules.json`
+- `.agent-kit/corrections/agent-rules.json`
+- `COUNCIL.md`
+- `.agent-kit/council-sessions/`
+- `.agent-kit/schemas/council-session.schema.json`
+- `.agent-kit/schemas/studio-session.schema.json`
+- `.agent-kit/schemas/session-event.schema.json`
+- `.agent-kit/schemas/project-context.schema.json`
+- `.agent-kit/schemas/correction-rules.schema.json`
+- `QUALITY_GATES.md`
+
+## Active Tool Surfaces
+
+| Tool | Instruction surface | Instruction status | Model-selection status | Enforcement | Evidence | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| Codex / AGENTS.md-compatible tools | `AGENTS.md`, optional `.codex/config.toml`, optional `.codex/agents/*.toml` | TBD | TBD | Partial | TBD | Confirm the tool loads root `AGENTS.md`, follows council routing, and uses `MODEL_ROUTING.md` for model choice. |
+| GitHub Copilot / VS Code | `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` | TBD | TBD | Advisory | TBD | Use `.agent-kit/assistant-adapters/github-copilot-instructions.md`, `github-next-supabase.instructions.md`, and `model-selection/github-copilot-model-selection.md` as starting points. |
+| Cursor | `.cursor/rules/cursor-agent-kit.mdc` and `.cursor/rules/cursor-model-selection.mdc` | Active on init | Advisory | Advisory | `agent-kit init` copies canonical rules from `.agent-kit/assistant-adapters/`; verify in Cursor Settings > Rules that both rules load. | `agent-kit init` installs `.cursor/rules/cursor-agent-kit.mdc` and `.cursor/rules/cursor-model-selection.mdc`. Re-run `agent-kit diff` after kit updates if the canonical adapter files changed. |
+| Claude Code | `.claude/agents/*.md` and optional `CLAUDE.md` | TBD | TBD | Partial | TBD | Use `.agent-kit/assistant-adapters/claude-code-subagents.md` and `model-selection/claude-code-subagents-with-models.md` as starting points. |
+
+## Model Selection
+
+- Use `.agent-kit/model-routing.json` as the provider-neutral routing contract.
+- Use `MODEL_ROUTING.md` for dated setup comments and evidence requirements.
+- Treat exact model names as June 2026 recommendations that must be reviewed when IDE or provider docs change.
+- Do not claim per-agent model enforcement in tools where model selection is controlled by a user picker, organization policy, or hosted agent setting.
+
+## Adapter Rules
+
+- Keep `AGENTS.md`, `AGENT_ROSTER.md`, and `.agent-kit/agent-roster.json` as the source of truth.
+- Adapter files should reference the council contract; they should not fork role definitions, security policy, frontend quality rules, or release gates.
+- Agents should read project context and active correction rules before meaningful work.
+- Agents should record meaningful decisions, handoffs, human corrections, artifacts, required-output status, and verification with `agent-kit session ...` commands when the CLI is available.
+- Agents should run `agent-kit session render` after changing session evidence so Markdown views stay current.
+- Agents may run `agent-kit studio export` after rendering sessions when a local visual review page would help the user inspect collaboration.
+- Do not place secrets, tokens, credentials, private URLs, or customer data in assistant instruction files.
+- Keep commands concrete and verified. Document known failures or environment prerequisites.
+- Update this file when a tool is added, removed, or confirmed to load the project instructions.
+- Record MCP/tool connector setup separately from model-selection setup. Tool access and model choice are different controls.
+
+## Cursor Activation
+
+`agent-kit init` installs the canonical Cursor rules automatically:
+
+- `.cursor/rules/cursor-agent-kit.mdc`
+- `.cursor/rules/cursor-model-selection.mdc`
+
+Verification steps:
+
+1. Run `agent-kit init --stack next-supabase` in the target project.
+2. Confirm both files exist under `.cursor/rules/`.
+3. Open Cursor Settings > Rules and verify the rules are active for the workspace.
+4. Start a meaningful task and confirm the agent reads `AGENTS.md`, `.agent-kit/agent-roster.json`, and project context before implementation.
+5. Record the verification date, owner, and evidence path in the Active Tool Surfaces table above.
+
+If a project already customized `.cursor/rules/`, review `.agent-kit/conflicts/` after `agent-kit update` before adopting newer adapter wording.
+
+## Acceptance Evidence
+
+Before claiming strong or best-practice maturity, replace the TBD rows above with:
+
+- The active tool and instruction-surface path.
+- The active model profile or model-selection policy.
+- The enforcement level: enforced, partial, advisory, or manual.
+- The command, screenshot, PR, or session evidence proving the instructions loaded.
+- Any manual invocation needed to select the correct agent, rule, or subagent.
+- The Agent Studio session path, rendered Markdown, or audit output proving the agent read context and recorded handoff evidence.
+- Optional `.agent-kit/studio/index.html` evidence when a static local Studio export was used.
+- The date and owner of the verification.

package/templates/next-supabase/COUNCIL.md

@@ -0,0 +1,54 @@
+# Council Sessions
+
+Use this file to record agent council evidence for meaningful planning, core-change, frontend-change, security-review, release, or research work.
+
+The machine-readable roster lives at `.agent-kit/agent-roster.json`. Model profile routing lives at `.agent-kit/model-routing.json`. Project-specific context lives in `.agent-kit/project-context.json` and `.agent-kit/project-context.md`. Durable corrections live in `.agent-kit/corrections/`. Schemas live in `.agent-kit/schemas/`. For structured Agent Studio records, write session metadata to `.agent-kit/council-sessions/<session-id>/session.json`, append visible events to `events.jsonl`, and render `index.md` plus `transcript.md`. Run `agent-kit studio export` when a self-contained local HTML view is useful for inspecting sessions. Legacy structured session JSON files should follow `.agent-kit/schemas/council-session.schema.json`. Machine-readable audit output follows `.agent-kit/schemas/audit-report.schema.json`.
+
+## Session Template
+
+```md
+## YYYY-MM-DD - Short Request Name
+
+- Workflow: planning | core-change | frontend-change | security-review | release | research
+- Status: planned | in-progress | blocked | complete
+- Request: What the user asked for
+- Affected layers: data, business logic, presentation, auth, deployment, docs
+
+### Required Outputs
+
+| Output | Status | Evidence |
+| --- | --- | --- |
+| Phased checklist | Missing/Partial/Complete/N/A | Link or note |
+| Architecture decision | Missing/Partial/Complete/N/A | Link or note |
+| Security review | Missing/Partial/Complete/N/A | Link or note |
+| Test evidence | Missing/Partial/Complete/N/A | Command or report |
+| Visual QA evidence | Missing/Partial/Complete/N/A | Screenshot, Storybook, or visual diff |
+| Docs impact | Missing/Partial/Complete/N/A | Updated file |
+
+### Handoffs
+
+| Agent | Decision | Risk | Next Handoff | Evidence |
+| --- | --- | --- | --- | --- |
+| Planner | TBD | TBD | Lead Architect | TBD |
+
+### Verification
+
+| Command Or Review | Result | Notes |
+| --- | --- | --- |
+| TBD | Pass/Fail/Skipped | TBD |
+```
+
+## Rules
+
+- Every handoff must include decision, risk, next handoff, and evidence.
+- Meaningful multi-agent work should use `agent-kit session start`, `decision`, `handoff`, `correct`, `artifact`, `verify`, `output`, and `render` when the CLI is available.
+- Static Studio export is optional, but exported HTML must be regenerated after session evidence changes and must not contain secrets.
+- Structured session JSON records must pass `agent-kit audit`.
+- Agent Studio `events.jsonl` rows must stay append-only, valid JSONL, and free of secrets.
+- Required outputs must be explicitly marked `complete`, `not-applicable`, `missing`, or `partial`; do not close a session as complete while any required output is still missing or partial.
+- Core changes must include Lead Architect evidence.
+- Auth, data mutation, dependency, external-call, secret, and release-risk work must include Security Reviewer evidence.
+- User-facing frontend work must include Frontend Design Lead, reference-set evidence, design critique verdict, creative direction, accessibility, and visual QA evidence.
+- Public-facing or conversion-facing copy work must include Marketing Copy Lead evidence, discovery questions, value proposition, proof, objections, voice/tone, and CTA hierarchy.
+- Behavior changes must include QA evidence or a documented test gap.
+- Human corrections must be recorded before continuing work and promoted into durable project or agent rules when they should affect future sessions.

package/templates/next-supabase/DECISIONS.md

@@ -0,0 +1,45 @@
+# Decisions
+
+Record architectural, technical, security, release, and design-direction decisions here.
+
+## Template
+
+```md
+## YYYY-MM-DD - Decision Title
+
+### Context
+
+What problem, constraint, or tradeoff forced this decision?
+
+### Decision
+
+What did we choose?
+
+### Consequences
+
+What becomes easier, harder, safer, or riskier because of this decision?
+
+### Follow-Up
+
+What should be revisited later?
+```
+
+## Active Decisions
+
+Add new decisions above this line or keep newest first.
+
+Record major frontend choices here when a creative direction, reference set, anti-reference, brand constraint, information architecture, visual QA tier, or component-system rule materially affects implementation.
+
+## Agent Kit Model Routing
+
+### Context
+
+AI coding tools differ in whether repository files can enforce per-agent model selection.
+
+### Decision
+
+Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` as the provider-neutral source for agent model profiles. Record IDE-specific setup and limitations in `ASSISTANT_ADAPTERS.md`.
+
+### Consequences
+
+Exact model names remain dated recommendations, while agents keep stable profile intent and evidence requirements.

package/templates/next-supabase/DEPLOYMENT.md

@@ -0,0 +1,45 @@
+# Deployment
+
+## Environments
+
+Document each environment:
+
+- Local
+- Preview
+- Production
+
+## Environment Variables
+
+Document required variables with placeholder examples only.
+
+Required Supabase variables usually include:
+
+- `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+- Server-only service-role key when needed
+
+## Migration Order
+
+Before deploying code that depends on database changes:
+
+1. Review migration safety.
+2. Apply schema and RLS changes.
+3. Verify policies and constraints.
+4. Deploy application code.
+5. Run smoke tests.
+
+## Observability
+
+Document:
+
+- Application logs
+- Supabase logs
+- Error reporting
+- Cron or background jobs
+- Alerting expectations
+
+## Rollback
+
+Document rollback steps for code, database migrations, and environment variable mistakes.
+
+Link upgrade-specific rollback evidence from `UPGRADE.md` when the release includes package, framework, Agent Kit, or migration changes.