@appsforgood/next-supabase-kit 0.1.3 → 0.1.5

package/schemas/agentic-level.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.dev/schemas/agentic-level.schema.json",
+  "title": "Agent Kit Agentic Level Report",
+  "type": "object",
+  "required": ["currentLevel", "targetLevel", "maintainerProfile", "computedAt", "signals"],
+  "additionalProperties": false,
+  "properties": {
+    "currentLevel": { "type": "integer", "enum": [3, 4, 5, 6] },
+    "targetLevel": { "type": "integer", "enum": [3, 4, 5, 6, 7, 8] },
+    "maintainerProfile": { "type": "boolean" },
+    "computedAt": { "type": "string", "format": "date-time" },
+    "maintainerNote": { "type": "string" },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "level", "label", "pass", "evidence", "remediation"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "level": { "type": "integer", "enum": [3, 4, 5, 6] },
+          "label": { "type": "string" },
+          "pass": { "type": "boolean" },
+          "evidence": { "type": "string" },
+          "remediation": { "type": "string" }
+        }
+      }
+    },
+    "climbSteps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "level", "label", "pass", "evidence", "remediation"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "level": { "type": "integer", "enum": [3, 4, 5, 6] },
+          "label": { "type": "string" },
+          "pass": { "type": "boolean" },
+          "evidence": { "type": "string" },
+          "remediation": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/onboarding-state.schema.json

@@ -28,6 +28,9 @@
     "wizardVersion": { "type": "string" },
     "ideSurface": { "type": "string", "enum": ["cursor", "copilot", "claude", "codex", "other"] },
     "ideVerifiedAt": { "type": "string", "format": "date-time" },
-    "visualQaTier": { "type": "string", "enum": ["baseline", "strong", "mature"] }
+    "visualQaTier": { "type": "string", "enum": ["baseline", "strong", "mature"] },
+    "targetAgenticLevel": { "type": "integer", "enum": [3, 4, 5, 6, 7, 8] },
+    "lastAgenticLevel": { "type": "integer", "enum": [3, 4, 5, 6] },
+    "lastAgenticComputedAt": { "type": "string", "format": "date-time" }
   }
 }

package/templates/next-supabase/ASSISTANT_ADAPTERS.md

@@ -26,9 +26,9 @@ Canonical source of truth:
 
 | Tool | Instruction surface | Instruction status | Model-selection status | Enforcement | Evidence | Notes |
 | --- | --- | --- | --- | --- | --- | --- |
-| Codex / AGENTS.md-compatible tools | `AGENTS.md`, optional `.codex/config.toml`, optional `.codex/agents/*.toml` | TBD | TBD | Partial | TBD | Run `agent-kit init --activate codex` to copy optional `.codex/config.toml`. Confirm the tool loads root `AGENTS.md`. |
+| Codex / AGENTS.md-compatible tools | `AGENTS.md`, `.codex/config.toml`, `.codex/agents/*.toml` | TBD | TBD | Partial | TBD | Run `agent-kit init --activate codex` to generate council custom agents and copy `.codex/config.toml`. |
 | GitHub Copilot / VS Code | `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` | TBD | TBD | Advisory | TBD | Run `agent-kit init --activate copilot` to promote Copilot instruction files. |
-| Cursor | `.cursor/rules/cursor-agent-kit.mdc` and `.cursor/rules/cursor-model-selection.mdc` | Active on init | Advisory | Advisory | `agent-kit init` copies canonical rules from `.agent-kit/assistant-adapters/`; verify in Cursor Settings > Rules that both rules load. | `agent-kit init` installs `.cursor/rules/cursor-agent-kit.mdc` and `.cursor/rules/cursor-model-selection.mdc`. Re-run `agent-kit diff` after kit updates if the canonical adapter files changed. |
+| 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. |
 
@@ -69,6 +69,30 @@ Verification steps:
 
 If a project already customized `.cursor/rules/`, review `.agent-kit/conflicts/` after `agent-kit update` before adopting newer adapter wording.
 
+Run `agent-kit init --activate cursor` to generate `.cursor/agents/*.md` and `.cursor/skills/*/SKILL.md` from the roster and kit skills.
+
+## Multi-agent delegation
+
+Same council playbook across IDEs — delegate to specialists instead of role-playing every role in one thread.
+
+| Risk / work | Cursor | Codex | Claude Code |
+| --- | --- | --- | --- |
+| Auth / RLS / secrets | `@security-reviewer` or Task `security-review` | spawn `security-reviewer.toml` | `@security-reviewer` |
+| Planning / scope | `@planner` | spawn `planner.toml` | `@planner` |
+| Frontend UI | `@frontend-design-lead` | spawn `frontend-design-lead.toml` | `@frontend-design-lead` |
+| QA / behavior changes | `@qa-engineer` or Task `bugbot` | spawn `qa-engineer.toml` | `@qa-engineer` |
+
+Record evidence with `agent-kit session checkpoint --file <json>` when the CLI is available.
+
+## Codex Activation
+
+`agent-kit init --activate codex` installs:
+
+- `.codex/config.toml`
+- `.codex/agents/*.toml` council custom agents with `model_reasoning_effort` from `.agent-kit/model-routing.json`
+
+Validate with `agent-kit adapter validate codex`.
+
 ## Antigravity Activation
 
 `agent-kit init --activate antigravity` installs a native runtime adapter without changing the canonical Agent Kit operating model:

package/templates/next-supabase/DOCS.md

@@ -11,6 +11,8 @@ 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:

package/templates/next-supabase/LOOP_CODING.md

@@ -0,0 +1,98 @@
+# 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/TESTING.md

@@ -55,6 +55,16 @@ Recommended baseline:
 - Visual QA evidence for high-risk UI changes
 - `agent-kit adapter validate antigravity` and `agent-kit package validate` when adapter/package assets change
 
+### Eval-driven PR loop
+
+Repeat **implement → check → fix** until tests and audit pass. See the kit's [LOOP_CODING.md](LOOP_CODING.md) for loop types, council handoffs, and safe automation limits. Minimum check commands:
+
+```bash
+npm test
+agent-kit audit --min-readiness baseline-setup
+agent-kit adapter validate all   # when IDE or adapter assets change
+```
+
 ## Security-Focused Tests
 
 Prioritize: