@appsforgood/next-supabase-kit 0.1.0

package/assistant-adapters/github-copilot-instructions.md

@@ -0,0 +1,35 @@
+# Repository Instructions
+
+This repository uses Agent Kit. Treat `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/`, and `QUALITY_GATES.md` as the source of truth for agent routing, project context, correction rules, model profiles, quality gates, and handoff evidence.
+
+## Workflows
+
+- Planning, phased roadmap, or ambiguous work starts with Planner.
+- Core changes require Lead Architect before implementation.
+- Frontend changes require Frontend Design Lead, brand/content intake, creative-direction rationale, visual QA evidence, state coverage, accessibility checks, and desktop/mobile verification.
+- Auth, RLS, data mutations, dependency changes, external calls, secrets, and release risk require Security Reviewer.
+- Behavior changes require QA evidence.
+- Significant changes require Documentation Maintainer updates.
+- Meaningful work should read local project context and active correction rules before implementation.
+- User corrections should be recorded before continuing, then applied to future sessions when durable.
+- Meaningful multi-agent work should record visible decisions, handoffs, artifacts, and verification in Agent Studio session files when available.
+
+## Validation
+
+Before proposing completion, run the repo's documented checks. For projects installed from this kit, the minimum setup check is:
+
+```sh
+agent-kit audit --min-readiness baseline-setup
+```
+
+Use a stronger gate before claiming best-practice readiness:
+
+```sh
+agent-kit audit --min-readiness best-practice-candidate
+```
+
+Do not claim best-practice readiness while starter placeholders remain in `COUNCIL.md`, `SPEC.md`, `DESIGN.md`, `SECURITY.md`, `TESTING.md`, `DEPLOYMENT.md`, or `ASSISTANT_ADAPTERS.md`.
+
+## Model Selection
+
+Use the active Copilot model selector or organization policy with `MODEL_ROUTING.md`. Repository instructions advise model choice but should not be treated as hard enforcement where Copilot keeps model selection user-controlled.

package/assistant-adapters/github-next-supabase.instructions.md

@@ -0,0 +1,28 @@
+---
+applyTo: "app/**/*.{ts,tsx},src/app/**/*.{ts,tsx},pages/**/*.{ts,tsx},src/pages/**/*.{ts,tsx},components/**/*.{ts,tsx},lib/**/*.{ts,tsx},utils/**/*.{ts,tsx},supabase/**/*,*.sql"
+---
+
+# Next.js + Supabase Agent Kit Instructions
+
+Follow `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/`, and `QUALITY_GATES.md`.
+
+## Next.js
+
+- Keep Server Component, Client Component, Route Handler, and Server Action boundaries explicit.
+- Do not expose secrets, service-role keys, privileged queries, or admin-only data to client bundles.
+- Preserve loading, empty, error, disabled, success, focus, and mobile states for user-facing changes.
+
+## Supabase
+
+- Enforce authorization with Postgres RLS where applicable.
+- Treat service-role access as server-only.
+- Document migration order, rollback risk, indexes, constraints, and policy changes.
+
+## Council Routing
+
+- Schema, auth, RLS, API behavior, dependency, and release changes require Lead Architect and Security Reviewer handoff.
+- UI changes require Frontend Design Lead evidence before implementation is accepted.
+- Behavior changes require QA evidence and living-doc updates.
+- Use the model profile in `MODEL_ROUTING.md`; treat Copilot model selection as advisory unless the active tool surface can enforce it.
+- Read project context and active corrections before changing behavior.
+- Record visible decisions, handoffs, human corrections, artifacts, and verification with Agent Studio session commands when available.

package/assistant-adapters/model-selection/claude-code-subagents-with-models.md

@@ -0,0 +1,32 @@
+# Claude Code Subagents With Model Notes
+
+Use this as a starter for `.claude/agents/*.md` files. Keep the canonical role definitions in `AGENTS.md` and `AGENT_ROSTER.md`.
+
+```md
+---
+name: lead-architect
+description: Use for core architecture, cross-layer changes, package behavior, and technical decisions.
+# June 2026 Agent Kit suggestion:
+# model: opus
+# effort: high
+---
+
+Read `AGENTS.md`, `AGENT_ROSTER.md`, `MODEL_ROUTING.md`, `.agent-kit/agent-roster.json`, and `.agent-kit/model-routing.json`.
+
+Review affected layers, preserved behavior, security impact, test plan, docs impact, and required council handoffs before implementation.
+```
+
+```md
+---
+name: frontend-design-lead
+description: Use for creative direction, reference-led critique, frontend distinctiveness, product-quality scorecards, and visual QA.
+# June 2026 Agent Kit suggestion:
+# model: opus
+# effort: high
+---
+
+Use `DESIGN.md`, `STYLE_GUIDE.md`, `MODEL_ROUTING.md`, and the frontend skills before accepting significant UI work.
+Reject generic AI-looking UI that is not specific to the product content, workflow, audience, and state model.
+```
+
+Record the actual Claude Code behavior, model field support, date, and owner in `ASSISTANT_ADAPTERS.md`.

package/assistant-adapters/model-selection/codex-config.example.toml

@@ -0,0 +1,29 @@
+# Codex model-selection example for Agent Kit.
+# Copy the relevant comments into ~/.codex/config.toml or a trusted project .codex/config.toml.
+# Verify current model availability in your Codex environment before uncommenting.
+
+# June 2026 Agent Kit suggested baseline:
+# model = "gpt-5.5"
+# model_reasoning_effort = "medium"
+
+# Use high reasoning for Lead Architect, Security Reviewer, and Supabase/Postgres Engineer
+# when spawning custom Codex agents or starting dedicated review threads.
+# model_reasoning_effort = "high"
+
+# Optional custom-agent files can live under .codex/agents/*.toml.
+# Keep each custom agent narrow and point it back to:
+# - AGENTS.md
+# - AGENT_ROSTER.md
+# - .agent-kit/agent-roster.json
+# - MODEL_ROUTING.md
+# - .agent-kit/model-routing.json
+
+# Example custom-agent fragment:
+# name = "lead-architect"
+# description = "Architecture and core-change council review."
+# model = "gpt-5.5"
+# model_reasoning_effort = "high"
+# developer_instructions = """
+# Read AGENTS.md, AGENT_ROSTER.md, MODEL_ROUTING.md, and .agent-kit/agent-roster.json.
+# Review affected layers, preserved behavior, tradeoffs, security impact, test plan, and docs impact.
+# """

package/assistant-adapters/model-selection/cursor-model-selection.mdc

@@ -0,0 +1,24 @@
+---
+description: Agent Kit model-selection reminder for Cursor.
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# Agent Kit Model Selection
+
+Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` when choosing a model for the active task.
+
+## June 2026 Recommendations
+
+<!--
+Cursor model selection is controlled by the user, workspace, model picker, or team policy.
+This rule advises routing; it should not be treated as hard enforcement.
+-->
+
+- Use a deep reasoning model for Lead Architect, Security Reviewer, Supabase/Postgres Engineer, migrations, RLS, auth, dependencies, release risk, and cross-layer decisions.
+- Use a strong coding model with large context for Next.js Engineer work across App Router, Server Actions, Route Handlers, forms, caching, and UI state.
+- Use a creative/vision-capable model for Frontend Design Lead work, especially screenshot critique, references, and distinctiveness benchmarking.
+- Use a fast or balanced model for low-risk docs, deployment notes, and repeated QA summaries.
+
+Record the selected Cursor model, rule evidence, date, owner, and limitations in `ASSISTANT_ADAPTERS.md`.

package/assistant-adapters/model-selection/github-copilot-model-selection.md

@@ -0,0 +1,20 @@
+# GitHub Copilot Model Selection
+
+Repository instructions can advise model choice, but model selection remains controlled by the Copilot surface, organization policy, and the user's active model picker.
+
+Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` before starting agentic work.
+
+## June 2026 Recommendations
+
+<!--
+Select the strongest available Copilot model for architecture, security, Supabase RLS, migrations, release risk, and ambiguous planning.
+Select a faster available model for docs-only cleanup, narrow test triage, or low-risk repeated checks.
+These comments are dated setup guidance, not a guarantee that Copilot will enforce model choice from repository files.
+-->
+
+## Evidence To Record
+
+- Copilot surface used: chat, edit, coding agent, PR review, or other.
+- Active model or organization policy, if visible.
+- Instruction file loaded: `.github/copilot-instructions.md` or `.github/instructions/*.instructions.md`.
+- Date, owner, and known limitations.

