@folpe/loom 0.2.0 → 0.4.0

package/data/presets/e-commerce.yaml

@@ -27,26 +27,14 @@ constitution:
     - Payment security — never handle raw card data, always use Stripe Elements
     - SEO drives traffic — product pages must be indexable with structured data
     - Performance converts — every 100ms of load time impacts conversion rate
-  stack:
-    - Next.js 16+ (App Router)
-    - React 19
-    - TypeScript 5 (strict)
-    - Tailwind CSS 4
-    - ShadCN UI
-    - Supabase (auth + database)
-    - Stripe (payments)
-    - Vercel (deployment)
   conventions:
     - Use Stripe Checkout or Payment Elements — never collect card details directly
     - Implement webhook handlers for Stripe events (payment success, refund, etc.)
     - Use ISR or SSG for product catalog pages for performance
     - Add JSON-LD structured data for products (price, availability, reviews)
     - Implement optimistic cart updates with server validation
-claudemd:
+context:
   projectDescription: >
-    This is an e-commerce application scaffolded with Loom. It includes product catalog, shopping
+    This is an e-commerce application. It includes product catalog, shopping
     cart, Stripe checkout, and transactional emails. The orchestrator coordinates the full agent
     team including marketing for copywriting and SEO.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start
-    by delegating to the orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/expo-mobile.yaml

@@ -20,25 +20,15 @@ constitution:
     - Offline-first — the app must be usable without network connectivity
     - Battery conscious — minimize background tasks and network requests
     - Smooth animations — target 60fps, never block the JS thread
-  stack:
-    - Expo SDK 52+
-    - React Native
-    - TypeScript 5 (strict)
-    - NativeWind (Tailwind for React Native)
-    - Expo Router (file-based navigation)
-    - Supabase (auth + database)
   conventions:
     - Use Expo Router for all navigation — file-based routing
     - Implement offline storage with async-storage or MMKV for critical data
     - Use expo-notifications for push notifications setup
     - Handle deep linking and universal links from the start
     - Test on both iOS and Android — never assume platform parity
-claudemd:
+context:
   projectDescription: >
-    This is a mobile application scaffolded with Loom using Expo and React Native. It uses
+    This is a mobile application using Expo and React Native. It uses
     NativeWind for styling and Expo Router for navigation. The orchestrator delegates mobile UI
     to the frontend agent, API integration to the backend agent, and native feature testing
     to the tests agent.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start
-    by delegating to the orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/fullstack-auth.yaml

@@ -23,26 +23,14 @@ constitution:
     - Least privilege — users and services get only the permissions they need
     - Defense in depth — middleware, RLS, and API validation work together
     - Session management — handle expiry, refresh, and revocation properly
-  stack:
-    - Next.js 16+ (App Router)
-    - React 19
-    - TypeScript 5 (strict)
-    - Tailwind CSS 4
-    - ShadCN UI
-    - Supabase Auth (email, OAuth, magic link)
-    - Supabase (database with RLS)
-    - Vercel (deployment)
   conventions:
     - Use Supabase Auth for all authentication flows
     - Implement middleware for route protection and role checks
     - Enable Row Level Security on all tables — no exceptions
     - Use server-side session validation, never trust client-only auth state
     - Separate admin and user dashboards with distinct layouts
-claudemd:
+context:
   projectDescription: >
-    This is a fullstack SaaS with complete authentication scaffolded with Loom. It includes email,
+    This is a fullstack SaaS with complete authentication. It includes email,
     OAuth, and magic link flows via Supabase Auth, plus RBAC and admin dashboard. The orchestrator
     coordinates security, frontend, backend, and database agents for auth-related tasks.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start
-    by delegating to the orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/landing-page.yaml

@@ -19,23 +19,14 @@ constitution:
     - Performance is UX — aim for perfect Lighthouse scores
     - Mobile-first responsive — design for small screens, enhance for large
     - Accessible by default — semantic HTML, ARIA, keyboard navigation
-  stack:
-    - Next.js 16+ (static export)
-    - React 19
-    - TypeScript 5 (strict)
-    - Tailwind CSS 4
-    - Vercel (deployment)
   conventions:
     - Use Server Components and static generation for maximum performance
     - Optimize all images with next/image and proper srcset
     - Implement structured data (JSON-LD) for SEO
     - Use CSS animations and transitions over JS-based animation libraries
     - Ensure all interactive elements have visible focus states
