@folpe/loom 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 CLI to scaffold Claude Code projects with curated agents, skills, and presets.
 
-Loom provides a ready-to-use library of specialized AI agents (frontend, backend, security, tests...) and skills (Next.js conventions, Tailwind patterns...) that integrate directly into your project's `.claude/` directory.
+Loom provides a ready-to-use library of **10 specialized agents**, **24 skills**, and **10 presets** that integrate directly into your project's `.claude/` directory — giving Claude Code deep expertise on your stack from day one.
 
 ## Install
 
@@ -12,7 +12,36 @@ npm i -g @folpe/loom
 
 ## Usage
 
-### List available agents, skills, and presets
+### Initialize a project (interactive)
+
+```bash
+loom init
+```
+
+Launches an interactive wizard: pick a preset, toggle agents, toggle skills, and generate everything.
+
+### Initialize from a preset
+
+```bash
+loom init saas-default
+loom init saas-full
+```
+
+### Customize with flags
+
+```bash
+loom init saas-default --remove-agent marketing --add-skill stripe-integration
+loom init mvp-lean --add-agent security --add-skill auth-rbac
+```
+
+| Flag | Description |
+|------|-------------|
+| `--add-agent <slugs...>` | Add extra agents to the preset |
+| `--remove-agent <slugs...>` | Remove agents from the preset |
+| `--add-skill <slugs...>` | Add extra skills |
+| `--remove-skill <slugs...>` | Remove skills |
+
+### List available resources
 
 ```bash
 loom list           # list everything
@@ -30,19 +59,9 @@ loom add skill tailwind-patterns
 
 Files are written to `.claude/agents/` and `.claude/skills/` in your current directory.
 
-### Initialize a full project from a preset
-
-```bash
-loom init saas-default
-```
-
-A preset installs a set of agents + skills and generates a `CLAUDE.md` configuration file — everything Claude Code needs to work with your project.
-
-Run `loom init` without arguments to choose interactively.
-
 ## What's included
 
-**Agents** — specialized AI roles, each with a focused system prompt:
+### Agents
 
 | Agent | Role |
 |-------|------|
@@ -57,13 +76,60 @@ Run `loom init` without arguments to choose interactively.
 | `ux-ui` | UI components, design systems |
 | `marketing` | Copy, landing pages, SEO |
 
-**Skills** — reusable knowledge files:
+### Skills
 
 | Skill | Description |
 |-------|-------------|
 | `nextjs-conventions` | Next.js 15+ / React 19 / TypeScript patterns |
-| `tailwind-patterns` | Tailwind CSS utilities and component patterns |
-| `hero-copywriting` | High-converting marketing copy guidelines |
+| `tailwind-patterns` | Tailwind CSS utilities and responsive design |
+| `shadcn-ui` | ShadCN UI components, forms, data tables |
+| `api-design` | REST API design, validation, error handling |
+| `supabase-patterns` | Supabase auth, RLS, storage, real-time |
+| `ui-ux-guidelines` | Accessibility, interaction, typography, color |
+| `layered-architecture` | Presentation → Facade → Service → DAL → Persistence |
+| `drizzle-patterns` | Drizzle ORM schemas, migrations, queries |
+| `server-actions-patterns` | Safe Server Actions with wrappers and validation |
+| `form-validation` | Zod dual validation (client + server) |
+| `auth-rbac` | CASL authorization with role hierarchy |
+| `i18n-patterns` | next-intl internationalization patterns |
+| `testing-patterns` | Vitest role-based testing strategy |
+| `resend-email` | Resend + React Email transactional emails |
+| `react-query-patterns` | TanStack React Query data fetching |
+| `table-pagination` | Server-side pagination with URL state |
+| `env-validation` | Zod environment variable validation |
+| `better-auth-patterns` | Better Auth setup with organizations |
+| `stripe-integration` | Stripe checkout, subscriptions, webhooks |
+| `hero-copywriting` | High-converting hero section copy |
+| `seo-optimization` | Meta tags, JSON-LD, Core Web Vitals |
+| `chrome-extension-patterns` | Manifest V3, content scripts, service workers |
+| `cli-development` | Node.js CLI with Commander.js |
+| `react-native-patterns` | React Native / Expo mobile patterns |
+
+### Presets
+
+| Preset | Agents | Skills | Best for |
+|--------|--------|--------|----------|
+| `saas-full` | 10 | 21 | Full SaaS with auth, billing, i18n, testing |
+| `saas-default` | 10 | 7 | Standard SaaS starter |
+| `fullstack-auth` | 9 | 6 | Fullstack app with authentication |
+| `e-commerce` | 10 | 9 | Online store with payments |
+| `api-backend` | 7 | 3 | Backend API service |
+| `expo-mobile` | 8 | 4 | Mobile app with Expo |
+| `landing-page` | 6 | 5 | Marketing landing page |
+| `chrome-extension` | 6 | 3 | Browser extension |
+| `mvp-lean` | 4 | 3 | Minimal viable product |
+| `cli-tool` | 4 | 1 | Command-line tool |
+
+## How it works
+
+Running `loom init <preset>` generates:
+
+- `.claude/agents/*.md` — one file per agent with system prompt and skills
+- `.claude/skills/*.md` — reusable knowledge files loaded contextually
+- `.claude/orchestrator.md` — dynamic orchestrator aware of all active agents
+- `CLAUDE.md` — project-level config with stack, conventions, and principles
+
+Claude Code reads these files automatically. The orchestrator delegates tasks to the right specialized agent, and each agent loads only the skills it needs.
 
 ## License
 

package/data/agents/backend/AGENT.md

@@ -10,6 +10,18 @@ tools:
   - Edit
   - Glob
   - Grep
+skills:
+  - supabase-patterns
+  - api-design
+  - nextjs-conventions
+  - layered-architecture
+  - server-actions-patterns
+  - drizzle-patterns
+  - auth-rbac
+  - i18n-patterns
+  - env-validation
+  - resend-email
+  - better-auth-patterns
 model: claude-sonnet-4-6
 ---
 

package/data/agents/database/AGENT.md

@@ -8,6 +8,9 @@ tools:
   - Read
   - Write
   - Edit
+skills:
+  - supabase-patterns
+  - drizzle-patterns
 model: claude-sonnet-4-6
 ---
 

package/data/agents/frontend/AGENT.md

@@ -10,6 +10,16 @@ tools:
   - Edit
   - Glob
   - Grep
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - shadcn-ui
+  - layered-architecture
+  - server-actions-patterns
+  - form-validation
+  - i18n-patterns
+  - react-query-patterns
+  - table-pagination
 model: claude-sonnet-4-6
 ---
 # Frontend Agent

package/data/agents/marketing/AGENT.md

@@ -7,6 +7,9 @@ tools:
   - Read
   - Write
   - Edit
+skills:
+  - hero-copywriting
+  - seo-optimization
 model: claude-sonnet-4-6
 ---
 

package/data/agents/orchestrator/AGENT.md

@@ -4,16 +4,6 @@ description: Main coordinator that analyzes tasks and delegates to specialized a
 role: orchestrator
 color: "#8B5CF6"
 tools: []
-delegates-to:
-  - frontend
-  - backend
-  - marketing
-  - ux-ui
-  - database
-  - tests
-  - review-qa
-  - security
-  - performance
 model: claude-opus-4-6
 ---
 
@@ -31,15 +21,7 @@ You are the central coordinator for the Loom project. Your job is to understand
 
 ## Delegation Rules
 
-- **frontend**: Any work involving React components, Next.js pages, layouts, client-side state, or browser-side rendering.
-- **backend**: API routes, server actions, authentication flows, server-side business logic, third-party service integrations.
-- **marketing**: Marketing copy, landing page content, email templates, SEO metadata, blog posts, and promotional text.
-- **ux-ui**: UI component design, design tokens, color palettes, spacing systems, accessibility audits, and responsive design patterns.
-- **database**: Schema design, migrations, seed data, query optimization, and ORM configuration.
-- **tests**: Unit tests, integration tests, end-to-end tests, and test infrastructure setup.
-- **review-qa**: Code review, best-practice enforcement, and comprehensive quality audits.
-- **security**: Security audits, vulnerability assessments, OWASP compliance, auth hardening, dependency scanning, and RLS policy review.
-- **performance**: Performance optimization, Core Web Vitals audits, bundle analysis, Lighthouse runs, query optimization, and rendering profiling.
+{{DELEGATION_RULES}}
 
 ## Workflow Guidelines
 

package/data/agents/security/AGENT.md

@@ -9,6 +9,9 @@ tools:
   - Edit
   - Glob
   - Grep
+skills:
+  - auth-rbac
+  - better-auth-patterns
 model: claude-sonnet-4-6
 ---
 

package/data/agents/tests/AGENT.md

@@ -10,6 +10,8 @@ tools:
   - Edit
   - Glob
   - Grep
+skills:
+  - testing-patterns
 model: claude-sonnet-4-6
 ---
 

package/data/agents/ux-ui/AGENT.md

@@ -9,6 +9,11 @@ tools:
   - Edit
   - Glob
   - Grep
+skills:
+  - ui-ux-guidelines
+  - shadcn-ui
+  - tailwind-patterns
+  - table-pagination
 model: claude-sonnet-4-6
 ---
 

package/data/presets/api-backend.yaml

@@ -35,6 +35,3 @@ claudemd:
     This is a backend API service scaffolded with Loom. It uses Next.js API Routes with Supabase
     as the database layer. The orchestrator delegates security concerns to the security agent,
     database schema work to the database agent, and 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/chrome-extension.yaml

@@ -34,6 +34,3 @@ claudemd:
     This is a Chrome extension scaffolded with Loom using Manifest V3. The orchestrator delegates
     popup/options UI work to the frontend agent, background worker logic to the backend agent,
     and security reviews of permissions and content scripts to the security 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/cli-tool.yaml

@@ -29,6 +29,3 @@ claudemd:
     This is a CLI tool scaffolded with Loom. It uses Commander.js for argument parsing and tsup
     for bundling. The orchestrator delegates implementation to the backend agent and 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/e-commerce.yaml

@@ -47,6 +47,3 @@ claudemd:
     This is an e-commerce application scaffolded with Loom. 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

@@ -39,6 +39,3 @@ claudemd:
     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

@@ -43,6 +43,3 @@ claudemd:
     This is a fullstack SaaS with complete authentication scaffolded with Loom. 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

@@ -36,6 +36,3 @@ claudemd:
     This is a landing page / marketing site scaffolded with Loom. 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

@@ -33,6 +33,3 @@ claudemd:
     This is a lean MVP scaffolded with Loom. 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,6 +20,8 @@ skills:
   - shadcn-ui
   - api-design
   - ui-ux-guidelines
+  - stripe-integration
+  - seo-optimization
 constitution:
   principles:
     - Ship fast, iterate often — prefer working software over perfect plans
@@ -45,6 +47,3 @@ claudemd:
     This is a SaaS application scaffolded with Loom. 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,71 @@
+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
+  stack:
+    - Next.js 16+ (App Router)
+    - React 19
+    - TypeScript 5 (strict)
+    - Tailwind CSS 4
+    - ShadCN UI
+    - Drizzle ORM
+    - PostgreSQL
+    - Better Auth
+    - Stripe
+    - Resend
+    - Vitest
+    - Vercel
+  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
+claudemd:
+  projectDescription: >
+    This is a full-featured SaaS application scaffolded with Loom. 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 };
+}
+```