@appsforgood/next-supabase-kit 0.1.0

package/BEST_PRACTICE_EVIDENCE.md

@@ -0,0 +1,45 @@
+# 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 CycloneDX SBOM for the package tarball, and verify release integrity before publish. | `.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`, `npm run sbom:check`, OpenSSF Scorecard, Dependency Review, npm Trusted Publishing, SBOM attestation, pack dry run. |
+| 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/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public package scaffold.
+- Added CLI commands for install, audit, diff, update, add skill, doctor, and research workflows.
+- Added Next.js + Supabase markdown templates.
+- Added core agent roles, skills, prompts, checklists, and provider-neutral design adapters.
+- Added CI and public npm release workflows with dry-run validation.
+- Added template-hash manifest tracking and `agent-kit audit --json`.
+- Added compatibility profiles, product-specific design briefs, screenshot review prompt, and sample installed output.
+- Promoted 100-repo research findings from `research/summaries/scan-overview.md` and `research/proposed-updates.md`.
+- Promoted downstream dogfood findings from `dogfood/qrcode-audit.md` and `dogfood/ai-news-audit.md`.
+- Added npm publish-token preflight and prepared draft GitHub Release `v0.1.0`.
+- Fixed package bin metadata so `agent-kit` is preserved during npm publish.
+- Replaced publish-token CI authentication with npm Trusted Publishing and optional read-token install verification.
+- Added a Planner agent, Planning and Agent Council skill, and machine-readable default council roster enforced by audit.
+- Rebranded package for public OSS as `@agent-skills/next-supabase-kit` with MIT license, citation policy, and public-readiness tests.
+- Added content-first design, visual QA, schema-backed council traceability, and public OSS repo-health hardening.
+- Added issue forms, PR template, CODEOWNERS, Dependabot, CodeQL, support, conduct, governance docs, and repo-health research signals.
+- Added label source of truth, PR labeler workflow, and repository-settings checklist for branch protection, release environment, private vulnerability reporting, and required labels.
+- Added shared `npm run release:check` gate for local, CI, and release readiness.
+- Added version consistency validation for package metadata, lockfile, changelog section, and release tags.
+- Added supply-chain hardening with `SUPPLY_CHAIN.md`, Dependency Review, OpenSSF Scorecard, workflow controls, provenance documentation, and supply-chain research signals.
+- Added lockfile-derived CycloneDX SBOM validation and release-workflow SBOM attestation for the npm package tarball.
+- Added committed example consistency validation so sample install output cannot drift from the current CLI.
+- Added `QUALITY_GATES.md` maturity model with audit coverage for baseline, strong, and best-practice evidence.
+- Added project-evidence placeholder warnings so fresh setup success is not confused with completed maturity evidence.
+- Added audit readiness verdicts: `needs-setup`, `baseline-setup`, `needs-improvement`, and `best-practice-candidate`.
+- Added `agent-kit audit --min-readiness <level>` so downstream projects can enforce readiness thresholds in CI.
+- Added `schemas/audit-report.schema.json` and runtime audit-report contract tests for machine-readable audit consumers.
+- Added `ASSISTANT_ADAPTERS.md` and provider-neutral assistant adapter templates for AGENTS.md-compatible tools, GitHub Copilot/VS Code, Cursor, and Claude Code.
+- Added `UPGRADE.md`, upgrade-maintenance skill, upgrade checklist, upgrade-review prompt, and audit coverage for reviewable updates and rollback evidence.
+- Added reference-led design critique skill, checklist, prompt, roster routing, and audit coverage so frontend work requires references, anti-references, source-safety notes, and a distinctiveness verdict.
+- Added frontend product-quality rubric skill, checklist, prompt, roster routing, audit coverage, and `DESIGN.md` scorecard fields so significant UI work has a repeatable acceptance threshold.
+- Added public-safe `DOGFOOD.md` and current read-only dogfood audit refreshes so downstream adoption evidence stays visible as the kit hardens.
+- Added older-install upgrade regression coverage proving diff previews missing/conflicting assets, update preserves customized docs, writes conflicts, installs new baseline assets, and audits with zero failures.
+- Added reusable post-publish verification script for `npm view`, public `npx doctor`, clean temp `init`, and `audit --json` with zero failures.
+- Added model-routing docs, schema, adapter examples, install/update/diff support, and audit warnings for per-agent model-selection setup.
+- Added Marketing Copy Lead, `MESSAGING.md`, copywriting skills, copy-review prompt, marketing-copy checklist, roster/model routing, and audit coverage for positioning, proof, objections, voice, and CTA evidence.
+- Added automatic assistant adapter rule installation to `.cursor/rules/` during `agent-kit init`, plus activation guidance in `ASSISTANT_ADAPTERS.md`.
+- Added `npm run smoke:audit-gate` and CI baseline readiness enforcement with `agent-kit audit --min-readiness baseline-setup`.
+- Added [PUBLISH.md](PUBLISH.md) release runbook and [RUNTIME_ORCHESTRATION_SCOPE.md](RUNTIME_ORCHESTRATION_SCOPE.md) for deferred Milestone 9 orchestration work.
+- Fixed Windows-safe npm/tar spawning in release and smoke scripts, cross-platform audit path handling for Agent Studio sessions, and cross-platform research scoring path normalization.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code Of Conduct
+
+## Standard
+
+Contributors should keep discussion professional, specific, and focused on improving reusable project quality.
+
+Expected behavior:
+
+- Treat maintainers and contributors with respect.
+- Critique ideas, code, evidence, and tradeoffs rather than people.
+- Keep issue and PR discussion actionable.
+- Respect security reporting boundaries and do not disclose private vulnerability details publicly.
+- Avoid publishing private downstream project details, customer data, secrets, or copied third-party source.
+
+Unacceptable behavior:
+
+- Harassment, threats, discrimination, or personal attacks.
+- Deliberate disruption of issues, reviews, or releases.
+- Public disclosure of vulnerabilities before maintainers can respond.
+- Posting secrets, exploit details, private project data, or non-public third-party code.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove content that violates this policy. Repeated or severe violations may lead to blocked participation in the repository.
+
+Report conduct concerns privately to the maintainers.

