@appsforgood/next-supabase-kit 0.1.5 → 0.1.7

package/templates/next-supabase/DECISIONS.md

@@ -44,6 +44,20 @@ Runtime command files are adapters. `AGENTS.md`, `.agent-kit/agent-roster.json`,
 
 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

package/templates/next-supabase/DESIGN.md

@@ -103,6 +103,7 @@ Run `.agent-kit/prompts/frontend-distinctiveness-benchmark.md` before accepting
 | 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:
 
@@ -166,6 +167,8 @@ Frontend work is not accepted until the following evidence exists:
 - 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.

package/templates/next-supabase/DOCS.md

@@ -42,6 +42,8 @@ Document primary workflows, including:
 - Planning and core-change handoffs from `AGENT_ROSTER.md`
 - Tool-specific assistant activation from `ASSISTANT_ADAPTERS.md`
 - Runtime command validation with `agent-kit adapter validate antigravity` when Antigravity is active
+- UI improvement command workflows from `.agent-kit/prompts/ui-command-index.md`
+- Deterministic UI detector and acceptance review from `.agent-kit/checklists/ui-detectors.md` and `.agent-kit/checklists/ui-acceptance-rubric.md`
 - Model-selection setup, enforcement status, and limitations from `MODEL_ROUTING.md`
 - Council-session evidence capture from `COUNCIL.md`
 - Upgrade review, conflict handling, migration review, and rollback evidence from `UPGRADE.md`
@@ -57,7 +59,9 @@ Document primary workflows, including:
 - Data creation and update workflow
 - Deployment workflow
 
-Runtime command files are adapters only. Native commands such as `/plan`, `/security`, `/frontend`, `/copy`, `/handoff`, `/audit`, `/setup`, `/upgrade`, and `/ship` should point back to `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, `.agent-kit/skills/`, and Agent Studio evidence.
+Runtime command files are adapters only. Native commands such as `/plan`, `/security`, `/frontend`, `/ui-audit`, `/ui-polish`, `/layout-cleanup`, `/responsive-cleanup`, `/accessibility-pass`, `/distinctiveness-pass`, `/screenshot-critique`, `/browser-qa`, `/copy`, `/handoff`, `/audit`, `/setup`, `/upgrade`, and `/ship` should point back to `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, `.agent-kit/skills/`, and Agent Studio evidence.
+
+High-risk UI work must include desktop and mobile screenshots plus authenticated or permission-state evidence when the surface requires login, roles, tenant context, or permissions.
 
 ## Integration Points
 

package/templates/next-supabase/QUALITY_GATES.md

@@ -56,7 +56,7 @@ Best-practice means evidence can survive handoff, release, and later audit.
 - Multi-agent work has local Agent Studio evidence: context loaded, corrections considered, decisions and handoffs recorded, required outputs tracked, artifacts linked, verification captured, and rendered Markdown current.
 - Supabase RLS policies are inventory-backed, least-privilege, and tested for cross-user or cross-tenant access.
 - Production readiness covers Next.js routing/rendering, caching, error boundaries, metadata, accessibility, performance, security headers, and Core Web Vitals evidence.
-- Frontend work starts from brand/content intake, reference-set review, anti-references, and creative-direction options, then proves first-screen proof, content fingerprint, asset provenance, product-quality scorecard, distinctiveness, desktop, mobile, key states, keyboard flow, and visual QA evidence.
+- Frontend work starts from brand/content intake, reference-set review, anti-references, and creative-direction options, then proves first-screen proof, content fingerprint, asset provenance, product-quality scorecard, distinctiveness, UI detector findings, desktop, mobile, key states, keyboard flow, and visual QA evidence.
 - Public-facing and conversion-facing copy starts from discovery questions, audience, pain, outcome, differentiator, proof, objections, voice/tone, and CTA hierarchy, with unsupported claims marked as assumptions.
 - Test evidence includes the smallest useful unit/regression checks plus critical-path smoke coverage.
 - Release evidence includes install or production smoke, migration order, dependency audit, package or deployment verification, logs, and rollback notes.
@@ -71,7 +71,7 @@ Best-practice means evidence can survive handoff, release, and later audit.
 | Planning or roadmap | Planner, Documentation Maintainer | Updated roadmap or checklist with owner, status, and acceptance evidence |
 | Core architecture | Planner, Lead Architect, QA, Docs | Affected-layer map, preserved contracts, tests, updated `SPEC.md` or `DECISIONS.md` |
 | Supabase/Auth/RLS | Lead Architect, Supabase/Postgres Engineer, Security Reviewer, QA | Migration notes, RLS inventory, negative authorization test, rollback risk |
