@appsforgood/next-supabase-kit 0.1.8 → 0.2.1

package/templates/next-supabase/DECISIONS.md

@@ -71,3 +71,17 @@ Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` as the provider-neutr
 ### Consequences
 
 Exact model names remain dated recommendations, while agents keep stable profile intent and evidence requirements.
+
+## Optional Executable Orchestrator
+
+### Context
+
+IDE rules and subagents provide advisory council routing but are not proof that an executable, resumable workflow ran.
+
+### Decision
+
+Keep `.agent-kit/orchestrator.json` disabled by default. When programmatic execution is required, install `@appsforgood/agent-kit-runtime`, validate deterministic aliases and credential references, and use its bounded LangGraph, SQLite checkpoint, approval, MCP, Docker, worktree, and redacted-evidence contracts. Permit at most one approved scoped commit; retain merge, push, pull request, deployment, and migration decisions for the operator.
+
+### Consequences
+
+The project can opt into stronger execution enforcement without making provider credentials or native runtime dependencies part of baseline Agent Kit use. Host execution and private network exceptions require explicit local rationale and approval evidence.

package/templates/next-supabase/DEPLOYMENT.md

@@ -18,6 +18,8 @@ Required Supabase variables usually include:
 - `NEXT_PUBLIC_SUPABASE_ANON_KEY`
 - Server-only service-role key when needed
 
+Optional Agent Kit runtime provider credentials must be referenced with `env:` names or OS-keychain entries. Do not copy resolved values into `.agent-kit/orchestrator.json`, deployment config, run evidence, or CI logs.
+
 ## Migration Order
 
 Before deploying code that depends on database changes:
@@ -42,4 +44,6 @@ Document:
 
 Document rollback steps for code, database migrations, and environment variable mistakes.
 
+If an orchestrated run produced a worktree or scoped commit, record the run ID, branch, commit, approval decisions, whether any migration/deploy command actually ran, and the manual keep/remove/merge decision. The runtime does not perform that repository or deployment step automatically.
+
 Link upgrade-specific rollback evidence from `UPGRADE.md` when the release includes package, framework, Agent Kit, or migration changes.

package/templates/next-supabase/DESIGN.md

@@ -34,6 +34,12 @@ Anti-references:
 - TBD: pattern, palette, layout, copy, or interaction style to avoid.
 - TBD: another explicit non-goal.
 
+Common visual tropes to reject unless a mature brand system explicitly requires them:
+
+- Accent-border cards, glow rails, neon strokes, gradient borders, and one-sided colored panel borders.
+- Generic gradient heroes, gradient text, abstract blobs, card soup, oversized rounded glass panels, and ornamental icon walls.
+- Fake dashboard metrics, decorative credibility badges, vague SaaS sayings, filler "features / benefits / how it works" sections, and color-only status styling.
+
 ## Creative Direction
 
 Before implementation, produce at least two distinct visual directions and choose one.

package/templates/next-supabase/DOCS.md

@@ -20,6 +20,7 @@ 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/`
@@ -42,6 +43,7 @@ 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`
@@ -61,6 +63,12 @@ Document primary workflows, including:
 
 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

package/templates/next-supabase/MODEL_ROUTING.md

@@ -6,6 +6,7 @@ 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`
 
@@ -16,6 +17,7 @@ Canonical source of truth:
 - 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
 
@@ -41,6 +43,13 @@ Canonical source of truth:
 | 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
 

package/templates/next-supabase/QUALITY_GATES.md

@@ -18,7 +18,7 @@ Use `agent-kit audit --min-readiness <level>` in CI when the project wants a mer
 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`, and `.agent-kit/schemas/` 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.
@@ -47,6 +47,7 @@ Strong means the project is safe for repeated team or agent delivery.
 - `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
 
@@ -63,6 +64,7 @@ Best-practice means evidence can survive handoff, release, and later audit.
 - 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
 
@@ -76,6 +78,7 @@ Best-practice means evidence can survive handoff, release, and later audit.
 | 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
@@ -91,3 +94,4 @@ Best-practice means evidence can survive handoff, release, and later audit.
 - 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.

