@appsforgood/next-supabase-kit 0.3.0 → 0.4.0

package/templates/next-supabase/AGENTS.md

@@ -1,140 +1,30 @@
-# Agent Setup
+# Agents
 
-This project uses explicit agent roles so implementation, security, quality, and documentation do not collapse into one vague assistant.
+This repo uses a small specialist pack. **Agent** = who. **Skill** = how. **Tool** = what they must use.
 
-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`, `.agent-kit/project-context.md`, and `.agent-kit/agent-briefs.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/`.
+Read `USER_GUIDE.md` for how to invoke these in Cursor, Claude, Codex, Copilot, and Antigravity.
 
-When `.agent-kit/orchestrator.json` is enabled, treat `agent-kit orchestrate validate`, plan/status output, approvals, runtime events, and worktree/commit state as the executable source of truth. IDE delegation is not proof that the graph ran. Never bypass a paused approval, capability mismatch, Docker/host policy, or the runtime rule that forbids automatic merge, push, pull request, deployment, and migration application.
+## Screenshot rule
 
-## Planner
+A user-visible change is not done until someone opened the running UI, captured desktop and mobile screenshots, and reviewed those images. Reading TSX is not QA.
 
-Owns planning, scope breakdown, sequencing, and council routing before implementation starts.
+## Who to ask
 
-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.
+| Ask | Agent |
+| --- | --- |
+| Plan, scope, who owns this | `@planner` |
+| Implement Next.js or Supabase | `@app-engineer` |
+| Auth, RLS, secrets, OWASP | `@security` |
+| UI looks wrong / generic | `@design` |
+| Is this done? | `@qa` |
+| Headlines, CTAs, empty states | `@copy` |
 
-## Lead Architect
+Do not ask one chat to be all six.
 
-Owns system design, affected-layer mapping, tradeoffs, and final implementation direction.
+## Handoff
 
-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.
+Planner names the owner. Security joins auth/data/secret work. Design joins user-facing screens. QA joins any behavior or UI change and **must use the browser**. Copy joins public/conversion copy. Stop there.
 
-## Next.js Engineer
+## Skills
 
-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.
+Default skills live in `.cursor/skills/*/SKILL.md` (and the matching Claude/Codex/Antigravity copies). QA of a screen always uses `browser-qa`, not `testing-qa` alone.

package/templates/next-supabase/CLAUDE.md

@@ -1,39 +1,7 @@
-# Claude Code Project Instructions
+# Claude Code
 
-This repository uses Agent Kit. Treat the following as the source of truth for council routing, project context, correction rules, model profiles, quality gates, and handoff evidence:
+This repo uses a small agent and skill pack. Read `AGENTS.md` and `USER_GUIDE.md`.
 
-- `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/agent-briefs.md` when present
-- `.agent-kit/corrections/project-rules.json`
-- `.agent-kit/corrections/agent-rules.json`
-- `COUNCIL.md`
-- `.agent-kit/council-sessions/`
-- `QUALITY_GATES.md`
+Subagents live in `.claude/agents/`. Use the matching subagent instead of one generic thread.
 
-## Subagents
-
-Project subagents live in `.claude/agents/*.md` and are generated from `.agent-kit/agent-roster.json` when you run:
-
-```sh
-agent-kit init --activate claude
-```
-
-Use the matching subagent for the active workflow instead of treating every request as a generic implementation pass.
-
-## Validation
-
-```sh
-agent-kit audit --min-readiness baseline-setup
-```
-
-Use `agent-kit session checkpoint --file <json>` to batch-record council evidence instead of many individual session commands.
-
-## Model Selection
-
-Use Claude Code model settings with the profiles in `MODEL_ROUTING.md`. Exact model names are dated recommendations — review when provider docs change.
+A user-visible change is not done until someone opened the running UI, captured desktop and mobile screenshots, and reviewed those images. If you cannot open a browser, use the Playwright fallback in `skills/browser-qa/SKILL.md`.

package/BEST_PRACTICE_EVIDENCE.md

@@ -1,45 +0,0 @@
-# Best-Practice Evidence Matrix
-
-This repository treats the 100-repo research pass as input, not proof. A practice only counts as part of the kit when it is promoted into at least one durable artifact and one validation path.
-
-## Evidence Rule
-
-- Research findings identify repeated gaps or strong patterns.
-- Promoted behavior must appear in installed templates, agents, skills, checklists, schemas, prompts, or repository workflows.
-- Validation must exist through audit checks, schema contracts, tests, release gates, install smoke, or documented external repository settings.
-- Fresh installs are only `baseline-setup` until project-specific evidence replaces starter placeholders.
-
-## Promotion Matrix
-
-| Research signal | Scan evidence | Promoted behavior | Installed or repo artifact | Validation path |
-| --- | --- | --- | --- | --- |
-| Supabase/Auth/RLS expectations are often weak or hard to discover. | 88 of 100 findings had weak or non-discoverable Supabase/Auth/RLS signals. | Make RLS, auth boundaries, service-role isolation, and migration review explicit defaults. | `templates/next-supabase/SECURITY.md`, `templates/next-supabase/SPEC.md`, `skills/supabase-auth-rls.md`, `skills/postgres-migrations.md`, `checklists/rls.md`. | `agent-kit audit`, template hash checks, install smoke, public-readiness tests. |
-| Agent handoff and AI-workflow contracts are immature. | 66 of 100 findings had immature agent handoff or AI-workflow signals. | Require Planner-first routing, Lead Architect ownership for core changes, council handoffs, and evidence records. | `rosters/next-supabase-default-council.json`, `templates/next-supabase/COUNCIL.md`, `schemas/agent-roster.schema.json`, `schemas/council-session.schema.json`, `skills/planning-council.md`, `skills/agent-handoff-tracing.md`. | Roster schema validation, council-session schema validation, `agent-kit audit`, `tests/audit.test.ts`, `tests/public-readiness.test.ts`. |
-| Agent instructions need to load in the tools teams actually use. | Follow-up review of current Codex/AGENTS.md, GitHub Copilot, VS Code, Cursor, and Claude Code instruction surfaces showed that each tool has its own activation path. | Keep the council roster as the source of truth and ship thin adapters for AGENTS.md-compatible tools, Copilot instructions, Cursor rules, and Claude Code subagents. | `templates/next-supabase/ASSISTANT_ADAPTERS.md`, `assistant-adapters/*`, `AGENTS.md`, `AGENT_ROSTER.md`, `.agent-kit/agent-roster.json`. | `agent-kit audit`, public-readiness tests, install smoke, project-specific adapter evidence. |
-| Reusable kits need a safe upgrade lifecycle. | Follow-up review of framework and tooling upgrade practices showed repeated use of upgrade guides, codemods, migration history, diff flows, release notes, and rollback evidence. | Separate initial install from upgrade review and require diff, update, migration, audit, release-note, and rollback evidence. | `UPGRADE.md`, `templates/next-supabase/UPGRADE.md`, `skills/upgrade-maintenance.md`, `checklists/upgrade.md`, `prompts/upgrade-review.md`. | `agent-kit audit`, public-readiness tests, install smoke, release check. |
-| Accessibility evidence is commonly too implicit. | 57 of 100 findings had weak accessibility signals. | Make WCAG-oriented review part of frontend and QA work instead of a late checklist. | `skills/accessibility-wcag.md`, `checklists/accessibility.md`, `checklists/frontend-quality.md`, `templates/next-supabase/TESTING.md`, `templates/next-supabase/STYLE_GUIDE.md`. | Public-readiness tests, install smoke, project maturity evidence in `QUALITY_GATES.md`. |
-| Security expectations are often incomplete. | 54 of 100 findings had implicit or incomplete security expectations. | Treat OWASP, least privilege, input validation, output encoding, dependency risk, and disclosure process as release concerns. | `agents/security-reviewer.md`, `skills/owasp-security-review.md`, `checklists/owasp.md`, `SECURITY.md`, `.github/workflows/codeql.yml`, `.github/workflows/dependency-review.yml`. | `npm audit --audit-level=moderate`, Dependency Review, CodeQL, public-readiness tests, release check. |
-| Reusable components and tokens do not prevent generic AI-looking UI. | Follow-up design review found frontend scoring over-weighted components, tokens, and states. | Require content-first creative direction, brand/content intake, real workflow screens, and screenshot evidence. | `templates/next-supabase/DESIGN.md`, `skills/content-first-design.md`, `skills/frontend-design-system.md`, `agents/frontend-design-lead.md`, `prompts/brand-content-intake.md`, `prompts/creative-direction-matrix.md`, `design-briefs/*`. | Frontend-change roster requirements, `agent-kit audit`, public-readiness tests, screenshot review prompt. |
-| Frontend critique needs reference and distinctiveness evidence. | Follow-up review of design-system and component-state practices showed that strong primitives and screenshots do not prove a product-specific visual direction. | Require reference sets, anti-references, source-safety notes, and a written design critique verdict before accepting significant frontend work. | `skills/reference-led-design-critique.md`, `prompts/design-critique-gate.md`, `checklists/design-critique.md`, `templates/next-supabase/DESIGN.md`, `rosters/next-supabase-default-council.json`. | Frontend-change roster requirements, `agent-kit audit`, public-readiness tests, install smoke. |
-| Frontend distinctiveness needs proof, not taste. | Focused follow-up review of design-system, service-design, content, accessibility, and visual-testing guidance showed that a polished UI can still be interchangeable without first-screen proof, content fingerprint, safe reference learning, asset provenance, state proof, and visual QA proof. | Require a frontend distinctiveness benchmark before accepting significant UI work. | `skills/frontend-distinctiveness-benchmark.md`, `prompts/frontend-distinctiveness-benchmark.md`, `checklists/frontend-distinctiveness.md`, `templates/next-supabase/DESIGN.md`, `rosters/next-supabase-default-council.json`, `research/summaries/frontend-distinctiveness-benchmark-patterns.md`. | Frontend-change roster requirements, `agent-kit audit`, public-readiness tests, install smoke. |
-| Frontend acceptance needs a repeatable product-quality threshold. | Focused follow-up review of design-system, service-design, component-state, and accessibility guidance showed that good primitives do not prove product-specific quality. | Score significant UI work against user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety. | `skills/frontend-product-quality-rubric.md`, `prompts/frontend-product-quality-scorecard.md`, `checklists/frontend-product-quality.md`, `templates/next-supabase/DESIGN.md`, `rosters/next-supabase-default-council.json`. | Frontend-change roster requirements, `agent-kit audit`, public-readiness tests, install smoke. |
-| Visual QA needs a path beyond manual taste review. | Follow-up visual-testing review identified Storybook, Playwright screenshots, Chromatic, Argos, Loki, and baseline evidence as repeatable patterns. | Provide visual QA tiers that scale from screenshot review to regression evidence. | `skills/visual-regression-qa.md`, `checklists/visual-regression.md`, `prompts/visual-qa-plan.md`, `templates/next-supabase/TESTING.md`. | Public-readiness tests, `QUALITY_GATES.md` maturity evidence, downstream visual QA artifacts. |
-| Public OSS maintainability needs more than a package tarball. | Repository-health follow-up identified structured intake, ownership, labels, support, and governance as durable signals. | Ship contributor intake, labels, CODEOWNERS, support, conduct, governance, and repository settings guidance. | `.github/ISSUE_TEMPLATE/*`, `.github/pull_request_template.md`, `.github/CODEOWNERS`, `.github/labels.yml`, `SUPPORT.md`, `GOVERNANCE.md`, `REPOSITORY_SETTINGS.md`. | Public-readiness tests, PR labeler workflow, documented branch and repository settings. |
-| Supply-chain trust must be visible before publish. | Supply-chain follow-up identified OIDC publishing, provenance, dependency review, Scorecard, SBOMs, workflow controls, and release gates. | Use Trusted Publishing, avoid long-lived npm publish tokens, generate and attest a package-rooted CycloneDX SBOM for every tarball, and verify each public package before creating the source release. | `.github/workflows/release.yml`, `.github/workflows/scorecard.yml`, `.github/workflows/dependency-review.yml`, `SUPPLY_CHAIN.md`, `scripts/release-check.mjs`, `scripts/sbom-check.mjs`. | `npm run release:check`, root/runtime SBOM checks, OpenSSF Scorecard, Dependency Review, npm Trusted Publishing, SBOM attestations, pack dry runs. |
-| Best-practice claims need a maturity model. | Follow-up review showed a green build alone does not prove best-practice readiness. | Separate setup validity from project evidence and best-practice candidacy. | `templates/next-supabase/QUALITY_GATES.md`, `schemas/audit-report.schema.json`, `skills/best-practice-maturity-review.md`, `src/install/audit.ts`. | `agent-kit audit --min-readiness`, audit-report schema validation, install smoke, release check. |
-| Downstream adoption evidence must stay current. | Current read-only dogfood audits of two older installs both produced `11 pass / 20 warn / 7 fail`, proving that later hardening made older installs drift below baseline setup. | Publish a sanitized dogfood summary and keep detailed local-path evidence repo-only. Treat stale dogfood findings as upgrade inputs. | `DOGFOOD.md`, `dogfood/*.md`, `UPGRADE.md`, `agent-kit audit`, `agent-kit update`, `tests/public-readiness.test.ts`. | Public-readiness tests, release check, read-only dogfood audit snapshots, package dry run. |
-| Older installs need a conflict-safe upgrade proof. | Dogfood audits showed both older installs lacked current roster schemas, assistant adapters, maturity gates, upgrade docs, and design critique assets. | Add a deterministic old-install fixture that proves diff previews missing/conflicting assets and update adds missing current assets while preserving customized docs through conflicts. | `tests/update.test.ts`, `src/install/diff.ts`, `src/install/install.ts`, `UPGRADE.md`, `DOGFOOD.md`. | Unit tests, audit report on upgraded fixture, release check. |
-| Public examples must not drift from CLI behavior. | Repeated package hardening changed installed docs, roster messages, manifest hashes, and audit output. Hand-maintained examples can look trustworthy while going stale. | Regenerate a clean install with the built CLI and compare committed example roster, stable manifest fields, audit output, and tree summary before release. | `examples/next-supabase-installed/*`, `scripts/example-check.mjs`, `scripts/release-check.mjs`. | `npm run examples:check`, `npm run release:check`, public-readiness tests. |
-| Package version metadata must agree before release. | Public npm release workflows can publish a package whose lockfile, changelog, or GitHub tag no longer matches `package.json`. | Validate SemVer shape, package-lock root version, changelog section, and release tag before release gates proceed. | `scripts/version-check.mjs`, `package.json`, `package-lock.json`, `CHANGELOG.md`, `.github/workflows/release.yml`. | `npm run version:check`, `npm run release:check`, public-readiness tests. |
-
-## What This Does Not Claim
-
-- A fresh install is not a completed best-practice project.
-- The kit does not copy source code, policy wording, or brand systems from reviewed repositories.
-- External settings such as branch protection, npm Trusted Publishing, and private vulnerability reporting still need to be configured in GitHub and npm.
-- Tool-specific adapters still need to be activated in each downstream project and verified in `ASSISTANT_ADAPTERS.md`.
-- Real upgrade evidence still needs to be recorded per downstream project in `UPGRADE.md`.
-- Real frontend quality still requires project-specific content, creative direction, screenshot review, and visual evidence.
-- Real frontend distinctiveness still requires project-specific references, anti-references, source-safety review, and a critique verdict.
-- Real frontend distinctiveness still requires first-screen proof, content fingerprint, asset provenance, state proof, visual QA proof, and product-specific acceptance evidence.
-- Public-safe dogfood summaries do not replace full downstream branch updates, adapter activation, or post-publish `npx` verification.

package/DOGFOOD.md

@@ -1,201 +0,0 @@
-# Dogfood Evidence
-
-This file is the public-safe summary of downstream adoption evidence. Detailed local-path notes live in `dogfood/` and are intentionally excluded from the npm package.
-
-## Evidence Rule
-
-- Dogfood evidence must run against the current built CLI, not an older remembered result.
-- Real-project audits may fail. Failure is useful when it proves the kit catches setup drift.
-- Public summaries use project archetypes instead of local paths or private project details.
-- A dogfood item only counts as promoted when it leads to an installed asset, audit check, test, release gate, or documented decision.
-
-## Current Read-Only Audit Snapshot
-
-Date: 2026-06-03
-CLI source: current `dist/index.js`
-Command: `node dist/index.js audit --json`
-Mode: read-only audit; no downstream files were modified.
-
-| Project Archetype | Summary | Readiness | Highest-Value Gaps Caught |
-| --- | --- | --- | --- |
-| SaaS/tool hybrid | 11 pass, 20 warn, 7 fail | `needs-setup` | Missing `.agent-kit/agent-roster.json`, schema contracts, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `COUNCIL.md`, `DESIGN.md`, `QUALITY_GATES.md`, `UPGRADE.md`, assistant adapters, visual QA evidence, reference-led design critique, and stale templates. |
-| Content/admin hybrid | 11 pass, 20 warn, 7 fail | `needs-setup` | Missing `.agent-kit/agent-roster.json`, schema contracts, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `COUNCIL.md`, `DESIGN.md`, `QUALITY_GATES.md`, `UPGRADE.md`, assistant adapters, visual QA evidence, reference-led design critique, and stale/customized templates. |
-
-## What This Proves
-
-- The audit distinguishes older valid installs from the current best-practice setup.
-- Current audits catch the exact post-research hardening areas: schema-backed council routing, assistant activation, maturity gates, upgrade lifecycle, visual QA, and reference-led frontend critique.
-- Real projects installed before later hardening phases need `agent-kit update` and conflict review before they can claim baseline setup under the current package.
-
-## What This Does Not Prove
-
-- These two projects are not yet best-practice candidates.
-- The public npm package has not yet been published and verified with `npx`.
-- Assistant adapters and upgrade lifecycle still need real activation/dogfood evidence after publication.
-- Reference-led design critique still needs a real UI change dogfood pass with screenshots or equivalent visual evidence.
-
-## 2026-07-04 Publish @0.1.8 Snapshot
-
-Date: 2026-07-04
-CLI source: local `dist/index.js` after `npm run release:check`
-
-- Setup-server API route coverage (`tests/setup-server-api.test.ts`), Playwright UI screenshot smoke (`smoke:ui-screens`, Playwright 1.55.1), and Agent Studio Milestone 8 completion (note/render POST endpoints, session picker, live office controls).
-- `readJsonBody` shared between setup and studio servers; oversized bodies return 400 without dropping the connection; studio SSE broadcasts notes.
-- Dedicated Ubuntu CI job for UI screenshots; not part of `release:check` matrix.
-- Local verification: `release:check` green (150 tests, setup-server.ts 86% statements), `smoke:ui-screens` produced 4 PNGs.
-- Published `@appsforgood/next-supabase-kit@0.1.8`; `publish:verify` passed against live registry.
-
-## 2026-07-04 Publish @0.1.7 Snapshot
-
-Date: 2026-07-04
-CLI source: public npm registry `@appsforgood/next-supabase-kit@0.1.7`
-
-- Published `@appsforgood/next-supabase-kit@0.1.7` with lifecycle README commands, `/spec`/`/test`/`/review` Antigravity adapters, and `prompts/lifecycle-command-index.md`.
-- Post-publish: `npm run publish:verify` against live registry.
-
-## 2026-07-04 Publish @0.1.6 Snapshot
-
-Date: 2026-07-04
-CLI source: public npm registry `@appsforgood/next-supabase-kit@0.1.6`
-Mode: local maintainer publish (token) after `npm run release:check`, then `npm run publish:verify`.
-
-- Published `@appsforgood/next-supabase-kit@0.1.6` to public npm (local token publish with `--provenance=false`; CI releases continue to use OIDC + provenance).
-- `npm run publish:verify` passed: registry visibility confirmed, `npx` doctor ok, clean temp `init` installed current baseline assets, and `audit --json --min-readiness baseline-setup` returned 0 failures (67 pass / 4 warn / readiness `baseline-setup`).
-
-## 2026-07-02 Publish Verification And Self-Install Snapshot
-
-Date: 2026-07-02
-CLI source: public npm registry (`@appsforgood/next-supabase-kit`, published) plus local `src/` for the self-install.
-Mode: post-publish verification against the live registry, and dogfooding the kit into this repo's own root.
-
-- `node scripts/post-publish-verify.mjs` against the published package passed: registry visibility confirmed, `npx` doctor ok, clean temp `init` installed 23 files, and `audit --json --min-readiness baseline-setup` returned 0 failures (readiness `baseline-setup`).
-- This repo now dogfoods its own kit at the root: `agent-kit init` installed the root docs, `.agent-kit/`, and Cursor rules; project context, council session, and overrides were filled with real evidence; `agent-kit audit --min-readiness best-practice-candidate` passes with 0 warnings and 0 failures.
-
-## 2026-06-07 Agent Studio Dogfood Snapshot
-
-Date: 2026-06-07
-CLI source: current `dist/index.js`
-Mode: downstream update, guided context generation, session recording, static Studio export, and final audit.
-
-| Project Archetype | Stage | Summary | Readiness | Notes |
-| --- | --- | --- | --- | --- |
-| Content/admin hybrid | Before update | 11 pass, 31 warn, 8 fail | `needs-setup` | Older partial install was missing current roster, schemas, docs, context, and Agent Studio assets. |
-| Content/admin hybrid | After update/onboard/export | 54 pass, 17 warn, 0 fail | `baseline-setup` | `agent-kit update` preserved customized docs through `.agent-kit/conflicts/`; `onboard`, session render, and `studio export` worked locally. |
-| Content/admin hybrid | After `session output` fix and completed session | 52 pass, 19 warn, 0 fail | `baseline-setup` | Completed planning session has all required outputs marked complete, verification recorded, rendered Markdown current, static Studio export regenerated, and 14 valid Agent Studio events. Extra warnings reflect template changes made during this fix and remaining project-specific evidence gaps. |
-
-### Finding Promoted Back Into The Kit
-
-Dogfood exposed that sessions could define required outputs but lacked a CLI command to update their status. The fix adds `agent-kit session output <name...> --status <missing|partial|complete|not-applicable> --evidence <evidence>`, a `required_output_updated` event type, renderer/static-export support, CLI smoke coverage, and completed-session regression tests.
-
-### Remaining Dogfood Gaps
-
-- Project context still needs real product summary, audience, workflows, auth/tenant model, UI direction, value proposition, and quality target answers.
-- Assistant adapter rows still need active-tool verification evidence in downstream projects beyond the kit repo itself.
-- Project-owned docs need conflict review before adopting newer template wording.
-- A real UI change still needs reference-led design critique and desktop/mobile visual QA evidence.
-- Public npm publish and `npm run publish:verify` still need maintainer release execution. See [PUBLISH.md](PUBLISH.md).
-
-## 2026-06-07 Release Gate Snapshot
-
-Date: 2026-06-07
-CLI source: current built CLI
-Command: `npm run release:check`
-Result: passed locally on Windows after assistant adapter install on init, baseline audit gate smoke, install smoke, Agent Studio smoke, SBOM check, and npm pack dry run.
-
-| Gate | Result |
-| --- | --- | --- |
-| Tests | 65 passed |
-| Example install shape | `baseline-setup`, 0 failures |
-| Install smoke | IDE adapter rules installed, `baseline-setup`, 0 failures |
-| Agent Studio smoke | `baseline-setup`, 0 failures |
-| Baseline audit gate smoke | `baseline-setup`, 0 failures |
-| npm pack dry run | `@appsforgood/next-supabase-kit@0.1.1` tarball validated |
-
-Remaining publish action: execute [PUBLISH.md](PUBLISH.md), then run `npm run publish:verify`.
-
-## 2026-06-07 Assistant Adapter Activation On Init
-
-Date: 2026-06-07
-CLI source: current built CLI
-Mode: init-time assistant adapter rule installation for downstream projects.
-
-| Surface | Path | Status | Evidence |
-| --- | --- | --- | --- |
-| Downstream init | `.cursor/rules/cursor-agent-kit.mdc` | Active on `agent-kit init` | `smoke:install`, `smoke:audit-gate`, and `tests/update.test.ts` verify rule installation. |
-| Downstream init | `.cursor/rules/cursor-model-selection.mdc` | Active on `agent-kit init` | Same smoke and update coverage as council rule. |
-| Template docs | `ASSISTANT_ADAPTERS.md` | Updated | Adapter activation steps and init-time install behavior documented for downstream projects. |
-
-## Promotion Back Into The Kit
-
-| Dogfood Finding | Promoted Kit Behavior |
-| --- | --- |
-| Older installs drift as the package improves. | Template hashes, `agent-kit diff`, `agent-kit update`, `UPGRADE.md`, upgrade checklist, and upgrade audit warnings. |
-| Existing project docs vary and must be preserved. | Conflict-safe writes and `.agent-kit/overrides.json`. |
-| Agent instructions can exist without machine-readable council routing. | `.agent-kit/agent-roster.json`, roster schema validation, and council-session evidence. |
-| AI tool activation cannot be assumed from `AGENTS.md` alone. | `ASSISTANT_ADAPTERS.md` and `.agent-kit/assistant-adapters/`. |
-| Frontend docs can miss product-specific design evidence. | `DESIGN.md`, content-first design skill, reference-led design critique, visual QA tiers, and screenshot review. |
-| Required session outputs were hard to complete without manual JSON edits. | `agent-kit session output`, `required_output_updated` events, renderer/export support, and completed-session audit coverage. |
-
-## Upgrade Regression Fixture
-
-The package also includes a deterministic test for an older install shape:
-
-- Older install has customized root docs and no current roster, schemas, assistant adapters, `DESIGN.md`, `QUALITY_GATES.md`, or `UPGRADE.md`.
-- `agent-kit update` behavior preserves customized docs and writes new template versions into `.agent-kit/conflicts/`.
-- `agent-kit diff` previews missing docs, changed docs, roster status, missing library folders, files update would create, and files update would write to conflicts.
-- Missing current baseline docs and `.agent-kit/agent-roster.json` are added.
-- `.agent-kit/schemas/`, `.agent-kit/assistant-adapters/`, and the reference-led design critique skill are installed.
-- The upgraded fixture audits with `0` failures and readiness `baseline-setup`.
-
-Covered by `tests/update.test.ts`.
-
-## Next Dogfood Passes
-
-- Review generated conflicts in the dogfood project and decide which project-owned docs should adopt the latest template wording.
-- Run `agent-kit update` on another real project on a dedicated branch and record conflict-review outcomes.
-- Activate at least one assistant adapter in a real project and record whether the chosen tool loads the canonical council instructions.
-- Apply the reference-led design critique gate to one real frontend change with desktop/mobile screenshot evidence.
-- After public publish, run `npm run publish:verify` to verify registry visibility, public `npx doctor`, clean temp `init`, and `audit --json` with zero failures.
-
-## BaseRepo Maintainer Dogfood Policy
-
-Date: 2026-06-17
-Policy: **gitignored local overlay + bootstrap script** (not committed to kit source)
-
-| Item | Detail |
-| --- | --- |
-| Bootstrap | `npm run dogfood:init` runs `agent-kit init --stack next-supabase --activate cursor --activate codex` against the repo root |
-| Gitignore | `.agent-kit/`, `.codex/`, init-generated council docs at repo root, and local pack tarballs — see `.gitignore` and [DOCS.md](DOCS.md#maintainer-dogfood) |
-| Validation | `node dist/index.js adapter validate cursor\|codex` after bootstrap |
-| Release evidence | [MAINTAINER_RELEASE.md](MAINTAINER_RELEASE.md) session checklist; loop patterns in [LOOP_CODING.md](LOOP_CODING.md) |
-| Rationale | Kit source stays in `templates/` and tracked maintainer docs; overlay proves Tier B activation without polluting commit history |
-
-This policy closes the gap where the kit shipped Level 5 IDE surfaces but BaseRepo maintainers operated at Level 4 day-to-day.
-
-## 2026-07-04 - Lifecycle Commands README Parity
-
-Date: 2026-07-04
-Scope: README/docs discoverability + three new Antigravity adapters
-
-| Item | Detail |
-| --- | --- |
-| README | Added **Workflow Commands** section: lifecycle diagram, 12 core + 8 UI slash commands, council table, skills-by-phase, skill activation narrative |
-| Canonical index | `prompts/lifecycle-command-index.md` for delivery commands (parallel to `prompts/ui-command-index.md`) |
-| New adapters | `/spec`, `/test`, `/review` in `antigravity/commands/` (20 total native commands) |
-| Roster | `testing` and `code-review` workflows; planning triggers for spec keywords |
-| Historical scope | `/build`, `/webperf`, `/code-simplify`, and `/build auto` were deferred in this 0.1.7 review; the later runtime ships bounded roster workflows rather than cloning those command semantics |
-| Verification | `npm test`, `agent-kit adapter validate antigravity` after build |
-
-## 2026-07-11 - README Examples Release 0.2.1
-
-Date: 2026-07-11
-Scope: publish the verified README rewrite through npm Trusted Publishing and confirm the public artifacts.
-
-| Evidence | Result |
-| --- | --- |
-| Local release gate | `npm run release:check` passed with 200 tests, coverage gates, package/adapters/examples/install/Studio/setup/audit checks, zero dependency vulnerabilities, SBOM validation, and package dry runs. |
-| Root package | `@appsforgood/next-supabase-kit@0.2.1` is public and the `latest` dist-tag resolves to `0.2.1`. |
-| Published README | npm returns the rewritten quick start, audit, council-session, frontend-review, update, and optional-runtime examples for `0.2.1`. |
-| Runtime package | `@appsforgood/agent-kit-runtime` remains at `0.1.3`; the release workflow correctly skipped its unchanged package. |
-| GitHub release | [`v0.2.1`](https://github.com/lukey662/agentsandskills/releases/tag/v0.2.1) was created only after public-registry verification. |
-| Supply chain | Trusted Publishing used GitHub Actions OIDC and generated the root-package SBOM attestation before publication. |

package/GOVERNANCE.md

@@ -1,45 +0,0 @@
-# Governance
-
-## Maintainer Model
-
-This project is maintained as a small public OSS package. Maintainers own release approval, public-package safety, research promotion, and final merge decisions.
-
-## Decision Rules
-
-Changes should improve reusable setup quality for many projects. Project-specific preferences belong downstream unless repeated evidence shows they generalize.
-
-Promoted best practices need at least one of:
-
-- Repeated findings from repository research.
-- Dogfood evidence from downstream installs.
-- Official framework or platform documentation.
-- A clear security, release, or maintainability requirement.
-
-Promotion targets should be explicit:
-
-- Installed root template.
-- Agent role.
-- Skill.
-- Prompt.
-- Checklist.
-- Schema.
-- Audit rule.
-- Research scanner signal.
-- CI or release gate.
-
-## Release Rules
-
-Releases require:
-
-- Passing CI.
-- Passing install smoke.
-- Passing dependency audit.
-- Passing package dry run.
-- Branch protection and repository settings reviewed when workflows, permissions, or release controls changed.
-- Public package metadata review.
-- No secrets, copied third-party source, or private downstream details.
-- Trusted Publishing or another npm-approved secure publish path.
-
-## Research Rules
-
-Research findings are evidence, not implementation. A pattern only becomes kit behavior after it is promoted into an installed asset, CLI/audit behavior, test, release gate, or recorded decision.

package/LOOP_CODING.md

@@ -1,107 +0,0 @@
-# Loop Coding
-
-Loop coding means the agent repeats **plan → act → check → fix** until a stop condition, instead of finishing in one chat turn. The Agent Kit is opinionated about **which loops are safe** and **which checkpoints must stay in place**.
-
-This document describes loop types, kit-safe patterns, and limits. It is the canonical reference for eval-driven development with `@appsforgood/next-supabase-kit`.
-
-## Loop Types
-
-| Loop type | What it means | Kit-safe version |
-| --- | --- | --- |
-| **Agent loop** | Same agent iterates on feedback until done | Use scoped prompts (for example `.agent-kit/prompts/implement-feature.md`); review each turn; do not remove Security Reviewer or QA gates |
-| **Eval-driven loop** | Code changes until **tests, audit, or evals pass** | `npm test` + `agent-kit audit` + CI — BaseRepo uses `npm run release:check` as the maintainer merge gate |
-| **Self-improving loop** | Agent critiques its own output and revises | Manual: delegate to `@qa-engineer` or run tests between passes; **avoid fully unsupervised self-critique on auth, RLS, or release tooling** |
-| **Council / team loop** | Planner → specialist → Security → QA handoffs | `agent-kit session handoff` + IDE subagents — the kit's core operating model |
-| **Background / overnight loop** | Runs without a human present | **Defer by default** — requires worktree policy, cost caps, kill switches, and stronger eval gates than agent freedom |
-
-## Practical Rule
-
-Climb maturity by adding **checkpoints** (tests, audit, guards, human review), not by removing them. Unsupervised loops are only healthy when **eval gates are stronger than the agent's freedom**.
-
-## Eval-Driven PR Loop (recommended)
-
-For feature work in a kit-consuming project:
-
-1. **Plan** — Planner classifies scope; Lead Architect maps affected layers when the change is core.
-2. **Implement** — Next.js / Supabase engineers (or general agent with council rules loaded).
-3. **Check** — run the smallest reliable gate set:
-   ```bash
-   npm test
-   agent-kit audit --min-readiness baseline-setup
-   agent-kit adapter validate all   # when IDE surfaces change
-   ```
-4. **Fix** — repeat implement/check until green or blocked on a documented gap.
-5. **Record** — `agent-kit session render` and mirror summary in `COUNCIL.md` for meaningful multi-agent work.
-
-BaseRepo maintainers use the same pattern at repo scale:
-
-```bash
-npm run release:check    # tests, build, package validate, smokes, adapter validate
-npm run smoke:audit-gate
-```
-
-## Council Loop (multi-agent)
-
-The default handoff order lives in `AGENTS.md` and `.agent-kit/agent-roster.json`:
-
-1. Planner — scope, workflow, council selection
-2. Lead Architect — core changes
-3. Domain engineers — data, UI, copy as needed
-4. Security Reviewer — auth, mutations, secrets, dependencies, release risk
-5. QA Engineer — behavior evidence
-6. Documentation Maintainer — living docs and council record
-
-Use Agent Studio when the CLI is available:
-
-```bash
-agent-kit session start --workflow core-change --request "Short title"
-agent-kit session handoff --from planner --to lead-architect --decision "..." --risk "..." --next "..." --evidence "..."
-agent-kit session verify --command "npm test" --result pass
-agent-kit session output phased-checklist --status complete --evidence "..."
-agent-kit session render
-```
-
-When CLI tooling is unavailable, append the session template in `COUNCIL.md` (see `MAINTAINER_RELEASE.md` for kit release evidence).
-
-## Hooks And Local Automation (Level 6 enablers)
-
-The kit does **not** ship unsupervised orchestration. It documents safe local enablers:
-
-| Pattern | Purpose | Starting point |
-| --- | --- | --- |
-| Pre-commit test or audit | Catch drift before commit | `.agent-kit/prompts/audit-project-setup.md`, project `npm test` |
-| Post-edit lint/typecheck | Fast feedback on save | Project ESLint / `tsc --noEmit` in editor or CI |
-| PR CI audit gate | Block merge below readiness | `.github/workflows/agent-kit-audit.yml` template |
-| Adapter validate on PR | Prove IDE templates stay shippable | `agent-kit adapter validate all` (BaseRepo: `npm run adapter:validate` in `release:check`) |
-
-For Cursor-specific hook/automation patterns, see Cursor Automations docs and keep Planner-first triage **opt-in** — never as a replacement for Security Reviewer or human release approval.
-
-## MCP Routing (delegation hint)
-
-Match MCP servers to council roles in consuming projects:
-
-| Role | Typical MCP use |
-| --- | --- |
-| Supabase/Postgres Engineer | Schema, migrations, RLS, logs, advisors |
-| Security Reviewer | Dependency/advisory checks; no broad production writes without review |
-| Deployment/Observability Engineer | Hosting logs, release status, error tracking |
-| QA Engineer | Test runners, visual diff tools where configured |
-
-Record active MCP surfaces in `ASSISTANT_ADAPTERS.md` when they affect council behavior.
-
-## What Not To Default
-
-- Overnight unsupervised agent runs on auth, RLS, or release tooling
-- Agents managing agents without eval harness and kill switches
-- Removing human review from publish, migration, or security-sensitive paths
-- Duplicating runtime product agents inside the kit repo (wrong shape for agent-kit)
-
-## Related Docs
-
-- `AGENTS.md` — council roles and default handoffs
-- `QUALITY_GATES.md` — Baseline / Strong / Mature evidence tiers
-- `COUNCIL.md` — session evidence template
-- `MAINTAINER_RELEASE.md` — kit maintainer release session checklist
-- `research/summaries/agentic-engineering-maturity-levels.md` — L3–L8 ladder and office integration
-- `TESTING.md` — project test and CI gate expectations
-- `PUBLISH.md` — npm publish runbook