package/checklists/accessibility.md

@@ -0,0 +1,12 @@
+# Accessibility Checklist
+
+- Semantic HTML used first.
+- ARIA used only when needed.
+- Keyboard navigation works.
+- Focus states are visible.
+- Color contrast meets WCAG 2.1 AA.
+- Forms have labels and error messages.
+- Custom controls expose state.
+- Content does not rely only on color or motion.
+- Critical flows have keyboard-only smoke coverage.
+- Accessibility tooling or manual checks are documented in `TESTING.md`.

package/checklists/agent-council.md

@@ -0,0 +1,13 @@
+# Agent Council Checklist
+
+- `.agent-kit/agent-roster.json` exists and matches the expected default council contract.
+- `.agent-kit/schemas/agent-roster.schema.json` exists for roster validation.
+- `.agent-kit/schemas/council-session.schema.json` exists for structured session evidence.
+- Planner starts planning, roadmap, ambiguous, and cross-layer requests.
+- Lead Architect reviews core changes before implementation.
+- Security Reviewer joins auth, data mutation, dependency, external-call, secret, and release-risk work.
+- Frontend Design Lead joins user-facing frontend work with creative direction and visual QA evidence.
+- QA Engineer verifies behavior changes before completion.
+- Documentation Maintainer updates living docs when behavior, architecture, release, or standards change.
+- Every handoff records decision, risk, next handoff, and evidence.
+- Missing required outputs are marked missing or partial rather than hidden.

package/checklists/brand-content.md

@@ -0,0 +1,15 @@
+# Brand And Content Checklist
+
+- Product category is named.
+- Primary audience and user needs are written in user language.
+- Real content inventory exists: nouns, labels, records, data fields, examples, and assets.
+- First screen is tied to a real task, object, or workflow.
+- Brand personality has 3-5 visible traits.
+- Existing logo, colors, fonts, platform conventions, and accessibility constraints are captured.
+- Category references are used for learning only; no source is copied.
+- Non-goals name visual tropes, copy patterns, palettes, or layouts to avoid.
+- Anti-references are explicit enough to prevent generic AI-site defaults.
+- Source-safety notes name brand marks, layouts, copy, or assets that must not be copied.
+- At least two creative directions were considered before implementation.
+- Chosen direction affects tokens, layout, copy, imagery, and interaction tone.
+- Missing content or assets are documented instead of hidden behind generic placeholders.

package/checklists/deployment.md

@@ -0,0 +1,10 @@
+# Deployment Checklist
+
+- Required env vars are present.
+- Server-only secrets are not exposed.
+- Migrations are applied in the right order.
+- RLS and Storage policies are verified.
+- Build passes.
+- Smoke tests pass.
+- Logs and monitoring are checked.
+- Rollback steps are documented.

package/checklists/design-critique.md

@@ -0,0 +1,13 @@
+# Design Critique Checklist
+
+- `DESIGN.md` includes a reference set and anti-references.
+- References are used for learning, not copying.
+- Source-safety notes identify brand marks, layouts, copy, or assets that must not be copied.
+- The first screen shows the product's real task, object, content, or workflow.
+- The chosen creative direction is visible in typography, layout, density, color, imagery, copy, and interaction tone.
+- Distinctiveness verdict is recorded as weak, adequate, or strong.
+- Frontend product-quality scorecard records user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety.
+- Generic AI-site risks are explicitly accepted, changed, or rejected.
+- Desktop and mobile screenshots or previews were reviewed.
+- Important empty, loading, error, disabled, success, and permission states were reviewed.
+- Accessibility and visual QA evidence match the risk of the UI change.

package/checklists/frontend-distinctiveness.md

