@appsforgood/next-supabase-kit 0.1.7 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsforgood/next-supabase-kit",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Open agent council, skills, prompts, checklists, and markdown templates for Next.js and Supabase projects.",
   "type": "module",
   "repository": {
@@ -69,21 +69,29 @@
     "node": ">=20"
   },
   "packageManager": "npm@11.6.2",
+  "workspaces": [
+    "packages/runtime"
+  ],
   "scripts": {
-    "build": "tsup && node scripts/copy-studio-assets.mjs",
+    "build": "npm run build --workspace @appsforgood/agent-kit-runtime && tsup && node scripts/copy-studio-assets.mjs",
+    "predev": "npm run build --workspace @appsforgood/agent-kit-runtime",
     "dev": "tsx src/cli/index.ts",
-    "typecheck": "tsc --noEmit",
+    "pretypecheck": "npm run build --workspace @appsforgood/agent-kit-runtime",
+    "typecheck": "tsc --noEmit && npm run typecheck --workspace @appsforgood/agent-kit-runtime",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "pretest": "npm run build --workspace @appsforgood/agent-kit-runtime",
     "test": "vitest run",
+    "pretest:coverage": "npm run build --workspace @appsforgood/agent-kit-runtime",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "smoke": "node dist/index.js doctor",
     "smoke:install": "node scripts/smoke-install.mjs",
     "smoke:studio": "node scripts/smoke-studio.mjs",
     "smoke:setup": "node scripts/smoke-setup.mjs",
+    "smoke:ui-screens": "node scripts/smoke-ui-screens.mjs",
     "smoke:audit-gate": "node scripts/smoke-audit-gate.mjs",
     "package:validate": "node dist/index.js package validate",
     "examples:check": "node scripts/example-check.mjs",
@@ -92,7 +100,8 @@
     "sbom:generate": "node scripts/sbom-check.mjs --output sbom.cdx.json",
     "publish:verify": "node scripts/post-publish-verify.mjs",
     "changeset": "changeset",
-    "changeset:version": "changeset version",
+    "changeset:check": "node scripts/version-packages.mjs --check",
+    "changeset:version": "node scripts/version-packages.mjs",
     "release:check": "node scripts/release-check.mjs",
     "pack:check": "npm pack --dry-run",
     "dogfood:init": "node scripts/dogfood-init.mjs",
@@ -106,6 +115,14 @@
     "simple-git": "^3.27.0",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "@appsforgood/agent-kit-runtime": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@appsforgood/agent-kit-runtime": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.4",
@@ -114,6 +131,7 @@
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",
+    "playwright": "^1.55.1",
     "prettier": "^3.9.4",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
@@ -123,5 +141,10 @@
   },
   "overrides": {
     "esbuild": "0.28.1"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true,
+    "esbuild@0.28.1": true,
+    "fsevents": false
   }
 }

package/prompts/frontend-design-review.md

@@ -9,9 +9,13 @@ Reject:
 - Missing frontend product-quality scorecard
 - Missing visual QA or component-state evidence
 - Generic AI-site gradients
+- Accent-border cards, glow rails, neon strokes, gradient borders, oversized glass panels, or ornamental icon walls
 - Vague SaaS copy
 - Fake metrics
+- Decorative credibility badges or unsupported proof
 - Card soup
+- Filler sections that replace the requested app or tool workflow
+- Color-only alerts, low-contrast tints, or vague status panels
 - Missing mobile states
 - Missing loading, empty, error, disabled, or success states
 
@@ -23,6 +27,8 @@ Recommend:
 - Which visual QA tier is appropriate for the change
 - Task-first layout
 - Domain-specific hierarchy
+- Restrained 1px full-border surfaces, subtle background tint when needed, clear labels, icons, and semantic state text
+- Concrete product nouns, user actions, constraints, real proof, and honest empty or connected-data states
 - Design tokens
 - Accessible forms and controls
 - WCAG 2.1 AA behavior

package/prompts/screenshot-review.md