-claudemd:
+context:
   projectDescription: >
-    This is a landing page / marketing site scaffolded with Loom. It focuses on SEO, conversion
+    This is a landing page / marketing site. It focuses on SEO, conversion
     optimization, and fast loading. The orchestrator delegates visual tasks to the frontend and
     ux-ui agents, copywriting to marketing, and performance audits to the performance agent.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start
-    by delegating to the orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/mvp-lean.yaml

@@ -15,24 +15,14 @@ constitution:
     - Iterate fast — build the simplest thing that works, then improve
     - Technical debt is acceptable — speed wins at the prototype stage
     - Validate assumptions — build to learn, not to last
-  stack:
-    - Next.js 16+ (App Router)
-    - React 19
-    - TypeScript 5 (strict)
-    - Tailwind CSS 4
-    - Supabase (auth + database)
-    - Vercel (deployment)
   conventions:
     - Prefer inline styles and co-located logic over abstractions
     - Use Supabase client directly — skip custom API layers when possible
     - Minimal component hierarchy — flatten where you can
     - Skip extensive error handling — focus on happy path first
     - One file per feature when practical
-claudemd:
+context:
   projectDescription: >
-    This is a lean MVP scaffolded with Loom. Speed and iteration are prioritized over architecture.
+    This is a lean MVP. Speed and iteration are prioritized over architecture.
     The orchestrator coordinates a small team of frontend, backend, and database agents to ship
     features as fast as possible.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start
-    by delegating to the orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/saas-default.yaml

@@ -1,4 +1,4 @@
-name: SaaS Default
+name: SaaS Full
 description: Standard SaaS project preset with full agent team, Next.js conventions, and Tailwind patterns. Includes
   orchestrator-driven multi-agent workflow.
 agents:
@@ -20,31 +20,22 @@ skills:
   - shadcn-ui
   - api-design
   - ui-ux-guidelines
+  - stripe-integration
+  - seo-optimization
 constitution:
   principles:
     - Ship fast, iterate often — prefer working software over perfect plans
     - User-first design — every feature must solve a real user problem
     - Type safety everywhere — leverage TypeScript strict mode
     - Convention over configuration — follow established patterns
-  stack:
-    - Next.js 16+ (App Router)
-    - React 19
-    - TypeScript 5 (strict)
-    - Tailwind CSS 4
-    - ShadCN UI
-    - Supabase (auth + database)
-    - Vercel (deployment)
   conventions:
     - Use Server Components by default, Client Components only when needed
     - Server Actions for all mutations
     - Zod validation at API boundaries
     - Mobile-first responsive design
     - Semantic HTML with ARIA attributes for accessibility
-claudemd:
+context:
   projectDescription: >
-    This is a SaaS application scaffolded with Loom. It uses a multi-agent architecture where the orchestrator delegates
+    This is a SaaS application. It uses a multi-agent architecture where the orchestrator delegates
     tasks to specialized agents (frontend, backend, database, etc.). Each agent follows the conventions defined in the
     linked skills.
-  orchestratorRef: >
-    The orchestrator agent (.claude/agents/orchestrator.md) is the main entry point. Always start by delegating to the
-    orchestrator, which will route tasks to the appropriate specialized agent.

package/data/presets/saas-full.yaml