package/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Contributions should improve reusable project setup, not encode one-off project preferences.
+
+## Contribution Rules
+
+- Add or update tests for CLI behavior.
+- Keep templates concise and actionable.
+- Do not copy source code from researched repositories.
+- Cite research findings when promoting a pattern into a core template.
+- Use the research-promotion issue form when proposing a pattern from public repos.
+- Use the PR template and include council scope, verification, security, docs, and citation evidence.
+- Use labels from `.github/labels.yml`; update the labels file when adding new issue-template labels.
+- Keep frontend guidance domain-aware and avoid generic AI-site defaults.
+- Keep security guidance aligned with OWASP Top 10 and Supabase RLS practices.
+- Keep public package contents neutral, reusable, and free of project-specific secrets or proprietary assumptions.
+- Treat workflow, dependency, and release changes as supply-chain risk changes requiring security review.
+
+## Research Contributions
+
+When adding a repo finding:
+
+1. Explain why the repo was selected.
+2. List strong practices.
+3. List weak practices that should not be copied.
+4. Identify patterns that affect kit templates, agents, skills, or checklists.
+
+## Downstream Dogfood Contributions
+
+When an existing project installs the kit:
+
+1. Run `agent-kit init --stack next-supabase` without `--force`.
+2. Run `agent-kit audit --json` and `agent-kit diff`.
+3. Run `agent-kit audit --min-readiness baseline-setup` when the project should at least preserve installed contracts.
+4. Record the project type, created files, conflict files, audit summary, readiness level, and top gaps in `dogfood/<project>-audit.md`.
+5. Promote repeated gaps into this package's templates, skills, checklists, prompts, profiles, or audit rules.
+6. Keep project-specific wording in the downstream project unless the pattern generalizes.
+7. Re-run package tests, `npm run examples:check`, and a temporary install smoke test before committing kit changes.
+
+## Release Checklist
+
+- `npm run release:check`
+- `npm run version:check`
+- `npm run examples:check`
+- Public-readiness tests
+- Dependency audit and package dry run
+- Dependency Review and Scorecard workflows configured
+- Manual install into a temporary Next.js/Supabase-like project

