name: tidyfactor-next description: "Production multi-tenant SaaS engine on Next.js 16, React 19, TypeScript strict, and Supabase with Contextual Decision Layer (CDL). Features locked tenant isolation (tenant_id + Postgres RLS) and pluggable query layer. Trigger on commands 'brief', 'init', 'tenant', 'rls', 'auth', 'data', 'storage', 'api', 'app', 'test', 'observe', 'deploy', or requests to build a multi-tenant SaaS."

TidyFactor Next.js

A command dispatcher for production multi-tenant SaaS on Next.js 16 and Supabase. This router declares commands and workflows without performing execution directly.

Commands

Read only the command file that matches the request. Do not load all commands simultaneously.

Non-Negotiable Invariants

1. Contextual Decision Layer (CDL): Resolve project baselines via /brief or .tidyfactor/next-brief.md before emitting code.
2. Locked Tenant Isolation: Every tenant-owned table MUST include tenant_id uuid NOT NULL REFERENCES tenants(id) ON DELETE CASCADE.
3. Forced RLS Boundary: Every tenant table MUST have ENABLE ROW LEVEL SECURITY and FORCE ROW LEVEL SECURITY.
4. Zero Service-Role Leaks: Never expose SUPABASE_SERVICE_ROLE_KEY to client components or public API responses.
5. 7-Axis Pre-Emit Critique: All generated code must be evaluated with /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */.

⚡ TidyFactor Next.js v1.4.0

The Production-Grade Multi-Tenant SaaS Architecture & Performance Skill for AI Coding Agents

Give Google Antigravity, Claude Code, Cursor, OpenAI Codex, or Windsurf a locked, security-first architecture for Next.js 16 + React 19 + Supabase — so your agent stops improvising tenant isolation and starts enforcing it.

🚀 Quick Start • 🎯 Why TidyFactor/Next • 🔒 Tenant Isolation • ⚡ 15-Stage Lifecycle • 🚀 Perf Engine • ❓ FAQ • 📖 بالعربية

📚 Table of Contents

• 🎯 Why TidyFactor/Next
• 🚀 Quick Start
• 🌟 Architectural Value Proposition
• 🔒 Locked Tenant Isolation Model
• ⚡ 15-Stage SaaS Command Lifecycle
• 🚀 Performance & Optimization Engine
  • 1. 8-Tier Runtime Performance Rules (Vercel Engineering)
  • 2. Development Environment Resource Diagnostics
  • 3. Optimization Safety Tiers (Green / Yellow / Red)
• 🛡️ RLS Policy Matrix & Auth Hooks
• 📋 Project Memory & ARCHITECTURE.md
• ❓ FAQ
• 🏛️ The TidyFactor Ecosystem
• 🏛️ TidyFactor Skill Methodology & Governance
• 🤝 Contributing
• 👨‍💻 Support
• 📜 License

🎯 Why TidyFactor/Next

Most Next.js agent skills teach your AI how to write idiomatic code — App Router conventions, caching APIs, and bundle-size tweaks. That is necessary, but it does not stop an agent from shipping a query that accidentally leaks Tenant A's data into Tenant B's dashboard.

TidyFactor/Next sits one layer deeper: it is an architecture and hard security contract, not just a style guide.

[!TIP] If you are building a SaaS where a cross-tenant data leak means a lawsuit, tidyfactor-next is the foundational guardrail layer your AI agent needs in addition to general React best practices.

🚀 Quick Start

1. Interactive Project Wizard & Direct Injection

# Interactive project wizard — scaffolds a new multi-tenant SaaS project
npx @alwkala/tidyfactor-next

# Or inject the skill directly into an existing Next.js repository
npx @alwkala/tidyfactor-next add-skill

2. Workspace Installation per AI Agent

Once installed, invoke /init or /brief inside your AI agent to discover project baselines and scaffold your ARCHITECTURE.md single source of truth!

🌟 Architectural Value Proposition

graph TD
    UserReq["🌐 Incoming Request"] --> Edge["🛡️ Edge Middleware<br/>(Fail-Closed Tenant Resolution)"]
    Edge --> Context["📦 Tenant Context<br/>(tenant_id + JWT Claims)"]
    Context --> App["⚡ Next.js 16 App Router<br/>(Server Components & Actions)"]
    App --> Query["🔌 Pluggable Query Layer<br/>(Supabase JS / Drizzle / Prisma)"]
    Query --> Postgres["🐘 PostgreSQL Database"]
    Postgres --> RLS["🔒 Row Level Security (RLS)<br/>USING (tenant_id = auth.jwt() ->> 'tenant_id')"]
    RLS --> Data["✅ Isolated Tenant Data"]

🔒 Locked Tenant Isolation Model

tidyfactor-next enforces strict, non-negotiable isolation rules across the entire lifecycle:

-- Standard Tenant Isolation Policy (Pattern 1)
ALTER TABLE public.organizations ENABLE ROW LEVEL SECURITY;

CREATE POLICY "organizations_tenant_isolation_select" ON public.organizations
  FOR SELECT USING (tenant_id = (auth.jwt() ->> 'tenant_id')::uuid);

CREATE POLICY "organizations_tenant_isolation_insert" ON public.organizations
  FOR INSERT WITH CHECK (tenant_id = (auth.jwt() ->> 'tenant_id')::uuid);

CREATE POLICY "organizations_tenant_isolation_update" ON public.organizations
  FOR UPDATE USING (tenant_id = (auth.jwt() ->> 'tenant_id')::uuid)
  WITH CHECK (tenant_id = (auth.jwt() ->> 'tenant_id')::uuid);

CREATE POLICY "organizations_tenant_isolation_delete" ON public.organizations
  FOR DELETE USING (tenant_id = (auth.jwt() ->> 'tenant_id')::uuid);

🚨 Non-Negotiable Safety Directives:

1. RLS is the Security Boundary: Application-layer WHERE tenant_id = ... is only a query-plan hint. If RLS is disabled, the system is defective by definition.
2. service_role Key Isolation: Never exposed to client bundles or public endpoints. Used exclusively in server-only contexts with re-verified tenant context.
3. Edge Context Propagation: Tenant identity is resolved once at the edge and passed down—never re-derived haphazardly in deep component trees.
4. Cross-Tenant Operations Review: Admin impersonation, cross-tenant migrations, or platform analytics must be isolated and flagged as security review triggers.

⚡ 15-Stage SaaS Command Lifecycle

The entire SaaS engineering lifecycle is structured into 15 deterministic commands with 100% operational coverage: