@folpe/loom 0.2.0 → 0.3.0

package/data/skills/form-validation/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: form-validation
+description: "Zod dual validation patterns for client and server with react-hook-form and ShadCN Form. Use when building forms, implementing validation, or creating input schemas with i18n error messages."
+---
+
+# Form Validation Patterns
+
+## Critical Rules
+
+- **One Zod schema, two validations** — share between client and server.
+- **Schema files in `src/schemas/`** — never inline schemas in components.
+- **Use ShadCN Form components** — `FormField`, `FormMessage` for consistent UX.
+- **Always show inline errors** — next to the field, not in toasts.
+- **Disable submit while pending** — prevent double submissions.
+- **Default values required** — every field needs a `defaultValues` entry in useForm.
+
+## Dual Validation Strategy
+
+Every form must validate on **both client and server**:
+- **Client**: instant feedback, UX quality.
+- **Server**: security, data integrity — never trust client validation alone.
+
+Use a single Zod schema shared between client and server.
+
+## Shared Schema Definition
+
+```ts
+// src/schemas/user.schema.ts
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters").max(100),
+  email: z.string().email("Invalid email address"),
+  role: z.enum(["USER", "ADMIN"]).default("USER"),
+  bio: z.string().max(500).optional(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+
+## Client-Side Validation with react-hook-form
+
+```tsx
+"use client";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { createUserSchema, type CreateUserInput } from "@/schemas/user.schema";
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+
+export function CreateUserForm() {
+  const form = useForm<CreateUserInput>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: { name: "", email: "", role: "USER" },
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl><Input {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {/* More fields... */}
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          Create
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Server-Side Validation
+
+```ts
+// src/actions/user.actions.ts
+"use server";
+import { createUserSchema } from "@/schemas/user.schema";
+
+export async function createUser(input: unknown) {
+  const parsed = createUserSchema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+  // proceed with validated data...
+}
+```
+
+## I18n Error Messages with Zod
+
+For internationalized error messages, use a Zod error map:
+
+```ts
+// src/lib/zod-i18n.ts
+import { z } from "zod";
+import { getTranslations } from "next-intl/server";
+
+export async function createI18nSchema() {
+  const t = await getTranslations("validation");
+
+  return {
+    createUser: z.object({
+      name: z.string().min(2, t("name.min", { min: 2 })),
+      email: z.string().email(t("email.invalid")),
+    }),
+  };
+}
+```
+
+Or use a custom error map:
+
+```ts
+// src/lib/zod-error-map.ts
+import { type ZodErrorMap, ZodIssueCode } from "zod";
+
+export function createZodErrorMap(t: (key: string, params?: Record<string, unknown>) => string): ZodErrorMap {
+  return (issue, ctx) => {
+    switch (issue.code) {
+      case ZodIssueCode.too_small:
+        return { message: t("too_small", { minimum: issue.minimum }) };
+      case ZodIssueCode.too_big:
+        return { message: t("too_big", { maximum: issue.maximum }) };
+      case ZodIssueCode.invalid_string:
+        if (issue.validation === "email") return { message: t("invalid_email") };
+        break;
+    }
+    return { message: ctx.defaultError };
+  };
+}
+```
+
+## Multi-Card Form Layout
+
+For complex forms, split into logical sections using Cards:
+
+```tsx
+<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+  <Card>
+    <CardHeader>
+      <CardTitle>Personal Information</CardTitle>
+    </CardHeader>
+    <CardContent className="grid gap-4 md:grid-cols-2">
+      {/* Name, Email fields */}
+    </CardContent>
+  </Card>
+
+  <Card>
+    <CardHeader>
+      <CardTitle>Preferences</CardTitle>
+    </CardHeader>
+    <CardContent className="space-y-4">
+      {/* Role, Bio fields */}
+    </CardContent>
+  </Card>
+
+  <div className="flex justify-end">
+    <Button type="submit">Create User</Button>
+  </div>
+</form>
+```

package/data/skills/hero-copywriting/SKILL.md

@@ -1,14 +1,22 @@
 ---
 name: hero-copywriting
-description: "Guidelines for writing high-converting hero sections. Use when creating landing pages, marketing pages, or any page with a hero section."
-allowed-tools: "Read, Write, Edit"
+description: "Guidelines for writing high-converting hero sections with headlines, CTAs, and social proof. Use when creating landing pages, writing marketing copy, designing hero sections, or building any page that needs a compelling above-the-fold area."
 ---
 
 # Hero Section Copywriting
 
+## Critical Rules
+
+- **Lead with the outcome, not the feature** — what does the user GET?
+- **Headlines must be 8-12 words maximum** — short, punchy, outcome-focused.
+- **CTA must use action verbs** — "Start", "Get", "Try", "Launch", "Build".
+- **Always include social proof** — logos, metrics, ratings, or testimonials.
+- **Be specific over generic** — "Save 5 hours a week" beats "Save time".
+- **Speak to the reader directly** — use "you" and "your".
+
 ## Headline Rules
 
-- **Lead with the outcome**, not the feature. What does the user GET?
+- Lead with the outcome, not the feature. What does the user GET?
   - Bad: "AI-powered project management"
   - Good: "Ship projects 3x faster with your AI co-pilot"
 - Keep headlines to **8-12 words maximum**.
@@ -41,7 +49,7 @@ allowed-tools: "Read, Write, Edit"
 
 ## Visual Guidelines
 
-- Hero should occupy the full viewport height on desktop (`min-h-screen` or `min-h-[80vh]`).
+- Hero should occupy the full viewport height on desktop (`min-h-dvh` or `min-h-[80vh]`).
 - Text should be left-aligned or center-aligned. Never justify.
 - Maximum content width: `max-w-2xl` for centered, `max-w-xl` for left-aligned.
 - Generous whitespace. Don't crowd the hero.

package/data/skills/i18n-patterns/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: i18n-patterns
+description: "Internationalization with next-intl for RSC, Server Actions, and Zod messages. Use when adding multi-language support, translating user-facing strings, or implementing locale-aware validation."
+---
+
+# I18n Patterns
+
+## Critical Rules
+
+- **All user-facing strings must be translated** — no hardcoded text in components.
+- **Use namespaces** — group translations by feature/page.
+- **Server-side `getTranslations`** — use in RSC and Server Actions.
+- **Client-side `useTranslations`** — use in Client Components only.
+- **Validation messages are translated** — use i18n error map with Zod.
+- **ICU message syntax** for plurals and interpolation: `"{count, plural, one {# item} other {# items}}"`.
+
+## Setup with next-intl
+
+### Configuration
+
+```ts
+// src/i18n/config.ts
+export const locales = ["en", "fr", "de"] as const;
+export type Locale = (typeof locales)[number];
+export const defaultLocale: Locale = "en";
+```
+
+### Message Files
+
+```
+messages/
+  en.json
+  fr.json
+  de.json
+```
+
+Structure messages by namespace:
+
+```json
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "loading": "Loading..."
+  },
+  "auth": {
+    "login": "Sign in",
+    "logout": "Sign out",
+    "register": "Create account"
+  },
+  "users": {
+    "title": "Users",
+    "create": "Create user",
+    "name": "Name",
+    "email": "Email"
+  },
+  "validation": {
+    "required": "This field is required",
+    "email.invalid": "Please enter a valid email",
+    "too_small": "Must be at least {minimum} characters",
+    "too_big": "Must be at most {maximum} characters"
+  }
+}
+```
+
+## Server Components (RSC)
+
+```tsx
+import { getTranslations } from "next-intl/server";
+
+export default async function UsersPage() {
+  const t = await getTranslations("users");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <Button>{t("create")}</Button>
+    </div>
+  );
+}
+```
+
+## Client Components
+
+```tsx
+"use client";
+import { useTranslations } from "next-intl";
+
+export function UserForm() {
+  const t = useTranslations("users");
+
+  return <label>{t("name")}</label>;
+}
+```
+
+## Server Actions with I18n
+
+Pass locale context to server actions for localized error messages:
+
+```ts
+// src/actions/user.actions.ts
+"use server";
+import { getLocale, getTranslations } from "next-intl/server";
+
+export async function createUser(input: unknown) {
+  const t = await getTranslations("validation");
+  const locale = await getLocale();
+
+  const schema = z.object({
+    name: z.string().min(2, t("too_small", { minimum: 2 })),
+    email: z.string().email(t("email.invalid")),
+  });
+
+  const parsed = schema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+  // ...
+}
+```
+
+## Zod Validation with I18n
+
+### Custom Error Map
+
+```ts
+// src/lib/zod-i18n.ts
+import { z } from "zod";
+
+export function createI18nErrorMap(
+  t: (key: string, params?: Record<string, unknown>) => string
+): z.ZodErrorMap {
+  return (issue, ctx) => {
+    switch (issue.code) {
+      case z.ZodIssueCode.too_small:
+        if (issue.type === "string") {
+          return { message: t("too_small", { minimum: issue.minimum }) };
+        }
+        break;
+      case z.ZodIssueCode.too_big:
+        if (issue.type === "string") {
+          return { message: t("too_big", { maximum: issue.maximum }) };
+        }
+        break;
+      case z.ZodIssueCode.invalid_string:
+        if (issue.validation === "email") {
+          return { message: t("email.invalid") };
+        }
+        break;
+      case z.ZodIssueCode.invalid_type:
+        if (issue.received === "undefined") {
+          return { message: t("required") };
+        }
+        break;
+    }
+    return { message: ctx.defaultError };
+  };
+}
+```
+
+## Date and Number Formatting
+
+```tsx
+import { useFormatter } from "next-intl";
+
+function PriceDisplay({ amount }: { amount: number }) {
+  const format = useFormatter();
+  return <span>{format.number(amount, { style: "currency", currency: "EUR" })}</span>;
+}
+
+function DateDisplay({ date }: { date: Date }) {
+  const format = useFormatter();
+  return <span>{format.dateTime(date, { dateStyle: "medium" })}</span>;
+}
+```

package/data/skills/layered-architecture/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: layered-architecture
+description: "Enforces strict layered architecture: Presentation → Facade → Service → DAL → Persistence. Use when structuring a Next.js application, creating new features with separation of concerns, or refactoring code into layers."
+---
+
+# Layered Architecture
+
+Strict separation of concerns across five layers. Each layer only calls the layer directly below it.
+
+## Critical Rules
+
+- **Never skip layers** — presentation must not call services directly.
+- **No business logic in facades** — they coordinate, not decide.
+- **No auth checks in DAL** — DAL is purely data access.
+- **No database calls in services** — services call DAL.
+- **Functional style** — pure functions, no classes, prefer composition over inheritance.
+- **Top-down design** — keep functions short, extract when >100 lines.
+
+## Layer Overview
+
+```
+Presentation (RSC / Client Components)
+    ↓
+Facade (entry point for business logic)
+    ↓
+Service (business rules, authorization)
+    ↓
+DAL — Data Access Layer (queries, data shaping)
+    ↓
+Persistence (Drizzle ORM / database)
+```
+
+## Presentation Layer
+
+- React Server Components and Client Components live here.
+- Components call **facades only** — never services or DAL directly.
+- RSC by default. Only add `"use client"` when strictly needed (hooks, events, browser APIs).
+- Top-down design: if a component exceeds ~100 lines, extract sub-functions/sub-components.
+- Functional over OOP — pure functions, composition, immutability.
+
+```tsx
+// app/(app)/users/page.tsx — Presentation
+import { getUserList } from "@/facades/user.facade";
+
+export default async function UsersPage() {
+  const users = await getUserList();
+  return <UserTable users={users} />;
+}
+```
+
+## Facade Layer
+
+- Entry points for business logic. One facade per domain entity.
+- Located in `src/facades/` — files named `{entity}.facade.ts`.
+- Facades orchestrate service calls and transform data for the presentation.
+- Facades handle auth context extraction and pass it down.
+- Never contain business logic — only coordination.
+
+```ts
+// src/facades/user.facade.ts
+import { getCurrentUser } from "@/lib/auth";
+import { listUsers, createUser } from "@/services/user.service";
+
+export async function getUserList() {
+  const currentUser = await getCurrentUser();
+  return listUsers(currentUser);
+}
+```
+
+## Service Layer
+
+- Contains all business rules and authorization checks.
+- Located in `src/services/` — files named `{entity}.service.ts`.
+- Services receive the auth context as parameter — never fetch it themselves.
+- CASL authorization checks happen here.
+- Services call DAL functions for data access.
+
+```ts
+// src/services/user.service.ts
+import { ForbiddenError } from "@casl/ability";
+import { defineAbilityFor } from "@/lib/casl";
+import { findAllUsers } from "@/dal/user.dal";
+
+export async function listUsers(currentUser: AuthUser) {
+  const ability = defineAbilityFor(currentUser);
+  ForbiddenError.from(ability).throwUnlessCan("read", "User");
+  return findAllUsers();
+}
+```
+
+## Data Access Layer (DAL)
+
+- Pure data access — no business logic, no authorization.
+- Located in `src/dal/` — files named `{entity}.dal.ts`.
+- DAL functions shape data: select specific columns, join relations, paginate.
+- Always return typed results — never raw query results.
+
+```ts
+// src/dal/user.dal.ts
+import { db } from "@/lib/db";
+import { users } from "@/schema";
+
+export async function findAllUsers() {
+  return db.select({
+    id: users.id,
+    name: users.name,
+    email: users.email,
+    role: users.role,
+  }).from(users);
+}
+```
+
+## Persistence Layer
+
+- Drizzle ORM schema definitions and database client.
+- Located in `src/schema/` for table definitions, `src/lib/db.ts` for the client.
+- Schema-only — no query logic here.
+
+## File Naming Convention
+
+```
+src/
+  facades/         # {entity}.facade.ts
+  services/        # {entity}.service.ts
+  dal/             # {entity}.dal.ts
+  schema/          # {entity}.ts (Drizzle table defs)
+  lib/db.ts        # Database client
+```
+
+- All new files use **kebab-case**.
+- One file per entity per layer — avoid catch-all files.

package/data/skills/nextjs-conventions/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: nextjs-conventions
-description: "Enforces Next.js 15+ / React 19 / TypeScript conventions and best practices. Use when working on any Next.js project to ensure consistent patterns."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "Next.js 15+ / React 19 / TypeScript conventions for App Router, RSC, route groups, and file naming. Use when creating pages, components, layouts, or structuring a Next.js application."
 ---
 
 # Next.js Conventions
 
+## Critical Rules
+
+- **RSC by default** — only add `"use client"` when strictly needed.
+- **Functional over OOP** — pure functions, composition, immutability. Never class components.
+- **kebab-case for all new files** — `user-profile.tsx`, `format-date.ts`.
+- **Top-down design** — extract sub-functions/sub-components when >100 lines.
+- **Never use `any`** — use `unknown` if the type is truly unknown.
+
 ## App Router
 
 - Use the App Router (`src/app/`) exclusively. Never use the Pages Router.
@@ -13,14 +20,39 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Use `loading.tsx` for Suspense boundaries and `error.tsx` for error boundaries.
 - Use `not-found.tsx` for 404 pages at the appropriate route level.
 
+## Route Groups
+
+Organize routes by access level using route groups:
+
+```
+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/
+```
+
+- `(public)` routes are accessible without authentication.
+- `(auth)` routes require a session but no specific role.
+- `(app)` routes require an active, verified user.
+- `admin` routes require admin role — not a route group so the URL reflects `/admin/`.
+
 ## Server vs Client Components
 
-- **Default to Server Components**. Only add `"use client"` when you need:
+- **RSC by default**. Only add `"use client"` when strictly needed:
   - Event handlers (`onClick`, `onChange`, etc.)
   - React hooks (`useState`, `useEffect`, `useRef`, etc.)
   - Browser-only APIs (`window`, `localStorage`, etc.)
 - Never import server-only modules in client components.
 - Pass server data to client components via props, not by importing server functions.
+- Wrap async data in `<Suspense>` boundaries for streaming and progressive rendering.
 
 ## Data Fetching
 
@@ -31,10 +63,10 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 ## File Naming
 
-- Components: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
-- Utilities: `kebab-case.ts` (e.g., `format-date.ts`)
-- Types: define in `src/types/` with `.ts` extension
-- Server Actions: `src/actions/{entity}.actions.ts`
+- **All new files: `kebab-case`** (e.g., `user-profile.tsx`, `format-date.ts`).
+- Types: define in `src/types/` with `.ts` extension.
+- Server Actions: `src/actions/{entity}.actions.ts`.
+- Schemas: `src/schemas/{entity}.schema.ts`.
 
 ## TypeScript
 
@@ -62,3 +94,10 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Use `next/link` for internal navigation. Never use `<a>` for internal links.
 - Use `next/font` for font loading.
 - Lazy load heavy client components with `dynamic()` from `next/dynamic`.
+
+## Code Design
+
+- **Functional over OOP** — pure functions, composition, immutability. Never use class components.
+- **Top-down design** — if a function or component exceeds ~100 lines, extract sub-functions or sub-components.
+- Prefer named exports over default exports (except for page/layout components).
+- Group imports: React/Next.js first, then external libs, then internal modules.

package/data/skills/react-native-patterns/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: react-native-patterns
-description: "React Native and Expo best practices for navigation, styling, performance, and native features. Use when building mobile apps with Expo. Inspired by callstackincubator/agent-skills and expo/skills."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "React Native and Expo best practices for navigation, styling, performance, and native features. Use when building mobile apps with Expo, implementing React Native navigation, styling with NativeWind, optimizing mobile performance, or adding push notifications."
 ---
 
 # React Native & Expo Patterns
 
+## Critical Rules
+
+- **Always try Expo Go first** — only use `npx expo run:ios/android` when custom native modules are required.
+- **Functional components only** — never class components.
+- **Use `expo-image` instead of React Native's `Image`** — better caching and performance.
+- **Use `react-native-safe-area-context`** — never React Native's built-in `SafeAreaView`.
+- **Use `FlashList` instead of `FlatList`** for large lists — significantly better performance.
+- **Never block the JS thread** — target 60fps, offload heavy computation to native.
+
 ## Expo Router
 
 - Use file-based routing in the `app/` directory exclusively.
@@ -23,12 +31,6 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Prefer `useWindowDimensions` over `Dimensions.get()` for responsive layouts.
 - Use flexbox exclusively for layout — avoid absolute positioning except for overlays.
 
-## Running the App
-
-- **Always try Expo Go first** before creating custom builds (`npx expo start`).
-- Only use `npx expo run:ios/android` when custom native modules are required.
-- Expo Go supports: all `expo-*` packages, Expo Router, Reanimated, Gesture Handler.
-
 ## Components
 
 - Use functional components only — never class components.