@@ -0,0 +1,58 @@
+name: SaaS Full
+description: SaaS complet avec architecture en couches, auth RBAC, i18n, forms, testing, emails et Stripe. Batteries-included.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - database
+  - ux-ui
+  - tests
+  - review-qa
+  - security
+  - performance
+  - marketing
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - shadcn-ui
+  - api-design
+  - supabase-patterns
+  - ui-ux-guidelines
+  - layered-architecture
+  - drizzle-patterns
+  - server-actions-patterns
+  - form-validation
+  - auth-rbac
+  - i18n-patterns
+  - testing-patterns
+  - resend-email
+  - react-query-patterns
+  - table-pagination
+  - env-validation
+  - better-auth-patterns
+  - stripe-integration
+  - hero-copywriting
+  - seo-optimization
+constitution:
+  principles:
+    - Functional over OOP — pure functions, composition, immutability
+    - Strict layered architecture — Presentation → Facade → Service → DAL → Persistence
+    - Type safety everywhere — TypeScript strict, Zod validation at boundaries
+    - Ship fast, iterate often — working software over perfect plans
+    - Security by design — auth + RBAC + validation at every layer
+  conventions:
+    - RSC by default, "use client" only when strictly needed
+    - Server Actions for all mutations, DAL for all reads
+    - Zod dual validation (client + server)
+    - Facades between presentation and services
+    - CASL authorization at service layer
+    - next-intl for all user-facing strings
+    - Vitest with role-based test strategy (PUBLIC/USER/ADMIN)
+    - kebab-case for all new files
+context:
+  projectDescription: >
+    This is a full-featured SaaS application. It follows a strict layered architecture
+    (Presentation → Facade → Service → DAL → Persistence) with multi-agent orchestration. Authentication is
+    handled by Better Auth with RBAC via CASL. The app supports i18n with next-intl, transactional emails via
+    Resend, payments via Stripe, and uses Drizzle ORM with PostgreSQL. Every feature is tested with Vitest
+    using a role-based strategy (PUBLIC/USER/ADMIN).

package/data/skills/api-design/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: api-design
-description: "REST API design principles, error handling, validation, and security patterns. Use when building API routes, server actions, or backend services."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "REST API design with validation, error handling, auth wrappers, and facades. Use when building API routes, server actions, implementing auth middleware, or designing backend services."
 ---
 
 # API Design Principles
 
+## Critical Rules
+
+- **Validate all incoming data** with Zod schemas at the API boundary.
+- **Never expose stack traces** or internal details in production error responses.
+- **Always use facades** between presentation and services.
+- **Auth wrappers on every protected endpoint** — `withAuth()`, `withAdmin()`.
+- **Consistent response shapes** — `{ data }` for success, `{ error, code }` for errors.
+- **Parameterized queries only** — never string concatenation for SQL.
+
 ## Route Structure
 
 - Use resource-based URLs: `/api/users`, `/api/posts/:id/comments`.
@@ -82,6 +90,39 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Check permissions at the resource level: "Can this user access THIS specific post?"
 - Return `401` for missing/invalid auth, `403` for insufficient permissions.
 
+### Auth Wrappers
+
+Use auth wrapper functions for consistent protection:
+
+```ts
+// Require any authenticated user
+export async function withAuth() {
+  const user = await getCurrentUser();
+  if (!user) throw new ApiError(401, "Unauthorized");
+  return user;
+}
+
+// Require authenticated user with valid token
+export async function withAuthToken(request: Request) {
+  const token = request.headers.get("authorization")?.replace("Bearer ", "");
+  if (!token) throw new ApiError(401, "Missing token");
+  return verifyToken(token);
+}
+
+// Dynamic auth — optional session, different behavior for authed/unauthed
+export async function withDynamicAuth() {
+  const user = await getCurrentUser();
+  return { user, isAuthenticated: !!user };
+}
+```
+
+## Facades
+
+- **Always use facades** between presentation and services.
+- One facade per domain entity in `src/facades/`.
+- Facades handle auth context extraction and coordinate service calls.
+- Routes/pages call facades — never services directly.
+
 ## Rate Limiting
 
 - Implement rate limiting on public endpoints and auth endpoints.

