@appsforgood/next-supabase-kit 0.2.1 → 0.4.0

package/templates/next-supabase/AGENT_ROSTER.md

@@ -1,101 +0,0 @@
-# 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, UI detector severity review, command-based UI polish/audit loops, 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, screenshot review, UI audit, UI polish, or browser QA.
-
-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
-- UI detector findings and severity
-- UI command workflow applied when polishing or auditing
-- Visual QA evidence
-- State coverage
-- Accessibility checks
-- Desktop/mobile verification
-- Authenticated screen evidence when applicable
-
-### 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, UI detector severity review, 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

@@ -1,146 +0,0 @@
-# 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/orchestrator.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`
-- `.agent-kit/schemas/orchestrator.schema.json`
-- `.agent-kit/schemas/runtime-run.schema.json`
-- `.agent-kit/schemas/runtime-event.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`, `.codex/config.toml`, `.codex/agents/*.toml` | TBD | TBD | Partial | TBD | Run `agent-kit init --activate codex` to generate council custom agents and copy `.codex/config.toml`. |
-| GitHub Copilot / VS Code | `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` | TBD | TBD | Advisory | TBD | Run `agent-kit init --activate copilot` to promote Copilot instruction files. |
-| Cursor | `.cursor/rules/*.mdc`, `.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md` | Active on init (rules); subagents on `--activate cursor` | Advisory | Partial | Run `agent-kit init --activate cursor`; verify subagents. | Delegate to `.cursor/agents/` instead of role-playing the council. |
-| Claude Code | `.claude/agents/*.md` and optional `CLAUDE.md` | TBD | TBD | Partial | TBD | Run `agent-kit init --activate claude` to generate subagents from `.agent-kit/agent-roster.json` and install `CLAUDE.md`. |
-| Antigravity | `.antigravity/agent-kit/plugin.json`, `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/SKILL.md` | TBD | TBD | Advisory | TBD | Run `agent-kit init --activate antigravity`, then `agent-kit adapter validate antigravity`; optional native validation is `agy plugin validate` when available. |
-| Agent Kit Runtime | `.agent-kit/orchestrator.json`, `@appsforgood/agent-kit-runtime`, `agent-kit orchestrate ...` | Disabled by default | Enforced aliases and capability gates when active | Enforced local graph and approval policy | TBD | This is the executable council. IDE adapters above remain instruction surfaces. |
-
-## 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.
-- Do not claim an orchestrated run from IDE delegation alone. Require runtime status, events, checkpoint, and scoped commit evidence.
-
-## Executable Runtime
-
-Install `@appsforgood/agent-kit-runtime`, configure credential references and deterministic aliases in `.agent-kit/orchestrator.json`, then run:
-
-```bash
-agent-kit orchestrate validate
-agent-kit orchestrate plan "Describe the goal"
-agent-kit orchestrate run "Describe the goal"
-agent-kit orchestrate approve <run-id>
-agent-kit orchestrate status <run-id>
-```
-
-Runs use explicit roster sequences, SQLite checkpoints, risk-tiered approvals, redacted JSONL evidence, an isolated Git worktree, Docker-first mutations, and an optional approved Cursor host executor. The runtime may create one scoped commit; it never merges, pushes, or opens a pull request. See `.agent-kit/assistant-adapters/orchestrator-runtime.md`.
-
-## 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.
-
-Run `agent-kit init --activate cursor` to generate `.cursor/agents/*.md` and `.cursor/skills/*/SKILL.md` from the roster and kit skills.
-
-## Multi-agent delegation
-
-Same council playbook across IDEs — delegate to specialists instead of role-playing every role in one thread.
-
-| Risk / work | Cursor | Codex | Claude Code |
-| --- | --- | --- | --- |
-| Auth / RLS / secrets | `@security-reviewer` or Task `security-review` | spawn `security-reviewer.toml` | `@security-reviewer` |
-| Planning / scope | `@planner` | spawn `planner.toml` | `@planner` |
-| Frontend UI | `@frontend-design-lead` | spawn `frontend-design-lead.toml` | `@frontend-design-lead` |
-| QA / behavior changes | `@qa-engineer` or Task `bugbot` | spawn `qa-engineer.toml` | `@qa-engineer` |
-
-Record evidence with `agent-kit session checkpoint --file <json>` when the CLI is available.
-
-## Codex Activation
-
-`agent-kit init --activate codex` installs:
-
-- `.codex/config.toml`
-- `.codex/agents/*.toml` council custom agents with `model_reasoning_effort` from `.agent-kit/model-routing.json`
-
-Validate with `agent-kit adapter validate codex`.
-
-## Antigravity Activation
-
-`agent-kit init --activate antigravity` installs a native runtime adapter without changing the canonical Agent Kit operating model:
-
-- `.antigravity/agent-kit/plugin.json`
-- `.antigravity/agent-kit/commands/*.toml`
-- `.antigravity/runtime-skills/*/SKILL.md`
-- `.antigravity/agent-kit/README.md`
-
-Validate the structural package with:
-
-```bash
-agent-kit adapter validate antigravity
-```
-
-If the local machine has the Antigravity CLI, teams may also run native plugin validation and record that evidence here. Runtime command files are adapters only; `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, `.agent-kit/prompts/ui-command-index.md`, `.agent-kit/checklists/ui-detectors.md`, and Agent Studio sessions remain canonical.
-
-The frontend adapter surface includes `/frontend` plus focused UI improvement commands: `/ui-audit`, `/ui-polish`, `/layout-cleanup`, `/responsive-cleanup`, `/accessibility-pass`, `/distinctiveness-pass`, `/screenshot-critique`, and `/browser-qa`. These commands invoke existing Frontend Design Lead, QA, accessibility, screenshot, and documentation gates; they do not replace the council workflow.
-
-## 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

@@ -1,54 +0,0 @@
-# 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

@@ -1,87 +0,0 @@
-# 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.
-
-## Runtime Adapter Rule
-
-### Context
-
-Agent Kit may expose runtime-native command surfaces such as Antigravity plugin commands.
-
-### Decision
-
-Runtime command files are adapters. `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, canonical `.agent-kit/skills/`, and Agent Studio session records remain the source of truth.
-
-### Consequences
-
-Native commands improve invocation ergonomics, but project policy, security gates, handoff rules, model routing, and documentation contracts stay centralized in Agent Kit files.
-
-## UI Improvement Harness Rule
-
-### Context
-
-Frontend work needs repeatable audit, polish, screenshot, responsive, accessibility, distinctiveness, and browser QA loops rather than one-off taste review.
-
-### Decision
-
-Use `.agent-kit/prompts/ui-command-index.md`, `.agent-kit/checklists/ui-detectors.md`, `.agent-kit/checklists/ui-acceptance-rubric.md`, and `.agent-kit/skills/ui-improvement-harness.md` as the source of truth for UI improvement commands and detector severity.
-
-### Consequences
-
-Meaningful UI work must classify blocker, major, and minor findings, require desktop and mobile screenshot evidence, and include authenticated or permission-state evidence for protected screens.
-
-## 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.
-
-## Optional Executable Orchestrator
-
-### Context
-
-IDE rules and subagents provide advisory council routing but are not proof that an executable, resumable workflow ran.
-
-### Decision
-
-Keep `.agent-kit/orchestrator.json` disabled by default. When programmatic execution is required, install `@appsforgood/agent-kit-runtime`, validate deterministic aliases and credential references, and use its bounded LangGraph, SQLite checkpoint, approval, MCP, Docker, worktree, and redacted-evidence contracts. Permit at most one approved scoped commit; retain merge, push, pull request, deployment, and migration decisions for the operator.
-
-### Consequences
-
-The project can opt into stronger execution enforcement without making provider credentials or native runtime dependencies part of baseline Agent Kit use. Host execution and private network exceptions require explicit local rationale and approval evidence.

