Document the spicedb-dev AI agent plugin

app/spicedb/best-practices/_meta.ts

@@ -10,14 +10,14 @@ export default {
   },
   priority: {
     title: "Essential",
-    href: "#priority-a-essential",
+    href: "/spicedb/best-practices#priority-a-essential",
   },
   "strongly-recommended": {
     title: "Strongly Recommended",
-    href: "#priority-b-strongly-recommended",
+    href: "/spicedb/best-practices#priority-b-strongly-recommended",
   },
   recommended: {
     title: "Recommended",
-    href: "#priority-c-recommended",
+    href: "/spicedb/best-practices#priority-c-recommended",
   },
 };

app/spicedb/best-practices/page.mdx

@@ -253,6 +253,15 @@ Where possible, we recommend `CheckBulk`, because its work is bounded to the lis
 LookupResources generally requires a lot of work, causes a higher load, and subsequently has some of the highest latencies.
 If you need its semantics but its performance is insufficient, we recommend checking out our [Materialize](https://authzed.com/products/authzed-materialize) offering.
 
+### Use the spicedb-dev Plugin for AI-Assisted Development
+
+Tags: **application**
+
+If you're using an AI coding agent, install the [`spicedb-dev` plugin](/spicedb/getting-started/build-with-an-agent) from the [AuthZed marketplace](https://github.com/authzed/authzed-marketplace) and keep it in the loop for your regular SpiceDB exploration and development.
+It helps you design permission models, generate and validate schemas, add relationship writes and permission checks to your application code, audit coverage as your app grows, and generate tests from your schema, catching common mistakes like checks with no corresponding writes before they reach production.
+It can also help you migrate from other authorization systems, such as OpenFGA, Okta FGA, or OSO.
+As with any AI-generated code, review and validate its output before you rely on it.
+
 ## Priority C Rules: Recommended
 
 ### Treat Writing Schema like Writing DB Migrations

app/spicedb/getting-started/_meta.ts

@@ -1,6 +1,7 @@
 export default {
   "discovering-spicedb": "What is SpiceDB?",
   "first-steps": "First Steps",
+  "build-with-an-agent": "Build with an AI Agent",
   install: "Installing SpiceDB",
   configuration: "Configuring SpiceDB",
   "client-libraries": "Client Libraries",

app/spicedb/getting-started/build-with-an-agent/page.mdx

@@ -0,0 +1,121 @@
+---
+title: "Build with your AI agent"
+description: "Install the spicedb-dev plugin for Claude Code, Codex CLI, or any AGENTS.md-based agent to design, implement, test, harden, and migrate SpiceDB authorization with AI assistance."
+---
+
+import { Callout, Cards } from "nextra/components";
+
+# Build with your AI agent
+
+If you're building with an AI coding agent, you don't have to design and wire up SpiceDB authorization by hand.
+The `spicedb-dev` plugin teaches your agent how to design a permission model, generate a schema, write the relationship and permission-check code, audit coverage as your app grows, generate tests, and migrate an existing authorization solution (OpenFGA, Okta FGA, OSO, etc.) onto SpiceDB.
+It's useful throughout the lifecycle, from exploration and design through implementation and testing, and can also help debug and harden an authorization setup you already have.
+
+It's an official AuthZed plugin, distributed through the [AuthZed marketplace](https://github.com/authzed/authzed-marketplace).
+
+<Callout type="info">
+  Treat the plugin's output like any AI-generated code: review and validate it before you rely on
+  it, especially when it's touching an existing authorization setup.
+</Callout>
+
+## Prerequisites
+
+- An AI coding agent.
+  See [Other agents](#other-agents) below if you're not using Claude Code or Codex CLI.
+- A running SpiceDB instance for the implementation steps.
+  The fastest option is an in-memory instance with no setup:
+
+  ```bash
+  spicedb serve-testing
+  ```
+
+  This starts SpiceDB on `localhost:50051` with no persistence: data is lost on restart, which is fine for development.
+  For a persistent local instance, see [Datastores](/spicedb/concepts/datastores); for a hosted, self-service instance, see [AuthZed Cloud](https://authzed.com/cloud).
+
+- The [`zed` CLI](/spicedb/getting-started/installing-zed) installed: the plugin's schema-validator agent uses it to validate `.zed` files.
+
+## Install the plugin
+
+### Claude Code
+
+```
+/plugin marketplace add authzed/authzed-marketplace
+/plugin install spicedb-dev@authzed-marketplace
+```
+
+### Codex CLI
+
+```bash
+codex plugin marketplace add authzed/authzed-marketplace
+codex plugin add spicedb-dev@authzed-marketplace
+```
+
+### Other agents
+
+Claude Code and Codex CLI are the only integrations tested against this plugin.
+If you're on a different AGENTS.md-reading harness, the most reliable path is to read the plugin's [skills](https://github.com/authzed/authzed-marketplace/tree/main/spicedb-dev/skills) directly from the marketplace repository and copy the authorization snippet described in [Plan your authorization](#plan-your-authorization) into your own `AGENTS.md` by hand.
+That gets you the plugin's guidance without depending on slash-command support.
+
+## What the plugin can do
+
+- **Design a permission model** interactively, starting from entities it finds in your existing data model (Prisma, Django, Go structs, GraphQL, or SQL)
+- **Generate a SpiceDB schema** from that model, and validate any `.zed` file for anti-patterns
+- **Implement authorization in code**: relationship writes (`WriteRelationships`, `DeleteRelationships`) and permission checks (`CheckPermission`, `BulkCheckPermission`, `LookupResources`, `LookupSubjects`) in Go, TypeScript, Python, C#, Java, Rust, and Ruby
+- **Audit permission coverage** across your codebase: for every permission in your schema, see whether a check exists in code, and catch unfiltered list endpoints, which is useful for debugging and hardening an authorization setup you didn't build with the plugin, too
+- **Generate tests**: positive, negative, and hierarchical-inheritance test fixtures and integration tests, generated from your schema
+- **Migrate from an existing authorization solution** (OpenFGA, Okta FGA, OSO, etc.): convert the model, the relationship data, the application code, and the tests, then verify the migration with a differential test harness before cutover
+
+## Plan your authorization
+
+Start any new project with:
+
+```
+/spicedb-dev:plan
+```
+
+This scopes the work and produces `authorization-plan.md`.
+It also writes an authorization snippet into your project's `CLAUDE.md` (or `AGENTS.md`) — the single most effective step, since it means your agent considers SpiceDB writes and checks automatically whenever it generates or modifies a handler, without you invoking a command every time.
+
+## Build a feature end to end
+
+| Situation                                     | Run this                         |
+| --------------------------------------------- | -------------------------------- |
+| Have a data model, need a permission design   | `/spicedb-dev:design-model`      |
+| Have a permission model, need a schema        | `/spicedb-dev:generate-schema`   |
+| Have a schema, need it validated              | `/spicedb-dev:validate-schema`   |
+| Have a schema, need it implemented in code    | `/spicedb-dev:implement-spicedb` |
+| Inherited a codebase, need a coverage picture | `/spicedb-dev:audit-coverage`    |
+| Feature set is stable, need tests             | `/spicedb-dev:test-permissions`  |
+
+After generating a schema, deploy it to your SpiceDB instance:
+
+```bash
+zed schema write schema.zed --endpoint localhost:50051 --token my-token
+```
+
+## Migrating to SpiceDB
+
+If you already run an existing authorization solution (OpenFGA, Okta FGA, OSO, etc.):
+
+```
+/spicedb-dev:migrate /path/to/your/project
+```
+
+This analyzes your project and holds a single pre-flight gate: every decision that can't be made mechanically (tenancy shape, identifier encoding, permission naming) is asked once, up front, and recorded.
+From there it converts the schema, migrates relationship data, rewrites client call sites, and converts your tests, phase by phase.
+It will not push, open a pull request, or work on your default branch, and it won't run your cutover for you — a generated differential test harness lets you dual-run SpiceDB beside your existing system and confirm the two agree before you flip over.
+
+## Learn more
+
+<Cards>
+  <Cards.Card
+    arrow={true}
+    title="spicedb-dev plugin source and README"
+    href="https://github.com/authzed/authzed-marketplace/tree/main/spicedb-dev"
+  />
+  <Cards.Card
+    arrow={true}
+    title="Best Practices"
+    href="/spicedb/best-practices#use-the-spicedb-dev-plugin-for-ai-assisted-development"
+  />
+</Cards>

app/spicedb/getting-started/first-steps/page.mdx

@@ -81,6 +81,9 @@ import { InlinePlayground } from "@/components/playground";
         <Cards.Card arrow={true} icon={<FontAwesomeIcon icon={faTerminal} />} title="Install the SpiceDB CLI tool: Zed" href="/spicedb/getting-started/installing-zed" />
     </Cards>
 
+    Building with an AI coding agent like Claude Code or Codex CLI?
+    The [`spicedb-dev` plugin](/spicedb/getting-started/build-with-an-agent) teaches your agent to design a permission model, generate and validate a schema, and implement relationship writes and permission checks directly in your application code.
+
     ### Take SpiceDB to Production
 
     Once you're ready to take things into production, you can reference our guides or explore a managed solution with AuthZed.