| name | tenancy |
| description | Use when creating, updating, reviewing, or debugging multi-tenancy, tenant isolation, tenantId scoping, organization data access, row-level security, tenant-aware cache keys, or cross-tenant security. |
Tenancy
Use this skill for safe multi-tenant data isolation.
Rules
- Follow the project’s existing tenancy model.
- Do not introduce a new tenancy architecture unless explicitly requested.
- Never trust tenant, organization, workspace, or account IDs from client input alone.
- Derive tenant scope from verified auth/session/context.
- Every tenant-owned query must be scoped.
- Prevent cross-tenant reads, writes, updates, deletes, joins, exports, and background jobs.
- Include tenant scope in cache keys for tenant-owned data.
- Include tenant scope in queue/job payloads when needed.
- Preserve existing response, error, logging, and test patterns.
- Avoid unrelated refactors.
Inspect First
Before changing tenancy-related code, check existing patterns for:
- tenant identification
- auth/session tenant context
- organization/workspace membership
- database scoping
- repository filters
- joins and relations
- cache keys
- background jobs
- admin/super-admin behavior
- tests for cross-tenant access
Implementation Checklist
- Identify the trusted tenant source.
- Pass tenant context explicitly through layers.
- Scope all tenant-owned reads and writes.
- Verify related records belong to the same tenant.
- Protect joins and nested queries.
- Scope cache keys by tenant.
- Scope background jobs by tenant.
- Add permission checks for tenant switching or admin access.
- Add or update cross-tenant tests.
Query Rules
- All tenant-owned tables/entities must be queried with tenant scope.
- Updates and deletes must include tenant scope, not only record ID.
- List queries must be tenant-scoped.
- Detail queries must be tenant-scoped.
- Joins must not pull related records from another tenant.
- Search, filters, exports, reports, and counts must be tenant-scoped.
- Unscoped admin queries must be explicit, privileged, and reviewed.
Security Rules
- Do not accept tenant scope from request body as trusted.
- Do not let users choose arbitrary tenant IDs.
- Verify user membership before allowing tenant access.
- Verify role/permission for tenant admin actions.
- Return safe errors that do not leak another tenant’s data.
- Avoid logging sensitive tenant data.
- Treat missing tenant scope as a security risk unless the route is truly global.
Cache Rules
- Tenant-owned cached data must include tenant scope in the cache key.
- User-specific cached data should include both tenant and user scope when needed.
- Do not share cached results across tenants.
- Invalidate tenant-scoped cache on tenant-owned mutations.
Job Rules
- Background jobs touching tenant data must include trusted tenant scope.
- Workers must re-check tenant scope before acting.
- Jobs must not rely on stale or client-provided tenant data.
- Duplicate/retried jobs must not cross tenant boundaries.
Tests
Cover relevant paths:
- tenant user can access own tenant data
- tenant user cannot access another tenant’s data
- update/delete cannot cross tenant boundary
- joins remain tenant-scoped
- cache key includes tenant scope
- background job uses tenant scope
- admin access requires explicit permission