package/templates/next-supabase/DEPLOYMENT.md

@@ -1,49 +0,0 @@
-# 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
-
-Optional Agent Kit runtime provider credentials must be referenced with `env:` names or OS-keychain entries. Do not copy resolved values into `.agent-kit/orchestrator.json`, deployment config, run evidence, or CI logs.
-
-## 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.
-
-If an orchestrated run produced a worktree or scoped commit, record the run ID, branch, commit, approval decisions, whether any migration/deploy command actually ran, and the manual keep/remove/merge decision. The runtime does not perform that repository or deployment step automatically.
-
-Link upgrade-specific rollback evidence from `UPGRADE.md` when the release includes package, framework, Agent Kit, or migration changes.

package/templates/next-supabase/DESIGN.md

@@ -1,180 +0,0 @@
-# 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.
-
-Common visual tropes to reject unless a mature brand system explicitly requires them:
-
-- Accent-border cards, glow rails, neon strokes, gradient borders, and one-sided colored panel borders.
-- Generic gradient heroes, gradient text, abstract blobs, card soup, oversized rounded glass panels, and ornamental icon walls.
-- Fake dashboard metrics, decorative credibility badges, vague SaaS sayings, filler "features / benefits / how it works" sections, and color-only status styling.
-
-## 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 |
-| UI detector proof | `.agent-kit/checklists/ui-detectors.md` completed with blocker, major, minor, pass, and not-applicable findings |
-
-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.
-- UI detector findings were classified and blockers were resolved.
-- Authenticated or permission-state screenshots were reviewed when the changed surface requires login, roles, tenant context, or permissions.
-- 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.