package/data/skills/auth-rbac/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: auth-rbac
+description: "CASL-based authorization with role hierarchies, organization roles, and safe route protection. Use when implementing access control, role-based permissions, or protecting routes and API endpoints."
+---
+
+# Auth & RBAC Patterns
+
+## Critical Rules
+
+- **Authorization in services, not routes** — use CASL in the service layer.
+- **Route groups for access control** — `(public)`, `(auth)`, `(app)`, `admin`.
+- **Middleware for redirects** — protect routes at the edge.
+- **Auth wrappers for pages** — `withAuth()`, `withAdmin()` in server components.
+- **Never trust client-side role checks** — always verify server-side.
+- **Principle of least privilege** — grant minimum required permissions.
+
+## Role System
+
+### Application Roles
+
+```ts
+// src/lib/roles.ts
+export const APP_ROLES = ["USER", "ADMIN", "SUPER_ADMIN"] as const;
+export type AppRole = (typeof APP_ROLES)[number];
+```
+
+### Organization Roles
+
+```ts
+export const ORG_ROLES = ["MEMBER", "MANAGER", "OWNER"] as const;
+export type OrgRole = (typeof ORG_ROLES)[number];
+```
+
+- Every user has an **app role** (global) and an **org role** (per organization).
+- Role checks always consider both: app role for platform features, org role for org resources.
+
+## CASL Authorization
+
+### Ability Definition
+
+```ts
+// src/lib/casl.ts
+import { AbilityBuilder, createMongoAbility, type MongoAbility } from "@casl/ability";
+
+type Actions = "create" | "read" | "update" | "delete" | "manage";
+type Subjects = "User" | "Post" | "Organization" | "all";
+export type AppAbility = MongoAbility<[Actions, Subjects]>;
+
+export function defineAbilityFor(user: AuthUser): AppAbility {
+  const { can, cannot, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+  // Base permissions for all authenticated users
+  can("read", "Post", { published: true });
+  can("update", "User", { id: user.id }); // own profile
+
+  if (user.role === "ADMIN") {
+    can("manage", "User");
+    can("manage", "Post");
+    can("read", "Organization");
+  }
+
+  if (user.role === "SUPER_ADMIN") {
+    can("manage", "all");
+  }
+
+  return build();
+}
+```
+
+### Organization Ability
+
+```ts
+export function defineOrgAbilityFor(user: AuthUser, orgRole: OrgRole): AppAbility {
+  const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);
+
+  can("read", "Organization");
+
+  if (orgRole === "MANAGER" || orgRole === "OWNER") {
+    can("update", "Organization");
+    can("manage", "User"); // manage org members
+  }
+
+  if (orgRole === "OWNER") {
+    can("delete", "Organization");
+  }
+
+  return build();
+}
+```
+
+## Service Layer Authorization
+
+Check permissions in the **service layer**, never in presentation or DAL:
+
+```ts
+// src/services/post.service.ts
+import { ForbiddenError } from "@casl/ability";
+import { defineAbilityFor } from "@/lib/casl";
+
+export async function deletePost(user: AuthUser, postId: string) {
+  const ability = defineAbilityFor(user);
+  const post = await findPostById(postId);
+
+  ForbiddenError.from(ability).throwUnlessCan("delete", {
+    ...post,
+    __typename: "Post",
+  });
+
+  return removePost(postId);
+}
+```
+
+## Safe Route Protection
+
+### Middleware-Level
+
+```ts
+// middleware.ts
+const publicRoutes = ["/", "/login", "/register", "/api/webhook"];
+const adminRoutes = ["/admin"];
+
+export async function middleware(request: NextRequest) {
+  const session = await getSession();
+
+  if (!session && !publicRoutes.some(r => request.nextUrl.pathname.startsWith(r))) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+
+  if (adminRoutes.some(r => request.nextUrl.pathname.startsWith(r))) {
+    if (session?.user.role !== "ADMIN" && session?.user.role !== "SUPER_ADMIN") {
+      return NextResponse.redirect(new URL("/", request.url));
+    }
+  }
+}
+```
+
+### Route Group Structure
+
+```
+src/app/
+  (public)/        # No auth required — landing, login, register
+    login/
+    register/
+  (auth)/          # Auth required, any role — onboarding
+    onboarding/
+  (app)/           # Auth required, active user — main app
+    dashboard/
+    settings/
+  admin/           # Admin only — user management, app settings
+    users/
+    settings/
+```
+
+### Auth Wrappers
+
+```ts
+// src/lib/auth-wrappers.ts
+import { getCurrentUser } from "@/lib/auth";
+import { redirect } from "next/navigation";
+
+export async function withAuth() {
+  const user = await getCurrentUser();
+  if (!user) redirect("/login");
+  return user;
+}
+
+export async function withAdmin() {
+  const user = await withAuth();
+  if (user.role !== "ADMIN" && user.role !== "SUPER_ADMIN") redirect("/");
+  return user;
+}
+
+export async function withOrgRole(orgId: string, requiredRole: OrgRole) {
+  const user = await withAuth();
+  const membership = await getOrgMembership(user.id, orgId);
+  if (!membership || !hasOrgRole(membership.role, requiredRole)) redirect("/");
+  return { user, membership };
+}
+```