package/DOGFOOD.md

@@ -0,0 +1,121 @@
+# 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-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 | `@agent-skills/next-supabase-kit@0.1.0` 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.

package/GOVERNANCE.md

@@ -0,0 +1,45 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# Agent Skills Next/Supabase Kit
+
+`@agent-skills/next-supabase-kit` installs an agent operating system for Next.js + Supabase projects.
+
+It gives agentic coders a default council roster, reusable skills, handoff rules, model-routing guidance, markdown docs, frontend design gates, Supabase/RLS security checks, upgrade workflows, and audit commands.
+
+The package answers one practical question:
+
+> Does this project have the setup needed for secure, maintainable, non-generic Next.js + Supabase delivery?
+
+This is not just a prompt bundle. A project gets machine-readable agent routing, model profile routing, schema-backed council evidence, living documentation templates, research-backed quality gates, and CLI checks for drift.
+
+It also includes a local Agent Studio workflow: project context, durable human corrections, append-only session events, and rendered Markdown transcripts that work without a database, web server, background daemon, or separate model API key.
+
+## Quick Start
+
+Use this in a Next.js + Supabase project after the public package is available on npm:
+
+```bash
+npx @agent-skills/next-supabase-kit init --stack next-supabase
+npx @agent-skills/next-supabase-kit audit
+npx @agent-skills/next-supabase-kit audit --min-readiness baseline-setup
+```
+
+The installer preserves existing docs. If a file already exists and differs from the template, the new version is written to `.agent-kit/conflicts/` for review.
+
+For local development of this repo:
+
+```bash
+npm install
+npm run build
+npm test
+npm run release:check
+```
+
+`npm run release:check` is the main pre-release proof command. It typechecks, tests, builds, install-smokes the package, checks examples, runs dependency audit, validates SBOM generation, and dry-runs packaging.
+
+## How Agentic Coders Should Use It
+
+Start with the installed files:
+
+- `AGENTS.md`: the high-level operating instructions.
+- `.agent-kit/agent-roster.json`: the machine-readable source of truth for agent routing.
+- `AGENT_ROSTER.md`: the human-readable roster summary.
+- `SKILLS.md`: when each reusable skill should be used.
+- `MODEL_ROUTING.md`: model-profile guidance for each agent and IDE.
+- `QUALITY_GATES.md`: what separates baseline setup, strong delivery, and best-practice evidence.
+- `DESIGN.md`: the frontend design and content contract.
+- `MESSAGING.md`: the positioning, value proposition, proof, objections, voice, and CTA contract.
+- `COUNCIL.md`: where meaningful handoffs and decisions are recorded.
+
+Default routing:
+
+- Planner handles plans, roadmaps, scope, and ambiguous requests first.
+- Lead Architect reviews core changes before implementation.
+- Security Reviewer joins auth, RLS, data mutation, dependency, secret, external-call, and release-risk work.
+- Frontend Design Lead owns content-first design, reference-led critique, distinctiveness benchmarking, product-quality scoring, and visual QA.
+- Marketing Copy Lead owns public-facing and conversion-facing copy, positioning, proof, objections, voice, and CTA hierarchy.
+- QA Engineer verifies behavior changes before completion.
+- Documentation Maintainer keeps the living markdown current.
+
+For meaningful multi-agent work, record the decision, risk, next handoff, required outputs, and verification evidence in `COUNCIL.md` or `.agent-kit/council-sessions/*.json`.
+
+For local Agent Studio sessions, use:
+
+```bash
+agent-kit init --guided
+agent-kit context validate
+agent-kit session start "Build checkout flow" --workflow frontend-change
+agent-kit session decision --agent planner --risk "Generic UI risk" "Use frontend-change workflow."
+agent-kit session handoff --from planner --to frontend-design-lead --decision "Start design intake." --risk "Generic UI risk."
+agent-kit session correct --agent frontend-design-lead --scope project "Keep UI dense and operational."
+agent-kit session verify --command "npm test" --result pass --notes "Tests passed."
+agent-kit session output "visual QA evidence" --status not-applicable --evidence "No UI change."
+agent-kit session render
+agent-kit correction list
+agent-kit studio export
+agent-kit audit --json
+```
+
+## What Gets Installed
+
+Root markdown docs:
+
+```text
+AGENTS.md
+AGENT_ROSTER.md
+ASSISTANT_ADAPTERS.md
+COUNCIL.md
+SKILLS.md
+SPEC.md
+DECISIONS.md
+DOCS.md
+DESIGN.md
+MESSAGING.md
+MODEL_ROUTING.md
+QUALITY_GATES.md
+STYLE_GUIDE.md
+SECURITY.md
+TESTING.md
+DEPLOYMENT.md
+UPGRADE.md
+```
+
+The `.agent-kit/` folder includes:
+
+- `agent-roster.json` for default workflow routing.
+- `model-routing.json` for provider-neutral model profile routing.
+- `project-context.json`, `project-context.md`, `corrections/`, and `council-sessions/` for local Agent Studio context, correction rules, session events, and rendered transcripts.
+- `schemas/` for agent roster, council-session, model-routing, project context, correction rules, session events, studio sessions, and audit-report contracts.
+- `agents/`, `skills/`, `prompts/`, and `checklists/`.
+- `assistant-adapters/` for Codex/AGENTS.md-compatible tools, GitHub Copilot/VS Code, Cursor, and Claude Code.
+- `design-briefs/` for SaaS, admin, marketplace, content, tool, ecommerce, portfolio/venue, education, community/social, and AI workflow surfaces.
+- `profiles/` for product-type and adjacent-stack adaptation.
+
+## Everyday Commands
+
+```bash
+agent-kit audit
+agent-kit audit --json
+agent-kit audit --min-readiness baseline-setup
+agent-kit context init
+agent-kit session start "Short task name"
+agent-kit session output "verification evidence" --status complete --evidence "npm test"
+agent-kit session render
+agent-kit correction list
+agent-kit studio export
+agent-kit diff
+agent-kit update
+agent-kit add skill frontend-design-system
+agent-kit doctor
+```
+
+Readiness levels from `agent-kit audit --json`:
+
+- `needs-setup`: required install or council contracts are failing.
+- `baseline-setup`: setup is valid, but starter evidence placeholders remain.
+- `needs-improvement`: no failures, but warnings remain.
+- `best-practice-candidate`: static audit found no failures or warnings.
+
+Use `agent-kit audit --min-readiness <level>` in CI when a project wants a merge or release threshold.
+
+## AI Mechanisms
+
+Agent Kit separates the mechanisms that make AI coding repeatable:
+
+- Instructions: `AGENTS.md`, assistant adapters, and IDE-specific rule files.
+- Roster: `.agent-kit/agent-roster.json` chooses agents, workflows, and handoffs.
+- Skills: `.agent-kit/skills/` keeps specialist workflows reusable.
+- Model routing: `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` map agents to model profiles.
+- Messaging: `MESSAGING.md` records audience, pain, outcome, proof, objections, voice, and conversion evidence for public-facing copy.
+- Local Agent Studio: `.agent-kit/project-context.*`, `.agent-kit/corrections/*.json`, and `.agent-kit/council-sessions/*` keep context, corrections, decisions, handoffs, required-output status, artifacts, verification, and rendered Markdown transcripts local.
+- Tools and MCP: `ASSISTANT_ADAPTERS.md` records browser, GitHub, Figma, Supabase, docs, or other connector setup.
+- Hooks and CI: optional local enforcement plus `agent-kit audit`, tests, install smoke, SBOM, and release gates.
+
+Some IDEs can partially enforce model settings; others only let project files advise the user. The kit records that difference instead of pretending every tool can force per-agent model selection.
+
+## Frontend Quality Bar
+
+The kit is intentionally strict about frontend work because normal AI output often looks generic.
+
+Significant UI work should prove:
+
+- Brand/content intake and real user needs.
+- A selected creative direction, with rejected alternatives.
+- Reference lessons and anti-references without copied source designs.
+- First-screen proof that the real product task, object, workflow, or content is visible.
+- A content fingerprint: real product nouns, labels, data shapes, actions, and edge cases.
+- Asset provenance for real, generated, licensed, and placeholder visuals.
+- Product-quality scorecard evidence.
+- Desktop, mobile, key states, accessibility, and visual QA evidence.
+
+The Frontend Design Lead should reject work that would still look valid for another product after only changing the logo or headline.
+
+## Security Bar
+
+The kit treats these as defaults, not optional polish:
+
+- OWASP Top 10 review for auth, API, Server Action, external-call, upload, and dependency changes.
+- Supabase RLS at the data boundary.
+- Service-role keys isolated to trusted server code.
+- Input validation and safe output rendering.
+- IDOR, SSRF, injection, broken auth, and misconfiguration review.
+- Dependency audit before release.
+
+## Updating An Existing Install
+
+Use the upgrade flow instead of overwriting project-owned docs:
+
+```bash
+agent-kit diff
+agent-kit update
+agent-kit audit --min-readiness baseline-setup
+```
+
+Document accepted local deviations in `.agent-kit/overrides.json`. Record version changes, conflicts, migration impact, rollback notes, and verification evidence in `UPGRADE.md`.
+
+## Research Evidence
+
+The repo includes a 100-repo research workflow plus focused follow-up summaries.
+
+Research volume does not count as proof by itself. A repeated pattern only becomes part of the kit when it is promoted into installed assets, audit checks, tests, release gates, schemas, workflows, or documented decisions.
+
+Useful evidence files:
+
+- `BEST_PRACTICE_EVIDENCE.md`: maps research signals to enforceable assets and validation paths.
+- `research/summaries/`: public-safe research summaries.
+- `research/proposed-updates.md`: promoted and future updates.
+- `DOGFOOD.md`: public-safe downstream adoption evidence.
+- `ROADMAP.md`: the phased done/left tracker.
+
+Research commands:
+
+```bash
+export GITHUB_TOKEN=ghp_replace_me
+agent-kit research discover --limit 100
+agent-kit research scan
+agent-kit research summarize
+agent-kit research propose-updates
+```
+
+Detailed per-repo findings are committed for repository development, but the public npm package ships generalized summaries and promoted decisions only. See `RESEARCH_CITATION_POLICY.md`.
+
+## Public Release And Supply Chain
+
+Public package name:
+
+```text
+@agent-skills/next-supabase-kit
+```
+
+Release expectations:
+
+- MIT license.
+- Public npm access.
+- npm Trusted Publishing through GitHub Actions OIDC.
+- No long-lived npm publish token for automation.
+- Dependency Review, CodeQL, OpenSSF Scorecard, Dependabot, SBOM validation, and SBOM attestation.
+- Post-publish verification with `npm run publish:verify`.
+
+Public release remains gated until the npm scope/package exists, Trusted Publishing is configured, and post-publish `npx` verification succeeds.
+
+## Repository Health
+
+The repo includes issue forms, PR template, labels, CODEOWNERS, Dependabot, CodeQL, Dependency Review, OpenSSF Scorecard, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `GOVERNANCE.md`, `REPOSITORY_SETTINGS.md`, and `SUPPLY_CHAIN.md`.
+
+These files are tested as public-readiness assets so the package can be maintained as public OSS, not just published as a tarball.
+
+## License
+
+MIT.