@folpe/loom 0.1.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,14 +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
 model: claude-opus-4-6
 ---
 
@@ -29,13 +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, security analysis, performance audits, and best-practice enforcement.
+{{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

@@ -0,0 +1,37 @@
+name: API Backend
+description: API / service backend avec focus sécurité, validation, tests et performance.
+agents:
+  - orchestrator
+  - backend
+  - database
+  - security
+  - tests
+  - review-qa
+  - performance
+skills:
+  - nextjs-conventions
+  - supabase-patterns
+  - api-design
+constitution:
+  principles:
+    - Security first — validate all inputs, sanitize all outputs
+    - Type-safe contracts — use Zod schemas as single source of truth
+    - Test everything — unit tests for logic, integration tests for endpoints
+    - Fail gracefully — meaningful error messages, proper HTTP status codes
+  stack:
+    - Next.js 16+ (API Routes)
+    - TypeScript 5 (strict)
+    - Supabase (database + auth)
+    - Zod (validation)
+    - Vercel (deployment)
+  conventions:
+    - Define Zod schemas for all request/response payloads
+    - Use middleware for auth, rate limiting, and CORS
+    - Implement proper error handling with consistent error response format
+    - Write integration tests for every endpoint
+    - Use database transactions for multi-step mutations
+claudemd:
+  projectDescription: >
+    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.

package/data/presets/chrome-extension.yaml

@@ -0,0 +1,36 @@
+name: Chrome Extension
+description: Extension Chrome (Manifest V3) avec popup React, content scripts et background workers.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - tests
+  - security
+  - review-qa
+skills:
+  - tailwind-patterns
+  - chrome-extension-patterns
+  - ui-ux-guidelines
+constitution:
+  principles:
+    - Minimal permissions — request only what the extension truly needs
+    - User privacy first — never collect data without explicit consent
+    - Fast popup — keep popup UI snappy, defer heavy work to background
+    - Cross-site safe — sanitize all DOM manipulation in content scripts
+  stack:
+    - TypeScript 5 (strict)
+    - Chrome APIs (Manifest V3)
+    - React 19 (popup / options page)
+    - Tailwind CSS 4
+    - tsup (bundling)
+  conventions:
+    - Use Manifest V3 service workers instead of background pages
+    - Separate concerns — popup, content scripts, and background have clear boundaries
+    - Use chrome.storage API for persistence, never localStorage in content scripts
+    - Validate all messages between content script and background worker
+    - Keep content script injection minimal to avoid page performance impact
+claudemd:
+  projectDescription: >
+    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.

package/data/presets/cli-tool.yaml

@@ -0,0 +1,31 @@
+name: CLI Tool
+description: Outil CLI Node.js avec parsing d'arguments, UX terminal soignée et distribution npm.
+agents:
+  - orchestrator
+  - backend
+  - tests
+  - review-qa
+skills:
+  - cli-development
+constitution:
+  principles:
+    - Unix philosophy — do one thing well, compose with other tools
+    - Fail loudly — clear error messages with actionable suggestions
+    - Zero-config defaults — sensible defaults, override with flags
+    - Scriptable — support stdin/stdout piping and non-interactive mode
+  stack:
+    - TypeScript 5 (strict)
+    - Node.js 20+
+    - Commander.js (CLI framework)
+    - tsup (bundling)
+  conventions:
+    - Use Commander.js for argument parsing and subcommands
+    - Exit with proper codes — 0 for success, 1 for errors, 2 for usage errors
+    - Support --json flag for machine-readable output
+    - Use stderr for progress/logging, stdout for actual output
+    - Include a --version and --help flag on every command
+claudemd:
+  projectDescription: >
+    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.

package/data/presets/e-commerce.yaml

@@ -0,0 +1,49 @@
+name: E-Commerce
+description: Boutique en ligne avec catalogue, panier, checkout Stripe et emails transactionnels.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - database
+  - security
+  - tests
+  - review-qa
+  - ux-ui
+  - performance
+  - marketing
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - hero-copywriting
+  - supabase-patterns
+  - stripe-integration
+  - shadcn-ui
+  - seo-optimization
+  - api-design
+  - ui-ux-guidelines
+constitution:
+  principles:
+    - Trust through UX — clear pricing, no surprise fees, transparent shipping
+    - 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:
+  projectDescription: >
+    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.

package/data/presets/expo-mobile.yaml

@@ -0,0 +1,41 @@
+name: Expo Mobile
+description: App mobile React Native avec Expo, navigation, notifications push et offline-first.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - database
+  - tests
+  - review-qa
+  - ux-ui
+  - performance
+skills:
+  - tailwind-patterns
+  - react-native-patterns
+  - supabase-patterns
+  - ui-ux-guidelines
+constitution:
+  principles:
+    - Native feel — respect platform conventions (iOS HIG, Material Design)
+    - 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:
+  projectDescription: >
+    This is a mobile application scaffolded with Loom 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.

package/data/presets/fullstack-auth.yaml

@@ -0,0 +1,45 @@
+name: Fullstack Auth
+description: SaaS avec authentification complète (email, OAuth, magic link), RBAC et dashboard admin.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - database
+  - security
+  - tests
+  - review-qa
+  - ux-ui
+  - performance
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - supabase-patterns
+  - shadcn-ui
+  - api-design
+  - ui-ux-guidelines
+constitution:
+  principles:
+    - Auth is infrastructure — get it right once, never cut corners on security
+    - 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:
+  projectDescription: >
+    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.

package/data/presets/landing-page.yaml

@@ -0,0 +1,38 @@
+name: Landing Page
+description: Site vitrine / marketing avec focus SEO, conversion, animations et responsive design.
+agents:
+  - orchestrator
+  - frontend
+  - ux-ui
+  - marketing
+  - performance
+  - review-qa
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - hero-copywriting
+  - seo-optimization
+  - ui-ux-guidelines
+constitution:
+  principles:
+    - Conversion-first — every section must guide visitors toward a clear CTA
+    - 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:
+  projectDescription: >
+    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.

package/data/presets/mvp-lean.yaml

@@ -0,0 +1,35 @@
+name: MVP Lean
+description: Prototype rapide avec stack minimale. Vitesse et itération avant la perfection.
+agents:
+  - orchestrator
+  - frontend
+  - backend
+  - database
+skills:
+  - nextjs-conventions
+  - tailwind-patterns
+  - supabase-patterns
+constitution:
+  principles:
+    - Ship it — working software over perfect architecture
+    - 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:
+  projectDescription: >
+    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.

package/data/presets/saas-default.yaml

@@ -1,10 +1,6 @@
-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.
-boilerplate:
-  repo: https://github.com/vercel/next.js.git
-  branch: canary
-  shallow: true
 agents:
   - orchestrator
   - frontend
@@ -20,6 +16,12 @@ skills:
   - nextjs-conventions
   - tailwind-patterns
   - hero-copywriting
+  - supabase-patterns
+  - shadcn-ui
+  - api-design
+  - ui-ux-guidelines
+  - stripe-integration
+  - seo-optimization
 constitution:
   principles:
     - Ship fast, iterate often — prefer working software over perfect plans
@@ -45,9 +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.
-specKit:
-  enabled: true
-  aiFlag: claude

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).