@@ -0,0 +1,12 @@
+# Frontend Distinctiveness Checklist
+
+- First viewport shows the real product object, task, workflow, content, or decision.
+- Product nouns, labels, data shapes, records, actions, and edge cases are visible or documented.
+- Reference benchmark includes 3-5 references with lessons to learn.
+- Anti-references include 2-3 category tropes, palettes, layouts, copy patterns, or interaction habits to avoid.
+- Source-safety notes explain what must not be copied from references.
+- At least two creative directions were compared before implementation.
+- Asset provenance is recorded for real, generated, licensed, and placeholder visuals.
+- Loading, empty, error, disabled, success, permission, and focus states are covered where relevant.
+- Desktop and mobile evidence exists, plus visual QA for high-risk screens.
+- A design cannot pass if it would still work unchanged for another product in the same category.

package/checklists/frontend-product-quality.md

@@ -0,0 +1,13 @@
+# Frontend Product Quality Checklist
+
+- User/task fit score is at least `1`, and preferably `2`.
+- Content specificity score is at least `1`, and preferably `2`.
+- Visual identity score explains why the result fits this product rather than a generic category.
+- Information architecture score covers primary and secondary workflows.
+- Component state score covers important loading, empty, error, disabled, success, permission, and focus states.
+- Accessibility and interaction score covers keyboard path, focus, contrast, labels, reduced motion, and error feedback.
+- Source-safety score confirms references were learned from, not copied.
+- Total score is at least `10/14` before acceptance.
+- Best-practice claim requires at least `12/14`, no critical zeroes, desktop/mobile screenshot review, and visual QA evidence.
+- Best-practice claim also requires frontend distinctiveness benchmark evidence: first-screen proof, content fingerprint, reference benchmark, asset provenance, state proof, and visual QA proof.
+- `DESIGN.md` records the scorecard verdict and required changes.

package/checklists/frontend-quality.md

@@ -0,0 +1,20 @@
+# Frontend Quality Checklist
+
+- First screen shows the actual product or task.
+- `DESIGN.md` includes product category, audience, user needs, content inventory, brand constraints, and creative direction.
+- Brand/content intake was completed before visual implementation.
+- At least two creative directions were considered.
+- Reference set, anti-references, and source-safety notes are recorded.
+- Design critique verdict is adequate or strong before release.
+- Frontend product-quality scorecard is at least adequate before release.
+- Visual direction fits the domain.
+- No generic AI-site gradient/card defaults.
+- Navigation is clear and predictable.
+- Loading, empty, error, disabled, and success states exist.
+- Mobile layout is designed, not incidental.
+- Component spacing, type, and density are consistent.
+- Forms are accessible and provide useful feedback.
+- Design tokens cover color, typography, spacing, radius, motion, depth, state color, and focus treatment.
+- A product-specific design brief has been used for SaaS, admin, marketplace, content, tool, ecommerce, portfolio/venue, education, community/social, or AI workflow surfaces.
+- Desktop and mobile screenshots have been reviewed with `prompts/screenshot-review.md`.
+- Visual QA tier is documented for high-risk UI changes.

package/checklists/marketing-copy.md

@@ -0,0 +1,11 @@
+# Marketing And Copy Checklist
+
+- `MESSAGING.md` identifies audience, pain, desired outcome, alternatives, differentiator, proof, objections, voice, and conversion goal.
+- Missing positioning inputs are asked as explicit questions before final copy is written.
+- Claims are supported by named proof or marked as assumptions.
+- Headline, subhead, CTA, proof, and objection handling match the same value proposition.
+- Copy uses real product nouns, workflows, constraints, and customer language.
+- CTAs have one primary action and clear secondary actions.
+- Onboarding, empty, error, upgrade, and permission copy provide a useful next step.
+- Risky claims around pricing, privacy, security, compliance, performance, medical, financial, or legal topics are reviewed before release.
+- Marketing Copy Lead hands off to Frontend Design Lead for public-facing layout and visual hierarchy.

package/checklists/owasp.md

