@appsforgood/next-supabase-kit 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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`.

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`.