-| Frontend/UI | Frontend Design Lead, QA, Docs | Brand/content intake, reference-set evidence, design critique verdict, distinctiveness benchmark, product-quality scorecard, creative direction, component states, accessibility, desktop/mobile visual QA |
+| Frontend/UI | Frontend Design Lead, QA, Docs | Brand/content intake, reference-set evidence, design critique verdict, distinctiveness benchmark, product-quality scorecard, creative direction, UI detector severity findings, component states, accessibility, desktop/mobile visual QA, authenticated screen evidence when applicable |
 | Marketing/copy | Marketing Copy Lead, Frontend Design Lead, QA, Docs | `MESSAGING.md`, audience and pain, value proposition, proof, objections, voice/tone, CTA hierarchy, risky-claim review |
 | Security-sensitive | Security Reviewer, Lead Architect, QA | OWASP review, boundary validation, dependency/secret review, regression or smoke evidence |
 | Release/package | Deployment/Observability Engineer, Security Reviewer, QA, Docs | Release gate output, dependency audit, install/deploy smoke, provenance or publish identity evidence |
@@ -83,6 +83,8 @@ Best-practice means evidence can survive handoff, release, and later audit.
 - A checklist item is not done until the evidence is linked or named.
 - A test is not evidence unless it covers the behavior, risk, or contract being claimed.
 - A screenshot is not visual QA unless it covers the important viewport, state, and content.
+- A UI detector pass is not complete until blockers, majors, minors, accepted exceptions, screenshots, viewport, auth state, and data state are named.
+- A high-risk UI change is not accepted while blocker detector findings remain or authenticated workflow evidence is missing.
 - A research finding is not a best practice until it is promoted into templates, skills, checklists, audit checks, tests, release gates, or documented decisions.
 - A runtime command is not canonical policy; it is accepted only when it wraps `AGENTS.md`, `.agent-kit/agent-roster.json`, `QUALITY_GATES.md`, canonical skills, and Agent Studio evidence.
 - A fresh install can be baseline setup while still warning on `TBD`, example rows, or starter instruction text; those placeholders must be replaced before claiming strong or best-practice maturity.

package/templates/next-supabase/SKILLS.md

@@ -108,6 +108,20 @@ Required checks:
 - Use the matching `.agent-kit/design-briefs/*` brief for SaaS, admin, marketplace, content, tool, ecommerce, portfolio/venue, education, community/social, or AI workflow surfaces.
 - Review final desktop and mobile screenshots with `.agent-kit/prompts/screenshot-review.md`.
 
+## UI Improvement Harness
+
+Use for operational UI audit, polish, layout cleanup, responsive cleanup, accessibility pass, screenshot critique, visual distinctiveness pass, and live browser QA loops.
+
+Required checks:
+- Use `.agent-kit/prompts/ui-command-index.md` to pick the workflow: UI audit, UI polish, layout cleanup, responsive cleanup, accessibility pass, distinctiveness pass, screenshot critique, or browser QA.
+- Run `.agent-kit/checklists/ui-detectors.md` and classify findings as blocker, major, minor, pass, or not applicable.
+- Apply `.agent-kit/checklists/ui-acceptance-rubric.md` before release.
+- Require desktop and mobile screenshot evidence for meaningful UI changes.
+- Require authenticated or permission-state evidence for protected app screens.
+- Block release when blocker detector findings remain.
+- Fix major findings or document accepted exceptions before high-risk UI changes ship.
+- Record route, viewport, auth state, data state, screenshots, detector findings, and residual risks.
+
 ## Content-First Creative Direction
 
 Use before designing or changing a user-facing site, product screen, dashboard, tool, marketplace, content experience, ecommerce flow, portfolio, venue page, education product, community surface, or AI workflow UI.

package/templates/next-supabase/SPEC.md

@@ -25,6 +25,7 @@ List behavior that must be preserved during changes:
 - Agent council routing in `.agent-kit/agent-roster.json`
 - Model profile routing in `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`
 - Optional runtime adapter commands and portable `SKILL.md` wrappers, when activated
+- UI improvement command workflows, detector severity findings, and acceptance rubric when frontend work is in scope
 - Council-session evidence in `COUNCIL.md`
 - Agent, council-session, model-routing, and audit-report schema contracts in `.agent-kit/schemas/`
 - Planner default ownership for planning and Lead Architect review for core changes
@@ -70,7 +71,7 @@ Record the current maturity target and evidence.
 | Architecture | TBD | TBD | TBD | Affected-layer map, `DECISIONS.md` |
 | Supabase/RLS | TBD | TBD | TBD | RLS inventory, migration tests |
 | Messaging | TBD | TBD | TBD | `MESSAGING.md`, proof map, objection handling, CTA hierarchy |
-| Frontend | TBD | TBD | TBD | `DESIGN.md`, reference-set evidence, design critique verdict, product-quality scorecard, screenshots, visual QA |
+| Frontend | TBD | TBD | TBD | `DESIGN.md`, reference-set evidence, design critique verdict, product-quality scorecard, UI detector findings, screenshots, visual QA |
 | Testing | TBD | TBD | TBD | Unit, regression, smoke, visual evidence |
 | Release | TBD | TBD | TBD | `DEPLOYMENT.md`, logs, rollback notes |
 