@@ -0,0 +1,12 @@
+# OWASP Checklist
+
+- Broken access control: RLS, ownership, tenant boundary, admin checks.
+- Cryptographic failures: secrets, tokens, PII, transport security.
+- Injection: SQL, command, template, prompt, and header injection.
+- Insecure design: abuse cases and missing security controls.
+- Misconfiguration: env vars, CORS, headers, storage, public buckets.
+- Vulnerable components: dependency additions and audit status.
+- Auth failures: login, logout, refresh, session expiry, protected routes.
+- Integrity failures: CI, package installs, migrations, webhooks.
+- Logging failures: errors visible without leaking secrets.
+- SSRF: external URL validation and egress restrictions.

package/checklists/rls.md

@@ -0,0 +1,10 @@
+# Supabase RLS Checklist
+
+- RLS enabled on every user-owned or tenant-owned table.
+- Policies exist for each required operation.
+- Policies enforce `auth.uid()` or tenant membership.
+- Admin policies are explicit and least-privilege.
+- Storage buckets have policies.
+- Service-role use is isolated to server-only code.
+- IDOR attempts are tested.
+- Policy assumptions are documented.

package/checklists/testing.md

@@ -0,0 +1,12 @@
+# Testing Checklist
+
+- Unit tests cover core logic.
+- Regression tests preserve existing behavior.
+- Playwright smoke tests cover critical paths.
+- Visual QA evidence exists for high-risk UI changes.
+- Auth, admin, and data mutations are prioritized.
+- Empty/error/loading states are covered where practical.
+- Test gaps and residual risks are documented.
+- CI gates are documented and match the commands used by the project.
+- Playwright smoke coverage exists for the primary workflow before release.
+- Visual baseline updates require human review and rationale when visual-regression tooling exists.

package/checklists/upgrade.md

@@ -0,0 +1,13 @@
+# Upgrade Checklist
+
+- [ ] Branch created before upgrade work.
+- [ ] Release notes, changelog, or migration guide reviewed.
+- [ ] `agent-kit diff` reviewed before template updates.
+- [ ] `agent-kit update` run only after preserving local work.
+- [ ] `.agent-kit/conflicts/` reviewed.
+- [ ] `.agent-kit/overrides.json` updated for accepted local deviations.
+- [ ] Next.js codemods or manual upgrade steps reviewed when framework behavior changes.
+- [ ] Supabase migration history, RLS impact, generated types, and rollback risk reviewed when data/auth changes.
+- [ ] Tests, smoke checks, visual QA, or release checks run for affected areas.
+- [ ] `agent-kit audit --min-readiness baseline-setup` passes.
+- [ ] Upgrade evidence, rollback notes, owner, and date recorded in `UPGRADE.md`.

package/checklists/visual-regression.md

@@ -0,0 +1,11 @@
+# Visual Regression Checklist
+
+- Visual QA tier is documented: baseline screenshots, Playwright screenshots, Storybook visual tests, or visual-regression service.
+- Desktop and mobile screenshots exist for primary screens.
+- Reusable components have state stories or screenshot cases for default, loading, empty, error, disabled, success, permission-denied, and mobile states.
+- Dynamic or volatile regions are mocked, masked, frozen, or excluded with rationale.
+- Baseline updates require human review and a short rationale.
+- CI or review notes link to screenshot artifacts, Storybook, Chromatic, Argos, Playwright report, or equivalent evidence.
+- Visual checks cover at least one narrow/mobile viewport and one desktop viewport.
+- Visual checks do not replace accessibility, keyboard, semantic, auth, or data-boundary tests.
+- Known visual QA gaps are recorded in `TESTING.md` before release.

package/design-adapters/claude-design.prompt.md

@@ -0,0 +1,27 @@
+# Claude Design Review Brief
+
+Review or generate UI direction for this product.
+
+Context:
+
+- DESIGN.md: `{{design_md}}`
+- Product: `{{product}}`
+- Users: `{{users}}`
+- Primary task: `{{primary_task}}`
+- Current risk: `{{design_risk}}`
+
+Output:
+
+- Design critique.
+- Brand/content gaps.
+- Creative-direction options or selected-direction critique.
+- Reference-set, anti-reference, and source-safety critique.
+- Frontend product-quality scorecard across user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety.
+- Improved information architecture.
+- Component inventory.
+- Mobile and desktop layout guidance.
+- Accessibility notes.
+- Copy improvements.
+- States for loading, empty, error, disabled, and success.
+
+Reject generic AI-site patterns and prefer product-specific workflow clarity.

