@appsforgood/next-supabase-kit 0.2.1 → 0.4.0

package/templates/next-supabase/DOCS.md

@@ -1,80 +0,0 @@
-# Developer Docs
-
-## Setup
-
-Document local setup:
-
-```bash
-npm install
-npm run dev
-```
-
-Add required environment variables in `.env.example`. Never place real secrets in docs.
-
-Run `agent-kit setup` to open Agent Office. The office and wizard show **Agentic Engineering Level** (L3–L6 computed from audit/adapter/context signals). See `LOOP_CODING.md` and kit `DOCS.md` for climb patterns. Do not confuse Agentic L5/L6 with audit readiness or visual QA tiers.
-
-## Architecture Overview
-
-Document:
-
-- Agent council routing in `.agent-kit/agent-roster.json`
-- Assistant activation surfaces in `ASSISTANT_ADAPTERS.md`
-- Optional runtime adapter surfaces such as `.antigravity/agent-kit/` and `.antigravity/runtime-skills/`
-- Optional executable orchestration in `@appsforgood/agent-kit-runtime`, configured by `.agent-kit/orchestrator.json`
-- Model profile routing in `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`
-- Council-session evidence in `COUNCIL.md`
-- Agent, council-session, model-routing, and audit-report schemas in `.agent-kit/schemas/`
-- Quality gate maturity model in `QUALITY_GATES.md`
-- Upgrade lifecycle in `UPGRADE.md`
-- Design identity and content-direction contract in `DESIGN.md`
-- Messaging, positioning, proof, objections, voice, and CTA contract in `MESSAGING.md`
-- Application routes
-- Shared components
-- Server-only modules
-- Supabase client creation
-- Auth middleware
-- Migrations and seed data
-- Test setup
-
-## Key Workflows
-
-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
-- Offline runtime validation and planning with `agent-kit orchestrate validate` and `agent-kit orchestrate plan`
-- 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`
-- Baseline, strong, and best-practice evidence review from `QUALITY_GATES.md`
-- Brand/content intake and creative-direction selection before frontend implementation
-- Reference-led design critique, anti-references, source-safety notes, and distinctiveness verdict from `DESIGN.md`
-- Frontend product-quality scorecard from `DESIGN.md`
-- Marketing-copy workflow, proof mapping, objection handling, and CTA hierarchy from `MESSAGING.md`
-- Visual QA tier and baseline approval workflow for high-risk UI changes
-- Sign up, login, logout, and session refresh
-- Main user workflow
-- Admin workflow
-- Data creation and update workflow
-- Deployment workflow
-
-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.
-
-## Optional Orchestrator
-
-Install `@appsforgood/agent-kit-runtime` only when the project needs executable council workflows. Keep `.agent-kit/orchestrator.json` disabled until provider aliases, credential references, mutation roles, MCP allowlists, Docker policy, limits, and approvals are reviewed.
-
-The runtime compiles roster sequences to bounded LangGraph nodes, checkpoints in SQLite, records redacted JSONL evidence, pauses for risk-tiered approvals, and uses an isolated Git worktree. It may create one approved scoped commit but never merges, pushes, opens a pull request, deploys, or applies migrations automatically. `agent-kit studio serve` exposes the same run and approval state in its Runs tab.
-
-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
-
-Document external APIs, webhooks, storage buckets, cron jobs, email providers, analytics, and monitoring.
-
-## Troubleshooting
-
-Record known issues, expected logs, and operational checks.

package/templates/next-supabase/LOOP_CODING.md

@@ -1,98 +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.
-
-## 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 |
-| **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:
-
-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.
-
-See [TESTING.md](TESTING.md) for CI gate expectations.
-
-## 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`.
-
-## 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 activation stays valid | `agent-kit adapter validate all` when adapter assets change |
-
-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:
-
-| 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
-
-## Related Docs
-
-- `AGENTS.md` — council roles and default handoffs
-- `QUALITY_GATES.md` — Baseline / Strong / Mature evidence tiers
-- `COUNCIL.md` — session evidence template
-- `TESTING.md` — project test and CI gate expectations

package/templates/next-supabase/MESSAGING.md