package/data/skills/better-auth-patterns/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: better-auth-patterns
+description: "Better Auth setup with session management, social login, organization plugin, and middleware. Use when implementing authentication, adding social login providers, or managing user sessions with Better Auth."
+---
+
+# Better Auth Patterns
+
+## Critical Rules
+
+- **Server-side session check** — use `getCurrentUser()` in RSC and Server Actions.
+- **Client-side `useSession()`** — only in Client Components for UI state.
+- **Middleware for redirects** — protect routes at the edge, not in pages.
+- **Never expose auth secrets** — keep `BETTER_AUTH_SECRET` server-only.
+- **Use plugins** — `organization()`, `admin()` for built-in features.
+- **Social login always available** — Google + GitHub as defaults.
+
+## Server Setup
+
+```ts
+// src/lib/auth.ts
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { organization, admin } from "better-auth/plugins";
+import { db } from "@/lib/db";
+
+export const auth = betterAuth({
+  database: drizzleAdapter(db, { provider: "pg" }),
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  },
+  plugins: [
+    organization(),
+    admin(),
+  ],
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // refresh daily
+  },
+});
+```
+
+## Client Setup
+
+```ts
+// src/lib/auth-client.ts
+import { createAuthClient } from "better-auth/react";
+import { organizationClient, adminClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [organizationClient(), adminClient()],
+});
+
+export const { useSession, signIn, signUp, signOut } = authClient;
+```
+
+## API Route Handler
+
+```ts
+// src/app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+## Session Management
+
+### Server-Side Session
+
+```ts
+// src/lib/auth-server.ts
+import { auth } from "@/lib/auth";
+import { headers } from "next/headers";
+
+export async function getCurrentUser() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+  return session?.user ?? null;
+}
+
+export async function requireAuth() {
+  const user = await getCurrentUser();
+  if (!user) redirect("/login");
+  return user;
+}
+```
+
+### Client-Side Session
+
+```tsx
+"use client";
+import { useSession } from "@/lib/auth-client";
+
+export function UserMenu() {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) return <Skeleton />;
+  if (!session) return <LoginButton />;
+
+  return <span>{session.user.name}</span>;
+}
+```
+
+## Authentication Flows
+
+### Sign Up
+
+```tsx
+"use client";
+import { authClient } from "@/lib/auth-client";
+
+async function handleSignUp(data: SignUpInput) {
+  const { error } = await authClient.signUp.email({
+    email: data.email,
+    password: data.password,
+    name: data.name,
+  });
+  if (error) toast.error(error.message);
+  else router.push("/dashboard");
+}
+```
+
+### Social Login
+
+```tsx
+async function handleGoogleLogin() {
+  await authClient.signIn.social({ provider: "google" });
+}
+```
+
+### Sign Out
+
+```tsx
+async function handleSignOut() {
+  await authClient.signOut();
+  router.push("/");
+}
+```
+
+## Middleware
+
+```ts
+// middleware.ts
+import { betterFetch } from "@better-fetch/fetch";
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { Session } from "better-auth/types";
+
+const publicRoutes = ["/", "/login", "/register", "/api/auth"];
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Skip public routes
+  if (publicRoutes.some((r) => pathname.startsWith(r))) {
+    return NextResponse.next();
+  }
+
+  // Check session
+  const { data: session } = await betterFetch<Session>(
+    "/api/auth/get-session",
+    {
+      baseURL: request.nextUrl.origin,
+      headers: { cookie: request.headers.get("cookie") ?? "" },
+    }
+  );
+
+  if (!session) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+
+  // Admin route protection
+  if (pathname.startsWith("/admin") && session.user.role !== "admin") {
+    return NextResponse.redirect(new URL("/", request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+## Organization Plugin
+
+```tsx
+// Create organization
+const { data: org } = await authClient.organization.create({
+  name: "Acme Inc",
+  slug: "acme",
+});
+
+// Invite member
+await authClient.organization.inviteMember({
+  email: "user@example.com",
+  role: "member",
+  organizationId: org.id,
+});
+
+// Switch active organization
+await authClient.organization.setActive({ organizationId: org.id });
+```