package/design-adapters/figma.prompt.md

@@ -0,0 +1,18 @@
+# Figma Design Brief
+
+Create a Figma-ready design direction.
+
+Include:
+
+- DESIGN.md brand/content inputs and creative-direction matrix.
+- Reference set, anti-references, and source-safety notes.
+- Product-quality scorecard requirements and acceptance threshold.
+- Page structure.
+- Component list.
+- Design tokens.
+- Responsive behavior.
+- Form and control states.
+- Accessibility requirements.
+- Notes for handoff to implementation.
+
+Avoid generic AI-site visual defaults and prioritize the real product workflow.

package/design-adapters/google-stitch.prompt.md

@@ -0,0 +1,36 @@
+# Google Stitch Design Brief
+
+Use this brief to generate distinct interface directions from real product content and brand constraints.
+
+DESIGN.md context:
+`{{design_md}}`
+
+Project type:
+`{{project_type}}`
+
+Audience:
+`{{audience}}`
+
+Primary workflow:
+`{{primary_workflow}}`
+
+Design requirements:
+
+- Create three distinct directions unless `DESIGN.md` already selects one.
+- Create mobile and desktop screens.
+- Show real workflow states.
+- Use domain-specific hierarchy.
+- Tie tokens, layout, copy, imagery, density, and interaction tone to the selected content and audience.
+- Use the reference set for learning only and respect all anti-references and source-safety notes.
+- Return a product-quality scorecard covering user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety.
+- Include design tokens.
+- Include empty, loading, error, disabled, and success states.
+- Meet WCAG 2.1 AA.
+
+Avoid:
+
+- Generic purple-blue gradients.
+- Abstract card dashboards.
+- Fake metrics.
+- Vague SaaS copy.
+- Placeholder landing pages.

package/design-adapters/human-designer-brief.prompt.md

@@ -0,0 +1,36 @@
+# Human Designer Brief
+
+## Product
+
+`{{product}}`
+
+## Audience
+
+`{{audience}}`
+
+## Primary Workflow
+
+`{{primary_workflow}}`
+
+## Design Context
+
+`{{design_md}}`
+
+## What We Need
+
+- Domain-specific visual direction.
+- Brand/content gaps and creative-direction recommendation.
+- Reference-set critique, anti-references, and source-safety concerns.
+- Product-quality scorecard with acceptance verdict.
+- Mobile and desktop screens.
+- Design tokens.
+- Component states.
+- Accessibility review.
+- Notes for implementation.
+
+## Avoid
+
+- Generic AI-generated SaaS visuals.
+- Placeholder copy.
+- Fake data.
+- Unclear primary action.

package/design-briefs/admin-dashboard.md

@@ -0,0 +1,21 @@
+# Admin Dashboard Design Brief
+
+Use this brief for internal tools, ops consoles, moderation queues, analytics, and support workflows.
+
+## Product Signals
+
+- First screen should prioritize active work, exceptions, stale items, and operational health.
+- Avoid oversized hero copy, decorative gradients, and promotional layout patterns.
+- Show filters, saved views, bulk actions, and audit trails where relevant.
+
+## Required States
+
+- Loading, empty, filtered-empty, error, partial-data, disabled, success, and permission-denied states.
+- Dense desktop workflow and usable mobile read/review mode.
+- Confirmation and undo patterns for destructive actions.
+
+## Design Direction
+
+- Favor calm information density, sticky table affordances, visible status language, and predictable controls.
+- Use color sparingly for severity, freshness, ownership, and action state.
+- Every chart or metric needs a label, source, timestamp, and empty/error fallback.

package/design-briefs/ai-workflow-product.md

