Saas Guardrails

Before you run this skill

This skill is brand-neutral. It reads its brand, palette and endpoints from brand.config.json at the repo root.

On first use, do this before anything else:

1. Run python3 brandkit.py. It prints the config source and any placeholder that is still unset.
2. If it says configured: False, copy brand.config.example.json to brand.config.json.
3. Ask the operator for each value under missing, then write them in. Do not guess a brand name, a domain, or a colour.
4. Anything the skill writes out should be passed through brandkit.fill(text), which swaps every {{TOKEN}} for its configured value and remaps the default palette to the operator's.

Text below uses {{TOKEN}} where a value is operator-specific. Treat an unresolved {{TOKEN}} in your output as a bug, not as literal copy.

SaaS Guardrails

The engineering contract for a multi-tenant SaaS, in any language.

The one idea behind everything here

A rule that executes beats a rule that must be remembered.

Prose rules decay. An agent reads "remember to check permissions" on turn 3 and forgets it on turn 40. So every rule here is placed as close as possible to a mechanism that fails loudly: a thrown error, a type error, a failing test, a database constraint. Where a rule genuinely cannot be mechanized it is marked [JUDGMENT] and belongs in a review, not in an agent's memory.

Two layers

This skill is deliberately split, because a stack-agnostic rule that names no mechanism is just advice, and advice is what fails.

The invariants never change. The binding changes per project. A project with no binding file is not yet governed by this skill: write the binding first, from bindings/_template.md.

Rule 0: Detect stack and mode before doing anything

# Which binding applies?
ls package.json pyproject.toml requirements.txt go.mod Gemfile Cargo.toml 2>/dev/null
test -f src/lib/resources.ts && echo "binding: nextjs-trpc-prisma"
test -f app/core/resources.py -o -f app/resources.py && echo "binding: python-fastapi-sqlalchemy"
ls bindings/ .claude/binding.md docs/binding.md 2>/dev/null

# Which mode?
ls prisma/migrations alembic/versions migrations 2>/dev/null | head -3
grep -rlE '"test"|pytest|vitest|jest' package.json pyproject.toml 2>/dev/null

Never guess. If the signals conflict, ask which applies.

The eight invariants (short form)

Full statements, rationale, and per-stack enforcement in references/11-invariants.md.

1. Registry. One file declares every feature: its permissions, plan limit or flag, nav entry, audit template, rate limit. Feature metadata lives nowhere else.
2. Chokepoint. One function or middleware wraps every application request and applies auth, tenancy, authorization, plan gates, transaction, usage counter, audit, and logging. Handlers contain business logic only.
3. Tenancy in one place, checked twice. The chokepoint proves the caller belongs to the tenant. Every query proves the row does.
4. Feature-oriented layout. Code is grouped by domain, not by technical type. Shared code is shared because two features use it, not because it might be reused someday.
5. One type source of truth. The database's generated types first, then the auth library's, then a single types module. Never a second hand-written copy of a shape the database already describes.
6. Grep index. Every authoritative export carries a keyword header so the next agent finds it in one search instead of reading files until it stumbles on the answer.
7. Chokepoint tests are mandatory. The more code depends on something, the less optional its test. Everything depends on invariants 1 to 3, so those are tested first and stay green.
8. Migrations only. Schema changes are versioned, reviewed, committed, and applied by a command. Never by hand, never by a sync-the-schema tool against anything shared.

Hard rules (every mode, every stack)

Ordered by how expensive the mistake is to undo. Where a rule names a mechanism, your binding says which one.

1. No implementation before both gates pass. Discovery answered, architecture approved in writing. Being told to "just start coding" does not open the gate. See 01-discovery-and-gates.md.
2. Tenancy is not optional. Every application table carries the tenant key. Every application read and write is scoped by it. Never fetch a tenant row by id alone.
3. Every app endpoint goes through the chokepoint. No bare handlers for application data. Only exceptions: signature-verified third-party webhooks, the auth library's own routes, and health checks.
4. Registry before code. A feature is declared before its handler exists. In a binding where an unregistered path throws, do not silence that error with a token override.
5. Types have one home. Never redeclare a shape the database already describes. The banned-construct list is per language and lives in your binding.
6. Schema validation on every input. Every endpoint, form, and webhook payload, with a max length on every string and array. No hand-rolled validation.
7. The database layer is a boundary. Data access is isolated, and business logic does not live inside it. Your binding names the mechanism that enforces the boundary.
8. Grep before you create. Search the keyword index first. Duplicating something that exists is the most common and most expensive failure in AI-assisted work.
9. Every authoritative export carries a keyword header. Format in 05-types-and-navigation.md. This is what makes rule 8 cheap.
10. Tests ship with the feature. The chokepoint suite in 06-testing.md is mandatory and stays green. A feature with no test is not done.
11. Migrations only. Never a schema-sync command against anything shared. Every foreign key and every filtered column gets an index. See 07-database.md.
12. Latest stable, never pre-release, always locked. No alpha, beta, RC, or nightly. Lockfile committed.
13. Secrets never touch git. Environment validated at boot so a missing key fails at startup, not at 2am under load.
14. One feature at a time, finished. Scope, contract, schema, endpoint, UI, tests, run the tests, review, next. Never ten half-features.
15. No scripts, seeds, or probe files without explicit permission. Everything in the repo must be shippable.
16. Design tokens only in UI code. No hex, no hardcoded colors, no forced theme classes.
17. Report honestly. Run the typecheck and the tests and paste the real output. Never claim green without running it.
18. Say what you left out. Name loose ends before handing over, including ones the user never asked about.

Rules we deliberately rejected

Recorded so no future session reintroduces them. All three come from the original guardrail doc.

The stack gate is kept. It just starts from whatever this project's binding is and asks whether there is a concrete reason to deviate.

Bindings

Reference files

Load on demand, never all at once. Files 02 through 09 are written against the Next binding and are the most detailed worked examples in the skill. When on another binding, read them for the reasoning and take the mechanism from your binding file.

Checklists

The onboarding promise

A new developer reaches their first correct commit in under 30 minutes, without asking anyone where code lives. That is the acceptance test for the whole architecture, and it is checked with a real person rather than assumed.

If someone cannot answer "where does the billing webhook live" or "where do I add a permission" within a minute of reading the binding and 03-add-a-feature.md, the architecture has drifted or the docs are lying. Fix one of them, and say which.