From 11381f89c3d723cda39e0b800662e67ddd3bbbf5 Mon Sep 17 00:00:00 2001
From: Magnus Hedemark <magnus919@pm.me>
Date: Fri, 21 Aug 2026 03:13:16 -0400
Subject: [PATCH] feat: add multi-tenant SaaS architecture (#360)

Add tenant semantics, planes, tenancy models, lifecycle and commercial handoffs, operations, templates, evals, and specialist routing.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
---
 .claude-plugin/marketplace.json               |  9 +++
 .codex-plugin/plugin.json                     |  1 +
 README.md                                     |  4 ++
 llms.txt                                      |  1 +
 multi-tenant-saas-architecture/README.md      | 39 +++++++++++
 multi-tenant-saas-architecture/SKILL.md       | 69 ++++++++++++++++++
 .../evals/evals.json                          | 70 +++++++++++++++++++
 .../control-and-application-planes.md         | 26 +++++++
 ...-identity-entitlements-metering-billing.md | 24 +++++++
 .../references/source-index.md                | 24 +++++++
 .../tenancy-and-data-partitioning-models.md   | 18 +++++
 ...nant-aware-operations-capacity-and-cost.md | 18 +++++
 .../tenant-domain-model-and-boundaries.md     | 28 ++++++++
 .../templates/saas-architecture-brief.md      | 57 +++++++++++++++
 .../templates/tenancy-decision-record.md      | 30 ++++++++
 .../templates/tenant-lifecycle-checklist.md   | 26 +++++++
 references/skill-triggers.md                  |  1 +
 17 files changed, 445 insertions(+)
 create mode 100644 multi-tenant-saas-architecture/README.md
 create mode 100644 multi-tenant-saas-architecture/SKILL.md
 create mode 100644 multi-tenant-saas-architecture/evals/evals.json
 create mode 100644 multi-tenant-saas-architecture/references/control-and-application-planes.md
 create mode 100644 multi-tenant-saas-architecture/references/onboarding-identity-entitlements-metering-billing.md
 create mode 100644 multi-tenant-saas-architecture/references/source-index.md
 create mode 100644 multi-tenant-saas-architecture/references/tenancy-and-data-partitioning-models.md
 create mode 100644 multi-tenant-saas-architecture/references/tenant-aware-operations-capacity-and-cost.md
 create mode 100644 multi-tenant-saas-architecture/references/tenant-domain-model-and-boundaries.md
 create mode 100644 multi-tenant-saas-architecture/templates/saas-architecture-brief.md
 create mode 100644 multi-tenant-saas-architecture/templates/tenancy-decision-record.md
 create mode 100644 multi-tenant-saas-architecture/templates/tenant-lifecycle-checklist.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index e9e157e..e892771 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -707,6 +707,15 @@
       "strict": false,
       "description": "Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope."
     },