@@ -0,0 +1,25 @@
+# AI Workflow Product Design Brief
+
+Use when designing AI assistants, automation tools, generation workflows, review queues, prompt tools, eval dashboards, agent consoles, or human-in-the-loop products.
+
+## First Screen
+
+Show the real work loop: input, context, model/agent state, output, review, approval, correction, or history. Do not hide the product behind a generic "AI-powered" hero.
+
+## Required Inputs
+
+- User role: operator, reviewer, creator, analyst, developer, admin, or end customer.
+- AI workflow: input sources, context, tools, model calls, outputs, approvals, retries, and audit trail.
+- Trust needs: citations, uncertainty, permissions, rate limits, cost, privacy, and rollback.
+- Human control points: edit, approve, reject, compare, regenerate, escalate, or export.
+
+## Avoid
+
+- Chat box as the only interface when the workflow needs structure.
+- Fake model confidence or fake analytics.
+- Magical language that hides limitations, costs, or review responsibility.
+- Outputs without provenance, status, or recovery path.
+
+## Required States
+
+Queued, streaming, partial output, failed tool call, hallucination report, needs review, approved, rejected, regenerated, rate limited, permission denied, audit trail, mobile review.

package/design-briefs/community-social.md

@@ -0,0 +1,26 @@
+# Community Or Social Design Brief
+
+Use when designing communities, forums, social feeds, member directories, messaging, comments, creator tools, clubs, or collaborative spaces.
+
+## First Screen
+
+Show the community's real activity, topics, people, norms, or contribution path. Avoid generic feed layouts that could belong to any network.
+
+## Required Inputs
+
+- Member types and participation goals.
+- Content types: posts, comments, events, projects, resources, profiles, messages, reactions.
+- Moderation and safety model.
+- Trust, reputation, privacy, consent, and notification rules.
+- Community tone: expert, casual, local, professional, creator-led, support-focused.
+
+## Avoid
+
+- Fake engagement metrics.
+- Infinite feeds without prioritization or safety states.
+- Profile cards with no real identity or contribution signals.
+- Missing empty states for new or quiet communities.
+
+## Required States
+
+New community empty state, muted/blocked/report states, moderation pending, deleted content, private content, notification overload, mobile composer, slow/offline posting.

package/design-briefs/content-app.md

@@ -0,0 +1,21 @@
+# Content App Design Brief
+
+Use this brief for publishing tools, editorial systems, knowledge bases, newsletters, and media products.
+
+## Product Signals
+
+- First screen should show the reading, editing, curation, or review workflow.
+- Avoid generic blog landing pages unless the request is a public marketing surface.
+- Make authorship, freshness, source, status, and editorial workflow visible.
+
+## Required States
+
+- Draft, scheduled, published, archived, review-needed, empty, loading, error, and success states.
+- Reader preferences, search, filtering, and mobile reading layout.
+- Source attribution and unavailable-media fallbacks.
+
+## Design Direction
+
+- Typography and spacing carry the design; do not over-rely on cards.
+- Support scanning with summaries, metadata, sectioning, and predictable hierarchy.
+- Tokens must define body text, display text, captions, links, code, and focus states.

package/design-briefs/ecommerce.md

@@ -0,0 +1,25 @@
+# Ecommerce Design Brief
+
+Use when designing storefronts, product detail pages, carts, checkout flows, merchandising tools, subscriptions, or order-management screens.
+
+## First Screen
+
+Show real product/category inventory, price or availability context, and the next buying or management action. Do not open with generic lifestyle marketing unless the request is explicitly a campaign page.
+
+## Required Inputs
+
+- Product categories, product attributes, variants, inventory, and fulfillment constraints.
+- Buyer goal: browse, compare, buy, reorder, subscribe, gift, or manage orders.
+- Trust signals: returns, shipping, warranty, reviews, security, stock, seller credibility.
+- Asset rules for product photography, thumbnails, swatches, badges, and empty inventory.
+
+## Avoid
+
+- Fake bestseller metrics.
+- Generic ecommerce grid with placeholder products.
+- Decorative hero sections that hide product inspection.
+- Checkout or cart states without error, unavailable, quantity, tax, shipping, and payment edge cases.
+
+## Required States
+
+Loading, empty category, no search results, variant unavailable, out of stock, price changed, cart error, payment error, order success, return/refund state, mobile product inspection.