From 667dce5cc72554fb6bb990b2dfa62bc461964f29 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 17:34:46 -0700 Subject: [PATCH 1/7] fix(best-practices): make sidebar priority links navigate from other pages The Essential/Strongly Recommended/Recommended sidebar entries used bare-hash hrefs, which only worked as in-page scroll anchors on the Best Practices page itself. From any other page they appended the hash to the current URL instead of navigating to Best Practices. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01SgEnJ8XrVePnhSU3scp4jE --- app/spicedb/best-practices/_meta.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/app/spicedb/best-practices/_meta.ts b/app/spicedb/best-practices/_meta.ts index 7d1b0786..1d0b05d3 100644 --- a/app/spicedb/best-practices/_meta.ts +++ b/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", }, }; From da769db88c92f61055fd76f0547b566d66d650b2 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 17:38:03 -0700 Subject: [PATCH 2/7] docs(getting-started): add Build with your AI agent page for the spicedb-dev plugin Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01SgEnJ8XrVePnhSU3scp4jE --- app/spicedb/getting-started/_meta.ts | 1 + .../build-with-an-agent/page.mdx | 113 ++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 app/spicedb/getting-started/build-with-an-agent/page.mdx diff --git a/app/spicedb/getting-started/_meta.ts b/app/spicedb/getting-started/_meta.ts index 5b04902f..d555bc0f 100644 --- a/app/spicedb/getting-started/_meta.ts +++ b/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", diff --git a/app/spicedb/getting-started/build-with-an-agent/page.mdx b/app/spicedb/getting-started/build-with-an-agent/page.mdx new file mode 100644 index 00000000..8951cd23 --- /dev/null +++ b/app/spicedb/getting-started/build-with-an-agent/page.mdx @@ -0,0 +1,113 @@ +--- +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 OpenFGA-family deployment onto SpiceDB. +It's useful throughout the lifecycle — exploration, design, 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). + + + 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. + + +## Prerequisites + +- An AI coding agent. + Claude Code and Codex CLI are the tested integrations, installed as a plugin; any other agent harness that reads an `AGENTS.md` file should also be able to use the plugin's skills and the `AGENTS.md` snippet `/spicedb-dev:plan` writes, though installation and slash-command support outside Claude Code and Codex CLI hasn't been verified. +- 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 your agent harness reads an `AGENTS.md` file, it should still be able to follow the plugin's skills and the `AGENTS.md` snippet described below, even without native support for installing the plugin package itself. + +## 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 — 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 OpenFGA, Okta FGA, or Auth0 FGA**: 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, because 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 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` | + +`implement-spicedb` routes to `implement-spicedb-relationships` or `implement-spicedb-checks` depending on what the handler does — both are required for a feature to work. +SpiceDB returns `NO_PERMISSION` for everything until relationships are written, so a handler with checks and no writes will silently deny every request. + +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 OpenFGA, Okta FGA, or Auth0 FGA: + +``` +/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 + + + + + + From 7774d8c5b7c28850389882fd292f2acd0c464210 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 17:42:34 -0700 Subject: [PATCH 3/7] docs(first-steps): point to the spicedb-dev AI agent plugin from the toolchain step Co-Authored-By: Claude Haiku 4.5 Claude-Session: https://claude.ai/code/session_01SgEnJ8XrVePnhSU3scp4jE --- app/spicedb/getting-started/first-steps/page.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/app/spicedb/getting-started/first-steps/page.mdx b/app/spicedb/getting-started/first-steps/page.mdx index 45c35506..af01c142 100644 --- a/app/spicedb/getting-started/first-steps/page.mdx +++ b/app/spicedb/getting-started/first-steps/page.mdx @@ -81,6 +81,9 @@ import { InlinePlayground } from "@/components/playground"; } title="Install the SpiceDB CLI tool: Zed" href="/spicedb/getting-started/installing-zed" /> + 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. From 0ffbc7100ef5db2a726cf9f678e9bb5caa13b415 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 17:45:52 -0700 Subject: [PATCH 4/7] docs(best-practices): recommend the spicedb-dev plugin for AI-assisted development --- app/spicedb/best-practices/page.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/app/spicedb/best-practices/page.mdx b/app/spicedb/best-practices/page.mdx index b60d8951..7720fa2f 100644 --- a/app/spicedb/best-practices/page.mdx +++ b/app/spicedb/best-practices/page.mdx @@ -253,6 +253,13 @@ 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. + ## Priority C Rules: Recommended ### Treat Writing Schema like Writing DB Migrations From 96043461774d9e31919b76d5813e5759ef2aae19 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 18:00:46 -0700 Subject: [PATCH 5/7] docs(spicedb-dev-plugin): address final review findings (formatting, em-dash overuse, agent-fallback guidance, cross-page consistency) Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01SgEnJ8XrVePnhSU3scp4jE --- app/spicedb/best-practices/page.mdx | 3 +- .../build-with-an-agent/page.mdx | 53 +++++++++++-------- .../getting-started/first-steps/page.mdx | 2 +- 3 files changed, 35 insertions(+), 23 deletions(-) diff --git a/app/spicedb/best-practices/page.mdx b/app/spicedb/best-practices/page.mdx index 7720fa2f..15ad27e3 100644 --- a/app/spicedb/best-practices/page.mdx +++ b/app/spicedb/best-practices/page.mdx @@ -258,7 +258,8 @@ If you need its semantics but its performance is insufficient, we recommend chec 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 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. +As with any AI-generated code, review and validate its output before you rely on it. ## Priority C Rules: Recommended diff --git a/app/spicedb/getting-started/build-with-an-agent/page.mdx b/app/spicedb/getting-started/build-with-an-agent/page.mdx index 8951cd23..2cfdc60c 100644 --- a/app/spicedb/getting-started/build-with-an-agent/page.mdx +++ b/app/spicedb/getting-started/build-with-an-agent/page.mdx @@ -9,18 +9,19 @@ import { Callout, Cards } from "nextra/components"; 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 OpenFGA-family deployment onto SpiceDB. -It's useful throughout the lifecycle — exploration, design, implementation, and testing — and can also help debug and harden an authorization setup you already have. +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). - 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. + 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. ## Prerequisites - An AI coding agent. - Claude Code and Codex CLI are the tested integrations, installed as a plugin; any other agent harness that reads an `AGENTS.md` file should also be able to use the plugin's skills and the `AGENTS.md` snippet `/spicedb-dev:plan` writes, though installation and slash-command support outside Claude Code and Codex CLI hasn't been verified. + 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: @@ -28,9 +29,10 @@ It's an official AuthZed plugin, distributed through the [AuthZed marketplace](h spicedb serve-testing ``` - This starts SpiceDB on `localhost:50051` with no persistence — data is lost on restart, which is fine for development. + 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. + +- The [`zed` CLI](/spicedb/getting-started/installing-zed) installed: the plugin's schema-validator agent uses it to validate `.zed` files. ## Install the plugin @@ -51,14 +53,15 @@ codex plugin add spicedb-dev@authzed-marketplace ### Other agents Claude Code and Codex CLI are the only integrations tested against this plugin. -If your agent harness reads an `AGENTS.md` file, it should still be able to follow the plugin's skills and the `AGENTS.md` snippet described below, even without native support for installing the plugin package itself. +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 — useful for debugging and hardening an authorization setup you didn't build with the plugin, too +- **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 OpenFGA, Okta FGA, or Auth0 FGA**: convert the model, the relationship data, the application code, and the tests, then verify the migration with a differential test harness before cutover @@ -71,19 +74,20 @@ Start any new project with: ``` 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, because it means your agent considers SpiceDB writes and checks automatically whenever it generates or modifies a handler, without you invoking a command every time. +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 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` | +| 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` | -`implement-spicedb` routes to `implement-spicedb-relationships` or `implement-spicedb-checks` depending on what the handler does — both are required for a feature to work. +`implement-spicedb` routes to `implement-spicedb-relationships` or `implement-spicedb-checks` depending on what the handler does; both are required for a feature to work. SpiceDB returns `NO_PERMISSION` for everything until relationships are written, so a handler with checks and no writes will silently deny every request. After generating a schema, deploy it to your SpiceDB instance: @@ -100,14 +104,21 @@ If you already run OpenFGA, Okta FGA, or Auth0 FGA: /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. +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 - - - + + diff --git a/app/spicedb/getting-started/first-steps/page.mdx b/app/spicedb/getting-started/first-steps/page.mdx index af01c142..2ce42f0c 100644 --- a/app/spicedb/getting-started/first-steps/page.mdx +++ b/app/spicedb/getting-started/first-steps/page.mdx @@ -82,7 +82,7 @@ import { InlinePlayground } from "@/components/playground"; 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. + 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 From f5d58e6628a8711d301a0c67037b82938634bd42 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Tue, 15 Sep 2026 22:08:44 -0700 Subject: [PATCH 6/7] docs(build-with-an-agent): generalize migration-source references, verify CLI syntax Refer to "an existing authorization solution (OpenFGA, Okta FGA, etc.)" generically instead of naming specific products as the definitive list; Auth0 FGA doesn't exist as a distinct product and is dropped. Removes the implement-spicedb routing explanation, since the plugin already handles that routing for the user. The Claude Code and Codex CLI install commands were independently verified against each project's own source (marketplace name in authzed-marketplace's marketplace.json; codex-rs's plugin_cmd.rs and marketplace_cmd.rs) and left unchanged, since they were already correct. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01SgEnJ8XrVePnhSU3scp4jE --- app/spicedb/getting-started/build-with-an-agent/page.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/app/spicedb/getting-started/build-with-an-agent/page.mdx b/app/spicedb/getting-started/build-with-an-agent/page.mdx index 2cfdc60c..15e5ae00 100644 --- a/app/spicedb/getting-started/build-with-an-agent/page.mdx +++ b/app/spicedb/getting-started/build-with-an-agent/page.mdx @@ -8,7 +8,7 @@ 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 OpenFGA-family deployment onto SpiceDB. +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, 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). @@ -63,7 +63,7 @@ That gets you the plugin's guidance without depending on slash-command support. - **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 OpenFGA, Okta FGA, or Auth0 FGA**: convert the model, the relationship data, the application code, and the tests, then verify the migration with a differential test harness before cutover +- **Migrate from an existing authorization solution** (OpenFGA, Okta FGA, 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 @@ -87,9 +87,6 @@ It also writes an authorization snippet into your project's `CLAUDE.md` (or `AGE | Inherited a codebase, need a coverage picture | `/spicedb-dev:audit-coverage` | | Feature set is stable, need tests | `/spicedb-dev:test-permissions` | -`implement-spicedb` routes to `implement-spicedb-relationships` or `implement-spicedb-checks` depending on what the handler does; both are required for a feature to work. -SpiceDB returns `NO_PERMISSION` for everything until relationships are written, so a handler with checks and no writes will silently deny every request. - After generating a schema, deploy it to your SpiceDB instance: ```bash @@ -98,7 +95,7 @@ zed schema write schema.zed --endpoint localhost:50051 --token my-token ## Migrating to SpiceDB -If you already run OpenFGA, Okta FGA, or Auth0 FGA: +If you already run an existing authorization solution (OpenFGA, Okta FGA, etc.): ``` /spicedb-dev:migrate /path/to/your/project From 104218b1367a5fedbe78513c4f63352f6c38dbd1 Mon Sep 17 00:00:00 2001 From: Sam Kim Date: Fri, 18 Sep 2026 12:26:15 -0700 Subject: [PATCH 7/7] docs(spicedb-dev-plugin): mention OSO as a supported migration source Addresses PR review feedback to call out OSO alongside OpenFGA and Okta FGA as an authorization system the spicedb-dev plugin can help migrate from. Co-Authored-By: Claude Sonnet 5 --- app/spicedb/best-practices/page.mdx | 1 + app/spicedb/getting-started/build-with-an-agent/page.mdx | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/app/spicedb/best-practices/page.mdx b/app/spicedb/best-practices/page.mdx index 15ad27e3..8aefb724 100644 --- a/app/spicedb/best-practices/page.mdx +++ b/app/spicedb/best-practices/page.mdx @@ -259,6 +259,7 @@ 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 diff --git a/app/spicedb/getting-started/build-with-an-agent/page.mdx b/app/spicedb/getting-started/build-with-an-agent/page.mdx index 15e5ae00..e3eca70b 100644 --- a/app/spicedb/getting-started/build-with-an-agent/page.mdx +++ b/app/spicedb/getting-started/build-with-an-agent/page.mdx @@ -8,7 +8,7 @@ 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, etc.) onto SpiceDB. +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). @@ -63,7 +63,7 @@ That gets you the plugin's guidance without depending on slash-command support. - **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, etc.): convert the model, the relationship data, the application code, and the tests, then verify the migration with a differential test harness before cutover +- **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 @@ -95,7 +95,7 @@ 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, etc.): +If you already run an existing authorization solution (OpenFGA, Okta FGA, OSO, etc.): ``` /spicedb-dev:migrate /path/to/your/project