@@ -1,81 +0,0 @@
-# Messaging And Copy
-
-This file is the persistent positioning, value proposition, voice, and copy-evidence contract for agents and reviewers.
-
-Use it before writing or changing public-facing pages, onboarding, empty states, pricing, upgrade prompts, CTAs, lifecycle emails, notifications, or conversion-critical UX copy.
-
-## Discovery Questions
-
-Answer these before final copy is accepted. If an answer is unknown, mark it as `TBD` and treat the copy as provisional.
-
-| Question | Current Answer | Evidence |
-| --- | --- | --- |
-| Who is the primary audience? | TBD | User research, customer notes, analytics, brief, or stakeholder input |
-| What painful, expensive, slow, risky, or annoying problem do they need solved? | TBD | Customer language, support notes, interviews, or domain research |
-| What outcome do they want? | TBD | Success metric, workflow completion, time saved, risk reduced, revenue gained, or quality improved |
-| What alternatives do they use today? | TBD | Competitors, spreadsheets, manual work, agencies, internal tools, or doing nothing |
-| Why is this product meaningfully different? | TBD | Feature, workflow, data, quality, speed, trust, price, integration, or niche focus |
-| What proof supports the claim? | TBD | Demo, shipped feature, customer quote, case study, benchmark, integration, certification, or domain expertise |
-| What objections could stop signup, activation, or purchase? | TBD | Trust, cost, time, migration, privacy, compliance, risk, support, or switching cost |
-| What action should the user take next? | TBD | Signup, book demo, start workflow, invite team, connect account, import data, or contact support |
-
-## Positioning
-
-One-sentence positioning statement:
-
-> For `TBD audience` who need `TBD outcome`, this product is a `TBD category` that `TBD differentiator`, unlike `TBD alternative`.
-
-Primary value proposition:
-
-- TBD
-
-Secondary value propositions:
-
-- TBD
-- TBD
-
-Non-goals and claims to avoid:
-
-- TBD
-
-## Proof And Objections
-
-| Claim | Proof Required | Current Proof | Status |
-| --- | --- | --- | --- |
-| TBD | TBD | TBD | Missing, partial, or proven |
-
-| Objection | Response | Evidence Or Product Support |
-| --- | --- | --- |
-| TBD | TBD | TBD |
-
-## Voice And Tone
-
-| Area | Decision |
-| --- | --- |
-| Voice traits | 3-5 traits, such as direct, expert, calm, playful, premium, practical, editorial, or technical |
-| Words to use | Product nouns, customer terms, category language, and approved phrases |
-| Words to avoid | Vague SaaS claims, unsupported AI claims, hype, jargon, or legally risky terms |
-| Error tone | Clear cause, useful recovery, no blame |
-| Security/privacy tone | Specific, factual, no invented guarantees |
-| Pricing/upgrade tone | Transparent, no hidden conditions or forced urgency |
-
-## Page And Flow Copy Inventory
-
-| Surface | Goal | Primary Message | Primary CTA | Secondary CTA | Proof | Objections |
-| --- | --- | --- | --- | --- | --- | --- |
-| Homepage hero | TBD | TBD | TBD | TBD | TBD | TBD |
-| Signup or onboarding | TBD | TBD | TBD | TBD | TBD | TBD |
-| Empty state | TBD | TBD | TBD | TBD | TBD | TBD |
-| Pricing or upgrade | Optional | Optional | Optional | Optional | Optional | Optional |
-
-## Acceptance Evidence
-
-Copy work is not accepted until:
-
-- Discovery questions are answered or explicitly marked unknown.
-- Audience, pain, outcome, differentiator, proof, objections, voice, and conversion goal are documented.
-- Claims are tied to proof or marked as assumptions.
-- CTA hierarchy has one primary action and clear secondary actions.
-- Onboarding, empty, error, permission, and upgrade copy provides a useful next step.
-- Marketing Copy Lead has handed off public-facing pages to Frontend Design Lead for layout and hierarchy review.
-- Risky claims are reviewed before release.

package/templates/next-supabase/MODEL_ROUTING.md