package/templates/next-supabase/SECURITY.md

@@ -49,6 +49,16 @@ Track project controls explicitly.
 - Keep `.env.example` documented with placeholder values only.
 - Rotate secrets after suspected exposure.
 
+## Optional Orchestrator
+
+- Keep `.agent-kit/orchestrator.json` disabled until provider aliases, credential references, MCP allowlists, mutation roles, Docker policy, and approval gates are reviewed.
+- Use `env:` or `keychain:` references only; never put resolved credentials in config, prompts, run records, or evidence.
+- Treat model output, repository content, MCP metadata/output, and provider errors as untrusted.
+- Require explicit host opt-in and approval for Cursor or stdio MCP execution.
+- Keep provider/MCP redirects blocked, remote MCP hosts allowlisted, private-network access off by default, and Docker network disabled unless approved.
+- Run `agent-kit audit` before orchestration. Sensitive-path and evidence-redaction controls do not replace repository secret scanning or data-classification review.
+- Review the isolated worktree and scoped commit manually. The runtime must not merge, push, deploy, or apply migrations.
+
 ## Review Notes
 
 Add security-sensitive decisions and exceptions to `DECISIONS.md`.

package/templates/next-supabase/SPEC.md

@@ -25,9 +25,10 @@ List behavior that must be preserved during changes:
 - Agent council routing in `.agent-kit/agent-roster.json`
 - Model profile routing in `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`
 - Optional runtime adapter commands and portable `SKILL.md` wrappers, when activated
+- Optional executable runtime policy in `.agent-kit/orchestrator.json`, when activated
 - UI improvement command workflows, detector severity findings, and acceptance rubric when frontend work is in scope
 - Council-session evidence in `COUNCIL.md`
-- Agent, council-session, model-routing, and audit-report schema contracts in `.agent-kit/schemas/`
+- Agent, council-session, model-routing, orchestrator, runtime-run, runtime-event, and audit-report schema contracts in `.agent-kit/schemas/`
 - Planner default ownership for planning and Lead Architect review for core changes
 - Quality gate evidence in `QUALITY_GATES.md`
 - Content-first design direction in `DESIGN.md`
@@ -68,6 +69,7 @@ Record the current maturity target and evidence.
 | Council routing | TBD | TBD | TBD | `AGENT_ROSTER.md`, `COUNCIL.md` |
 | Model routing | TBD | TBD | TBD | `MODEL_ROUTING.md`, `ASSISTANT_ADAPTERS.md` |
 | Runtime adapters | TBD | TBD | TBD | `agent-kit adapter validate antigravity`, `.antigravity/agent-kit/`, `.antigravity/runtime-skills/` |
+| Executable orchestration | TBD | TBD | TBD | `agent-kit orchestrate validate`, plan/status output, approvals, redacted events, scoped worktree commit |
 | Architecture | TBD | TBD | TBD | Affected-layer map, `DECISIONS.md` |
 | Supabase/RLS | TBD | TBD | TBD | RLS inventory, migration tests |
 | Messaging | TBD | TBD | TBD | `MESSAGING.md`, proof map, objection handling, CTA hierarchy |

package/templates/next-supabase/STYLE_GUIDE.md

@@ -45,6 +45,21 @@ Prefer:
 - Mobile-first responsive layouts.
 - Creative direction that is visibly tied to product content and user need.
 