@@ -9,7 +9,8 @@ Check:
 - First screen shows the real product, task, object, or workflow.
 - The selected creative direction is visible in tokens, layout, copy, imagery, density, and interaction tone.
 - Layout is usable on desktop and mobile without overlapping text or controls.
-- Visual direction fits the domain and does not rely on generic AI-site gradients, card soup, vague SaaS copy, or fake metrics.
+- Visual direction fits the domain and does not rely on generic AI-site gradients, accent-border cards, glow rails, neon strokes, gradient borders, card soup, oversized glass panels, ornamental icon walls, vague SaaS copy, decorative credibility badges, filler sections, or fake metrics.
+- Cards, callouts, alerts, panels, and status messages use restrained 1px full-border surfaces, subtle background tint when needed, clear labels, icons, semantic state text, and WCAG AA contrast instead of decorative borders or color-only state.
 - Design tokens are visible in color, typography, spacing, radius, state color, and focus treatment.
 - Loading, empty, error, disabled, success, and mobile states are represented or explicitly accounted for.
 - Visual QA tier is appropriate for the risk: screenshot review, Playwright screenshots, Storybook visual tests, or visual-regression service.

package/schemas/audit-report-v2.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.dev/schemas/audit-report-v2.schema.json",
+  "title": "Agent Kit Audit Report v2",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "tool", "root", "summary", "readiness", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "const": "agent-kit" },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "root": { "const": "." },
+    "summary": {
+      "type": "object",
+      "required": ["pass", "warn", "fail", "suppressed"],
+      "additionalProperties": false,
+      "properties": {
+        "pass": { "type": "integer", "minimum": 0 },
+        "warn": { "type": "integer", "minimum": 0 },
+        "fail": { "type": "integer", "minimum": 0 },
+        "suppressed": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "readiness": { "$ref": "audit-report.schema.json#/$defs/readiness" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["level", "area", "message", "ruleId", "ruleVersion", "confidence", "evidence"],
+        "additionalProperties": false,
+        "properties": {
+          "level": { "type": "string", "enum": ["pass", "warn", "fail"] },
+          "area": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 },
+          "remediation": { "type": "string", "minLength": 1 },
+          "ruleId": { "type": "string", "minLength": 1 },
+          "ruleVersion": { "type": "string", "minLength": 1 },
+          "helpUri": { "type": "string", "format": "uri" },
+          "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+          "fixable": { "type": "boolean" },
+          "suppressed": { "type": "boolean" },
+          "suppressionReason": { "type": "string", "minLength": 1 },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["kind", "summary"],
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "type": "string", "enum": ["file", "command", "configuration", "runtime"] },
+                "summary": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "line": { "type": "integer", "minimum": 1 },
+                "column": { "type": "integer", "minimum": 1 },
+                "observedAt": { "type": "string", "format": "date-time" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/audit-report.schema.json

@@ -2,6 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://agent-skills.dev/schemas/audit-report.schema.json",
   "title": "Agent Kit Audit Report",
+  "$defs": {
+    "readiness": {
+      "type": "object",
+      "required": ["level", "summary", "nextActions"],
+      "additionalProperties": false,
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["needs-setup", "baseline-setup", "needs-improvement", "best-practice-candidate"]
+        },
+        "summary": { "type": "string", "minLength": 1 },
+        "nextActions": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  },
   "type": "object",
   "required": ["summary", "readiness", "findings"],
   "additionalProperties": false,
@@ -16,22 +31,7 @@
         "fail": { "type": "integer", "minimum": 0 }
       }
     },
-    "readiness": {
-      "type": "object",
-      "required": ["level", "summary", "nextActions"],
-      "additionalProperties": false,
-      "properties": {
-        "level": {
-          "type": "string",
-          "enum": ["needs-setup", "baseline-setup", "needs-improvement", "best-practice-candidate"]
-        },
-        "summary": { "type": "string", "minLength": 1 },
-        "nextActions": {
-          "type": "array",
-          "items": { "type": "string" }
-        }
-      }
-    },
+    "readiness": { "$ref": "#/$defs/readiness" },
     "findings": {
       "type": "array",
       "items": {

package/schemas/orchestrator.schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.dev/schemas/orchestrator.schema.json",
+  "title": "Agent Kit Orchestrator Configuration",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "enabled": { "type": "boolean", "default": false },
+    "defaultWorkflow": { "type": "string", "minLength": 1, "default": "planning" },
+    "defaultAlias": { "type": "string", "minLength": 1, "default": "balanced" },
+    "databasePath": { "type": "string", "minLength": 1, "default": ".agent-kit/runtime/runtime.sqlite" },
+    "providers": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/provider" },
+      "default": {}
+    },
+    "modelAliases": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/modelAlias" },
+      "default": {}
+    },
+    "agentRoutes": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "default": {}
+    },
+    "agentExecutors": {
+      "type": "object",
+      "additionalProperties": { "enum": ["model", "cursor"] },
+      "default": {}
+    },
+    "mutationAgents": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "cursor": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "command": { "type": "string", "minLength": 1, "default": "cursor-agent" },
+        "args": { "type": "array", "items": { "type": "string" } },
+        "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }
+      }
+    },
+    "mcpServers": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/mcpServer" },
+      "default": {}
+    },
+    "sandbox": { "$ref": "#/$defs/sandbox" },
+    "approvals": { "$ref": "#/$defs/approvals" },
+    "limits": { "$ref": "#/$defs/limits" }
+  },
+  "$defs": {
+    "credentialRef": {
+      "type": "string",
+      "pattern": "^(?:env:[A-Z][A-Z0-9_]*|keychain:[a-zA-Z0-9_.:@/-]+)$"
+    },
+    "capability": {
+      "enum": ["text", "tools", "parallel-tools", "structured-output", "streaming", "vision", "reasoning", "usage"]
+    },
+    "provider": {
+      "type": "object",
+      "required": ["kind"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": ["openai", "anthropic", "gemini", "xai", "deepseek", "kimi", "glm", "openrouter", "ollama", "lm-studio", "vllm", "openai-compatible"]
+        },
+        "baseUrl": { "type": "string", "format": "uri" },
+        "credentialRef": { "$ref": "#/$defs/credentialRef" },
+        "allowPrivateNetwork": { "type": "boolean", "default": false },
+        "capabilities": { "type": "array", "items": { "$ref": "#/$defs/capability" }, "uniqueItems": true },
+        "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 600000 }
+      }
+    },
+    "modelAlias": {
+      "type": "object",
+      "required": ["candidates"],
+      "additionalProperties": false,
+      "properties": {
+        "candidates": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["provider", "model"],
+            "additionalProperties": false,
+            "properties": {
+              "provider": { "type": "string", "minLength": 1 },
+              "model": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "requiredCapabilities": { "type": "array", "items": { "$ref": "#/$defs/capability" }, "uniqueItems": true },
+        "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }
+      }
+    },
+    "mcpServer": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["transport", "command"],
+          "additionalProperties": false,
+          "properties": {
+            "transport": { "const": "stdio" },
+            "command": { "type": "string", "minLength": 1 },
+            "args": { "type": "array", "items": { "type": "string" } },
+            "envRefs": { "type": "object", "additionalProperties": { "$ref": "#/$defs/credentialRef" } },
+            "allowHostExecution": { "type": "boolean", "default": false },
+            "allowedTools": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["transport", "url", "allowedHosts"],
+          "additionalProperties": false,
+          "properties": {
+            "transport": { "const": "streamable-http" },
+            "url": { "type": "string", "format": "uri" },
+            "authRef": { "$ref": "#/$defs/credentialRef" },
+            "allowedHosts": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+            "allowPrivateNetwork": { "type": "boolean", "default": false },
+            "allowedTools": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+          }
+        }
+      ]
+    },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "enum": ["docker", "host-readonly"] },
+        "image": { "type": "string", "minLength": 1 },
+        "network": { "enum": ["none", "approved"] },
+        "allowHostMutations": { "type": "boolean" },
+        "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 },
+        "memoryMb": { "type": "integer", "minimum": 128, "maximum": 32768 },
+        "cpus": { "type": "number", "exclusiveMinimum": 0, "maximum": 32 }
+      }
+    },
+    "approvals": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "const": "risk-tiered" },
+        "requirePlan": { "type": "boolean" },
+        "requireFinalCommit": { "type": "boolean" }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxSteps": { "type": "integer", "minimum": 1, "maximum": 100 },
+        "maxAgentVisits": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "maxRetriesPerNode": { "type": "integer", "minimum": 0, "maximum": 5 },
+        "maxToolCallsPerAgent": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "runTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 86400000 }
+      }
+    }
+  }
+}