@@ -1,130 +0,0 @@
-# Model Routing
-
-Use this file to choose the right model profile for each agent and to record how the active AI coding tools apply those choices.
-
-Canonical source of truth:
-
-- `.agent-kit/model-routing.json`
-- `.agent-kit/schemas/model-routing.schema.json`
-- `.agent-kit/orchestrator.json`
-- `.agent-kit/agent-roster.json`
-- `ASSISTANT_ADAPTERS.md`
-
-## Policy
-
-- Keep role behavior in `AGENTS.md`, `AGENT_ROSTER.md`, and `.agent-kit/agent-roster.json`.
-- Keep reusable skills in `SKILLS.md` and `.agent-kit/skills/`.
-- Keep model choice as a dated, reviewable routing layer.
-- Do not store secrets, API keys, billing notes, private model entitlement details, or workspace-only vendor terms in this file.
-- If an IDE cannot enforce per-agent model choice, document the limitation honestly and use the closest manual or advisory setup.
-- Runtime aliases must use an ordered candidate list, explicit required capabilities, and bounded attempts. Missing capabilities are skipped before a provider call.
-
-## Agent Profiles
-
-| Agent | Default profile | Effort | Escalate when |
-| --- | --- | --- | --- |
-| Planner | `balanced-reasoning` | Medium | Scope affects architecture, auth, data, release, or package behavior. |
-| Lead Architect | `deep-reasoning-large-context` | High | Always for core-change council review. |
-| Supabase/Postgres Engineer | `deep-reasoning-large-context` | High | Schema, RLS, migration order, rollback, or authorization impact exists. |
-| Next.js Engineer | `coding-large-context` | Medium | Server/client boundary, caching, auth, or mutation behavior is uncertain. |
-| Frontend Design Lead | `creative-vision-large-context` | High | Significant UI, screenshots, references, content strategy, or visual QA is involved. |
-| Marketing Copy Lead | `creative-vision-large-context` | High | Positioning, value proposition, conversion copy, voice/tone, proof review, or public-facing copy handoff is involved. |
-| Security Reviewer | `deep-reasoning-large-context` | High | OWASP, IDOR, SSRF, injection, broken auth, dependency, secret, or release risk exists. |
-| QA Engineer | `balanced-reasoning` | Medium | Flaky tests, concurrency, auth flows, visual regression, or hard-to-reproduce bugs exist. |
-| Documentation Maintainer | `fast-targeted` | Low | Docs encode architecture, migrations, security, or release decisions. |
-| Deployment/Observability Engineer | `fast-targeted` | Low | Production release, rollback, env vars, logs, or incident review is involved. |
-
-## Tool Setup
-
-| Tool | Instruction surface | Model-selection status | Enforcement | Evidence |
-| --- | --- | --- | --- | --- |
-| Codex | `AGENTS.md`, `.codex/config.toml`, optional `.codex/agents/*.toml` | Unverified | Partial | Record date, owner, command/session, and active model settings. |
-| Claude Code | `CLAUDE.md`, `.claude/agents/*.md` | Unverified | Partial | Record date, owner, subagent files, and model frontmatter behavior. |
-| Cursor | `.cursor/rules/*.mdc` | Unverified | Advisory | Record date, owner, model picker/team setting, and loaded rule evidence. |
-| GitHub Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Unverified | Advisory | Record date, owner, selected chat/coding-agent model, and loaded instruction evidence. |
-| Antigravity | `.antigravity/agent-kit/plugin.json`, `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/SKILL.md` | Unverified | Advisory | Record date, owner, `agent-kit adapter validate antigravity`, and optional native `agy plugin validate` output. |
-| Agent Kit Runtime | `.agent-kit/orchestrator.json` | Alias routing and fallbacks | Enforced | Record `orchestrate validate`, provider probes, selected provider/model events, and fallback reasons. |
-
-## Runtime Aliases
-
-The executable runtime supports native adapters for OpenAI, Anthropic, Gemini, and OpenAI-compatible APIs including xAI/Grok, DeepSeek, Kimi, GLM, OpenRouter, Ollama, LM Studio, and vLLM. Configure project-owned model names in `.agent-kit/orchestrator.json`; do not copy dated IDE recommendations into active runtime aliases without verifying provider documentation and access.
-
-Each alias is deterministic: candidates are attempted in order, capability mismatches do not consume an attempt, provider failures are recorded, and `maxAttempts` bounds fallback. Tool-using agents automatically require the `tools` capability, so text-only local models fail closed instead of receiving unsupported tool calls.
-
-## June 2026 Commented Recommendations
-
-These are setup comments, not permanent guarantees. Verify against the active IDE and provider docs before enabling.
-
-### Codex
-
-```toml
-# ~/.codex/config.toml or trusted project .codex/config.toml
-# June 2026 Agent Kit suggestion:
-# model = "gpt-5.5"
-# model_reasoning_effort = "medium"
-#
-# For custom Codex agents, pin only where the role needs it:
-# model = "gpt-5.5"
-# model_reasoning_effort = "high"
-```
-
-### Claude Code
-
-```md
----
-name: lead-architect
-description: Use for architecture, cross-layer changes, and core-change council review.
-# June 2026 Agent Kit suggestion:
-# model: opus
-# effort: high
----
-```
-
-### Cursor
-
-```mdc
----
-description: Agent Kit model-selection reminder.
-alwaysApply: true
----
-
-<!--
-June 2026 Agent Kit suggestion:
-- Use the model picker or team model policy for the active task.
-- Prefer a deep reasoning model for Lead Architect, Security Reviewer, and Supabase/Postgres Engineer.
-- Prefer a fast/balanced coding model for Docs, Deployment, and low-risk QA passes.
-- Cursor rules advise model choice; they should not be treated as hard enforcement.
--->
-```
-
-### GitHub Copilot
-
-```md
-<!--
-June 2026 Agent Kit suggestion:
-- Select the strongest available model for architecture, security, RLS, and release-risk review.
-- Use a faster model for docs-only or low-risk mechanical changes.
-- Repository instructions advise model choice; Copilot model selection remains tool/user controlled.
--->
-```
-
-### Antigravity
-
-```md
-<!--
-June 2026 Agent Kit suggestion:
-- Use native `/plan`, `/security`, `/frontend`, `/copy`, `/handoff`, `/audit`, `/setup`, `/upgrade`, and `/ship` commands as runtime entrypoints.
-- Keep model choice aligned with MODEL_ROUTING.md profiles, but record that Antigravity model enforcement is advisory unless the runtime/workspace provides stronger controls.
-- Validate structural assets with `agent-kit adapter validate antigravity`; native `agy plugin validate` is optional when the CLI is installed.
--->
-```
-
-## Acceptance Evidence
-
-Before claiming strong or best-practice maturity, record:
-
-- Active IDE/tool and version or environment.
-- Model picker or config location.
-- Which agent profiles are enforced, partial, advisory, or manual.
-- Screenshot, command, session transcript, or PR evidence that instructions loaded.
-- Date and owner of the verification.

package/templates/next-supabase/QUALITY_GATES.md

@@ -1,97 +0,0 @@
-# Quality Gates
-
-This file defines the project maturity model. Use it to decide whether a change is merely working, strong enough for normal delivery, or best-practice ready.
-
-## Maturity Levels
-
-`agent-kit audit --json` reports one readiness verdict:
-
-- `needs-setup`: required install or council contract checks are failing.
-- `baseline-setup`: setup is valid, but starter evidence placeholders remain.
-- `needs-improvement`: no blocking failures, but warnings remain.
-- `best-practice-candidate`: static audit found no failures or warnings.
-
-Use `agent-kit audit --min-readiness <level>` in CI when the project wants a merge or release threshold. New projects usually start at `baseline-setup`; mature projects should move toward `best-practice-candidate`.
-
-### Baseline
-
-Baseline means the project is usable and the agent kit can audit it.
-
-- `AGENTS.md`, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `COUNCIL.md`, `SPEC.md`, `DECISIONS.md`, `DOCS.md`, `DESIGN.md`, `MESSAGING.md`, `MODEL_ROUTING.md`, `STYLE_GUIDE.md`, `SECURITY.md`, `TESTING.md`, `DEPLOYMENT.md`, and `UPGRADE.md` exist.
-- `.agent-kit/agent-roster.json`, `.agent-kit/model-routing.json`, disabled-by-default `.agent-kit/orchestrator.json`, and `.agent-kit/schemas/` exist.
-- `.agent-kit/assistant-adapters/` exists.
-- Runtime adapters such as Antigravity are validated with `agent-kit adapter validate <target>` before being treated as active.
-- Agent Studio schemas for project context, correction rules, session events, and studio sessions exist when the installed kit version includes them.
-- Planner is the default planning route.
-- Lead Architect reviews core changes.
-- Security Reviewer reviews auth, RLS, dependency, secret, external-call, and release-risk changes.
-- Marketing Copy Lead reviews public-facing or conversion-facing copy, positioning, proof, objections, voice, and CTA hierarchy.
-- QA evidence is recorded before behavior changes are accepted.
-
-### Strong
-
-Strong means the project is safe for repeated team or agent delivery.
-
-- Council sessions record workflow, decision, risk, next handoff, required outputs, and evidence.
-- `.agent-kit/project-context.json` and `.agent-kit/project-context.md` capture product intent, users, workflows, auth/data assumptions, integrations, design direction, quality target, and open questions.
-- Active project and agent corrections are reviewed before implementation and are reflected in future session behavior.
-- Agent Studio sessions render current `index.md` and `transcript.md` files after visible decisions, handoffs, artifacts, corrections, or verification change.
-- Optional static Studio exports are regenerated from local files after session evidence changes and are checked for secret leakage.
-- `ASSISTANT_ADAPTERS.md` records active AI tool surfaces, model-selection status, enforcement level, and verification evidence.
-- `MODEL_ROUTING.md` records active model-selection status, dated recommendations, enforcement limits, and known IDE limitations.
-- `MESSAGING.md` captures audience, pain, desired outcome, alternatives, differentiator, proof, objections, voice, conversion goal, and copy inventory.
-- `SPEC.md` documents affected architecture, behavioral contracts, data model, RLS inventory, and critical workflows.
-- `SECURITY.md` covers OWASP Top 10, Supabase RLS, service-role isolation, secrets, IDOR prevention, dependency risk, and external-call risk.
-- `DESIGN.md` captures audience, user needs, real content, brand constraints, reference set, anti-references, creative direction, design critique verdict, distinctiveness benchmark, product-quality scorecard, design tokens, and visual QA tier.
-- `STYLE_GUIDE.md` defines component patterns, states, responsive behavior, accessibility, and anti-generic AI-site rules.
-- `TESTING.md` defines unit, regression, smoke, visual QA, accessibility, and release checks.
-- `DEPLOYMENT.md` documents environments, migrations, env vars, observability, rollback, and post-release verification.
-- `UPGRADE.md` documents diff/update flow, release notes, migration review, generated types, and rollback evidence.
-- When executable orchestration is enabled, `orchestrate validate` passes and provider aliases, credentials, mutation roles, MCP, Docker, limits, and approvals have named owners.
-
-### Best-Practice
-
-Best-practice means evidence can survive handoff, release, and later audit.
-
-- Every meaningful change maps affected layers: data, business logic, presentation, auth, deployment, docs, and tests.
-- 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, 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.
-- Runtime adapter evidence includes command/plugin validation, portable `SKILL.md` coverage, package allowlist coverage, and proof that adapter files point back to Agent Kit source-of-truth contracts.
-- Repo health includes issue/PR templates, CODEOWNERS, dependency updates, CodeQL or equivalent scanning, dependency review, provenance expectations, support, conduct, and governance.
-- Public or shared package releases use Trusted Publishing or equivalent identity-bound release provenance.
-- Executable runs have offline plan evidence, explicit approvals, bounded provider/tool outcomes, redacted run events, isolated worktree status, scoped commit review, and a manual merge/remove decision.
-
-## Change Acceptance Matrix
-
-| Change Type | Required Council | Required Evidence |
-| --- | --- | --- |
-| 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, 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 |
-| Runtime adapter/package | Planner, Lead Architect, Security Reviewer, QA, Docs | `agent-kit adapter validate`, `agent-kit package validate`, command/skill asset coverage, source-of-truth references, no secret-like runtime assets |
-| Executable orchestration | Planner, Lead Architect, Security Reviewer, QA, Docs, Deployment/Observability Engineer | `orchestrate validate` and plan, provider/MCP policy, approvals, run ID/events, worktree/commit, timeout/cancel behavior, manual integration decision |
-| Upgrade/dependency | Planner, Lead Architect, Security Reviewer, QA, Docs, Deployment/Observability Engineer | Release notes, codemods or migration guide, `agent-kit diff`, conflict review, audit output, rollback notes |
-
-## Evidence Rules
-
-- 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.
-- A local customization is acceptable only when `.agent-kit/overrides.json` explains why and when it was reviewed.
-- A human correction is not durable until it is stored in `.agent-kit/corrections/`, remains secret-safe, has a clear scope, and is visible to future agents through installed instructions.
-- An upgrade is not complete until `UPGRADE.md` records version changes, migration impact, rollback process, and verification evidence.
-- IDE delegation is not executable-runtime evidence. Require `orchestrate status`, versioned run events, checkpoint state, and worktree/commit evidence.