+### Anti-Slop UI Rules
+
+Do not use generic AI-slop treatments as a substitute for product design. If a mature brand system intentionally uses one of these patterns, record the exception and rationale in `DESIGN.md` or `.agent-kit/overrides.json`.
+
+- No accent-border cards. Replace thick, high-contrast, one-sided colored borders, glow rails, neon strokes, and gradient borders on cards, callouts, alerts, panels, or status messages with restrained 1px full-border surfaces, subtle background tint when needed, clear labels, icons, and semantic state text.
+- No gradient-as-design. Replace generic purple-blue gradient heroes, gradient text, and gradient blobs with product-specific imagery, workflow screenshots, object-focused media, real content, or a quiet tokenized background.
+- No card soup. Replace large grids of decorative cards with task-first layouts: tables, lists, timelines, forms, split panes, dashboards with real hierarchy, or workflow-specific grouped sections.
+- No fake dashboard proof. Replace invented metrics, placeholder charts, and claims like "98% faster" with real product data, honest sample labels, empty states, or "connect data to view this" states.
+- No vague SaaS sayings. Replace phrases like "supercharge your workflow", "unlock insights", "seamless collaboration", or "AI-powered productivity" with concrete user actions, product nouns, constraints, and outcomes the product actually supports.
+- No badge or confetti credibility. Replace decorative badges, pills, stars, awards, or "trusted by" placeholders with real proof, integration names, security posture, support details, or omit the section.
+- No oversized rounded glass panels. Replace translucent blur cards, frosted panels, and soft-glow shells with normal surfaces, clear section boundaries, practical density, and brand-appropriate depth.
+- No ornamental icon walls. Replace generic floating icons with functional icons attached to commands, states, navigation, feature rows, or concrete workflow steps.
+- No layout filler sections. Replace generic "features", "benefits", or "how it works" sections when the user asked for an app or tool with the actual usable workflow as the first screen.
+- No inaccessible decorative state styling. Replace color-only alerts, low-contrast tints, and vague status panels with semantic text, icons, ARIA-compatible state, WCAG AA contrast, and recovery actions.
+
 Use `.agent-kit/prompts/brand-content-intake.md` and `.agent-kit/prompts/creative-direction-matrix.md` when inputs are under-specified. Use `.agent-kit/design-briefs/*` before designing SaaS, admin dashboard, marketplace, content app, tool, ecommerce, portfolio/venue, education, community/social, or AI workflow surfaces. Use `.agent-kit/prompts/screenshot-review.md` after implementation to review desktop and mobile screenshots. Use `.agent-kit/prompts/visual-qa-plan.md` when a change needs repeatable visual regression or component-state evidence.
 
 Use `.agent-kit/prompts/design-critique-gate.md` before accepting significant frontend work. `DESIGN.md` should name a reference set, anti-references, source-safety notes, and a distinctiveness verdict so a design cannot pass only because it has tokens, states, and screenshots.

package/templates/next-supabase/TESTING.md

@@ -69,6 +69,12 @@ agent-kit audit --min-readiness baseline-setup
 agent-kit adapter validate all   # when IDE or adapter assets change
 ```
 
+## Optional Orchestrator Tests
+
+When `.agent-kit/orchestrator.json` is enabled, add evidence for offline config/plan validation, required capability routing, approval pause/resume, provider/MCP failure handling, Docker or explicit host policy, worktree isolation, scoped commit review, cancellation/timeout, and redacted event export. Use mocked loopback providers for deterministic tests; keep real credentials out of fixtures and CI logs.
+
+Run `agent-kit orchestrate status <run-id>` after a test run and record the run ID, approvals, worktree/commit, and remaining manual merge or cleanup step.
+
 ## Security-Focused Tests
 
 Prioritize:

package/templates/next-supabase/UPGRADE.md

@@ -24,6 +24,7 @@ Use `agent-kit audit --min-readiness best-practice-candidate` only after starter
 - Review `AGENTS.md`, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `MODEL_ROUTING.md`, `COUNCIL.md`, `QUALITY_GATES.md`, `SECURITY.md`, `TESTING.md`, and `DEPLOYMENT.md`.
 - If using Antigravity, review `.antigravity/agent-kit/plugin.json`, `.antigravity/agent-kit/commands/*.toml`, and `.antigravity/runtime-skills/*/SKILL.md`.
 - Validate runtime adapter assets with `agent-kit adapter validate antigravity`.
+- If `@appsforgood/agent-kit-runtime` is installed, finish or cancel paused runs, update it deliberately, review `.agent-kit/orchestrator.json` and runtime schema conflict proposals, then run `agent-kit orchestrate validate` and an offline plan.
 - Record accepted tradeoffs in `DECISIONS.md`.
 - Update this file with package version, release notes, migration status, rollback notes, owner, and date.