@appsforgood/next-supabase-kit 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.5
+
+- Added computed **Agentic Engineering Level** (L3–L6) in Agent Office and setup wizard: iceberg strip, climb checklist, `/api/state` payload, and `POST /api/agentic-level/refresh`.
+- Added [`src/studio/agentic-level.ts`](src/studio/agentic-level.ts), [`schemas/agentic-level.schema.json`](schemas/agentic-level.schema.json), and maintainer-profile L6 signals for kit source repos.
+- Extended setup wizard with adapter validate chip on IDE activation, audit-readiness vs Agentic level copy, and `LOOP_CODING.md` eval-loop next steps on complete.
+- Added [`research/summaries/agentic-engineering-maturity-levels.md`](research/summaries/agentic-engineering-maturity-levels.md) and cross-links from `DOCS.md`, `HANDOVER.md`, and `LOOP_CODING.md`.
+
+## 0.1.4
+
+- Added true multi-agent IDE activation for **Cursor** (`.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md`, scoped rules) and **Codex** (`.codex/agents/*.toml` with model routing effort) via `agent-kit init --activate cursor|codex`.
+- Added shared roster adapter generation (`roster-adapters.ts`) and assistant adapter table parsing so audit and `adapter validate` warn when Active Cursor/Codex rows lack specialist files.
+- Fixed setup wizard IDE activation order so `present` is detected after files are generated and conflicts are returned in the API response.
+- Quoted YAML frontmatter in generated Cursor/Claude subagents and Cursor skills so descriptions with colons or quotes remain valid.
+- Stopped post-copy mutation of existing `.codex/config.toml`; conflict-safe copy behavior now protects customized Codex config.
+- Fixed `cursor-planner.mdc` scoped rule frontmatter and expanded adapter validation, IDE activation, and SSE stream tests.
+
 ## 0.1.3
 
 - Added Antigravity runtime adapter support with `agent-kit init --activate antigravity`, `antigravity/plugin.json`, native `/setup`, `/audit`, `/plan`, `/handoff`, `/frontend`, `/security`, `/copy`, `/ship`, and `/upgrade` command files, and portable `runtime-skills/*/SKILL.md` wrappers.

package/DOGFOOD.md

@@ -119,3 +119,18 @@ Covered by `tests/update.test.ts`.
 - Activate at least one assistant adapter in a real project and record whether the chosen tool loads the canonical council instructions.
 - Apply the reference-led design critique gate to one real frontend change with desktop/mobile screenshot evidence.
 - After public publish, run `npm run publish:verify` to verify registry visibility, public `npx doctor`, clean temp `init`, and `audit --json` with zero failures.
