Authorization Planner

Authorization Planner

This plugin adds a first pass at SpiceDB fine-grained authorization to an application being built or modified. The goal is getting authorization structurally correct -- right permissions, right places, right operations. It is not a production hardening or debugging tool.

Ideal Workflow

Once, early -- before or alongside data model design

Run /spicedb-dev:plan. This scopes the work, produces authorization-plan.md, and writes an authorization snippet to CLAUDE.md so permissions are considered automatically in every future session without needing to invoke any command. This is the most important setup step.

Then /spicedb-dev:design-model -- scans for existing model files and extracts entity names. Produces permission-model.md.

Then /spicedb-dev:generate-schema -- converts the model to schema.zed. Schema-validator runs automatically.

Deploy the schema externally: zed schema write schema.zed.

Continuously, alongside every feature

Every feature needs both operations -- this is the most common implementation mistake:

1. Relationship writes (/spicedb-dev:implement-spicedb-relationships) -- run when writing handlers that create resources, grant membership, or delete resources. SpiceDB returns NO_PERMISSION for everything until relationships are written. Writes must come before checks.

2. Permission checks (/spicedb-dev:implement-spicedb-checks) -- run when writing any handler that reads, modifies, or deletes a resource on behalf of a user. For list endpoints, use LookupResources -- not CheckPermission in a loop.

Use /spicedb-dev:implement-spicedb when unsure which is needed -- it communicates the paired requirement and routes to the right command.

Periodically

/spicedb-dev:audit-coverage produces a coverage matrix: every permission in the schema vs. whether a corresponding check exists in code. Routes each gap to the correct implement command.

Once, when stable

/spicedb-dev:test-permissions generates test fixtures and integration tests from the schema.

Routing by Situation

• New project, no existing auth → /spicedb-dev:plan
• Have a data model, need permission design → /spicedb-dev:design-model
• Have a permission model, need a schema → /spicedb-dev:generate-schema
• Have a schema, need implementation → /spicedb-dev:implement-spicedb
• Inherited codebase, need coverage picture → /spicedb-dev:audit-coverage
• Unsure which SpiceDB pattern fits → spicedb-schema-design skill
• Questions about client code or consistency → spicedb-best-practices skill

Scoping Tips

Greenfield: Start with the simplest model that works. Three resources with basic RBAC beats ten resources with speculative complexity. Add caveats and custom roles only when a concrete scenario requires them.

Existing app: The checkpoint-identifier agent can map current authorization boundaries before designing the SpiceDB model. Run it early to reveal scope that isn't obvious from the data model alone.

Multi-tenant SaaS: Finalize tenant isolation before designing resource-level permissions. The tenant boundary is the most consequential design decision -- getting it wrong affects every other resource.

Migration: Do not skip Phase 1. Read existing auth code first to understand the current permission surface. See the Migration Track in /spicedb-dev:plan.