+    {
+      "name": "multi-tenant-saas-architecture",
+      "source": "./",
+      "skills": [
+        "./multi-tenant-saas-architecture"
+      ],
+      "strict": false,
+      "description": "Design and review end-to-end multi-tenant SaaS architectures: tenant and subscription semantics, control and application planes, pooled or isolated tenancy, onboarding, entitlements, metering, billing handoffs, lifecycle, partitioning, and tenant-aware operations. Use when a subscription product needs a coherent tenant model and architecture decision across these seams. Do not use for threat modeling or isolation controls, API contract semantics, data-platform design, backend implementation, migration execution, privacy compliance artifacts, capacity evidence, financial modeling, or infrastructure operations; route those to the named specialist owners."
+    },
     {
       "name": "neckbeard",
       "source": "./",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 536b5b9..6da105e 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -96,6 +96,7 @@
     "./migration-engineering",
     "./ml-engineering",
     "./mobile-development",
+    "./multi-tenant-saas-architecture",
     "./neckbeard",
     "./notion",
     "./nous-branding",
diff --git a/README.md b/README.md
index 2d34cb2..33880a2 100644
--- a/README.md
+++ b/README.md
@@ -320,6 +320,10 @@ Machine learning engineering methodology — model training, fine-tuning (LoRA/Q
 
 Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native as ONE family skill with per-framework references: project scaffolding, builds and code signing, device and emulator testing, store submission (App Store/TestFlight and Google Play), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Ships 4 framework references (ios, android, flutter, react-native) and 6 evals. Routes web UI work to frontend-engineering and server-side work to backend-engineering.
 
+### [multi-tenant-saas-architecture](multi-tenant-saas-architecture/SKILL.md)
+
+Design end-to-end multi-tenant SaaS architectures by connecting tenant semantics, control/application planes, tenancy and partitioning choices, onboarding, entitlements, metering, billing handoffs, lifecycle, restore, noisy-neighbor behavior, and tenant-aware operations. Routes security, capacity, finance, platform, API, implementation, data, migration, and privacy details to their specialist owners.
+
 ### [neckbeard](neckbeard/SKILL.md)
 
 Evidence-driven software delivery operating model — routes a change through framing, discovery, design, implementation, review, verification, delivery, and learning, choosing the smallest *safe* intervention and proving it at the real delivery boundary. Every non-trivial run leaves an inspectable evidence ledger. Composes the specialist catalog rather than replacing it. Ships a versioned evaluation harness that measures SDLC outcomes, never LOC. Not a "10x developer" persona.
diff --git a/llms.txt b/llms.txt
index 33229c2..1017341 100644
--- a/llms.txt
+++ b/llms.txt
@@ -80,6 +80,7 @@
 - [migration-engineering](migration-engineering/SKILL.md): Plan and execute safe cross-system migrations, including service extraction from monoliths. Use when moving data, schemas, interfaces, infrastructure, or service ownership through compatibility windows, dual-running, reconciliation, cutover, recovery, or deprecation. Do not use for deciding whether decomposition is justified, designing a target architecture, or implementing one named technology; route those to the relevant architecture or specialist skill.
 - [ml-engineering](ml-engineering/SKILL.md): Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm).
 - [mobile-development](mobile-development/SKILL.md): Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope.
+- [multi-tenant-saas-architecture](multi-tenant-saas-architecture/SKILL.md): Design and review end-to-end multi-tenant SaaS architectures: tenant and subscription semantics, control and application planes, pooled or isolated tenancy, onboarding, entitlements, metering, billing handoffs, lifecycle, partitioning, and tenant-aware operations. Use when a subscription product needs a coherent tenant model and architecture decision across these seams. Do not use for threat modeling or isolation controls, API contract semantics, data-platform design, backend implementation, migration execution, privacy compliance artifacts, capacity evidence, financial modeling, or infrastructure operations; route those to the named specialist owners.
 - [neckbeard](neckbeard/SKILL.md): Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request (issue, ticket, or request) from intake through planning, gates, implementation, review, verified PR, and authorized post-merge release. neckbeard routes the change through framing, discovery, design, implementation, review, verification, delivery, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, and leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory.
 - [notion](notion/SKILL.md): Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation. Use when an agent needs to read Notion content, answer questions from a team wiki or database, or make a confirmed edit. Do not use for building Notion integrations or block-level page composition beyond property updates (that is Notion API application development), or for other knowledge bases (that is their own tooling).
 - [nous-branding](nous-branding/SKILL.md): Generate images and content consistent with the Nous Research brand identity. Use when creating visuals in the Nous / Theia / Hermes ecosystem: a "cyber-classical" style blending neo-classical statuary, cyberpunk/industrial grunge, and retro anime illustration. Covers official brand color palette, typography (Inter/IBM Plex Sans, JetBrains Mono, heavy distressed display faces), the Nous Girl mascot, texture system, and image prompt construction. Ships reference images for palette, mascot, and brand collage that can be used as img2img inputs.
diff --git a/multi-tenant-saas-architecture/README.md b/multi-tenant-saas-architecture/README.md
new file mode 100644
index 0000000..19bb65f
--- /dev/null
+++ b/multi-tenant-saas-architecture/README.md
@@ -0,0 +1,39 @@
+# multi-tenant-saas-architecture
+Design a coherent architecture for subscription products serving many customer tenants.
+
+## Why Install This Skill
+
+Multi-tenant SaaS decisions cross product semantics, identity, provisioning, data placement, usage, billing, and operations. Without one architecture view, teams often choose an isolation model before defining the customer promise, or let billing, support, and deletion paths become afterthoughts.
+
+This skill helps an agent turn those seams into explicit decisions and handoffs. It compares tenancy shapes per resource, distinguishes control-plane policy from application serving, and makes tenant lifecycle and noisy-neighbor behavior reviewable without replacing security, finance, capacity, platform, API, or implementation specialists.
+
+## What You Get
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Triggerable workflow, output contract, and ownership boundaries |
+| `references/` | Five focused decision guides plus public-source and transformation index |
+| `templates/` | SaaS brief, tenancy decision record, and lifecycle checklist |
+| `evals/evals.json` | Eight output-quality cases for architecture and routing behavior |
+
+## Quick Start
+
+No credentials or runtime dependencies are required. Start with a service promise and tenant vocabulary, then use the brief template:
+
+```text
+Define the tenant model and compare pooled, bridge, and silo choices for this SaaS product.
+```
+
+## Triggers
+
+- Designing or reviewing a multi-tenant SaaS architecture
+- Choosing pooled, bridge, silo, or hybrid tenancy
+- Defining control-plane and application-plane boundaries
+- Connecting onboarding, entitlements, metering, billing, and tenant lifecycle
+- Planning tenant-aware restore, deletion, quotas, or noisy-neighbor behavior
+
+## Requirements
+
+- An agent client that supports Agent Skills-format directories
+- Repository access to the linked specialist skills when handoffs are needed
+- Organization-specific customer, contract, scale, privacy, and recovery facts supplied by the user
diff --git a/multi-tenant-saas-architecture/SKILL.md b/multi-tenant-saas-architecture/SKILL.md
new file mode 100644
index 0000000..93daed9
--- /dev/null
+++ b/multi-tenant-saas-architecture/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: multi-tenant-saas-architecture
+description: >-
+  Design and review end-to-end multi-tenant SaaS architectures: tenant and
+  subscription semantics, control and application planes, pooled or isolated
+  tenancy, onboarding, entitlements, metering, billing handoffs, lifecycle,
+  partitioning, and tenant-aware operations. Use when a subscription product
+  needs a coherent tenant model and architecture decision across these seams.
+  Do not use for threat modeling or isolation controls, API contract semantics,
+  data-platform design, backend implementation, migration execution, privacy
+  compliance artifacts, capacity evidence, financial modeling, or infrastructure
+  operations; route those to the named specialist owners.
+license: MIT
+compatibility: Platform-agnostic methodology. No runtime dependencies.
+metadata:
+  tags: multi-tenant, saas, control-plane, application-plane, tenancy, entitlements, billing
+---
+
+# Multi-Tenant SaaS Architecture
+
+Use this skill to join product tenancy semantics to system boundaries and operating decisions. It owns the cross-cutting architecture choice, not the implementation or specialist evidence behind each choice.
+
+## Workflow
+
+1. **Frame the service promise.** Identify customer/account shape, users and operators, subscription commitments, regions, data classes, lifecycle states, support model, scale assumptions, and unknowns. Separate contractual promises from aspirations.
+2. **Define tenant semantics.** Load `references/tenant-domain-model-and-boundaries.md`. Establish tenant, account, organization, user, membership, subscription, entitlement, resource, and environment meanings, ownership, cardinality, and lifecycle authority.
+3. **Separate planes.** Load `references/control-and-application-planes.md`. Draw the control-plane policy and lifecycle responsibilities apart from application-plane request and data serving, including asynchronous handoffs and failure behavior.
+4. **Choose isolation per resource.** Load `references/tenancy-and-data-partitioning-models.md`. Compare pooled, bridge, silo, and hybrid choices by data, compute, cache, queue, search, and operational resource. Record why the choice meets the promise and what can trigger a change.
+5. **Connect the commercial path.** Load `references/onboarding-identity-entitlements-metering-billing.md`. Trace signup, identity, provisioning, configuration, entitlement evaluation, usage capture, invoice authority, suspension, support, and reactivation without making billing or security policy implicit.
+6. **Design lifecycle and operations.** Load `references/tenant-aware-operations-capacity-and-cost.md`. Cover deployment, observability, quotas, hot tenants, restore scope, export/deletion, cost attribution, and escalation. Route evidence-heavy decisions to the specialist owners.
+7. **Record and challenge.** Use `templates/saas-architecture-brief.md`, `templates/tenancy-decision-record.md`, and `templates/tenant-lifecycle-checklist.md`. Test cross-tenant safety, lifecycle idempotency, entitlement lag, billing disagreement, restore scope, and noisy-neighbor behavior.
+
+## Output Contract
+
+Produce a SaaS architecture brief with: service promise; domain vocabulary and authorities; control/application plane boundary; resource-by-resource tenancy choices; lifecycle state transitions; entitlement, metering, and billing handoffs; data and recovery boundaries; tenant-aware operational scenarios; explicit assumptions and evidence gaps; specialist handoffs; and decisions with owners and review triggers.
+
+## Ownership Boundaries
+
+- Threat modeling, authorization, tenant isolation controls, secrets, and security evidence belong to [`secure-software-engineering`](../secure-software-engineering/SKILL.md).
+- Capacity models, load or soak evidence, quotas as capacity controls, unit cost, and SLO-cost tradeoffs belong to [`capacity-and-cost-engineering`](../capacity-and-cost-engineering/SKILL.md).
+- Pricing, ARR/MRR, churn, retention, margin, and SaaS financial outcomes belong to [`financial-modeling`](../financial-modeling/SKILL.md).
+- Infrastructure, networking, deployment, observability substrate, and secret-management implementation belong to [`platform-engineering`](../platform-engineering/SKILL.md).
+- API, event, webhook, schema, compatibility, and deprecation contracts belong to [`api-design-and-evolution`](../api-design-and-evolution/SKILL.md).
+- Service code, data access, jobs, integrations, and application-level tests belong to [`backend-engineering`](../backend-engineering/SKILL.md).
+- Storage-platform, data-model, data-product, and governance decisions belong to [`data-architect`](../data-architect/SKILL.md); lifecycle deletion requirements and verification belong to [`privacy-engineering`](../privacy-engineering/SKILL.md).
+- Cross-system tenant moves, partition migrations, cutovers, reconciliation, and deprecation execution belong to [`migration-engineering`](../migration-engineering/SKILL.md).
+- General system boundary and architecture-quality decisions belong to [`software-architecture`](../software-architecture/SKILL.md); this skill adds SaaS tenant and commercial lifecycle semantics to that decision.
+
+## When Not To Use
+
+Do not use this skill for an isolated security review, API contract, data-platform choice, service implementation, migration plan, privacy artifact, capacity study, financial model, or platform runbook. Start with the narrower owner when the SaaS context is incidental. For a general architecture decision with no tenant lifecycle or subscription boundary, use [`software-architecture`](../software-architecture/SKILL.md).
+
+## Reference Guide
+
+| Load when | Reference or template |
+|---|---|
+| Defining tenant/account/subscription terms and ownership | `references/tenant-domain-model-and-boundaries.md` |
+| Splitting lifecycle policy from request serving | `references/control-and-application-planes.md` |
+| Comparing pooled, bridge, silo, or hybrid isolation | `references/tenancy-and-data-partitioning-models.md` |
+| Connecting signup, identity, entitlements, usage, and billing | `references/onboarding-identity-entitlements-metering-billing.md` |
+| Planning tenant-aware operations, restore, fairness, and unit-cost inputs | `references/tenant-aware-operations-capacity-and-cost.md` |
+| Producing the overall architecture artifact | `templates/saas-architecture-brief.md` |
+| Capturing a tenancy choice and trigger to revisit it | `templates/tenancy-decision-record.md` |
+| Checking tenant lifecycle completeness | `templates/tenant-lifecycle-checklist.md` |
+| Reviewing public provenance and transformation limits | `references/source-index.md` |
+
+## Completion
+
+Stop when each material SaaS decision has an accountable owner, alternatives and consequences, a lifecycle and failure path, evidence or a named gap, and an explicit specialist handoff. Escalate unresolved tenant authority, isolation, commercial, privacy, or recovery questions rather than inventing policy.
diff --git a/multi-tenant-saas-architecture/evals/evals.json b/multi-tenant-saas-architecture/evals/evals.json
new file mode 100644
index 0000000..3209d4a
--- /dev/null
+++ b/multi-tenant-saas-architecture/evals/evals.json
@@ -0,0 +1,70 @@
+{
+  "schema_version": 1,
+  "skill_name": "multi-tenant-saas-architecture",
+  "evals": [
+    {
+      "id": "pooled-versus-siloed-choice",
+      "prompt": "A B2B analytics SaaS wants pooled storage for most customers but promises dedicated processing to regulated enterprise tenants. Produce the architecture decision.",
+      "expected_output": "A resource-by-resource pooled, bridge, or silo comparison tied to customer promises, blast radius, operations, cost, and revisit triggers.",
+      "assertions": ["distinguishes resource classes instead of choosing one shape for the whole product", "states evidence gaps and revisit triggers", "routes isolation controls to secure-software-engineering and quantitative capacity evidence to capacity-and-cost-engineering"],
+      "files": ["references/tenancy-and-data-partitioning-models.md", "templates/tenancy-decision-record.md"],
+      "case_set": "dev"
+    },
+    {
+      "id": "control-application-planes",
+      "prompt": "Design tenant provisioning for a SaaS where an admin changes a plan and the application must enforce the new entitlement even if the provisioning worker is delayed.",
+      "expected_output": "A control/application plane design with authority, desired state, propagation freshness, stale behavior, idempotency, retries, reconciliation, and user-visible status.",
+      "assertions": ["separates lifecycle policy from application serving without requiring separate deployments", "defines stale entitlement and delayed worker behavior", "does not invent an API contract or platform implementation"],
+      "files": ["references/control-and-application-planes.md", "references/onboarding-identity-entitlements-metering-billing.md"],
+      "case_set": "dev"
+    },
+    {
+      "id": "tenant-lifecycle",
+      "prompt": "Create a lifecycle design for signup, federation, provisioning, suspension, export, deletion, and reactivation for an enterprise tenant.",
+      "expected_output": "A state-aware lifecycle with authorities, idempotency keys, failure paths, customer-visible states, evidence owners, and specialist handoffs.",
+      "assertions": ["covers onboarding through deletion and reactivation", "names retry or reconciliation behavior for asynchronous steps", "routes privacy deletion verification and identity/security controls to their owners"],
+      "files": ["references/tenant-domain-model-and-boundaries.md", "templates/tenant-lifecycle-checklist.md"],
+      "case_set": "regression"
+    },
+    {
+      "id": "entitlement-billing-handoff",
+      "prompt": "A payment provider reports a failed renewal after a tenant exceeded a usage allowance. Decide how metering, invoice authority, entitlement state, grace period, and suspension should interact.",
+      "expected_output": "An explicit usage-to-billing-to-entitlement handoff with authoritative systems, late/duplicate usage handling, disagreement policy, effective times, support override expiry, and routing of financial outcomes.",
+      "assertions": ["does not treat signup or billing as one synchronous transaction", "identifies authority when billing and entitlement disagree", "routes pricing, churn, margin, and financial outcomes to financial-modeling"],
+      "files": ["references/onboarding-identity-entitlements-metering-billing.md"],
+      "case_set": "regression"
+    },
+    {
+      "id": "partitioning-and-deletion",
+      "prompt": "Choose data partitioning for tenant records and design the architecture review for a tenant deletion request that must cover replicas, caches, search, logs, backups, and derived data.",
+      "expected_output": "A partitioning choice with tenant authority, resource boundaries, deletion dependencies, verification evidence, and explicit privacy/data/security handoffs.",
+      "assertions": ["enumerates primary and derived data boundaries beyond the main database", "requires verifiable deletion rather than policy-only claims", "routes storage design to data-architect and privacy requirements to privacy-engineering"],
+      "files": ["references/tenancy-and-data-partitioning-models.md", "references/tenant-aware-operations-capacity-and-cost.md"],
+      "case_set": "regression"
+    },
+    {
+      "id": "tenant-aware-restore",
+      "prompt": "A single tenant corrupted data in a pooled service. Compare tenant-scoped, partition-scoped, and service-wide restore options and define the reopen gate.",
+      "expected_output": "A restore decision based on authority, blast radius, ordering, derived-data reconciliation, customer impact, and a tested recovery handoff.",
+      "assertions": ["compares restore scope rather than assuming tenant-scoped restore is possible", "requires reconciliation before reopening traffic", "routes recovery execution to migration-engineering or resilience-and-recovery as appropriate"],
+      "files": ["references/tenant-aware-operations-capacity-and-cost.md", "templates/saas-architecture-brief.md"],
+      "case_set": "release"
+    },
+    {
+      "id": "hot-tenant-noisy-neighbor",
+      "prompt": "One tenant generates ten times the normal queue and storage load. Design the architecture response while preserving service promises for other tenants.",
+      "expected_output": "Tenant-aware detection, fairness boundary, mitigation choices, customer communication, tier implications, and measured evidence plan with specialist routing.",
+      "assertions": ["distinguishes hot-tenant detection from generic fleet averages", "covers queues, storage, cache, background work, or other relevant resource boundaries", "routes load evidence and unit cost to capacity-and-cost-engineering and implementation to platform-engineering"],
+      "files": ["references/tenant-aware-operations-capacity-and-cost.md", "references/tenancy-and-data-partitioning-models.md"],
+      "case_set": "release"
+    },
+    {
+      "id": "near-boundary-routing",
+      "prompt": "For a multi-tenant product, separately classify these requests: write an OpenAPI contract, threat-model tenant isolation, calculate gross margin by tier, size a load test, provision Kubernetes namespaces, implement a tenant middleware, migrate a tenant between databases, design a data retention verification plan, and choose a target architecture.",
+      "expected_output": "A concise routing table that keeps SaaS architecture as the coordinator while sending each specialist task to its named owner.",
+      "assertions": ["routes API contracts to api-design-and-evolution", "routes threat modeling to secure-software-engineering", "routes gross margin to financial-modeling and load sizing to capacity-and-cost-engineering", "routes Kubernetes provisioning to platform-engineering and middleware implementation to backend-engineering", "routes tenant migration to migration-engineering, retention verification to privacy-engineering, and general target architecture to software-architecture"],
+      "files": ["SKILL.md"],
+      "case_set": "regression"
+    }
+  ]
+}
diff --git a/multi-tenant-saas-architecture/references/control-and-application-planes.md b/multi-tenant-saas-architecture/references/control-and-application-planes.md
new file mode 100644
index 0000000..d9d8b5f
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/control-and-application-planes.md
@@ -0,0 +1,26 @@
+# Control Plane and Application Plane
+
+Use the planes as responsibility lenses, not mandatory deployment units.
+
+## Control plane
+
+The control plane owns tenant-facing and operator-facing policy and lifecycle decisions: registration, tenant records, identity federation configuration, plan and entitlement state, provisioning intent, placement, configuration, suspension, export/deletion requests, and administrative audit. It should be authoritative for desired state and expose operation status rather than pretending provisioning is instantaneous.
+
+## Application plane
+
+The application plane serves tenant work: request admission, tenant context propagation, business workflows, tenant data access, usage events, and user-visible results. It should consume versioned control-plane state with an explicit freshness and failure policy. It must not infer entitlements from a client claim or silently bypass a missing control-plane decision.
+
+## Handoff record
+
+For every cross-plane flow, name:
+
+- command or event and its authority;
+- state transition and idempotency key;
+- propagation delay and stale-state behavior;
+- retry, duplicate, timeout, and reconciliation behavior;
+- customer-visible status and support action;
+- audit evidence and owner.
+
+Examples include tenant creation followed by resource provisioning, plan change followed by entitlement update, suspension followed by request denial, and deletion followed by tombstone or purge confirmation.
+
+Do not turn this guide into an API contract or deployment runbook. Route interface details to `api-design-and-evolution` and substrate implementation to `platform-engineering`.
diff --git a/multi-tenant-saas-architecture/references/onboarding-identity-entitlements-metering-billing.md b/multi-tenant-saas-architecture/references/onboarding-identity-entitlements-metering-billing.md
new file mode 100644
index 0000000..d108b87
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/onboarding-identity-entitlements-metering-billing.md
@@ -0,0 +1,24 @@
+# Onboarding, Identity, Entitlements, Metering, and Billing
+
+Model the commercial path as a set of authorities and handoffs, not one synchronous signup transaction.
+
+## Lifecycle path
+
+1. Capture a prospective account and the intended tenant, region, plan, and owner.
+2. Establish identity and membership using an agreed identity authority; record invitations, federation, and deprovisioning expectations.
+3. Create tenant desired state and provision resources idempotently.
+4. Publish configuration and entitlement state with effective time, version, and reason.
+5. Serve requests using server-derived tenant context and an entitlement decision appropriate to the operation.
+6. Emit usage facts with a stable tenant, subject, meter, event time, quantity, and deduplication identity.
+7. Hand usage to the billing authority for rating, invoicing, payment state, credits, disputes, and tax treatment.
+8. Propagate payment or contract state back to entitlements and support workflows with explicit grace and suspension behavior.
+
+## Questions that prevent hidden policy
+
+- Is the plan change effective immediately, at renewal, or after provisioning succeeds?
+- What happens if usage arrives late, twice, or after a tenant is suspended?
+- Which system is authoritative when entitlement and billing disagree?
+- Can support grant a temporary override, who approves it, and when does it expire?
+- Are quotas product promises, operational protections, or both?
+
+Keep pricing, ARR, churn, margin, and forecast outcomes with `financial-modeling`. Keep contract schemas and webhook compatibility with `api-design-and-evolution`; keep identity and authorization controls with `secure-software-engineering`; keep service implementation with `backend-engineering`.
diff --git a/multi-tenant-saas-architecture/references/source-index.md b/multi-tenant-saas-architecture/references/source-index.md
new file mode 100644
index 0000000..b4a6f6c
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/source-index.md
@@ -0,0 +1,24 @@
+# Source Index and Transformation Boundary
+
+This skill is an original, task-centered synthesis. Public sources inform concepts and terminology; they are not copied as instructional text.
+
+| Public source | Use in this skill | URL |
+|---|---|---|
+| NIST SP 800-57 Part 1 Rev. 5 | Key ownership and lifecycle questions that affect tenant data boundaries | https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final |
+| OWASP Application Security Verification Standard | Boundary verification and authorization evidence as a security handoff | https://github.com/OWASP/ASVS |
+| OWASP API Security Top 10 | Object/function authorization and resource-consumption risks to route to security/API owners | https://owasp.org/API-Security/editions/2023/en/0x11-t10/ |
+| OpenID Connect Core 1.0 | Identity-provider and relying-party terminology for onboarding handoffs | https://openid.net/specs/openid-connect-core-1_0.html |
+| RFC 7644 (SCIM Protocol) | Provisioning and deprovisioning vocabulary for enterprise tenant lifecycle | https://www.rfc-editor.org/rfc/rfc7644 |
+| W3C Trace Context | Trace propagation context for tenant-aware observability handoffs | https://www.w3.org/TR/trace-context/ |
+| Google SRE resources | Reliability, failure, and operational evidence framing | https://sre.google/sre-book/table-of-contents/ |
+| W3C Data Privacy Vocabulary | Neutral vocabulary for data categories, purposes, and personal-data handling | https://www.w3.org/TR/dpv/ |
+
+## Licensed-books boundary
+
+The supplied private comparison report and purchased books may inform research only. This repository does not reproduce their prose, tables, diagrams, examples, taxonomies, chapter order, or distinctive presentation. The deliverable is organized around user tasks and repository ownership boundaries, with fresh examples, templates, and eval fixtures. No purchased ebook is a source file for this skill and no purchased ebook should be read or quoted when using it.
+
+## Provenance and review
+
+- Research input: the safe synthesized architecture comparison supplied for this task.
+- Transformation: public sources, issue requirements, and existing specialist boundaries were compared, then rewritten as original procedures and artifacts.
+- Review rule: if a future edit resembles a source's distinctive expression or structure, rewrite it from the user task and re-check this boundary before publication.
diff --git a/multi-tenant-saas-architecture/references/tenancy-and-data-partitioning-models.md b/multi-tenant-saas-architecture/references/tenancy-and-data-partitioning-models.md
new file mode 100644
index 0000000..6739397
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/tenancy-and-data-partitioning-models.md
@@ -0,0 +1,18 @@
+# Tenancy and Data Partitioning Models
+
+Choose an isolation shape per resource. A product can pool application compute, bridge selected data or compute, and silo high-sensitivity or high-demand resources at the same time.
+
+| Shape | Strength | Cost or risk to test |
+|---|---|---|
+| Pooled | Efficient utilization and simple fleet-wide change | Strong tenant context, query scoping, fairness, and restore targeting are required |
+| Bridge | Shared control or compute with selected dedicated resources | Placement rules and cross-resource consistency become more complex |
+| Silo | Clear blast-radius and performance boundary | Provisioning, upgrades, idle cost, and fleet variation increase |
+| Hybrid | Matches different tiers, regions, or resource classes | Policy drift and migration paths need explicit governance |
+
+Evaluate each resource class separately: primary records, object storage, cache, queue, search index, analytics copy, encryption keys, backups, and runtime capacity. For each, record tenant boundary, authoritative identifier, access path, failure blast radius, operational owner, cost attribution, and migration trigger.
+
+## Decision pressures
+
+Use actual promises and evidence: regulatory or contractual isolation, tenant data volume, peak skew, region/residency, recovery scope, support model, deployment cadence, team capability, and unit economics. Do not claim that a silo is automatically safer or that pooling is automatically cheaper. Both require controls and evidence.
+
+Security threat modeling and enforcement belong to `secure-software-engineering`; data storage architecture and schema choices belong to `data-architect`; moving a tenant between shapes belongs to `migration-engineering`; quantitative load and cost evidence belongs to `capacity-and-cost-engineering`.
diff --git a/multi-tenant-saas-architecture/references/tenant-aware-operations-capacity-and-cost.md b/multi-tenant-saas-architecture/references/tenant-aware-operations-capacity-and-cost.md
new file mode 100644
index 0000000..5b4a600
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/tenant-aware-operations-capacity-and-cost.md
@@ -0,0 +1,18 @@
+# Tenant-Aware Operations, Capacity, and Cost
+
+An operational design is incomplete if it only describes the fleet average. Record tenant distribution, tier promises, resource ownership, and what happens when one tenant is unusually large, busy, expensive, or failing.
+
+## Required scenarios
+
+- **Hot tenant:** detect skew, protect other tenants, choose throttle, queue, placement, or isolation behavior, and define customer communication.
+- **Noisy neighbor:** prove fairness at the resource boundary, not just at the API gateway; include caches, queues, storage, and background work.
+- **Tenant restore:** identify whether restore is tenant-scoped, partition-scoped, or service-wide; preserve ordering and reconcile derived data before reopening traffic.
+- **Tenant deletion/export:** enumerate primary, replicas, caches, indexes, logs, backups, and derived data; verify completion and legal holds with `privacy-engineering`.
+- **Placement change:** define the trigger, compatibility window, movement evidence, and recovery path with `migration-engineering`.
+- **Cost anomaly:** attribute shared baseline and tenant-variable cost separately; route quantitative modeling to `capacity-and-cost-engineering` and commercial decisions to `financial-modeling`.
+
+## Evidence handoffs
+
+The architecture brief names the metric, owner, and decision trigger. It does not invent universal thresholds. `capacity-and-cost-engineering` owns demand distributions, load/soak evidence, unit cost, quota controls, and SLO-cost tradeoffs. `platform-engineering` owns the implementation of autoscaling, scheduling, telemetry substrate, and resource policies. `site-reliability-engineering` owns SLOs, error budgets, incident command, and live operations.
+
+For every tenant-aware metric, distinguish tenant identity from sensitive payload, define aggregation and access, and check whether the telemetry creates a privacy obligation.
diff --git a/multi-tenant-saas-architecture/references/tenant-domain-model-and-boundaries.md b/multi-tenant-saas-architecture/references/tenant-domain-model-and-boundaries.md
new file mode 100644
index 0000000..695262b
--- /dev/null
+++ b/multi-tenant-saas-architecture/references/tenant-domain-model-and-boundaries.md
@@ -0,0 +1,28 @@
+# Tenant Domain Model and Boundaries
+
+Start with meanings, not tables. A tenant is the customer boundary whose data, policy, usage, and service promise are managed together. It may be an organization, account, workspace, or another domain object, but the chosen term must be stable and user-visible.
+
+## Minimum vocabulary
+
+| Concept | Decide explicitly |
+|---|---|
+| Tenant | What customer boundary owns data, configuration, usage, and support history? |
+| Account or organization | Is this the commercial payer, the operating group, or both? Can one payer own several tenants? |
+| User | Is identity global, tenant-scoped, or federated? Can one user belong to many tenants? |
+| Membership | Which tenant-local role and status govern a user's actions? |
+| Subscription | What commercial agreement is attached to which account or tenant, for what period and status? |
+| Entitlement | Which product capability, limit, region, or support promise is granted, and who may change it? |
+| Resource | Which objects are tenant-owned, shared, or platform-owned? |
+| Environment | Does a tenant have production, test, or regional environments with separate lifecycle and data rules? |
+
+For each concept record: authoritative owner, identifier, cardinality, state machine, audit requirement, deletion relationship, and cross-tenant visibility rule. A shared identity provider does not make application authorization global; application membership still needs an authoritative decision.
+
+## Boundary tests
+
+- A request can resolve one tenant context before accessing tenant-owned resources.
+- A support operator has a separate, reviewable path from ordinary membership.
+- A subscription change has one authority and an observable propagation path to entitlements.
+- A tenant suspension, export, restore, and deletion operation names every dependent store and derived artifact.
+- A tenant move between partitions preserves identity, ownership, and billing references without silently changing the customer promise.
+
+Keep storage schema and API contract mechanics with `data-architect` and `api-design-and-evolution`; keep authorization and isolation controls with `secure-software-engineering`.
diff --git a/multi-tenant-saas-architecture/templates/saas-architecture-brief.md b/multi-tenant-saas-architecture/templates/saas-architecture-brief.md
new file mode 100644
index 0000000..8631c33
--- /dev/null
+++ b/multi-tenant-saas-architecture/templates/saas-architecture-brief.md
@@ -0,0 +1,57 @@
+# SaaS Architecture Brief
+
+## Decision
+- **Product/service:**
+- **Decision owner:**
+- **Review date or trigger:**
+- **Status:** draft | decided | superseded
+
+## Service promise and context
+- Customer and tenant promise:
+- Users, operators, and support actors:
+- Subscription and region assumptions:
+- Data classes and lifecycle constraints:
+- Scale, skew, and recovery facts:
+- Unknowns requiring evidence:
+
+## Domain authorities
+| Concept | Meaning | Authoritative owner | States and transitions | Cross-tenant rule |
+|---|---|---|---|---|
+| Tenant | | | | |
+| Account/subscription | | | | |
+| User/membership | | | | |
+| Entitlement/resource | | | | |
+
+## Planes and flows
+- Control-plane responsibilities:
+- Application-plane responsibilities:
+- Provisioning and configuration handoff:
+- Entitlement and usage handoff:
+- Billing and suspension handoff:
+- Retry, stale state, reconciliation, and support behavior:
+
+## Tenancy choices
+| Resource | Shape | Why it fits the promise | Failure blast radius | Cost/fairness concern | Revisit trigger |
+|---|---|---|---|---|---|
+| Primary data | | | | | |
+| Runtime compute | | | | | |
+| Cache/queue/search | | | | | |
+| Backup/restore | | | | | |
+
+## Lifecycle and operations
+- Onboarding and deprovisioning:
+- Hot-tenant/noisy-neighbor behavior:
+- Restore, export, and deletion scope:
+- Tenant-aware observability and privacy constraints:
+
+## Decisions and handoffs
+| Decision or open question | Owner | Evidence or gap | Handoff |
+|---|---|---|---|
+| | | | |
+
+## Verification
+- Cross-tenant negative cases:
+- Lifecycle idempotency and retry cases:
+- Entitlement/billing disagreement:
+- Restore and deletion evidence:
+- Capacity/noisy-neighbor evidence:
diff --git a/multi-tenant-saas-architecture/templates/tenancy-decision-record.md b/multi-tenant-saas-architecture/templates/tenancy-decision-record.md
new file mode 100644
index 0000000..263e6aa
--- /dev/null
+++ b/multi-tenant-saas-architecture/templates/tenancy-decision-record.md
@@ -0,0 +1,30 @@
+# Tenancy Decision Record
+
+## Context
+- Resource or resource class:
+- Tenant promise and affected tiers:
+- Current and forecast distribution:
+- Data, residency, recovery, and support constraints:
+
+## Options
+| Option | Isolation boundary | Operational shape | Benefits | Costs and failure modes |
+|---|---|---|---|---|
+| Pooled | | | | |
+| Bridge | | | | |
+| Silo | | | | |
+| Hybrid | | | | |
+
+## Decision
+- Selected shape:
+- Why this is sufficient for the stated promise:
+- Controls and evidence owned by `secure-software-engineering`:
+- Capacity and cost evidence owned by `capacity-and-cost-engineering`:
+- Data/privacy evidence owners:
+- Platform implementation owner:
+
+## Revisit
+- Trigger metric or event:
+- Review owner:
+- Migration or coexistence path:
+- Customer communication obligation:
+- Supersession condition:
diff --git a/multi-tenant-saas-architecture/templates/tenant-lifecycle-checklist.md b/multi-tenant-saas-architecture/templates/tenant-lifecycle-checklist.md
new file mode 100644
index 0000000..94dc92a
--- /dev/null
+++ b/multi-tenant-saas-architecture/templates/tenant-lifecycle-checklist.md
@@ -0,0 +1,26 @@
+# Tenant Lifecycle Checklist
+
+Use one row per tenant state transition. Mark unknowns instead of assuming success.
+
+| Stage | Authority and input | Idempotency key | User-visible state | Failure/retry path | Evidence and owner | Done |
+|---|---|---|---|---|---|---|
+| Prospect/account accepted | | | | | | |
+| Identity and membership established | | | | | | |
+| Tenant desired state created | | | | | | |
+| Resources provisioned | | | | | | |
+| Configuration and entitlements active | | | | | | |
+| Usage metering active | | | | | | |
+| Billing handoff verified | | | | | | |
+| Suspension or grace period | | | | | | |
+| Export or deletion requested | | | | | | |
+| Data purged and evidence retained | | | | | | |
+| Restore or reactivation | | | | | | |
+
+## Boundary checks
+
+- [ ] Tenant context is derived and validated at each application access path; route control verification to `secure-software-engineering`.
+- [ ] API and event contracts have an owner and compatibility policy; route contract work to `api-design-and-evolution`.
+- [ ] Data, replicas, backups, caches, indexes, logs, and derived data are named; route implementation to `data-architect`, `data-engineering`, and `privacy-engineering` as applicable.
+- [ ] Placement moves have a migration owner and recovery classification.
+- [ ] Hot-tenant and noisy-neighbor behavior has measured capacity evidence.
+- [ ] Pricing, invoice, churn, and margin claims have a financial-modeling owner.
diff --git a/references/skill-triggers.md b/references/skill-triggers.md
index f768d9c..625a47a 100644
--- a/references/skill-triggers.md
+++ b/references/skill-triggers.md
@@ -48,6 +48,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
 | "last.fm", "scrobble", "music discovery", "listening history", "similar artists", "lastfm", "weekly top artists", "genre charts" | [lastfm](../lastfm/SKILL.md) |
 | "MeshCore Companion", "meshcore-packet-capture", "MeshCore packet capture", "BLE radio capture", "serial radio capture", "MeshCore MQTT", "LetsMesh", "PACKETCAPTURE_", "meshcore-packet-capture Docker", "MeshCore NixOS" | [meshcore-packet-capture](../meshcore-packet-capture/SKILL.md) |
 | "migration engineering", "migration plan", "schema migration", "data migration", "API migration", "infrastructure migration", "service migration", "cross-system migration", "expand contract", "compatibility window", "dual-running", "backfill", "reconciliation", "cutover plan", "irreversible migration", "rollback plan", "roll-forward", "migration deprecation", "migration cleanup", "migration observability", "migration correctness evidence", "migration ownership" | [migration-engineering](../migration-engineering/SKILL.md) |
+| "multi-tenant SaaS", "multi-tenant architecture", "SaaS architecture", "tenant model", "tenant domain model", "control plane application plane", "control-plane", "application-plane", "pooled tenancy", "bridge tenancy", "silo tenancy", "hybrid tenancy", "tenant partitioning", "tenant onboarding", "tenant entitlements", "usage metering billing", "tenant lifecycle", "tenant restore", "noisy neighbor", "hot tenant" | [multi-tenant-saas-architecture](../multi-tenant-saas-architecture/SKILL.md) |
 | "nous", "theia", "hermes brand", "brand identity", "style guide", "mascot", "anime style", "cyber-classical", "color palette reference" | [nous-branding](../nous-branding/SKILL.md) |
 | "okf", "open knowledge format", "knowledge bundle", "LLM wiki", "agent knowledge", "Google knowledge format", "markdown knowledge", "vendor-neutral knowledge", "create an OKF bundle", "validate OKF", "concept document", "knowledge format" | [open-knowledge-format](../open-knowledge-format/SKILL.md) |
 | "raleigh", "open data", "city of raleigh", "raleigh data", "crime data", "food inspections", "building permits", "arcgis", "public data", "raleighnc" | [raleigh](../raleigh/SKILL.md) |