package/schemas/runtime-event.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.dev/schemas/runtime-event.schema.json",
+  "title": "Agent Kit Runtime Event",
+  "type": "object",
+  "required": ["schemaVersion", "eventId", "sequence", "runId", "createdAt", "type"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "eventId": { "type": "string", "minLength": 1 },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "type": {
+      "enum": [
+        "run_started",
+        "run_status_changed",
+        "agent_started",
+        "agent_completed",
+        "handoff",
+        "approval_requested",
+        "approval_decided",
+        "tool_started",
+        "tool_completed",
+        "provider_selected",
+        "artifact",
+        "verification",
+        "run_error",
+        "run_completed"
+      ]
+    },
+    "agentId": { "type": "string", "minLength": 1 },
+    "text": { "type": "string" },
+    "status": { "enum": ["planned", "running", "awaiting-approval", "blocked", "cancelled", "failed", "complete"] },
+    "approval": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["approvalId", "runId", "risk", "title", "detail", "requestedAt"],
+          "additionalProperties": false,
+          "properties": {
+            "approvalId": { "type": "string", "minLength": 1 },
+            "runId": { "type": "string", "minLength": 1 },
+            "risk": { "enum": ["plan", "write", "network", "secret", "destructive", "host-mutation", "final-commit"] },
+            "title": { "type": "string", "minLength": 1 },
+            "detail": { "type": "string" },
+            "requestedAt": { "type": "string", "format": "date-time" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["approvalId", "decision", "decidedAt"],
+          "additionalProperties": false,
+          "properties": {
+            "approvalId": { "type": "string", "minLength": 1 },
+            "decision": { "enum": ["approve", "reject"] },
+            "decidedAt": { "type": "string", "format": "date-time" },
+            "actor": { "type": "string", "minLength": 1 },
+            "note": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "data": { "type": "object", "additionalProperties": true }
+  }
+}

package/schemas/runtime-run.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.dev/schemas/runtime-run.schema.json",
+  "title": "Agent Kit Runtime Run",
+  "type": "object",
+  "required": ["schemaVersion", "runId", "workflowId", "goal", "status", "createdAt", "updatedAt", "sourceRoot", "baseCommit", "results"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
+    "workflowId": { "type": "string", "minLength": 1 },
+    "goal": { "type": "string", "minLength": 1 },
+    "status": { "$ref": "#/$defs/status" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "sourceRoot": { "type": "string", "minLength": 1 },
+    "baseCommit": { "type": "string", "minLength": 1 },
+    "worktreePath": { "type": "string", "minLength": 1 },
+    "branchName": { "type": "string", "minLength": 1 },
+    "activeAgentId": { "type": "string", "minLength": 1 },
+    "pendingApproval": { "$ref": "#/$defs/approvalRequest" },
+    "commit": { "type": "string", "minLength": 1 },
+    "changed": { "type": "string" },
+    "results": { "type": "array", "items": { "$ref": "#/$defs/agentResult" } },
+    "error": { "type": "string" }
+  },
+  "$defs": {
+    "status": { "enum": ["planned", "running", "awaiting-approval", "blocked", "cancelled", "failed", "complete"] },
+    "risk": { "enum": ["plan", "write", "network", "secret", "destructive", "host-mutation", "final-commit"] },
+    "approvalRequest": {
+      "type": "object",
+      "required": ["approvalId", "runId", "risk", "title", "detail", "requestedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "approvalId": { "type": "string", "minLength": 1 },
+        "runId": { "type": "string", "minLength": 1 },
+        "risk": { "$ref": "#/$defs/risk" },
+        "title": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string" },
+        "requestedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "agentResult": {
+      "type": "object",
+      "required": ["agentId", "summary", "decision", "risk", "artifacts", "verification"],
+      "additionalProperties": false,
+      "properties": {
+        "agentId": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string" },
+        "decision": { "type": "string" },
+        "risk": { "type": "string" },
+        "artifacts": { "type": "array", "items": { "type": "string" } },
+        "verification": { "type": "array", "items": { "type": "string" } },
+        "requestedHandoff": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/session-event.schema.json

@@ -6,6 +6,8 @@
   "required": ["type", "createdAt"],
   "additionalProperties": false,
   "properties": {
+    "eventId": { "type": "string", "format": "uuid" },
+    "sequence": { "type": "integer", "minimum": 1 },
     "type": {
       "type": "string",
       "enum": [

package/templates/next-supabase/.agent-kit/orchestrator.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "enabled": false,
+  "defaultWorkflow": "planning",
+  "defaultAlias": "balanced",
+  "databasePath": ".agent-kit/runtime/runtime.sqlite",
+  "providers": {},
+  "modelAliases": {},
+  "agentRoutes": {},
+  "agentExecutors": {},
+  "mutationAgents": [
+    "supabase-postgres-engineer",
+    "nextjs-engineer",
+    "frontend-design-lead",
+    "marketing-copy-lead",
+    "qa-engineer",
+    "docs-maintainer",
+    "deployment-observability-engineer"
+  ],
+  "cursor": {
+    "enabled": false,
+    "command": "cursor-agent",
+    "args": ["--print", "--output-format", "stream-json", "--force"],
+    "timeoutMs": 900000
+  },
+  "mcpServers": {},
+  "sandbox": {
+    "provider": "docker",
+    "image": "node:22-bookworm-slim",
+    "network": "none",
+    "allowHostMutations": false,
+    "timeoutMs": 600000,
+    "memoryMb": 2048,
+    "cpus": 2
+  },
+  "approvals": {
+    "mode": "risk-tiered",
+    "requirePlan": true,
+    "requireFinalCommit": true
+  },
+  "limits": {
+    "maxSteps": 24,
+    "maxAgentVisits": 2,
+    "maxRetriesPerNode": 2,
+    "maxToolCallsPerAgent": 20,
+    "runTimeoutMs": 3600000
+  }
+}

package/templates/next-supabase/.agent-kit/runtime/gitignore.template

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/templates/next-supabase/AGENTS.md

@@ -4,6 +4,8 @@ This project uses explicit agent roles so implementation, security, quality, and
 
 Use `.agent-kit/agent-roster.json` as the default council contract. Use `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` to choose model profiles for each agent. Before meaningful work, read `.agent-kit/project-context.json`, `.agent-kit/project-context.md`, and `.agent-kit/agent-briefs.md` when present, then apply active corrections from `.agent-kit/corrections/project-rules.json` and `.agent-kit/corrections/agent-rules.json`. When a request is ambiguous, planning-oriented, or cross-layer, start with Planner and follow the matching workflow in `AGENT_ROSTER.md`. Use `ASSISTANT_ADAPTERS.md` to confirm which AI coding tools load these instructions and how model selection is handled. Record meaningful council sessions in `COUNCIL.md` or the local Agent Studio files under `.agent-kit/council-sessions/`.
 
+When `.agent-kit/orchestrator.json` is enabled, treat `agent-kit orchestrate validate`, plan/status output, approvals, runtime events, and worktree/commit state as the executable source of truth. IDE delegation is not proof that the graph ran. Never bypass a paused approval, capability mismatch, Docker/host policy, or the runtime rule that forbids automatic merge, push, pull request, deployment, and migration application.
+
 ## Planner
 
 Owns planning, scope breakdown, sequencing, and council routing before implementation starts.

package/templates/next-supabase/ASSISTANT_ADAPTERS.md

@@ -9,6 +9,7 @@ Canonical source of truth:
 - `.agent-kit/agent-roster.json`
 - `MODEL_ROUTING.md`
 - `.agent-kit/model-routing.json`
+- `.agent-kit/orchestrator.json`
 - `.agent-kit/project-context.json`
 - `.agent-kit/project-context.md`
 - `.agent-kit/corrections/project-rules.json`
@@ -20,6 +21,9 @@ Canonical source of truth:
 - `.agent-kit/schemas/session-event.schema.json`
 - `.agent-kit/schemas/project-context.schema.json`
 - `.agent-kit/schemas/correction-rules.schema.json`
+- `.agent-kit/schemas/orchestrator.schema.json`
+- `.agent-kit/schemas/runtime-run.schema.json`
+- `.agent-kit/schemas/runtime-event.schema.json`
 - `QUALITY_GATES.md`
 
 ## Active Tool Surfaces
@@ -31,6 +35,7 @@ Canonical source of truth:
 | Cursor | `.cursor/rules/*.mdc`, `.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md` | Active on init (rules); subagents on `--activate cursor` | Advisory | Partial | Run `agent-kit init --activate cursor`; verify subagents. | Delegate to `.cursor/agents/` instead of role-playing the council. |
 | Claude Code | `.claude/agents/*.md` and optional `CLAUDE.md` | TBD | TBD | Partial | TBD | Run `agent-kit init --activate claude` to generate subagents from `.agent-kit/agent-roster.json` and install `CLAUDE.md`. |
 | Antigravity | `.antigravity/agent-kit/plugin.json`, `.antigravity/agent-kit/commands/*.toml`, `.antigravity/runtime-skills/*/SKILL.md` | TBD | TBD | Advisory | TBD | Run `agent-kit init --activate antigravity`, then `agent-kit adapter validate antigravity`; optional native validation is `agy plugin validate` when available. |
+| Agent Kit Runtime | `.agent-kit/orchestrator.json`, `@appsforgood/agent-kit-runtime`, `agent-kit orchestrate ...` | Disabled by default | Enforced aliases and capability gates when active | Enforced local graph and approval policy | TBD | This is the executable council. IDE adapters above remain instruction surfaces. |
 
 ## Model Selection
 
@@ -51,6 +56,21 @@ Canonical source of truth:
 - Keep commands concrete and verified. Document known failures or environment prerequisites.
 - Update this file when a tool is added, removed, or confirmed to load the project instructions.
 - Record MCP/tool connector setup separately from model-selection setup. Tool access and model choice are different controls.
+- Do not claim an orchestrated run from IDE delegation alone. Require runtime status, events, checkpoint, and scoped commit evidence.
+
+## Executable Runtime
+
+Install `@appsforgood/agent-kit-runtime`, configure credential references and deterministic aliases in `.agent-kit/orchestrator.json`, then run:
+
+```bash
+agent-kit orchestrate validate
+agent-kit orchestrate plan "Describe the goal"
+agent-kit orchestrate run "Describe the goal"
+agent-kit orchestrate approve <run-id>
+agent-kit orchestrate status <run-id>
+```
+
+Runs use explicit roster sequences, SQLite checkpoints, risk-tiered approvals, redacted JSONL evidence, an isolated Git worktree, Docker-first mutations, and an optional approved Cursor host executor. The runtime may create one scoped commit; it never merges, pushes, or opens a pull request. See `.agent-kit/assistant-adapters/orchestrator-runtime.md`.
 
 ## Cursor Activation