@@ -83,6 +84,8 @@ Record the current maturity target and evidence.
 - Audience, pain, desired outcome, differentiator, proof, objections, voice, and CTA hierarchy are documented before public-facing or conversion-facing copy is accepted.
 - Reference set, anti-references, source-safety notes, and design critique verdict are documented before accepting significant frontend work.
 - Frontend product-quality scorecard is documented before accepting significant frontend work.
+- UI detector findings are classified before accepting meaningful audit, polish, layout, responsive, accessibility, screenshot, distinctiveness, or browser QA work.
+- Authenticated or permission-state screenshots are reviewed when the changed surface requires login, roles, tenant context, or permissions.
 - First screens show the real product, task, object, content, or workflow.
 
 ## Brand And Content Inventory
@@ -102,6 +105,7 @@ Track the inputs that make the UI specific to this product.
 | Chosen creative direction | TBD | Creative-direction matrix and screenshots |
 | Design critique verdict | TBD | `DESIGN.md`, critique-gate review |
 | Visual QA tier | TBD | `TESTING.md`, Storybook, Playwright report, visual-regression service, or screenshot artifacts |
+| UI detector evidence | TBD | `.agent-kit/checklists/ui-detectors.md`, `.agent-kit/checklists/ui-acceptance-rubric.md`, browser QA notes |
 
 ## Component And State Inventory
 

package/templates/next-supabase/STYLE_GUIDE.md

@@ -51,7 +51,9 @@ Use `.agent-kit/prompts/design-critique-gate.md` before accepting significant fr
 
 Use `.agent-kit/prompts/frontend-distinctiveness-benchmark.md` before accepting significant frontend work. `DESIGN.md` should prove first-screen specificity, content fingerprint, reference benchmark, asset provenance, state proof, and visual QA proof so a design cannot pass while remaining interchangeable with another product in the same category.
 
-Use `.agent-kit/prompts/frontend-product-quality-scorecard.md` before accepting significant frontend work. `DESIGN.md` should score user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety. Reject work with critical zeroes or a total score below `10/14`; reserve best-practice claims for `12/14` or higher with desktop/mobile and visual QA evidence.
+Use `.agent-kit/prompts/frontend-product-quality-scorecard.md` before accepting significant frontend work. `DESIGN.md` should score user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety. Reject work with critical zeroes or a total score below `10/14`; reserve best-practice claims for `12/14` or higher with desktop/mobile, authenticated screen evidence when applicable, UI detector findings, and visual QA evidence.
+
+Use `.agent-kit/prompts/ui-command-index.md`, `.agent-kit/checklists/ui-detectors.md`, and `.agent-kit/checklists/ui-acceptance-rubric.md` for UI audit, polish, layout cleanup, responsive cleanup, accessibility pass, distinctiveness pass, screenshot critique, and browser QA loops.
 
 ## Messaging And Copy Rules
 

package/templates/next-supabase/TESTING.md

@@ -9,6 +9,7 @@ Testing should be proportional to risk. Auth, data mutations, payments, admin ac
 - Integration tests for API, Server Actions, and Supabase interactions where practical.
 - Playwright smoke tests for auth and critical user workflows.
 - Visual QA for important user-facing screens and reusable component states.
+- UI detector review for audit, polish, layout, responsive, accessibility, screenshot, distinctiveness, and browser QA workflows.
 - Runtime adapter validation for plugin manifests, native commands, portable `SKILL.md` wrappers, source-of-truth references, package allowlists, and secret safety.
 
 ## Critical Smoke Paths
@@ -35,6 +36,8 @@ Choose the smallest reliable visual QA tier for the project:
 Required rules:
 
 - Capture default, loading, empty, error, disabled, success, permission-denied, and mobile states where relevant.
+- Run `.agent-kit/checklists/ui-detectors.md` for meaningful UI audit or polish work and classify blocker, major, minor, pass, and not-applicable findings.
+- High-risk UI changes require desktop and mobile screenshots plus authenticated or permission-state evidence when the workflow requires login, tenant context, roles, or permissions.
 - Stabilize dynamic data, animations, dates, avatars, generated media, and third-party widgets before visual comparison.
 - Review baseline updates as product changes; do not auto-accept visual diffs without rationale.
 - Keep accessibility, semantic, keyboard, auth, and data-boundary tests separate from visual checks.
@@ -53,6 +56,7 @@ Recommended baseline:
 - `agent-kit audit --min-readiness baseline-setup`
 - Playwright smoke tests for critical paths
 - Visual QA evidence for high-risk UI changes
+- UI detector findings and accepted exceptions for meaningful UI changes
 - `agent-kit adapter validate antigravity` and `agent-kit package validate` when adapter/package assets change
 
 ### Eval-driven PR loop