+
+## BaseRepo Maintainer Dogfood Policy
+
+Date: 2026-06-17
+Policy: **gitignored local overlay + bootstrap script** (not committed to kit source)
+
+| Item | Detail |
+| --- | --- |
+| Bootstrap | `npm run dogfood:init` runs `agent-kit init --stack next-supabase --activate cursor --activate codex` against the repo root |
+| Gitignore | `.agent-kit/`, `.codex/`, init-generated council docs at repo root, and local pack tarballs — see `.gitignore` and [DOCS.md](DOCS.md#maintainer-dogfood) |
+| Validation | `node dist/index.js adapter validate cursor\|codex` after bootstrap |
+| Release evidence | [MAINTAINER_RELEASE.md](MAINTAINER_RELEASE.md) session checklist; loop patterns in [LOOP_CODING.md](LOOP_CODING.md) |
+| Rationale | Kit source stays in `templates/` and tracked maintainer docs; overlay proves Tier B activation without polluting commit history |
+
+This policy closes the gap where the kit shipped Level 5 IDE surfaces but BaseRepo maintainers operated at Level 4 day-to-day.

package/LOOP_CODING.md

@@ -0,0 +1,107 @@
+# 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. It is the canonical reference for eval-driven development with `@appsforgood/next-supabase-kit`.
+
+## 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 — BaseRepo uses `npm run release:check` as the maintainer merge gate |
+| **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 in a kit-consuming project:
+
+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.
+
+BaseRepo maintainers use the same pattern at repo scale:
+
+```bash
+npm run release:check    # tests, build, package validate, smokes, adapter validate
+npm run smoke:audit-gate
+```
+
+## 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` (see `MAINTAINER_RELEASE.md` for kit release evidence).
+
+## 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 templates stay shippable | `agent-kit adapter validate all` (BaseRepo: `npm run adapter:validate` in `release:check`) |
+
+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 in consuming projects:
+
+| 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
+- Duplicating runtime product agents inside the kit repo (wrong shape for agent-kit)
+
+## Related Docs
+
+- `AGENTS.md` — council roles and default handoffs
+- `QUALITY_GATES.md` — Baseline / Strong / Mature evidence tiers
+- `COUNCIL.md` — session evidence template
+- `MAINTAINER_RELEASE.md` — kit maintainer release session checklist
+- `research/summaries/agentic-engineering-maturity-levels.md` — L3–L8 ladder and office integration
+- `TESTING.md` — project test and CI gate expectations
+- `PUBLISH.md` — npm publish runbook

package/MAINTAINER_RELEASE.md

@@ -0,0 +1,100 @@
+# Maintainer Release Evidence
+
+Use this checklist when shipping `@appsforgood/next-supabase-kit` releases. It aligns kit maintainer practice with the **Strong** tier in `QUALITY_GATES.md`: council sessions record workflow, decision, risk, next handoff, required outputs, and evidence.
+
+For loop patterns and safe automation limits, see [LOOP_CODING.md](LOOP_CODING.md). For publish steps, see [PUBLISH.md](PUBLISH.md).
+
+## When To Open A Session
+
+Start `agent-kit session` (or a `COUNCIL.md` entry) when the release includes any of:
+
+- CLI or install behavior changes
+- New or changed IDE adapter surfaces (Cursor, Codex, Claude, Copilot, Antigravity)
+- Audit, roster, schema, or Agent Studio contract changes
+- Security-sensitive dependency or publish pipeline changes
+- Multi-agent work spanning Planner → Architect → QA
+
+Skip a formal session only for typo-only doc fixes with no behavioral impact.
+
+## Bootstrap Maintainer Dogfood
+
+Maintainers run the kit locally on BaseRepo without committing the overlay:
+
+```bash
+npm run dogfood:init
+node dist/index.js adapter validate cursor
+node dist/index.js adapter validate codex
+```
+
+Generated paths (`.agent-kit/`, `.cursor/`, `.codex/`, root council docs from init) are **gitignored**. Kit source stays in `templates/`, `assistant-adapters/`, and tracked root docs such as `DOCS.md` and `SPEC.md`.
+
+## Release Session Workflow
+
+```bash
+agent-kit session start --workflow release --request "Release vX.Y.Z"
+agent-kit session decision --agent planner --decision "..." --risk "..." --next "lead-architect" --evidence "..."
+agent-kit session verify --command "npm run release:check" --result pass --notes "..."
+agent-kit session verify --command "npm run smoke:audit-gate" --result pass
+agent-kit session output changelog --status complete --evidence "CHANGELOG.md#X.Y.Z"
+agent-kit session output test-evidence --status complete --evidence "vitest + smokes green"
+agent-kit session output publish-evidence --status complete --evidence "npm run publish:verify or GitHub Release vX.Y.Z"
+agent-kit session render
+```
+
+After publish, append a short evidence block to [DOGFOOD.md](DOGFOOD.md) (public-safe, no local paths).
+
+## COUNCIL.md Mirror Template
+
+When Agent Studio CLI is unavailable, paste this block into root `COUNCIL.md` (maintainer overlay, gitignored) or into the PR description:
+
+```md
+## YYYY-MM-DD - Release vX.Y.Z
+
+- Workflow: release
+- Status: complete
+- Request: Ship @appsforgood/next-supabase-kit@X.Y.Z
+- Affected layers: CLI, install, adapters, docs, CI, deployment
+
+### Required Outputs
+
+| Output | Status | Evidence |
+| --- | --- | --- |
+| Phased checklist | Complete | ROADMAP / PR scope |
+| Architecture decision | Complete/N/A | DECISIONS.md or PR note |
+| Security review | Complete | Dependency audit in release:check; no secret in adapters |
+| Test evidence | Complete | npm run release:check; npm run smoke:audit-gate |
+| Adapter validation | Complete | npm run adapter:validate (all IDE templates) |
+| Docs impact | Complete | CHANGELOG.md, DOCS.md, PUBLISH.md if process changed |
+| Publish verification | Complete | npm run publish:verify or Release workflow green |
+
+### Handoffs
+
+| Agent | Decision | Risk | Next Handoff | Evidence |
+| --- | --- | --- | --- | --- |
+| Planner | Release scope approved | Missed breaking change | Lead Architect / QA | PR + CHANGELOG |
+| QA Engineer | release:check green | Residual flake | Documentation Maintainer | CI logs |
+| Documentation Maintainer | CHANGELOG + DOGFOOD updated | Stale public evidence | Deployment/Observability | DOGFOOD.md entry |
+
+### Verification
+
+| Command Or Review | Result | Notes |
+| --- | --- | --- |
+| npm run release:check | Pass | Includes adapter:validate |
+| npm run smoke:audit-gate | Pass | baseline-setup, 0 failures |
+| npm run publish:verify | Pass/Skipped | Required after registry publish |
+```
+
+## Pre-Merge Gate (BaseRepo)
+
+Every release PR must pass:
+
+1. `npm run release:check` (tests, build, package validate, smokes, **adapter validate all**, audit, pack dry-run)
+2. `npm run smoke:audit-gate`
+3. CHANGELOG section for the target version
+4. Session render or COUNCIL mirror with verification table filled in
+
+## Post-Publish
+
+1. Run `npm run publish:verify` after registry propagation (or confirm Release workflow verification).
+2. Update `DOGFOOD.md` with publish verification snapshot (no machine paths).
+3. Mark release items in `ROADMAP.md`.

package/assistant-adapters/codex-agents.md

@@ -18,6 +18,19 @@ Use `AGENTS.md` as the primary project instruction surface.
 - `.agent-kit/council-sessions/`
 - `QUALITY_GATES.md`
 
+## Council Custom Agents
+
+After `agent-kit init --activate codex`, council specialists live in `.codex/agents/*.toml`.
+
+Spawn a dedicated custom agent instead of role-playing the whole council in one thread:
+
+- **Planning / scope:** `.codex/agents/planner.toml`
+- **Security / RLS / secrets:** `.codex/agents/security-reviewer.toml` (high reasoning effort)
+- **Frontend UI:** `.codex/agents/frontend-design-lead.toml`
+- **QA / tests:** `.codex/agents/qa-engineer.toml`
+
+Each file sets `model_reasoning_effort` from `.agent-kit/model-routing.json`. Verify model names in your Codex environment against `MODEL_ROUTING.md`.
+
 ## Operating Rule
 
 When a task is planning-oriented, ambiguous, risky, frontend-facing, security-sensitive, or release-related, start from the roster workflow instead of treating the request as a single generic implementation pass.
@@ -34,3 +47,5 @@ Record in `ASSISTANT_ADAPTERS.md`:
 - The command, session, or screenshot that proves the instructions loaded.
 - The model-selection setting or profile used for the active role.
 - Any known limitations or manual invocation steps.
+
+Run `agent-kit adapter validate codex` after activation.

package/assistant-adapters/cursor-agent-kit.mdc

@@ -20,6 +20,7 @@ Use `AGENTS.md`, `AGENT_ROSTER.md`, `.agent-kit/agent-roster.json`, `MODEL_ROUTI
 - Meaningful work should read project context and active corrections first.
 - Human corrections should be recorded before continuing and promoted to durable project or agent correction rules when they should affect future work.
 - Meaningful multi-agent work should use `agent-kit session checkpoint --file <json>` or individual `agent-kit session ...` commands and render Markdown evidence when available.
+- For council work, delegate to the matching project subagent in `.cursor/agents/` instead of role-playing every role in the main thread.
 
 ## Validation
 

package/assistant-adapters/cursor-frontend.mdc

@@ -0,0 +1,16 @@
+---
+description: Require Frontend Design Lead evidence for significant UI and component work.
+globs:
+  - "src/app/**"
+  - "src/components/**"
+  - "**/*.css"
+alwaysApply: false
+---
+
+# Frontend design gate reminders
+
+Significant UI changes require **Frontend Design Lead** review: brand/content intake, creative-direction rationale, reference-led critique, product-quality scorecard, accessibility, and visual QA evidence.
+
+Delegate to `@frontend-design-lead` in `.cursor/agents/frontend-design-lead.md` for isolated design review context.
+
+Reject generic AI-looking UI that is not specific to the product workflow and content model.

package/assistant-adapters/cursor-planner.mdc

@@ -0,0 +1,14 @@
+---
+description: Route ambiguous, planning, and cross-layer requests through the Planner workflow first.
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
+# Planner routing
+
+When a request is ambiguous, planning-oriented, roadmap-related, or spans multiple layers, start with the **Planner** workflow before implementation.
+
+Delegate to the `@planner` subagent in `.cursor/agents/planner.md` when the task needs isolated planning context.
+
+Read project context, corrections, and `AGENT_ROSTER.md` before choosing a workflow.

package/assistant-adapters/cursor-security.mdc

@@ -0,0 +1,18 @@
+---
+description: Require Security Reviewer for auth, RLS, secrets, API mutations, and external calls.
+globs:
+  - "supabase/**"
+  - "**/auth/**"
+  - "**/api/**"
+  - "**/middleware.ts"
+  - "**/proxy.ts"
+alwaysApply: false
+---
+
+# Security gate reminders
+
+Auth, RLS, data mutation, dependency, secret, external-call, and release-risk changes require **Security Reviewer** review before acceptance.
+
+Delegate to `@security-reviewer` in `.cursor/agents/security-reviewer.md` or Task `security-review` for isolated review context.
+
+Verify OWASP Top 10, IDOR, SSRF, injection, broken auth, and least-privilege boundaries.

package/assistant-adapters/model-selection/codex-config.example.toml

@@ -1,6 +1,9 @@
 # Codex model-selection example for Agent Kit.
 # Copy the relevant comments into ~/.codex/config.toml or a trusted project .codex/config.toml.
 # Verify current model availability in your Codex environment before uncommenting.
+#
+# Custom council agents generated by agent-kit live under .codex/agents/*.toml.
+# Run `agent-kit init --activate codex` to create them from the project roster.
 
 # June 2026 Agent Kit suggested baseline:
 # model = "gpt-5.5"