@husnudarici/claude-kit 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 husnudarici
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,13 @@
-# claude-kit
+# @husnudarici/claude-kit
 
 Scaffold a complete `.claude/` folder structure for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) projects with one command.
 
-Sets up agents, commands, hooks, rules, skills, and settings so Claude Code works exactly the way you want.
+Sets up agents, commands, hooks, rules, skills, and settings so Claude Code works exactly the way you want -- optimized for SaaS developers building Web, Android, and iOS apps.
 
 ## Quick Start
 
 ```bash
-npx claude-kit init
+npx @husnudarici/claude-kit init
 ```
 
 That's it. Your `.claude/` folder is ready.
@@ -16,35 +16,50 @@ That's it. Your `.claude/` folder is ready.
 
 ```
 .claude/
-├── agents/                 # Custom AI agents
-│   ├── code-reviewer.md    # Reviews PRs for bugs, security, performance
-│   ├── debugger.md         # Systematic bug diagnosis
-│   ├── test-writer.md      # Generates comprehensive test suites
-│   ├── refactorer.md       # Improves code structure safely
-│   ├── doc-writer.md       # Generates documentation from code
-│   └── security-auditor.md # OWASP-based security audits
-├── commands/               # One-word automations (/deploy, /fix-issue)
-│   ├── fix-issue.md        # Diagnose and fix GitHub issues
-│   ├── deploy.md           # Deploy to production with all checks
-│   └── pr-review.md        # Thorough PR review workflow
-├── hooks/                  # Auto-run scripts
-│   ├── pre-commit.sh       # Type check + lint + test before commit
-│   └── lint-on-save.sh     # Auto-lint after every file edit
-├── rules/                  # Guardrails scoped to file patterns
-│   ├── frontend.md         # React/Next.js component standards
-│   ├── database.md         # Query safety and migration rules
-│   └── api.md              # API route validation and error handling
-├── skills/                 # Reusable capability bundles
-│   └── frontend-design/
-│       └── SKILL.md        # Design system enforcement
-└── settings.json           # Permissions, model, hooks config
-CLAUDE.md                   # Project brain -- root context file
+├── agents/                    # Custom AI agents
+│   ├── code-reviewer.md       # Reviews PRs for bugs, security, performance
+│   ├── debugger.md            # Systematic bug diagnosis
+│   ├── test-writer.md         # Generates comprehensive test suites
+│   ├── refactorer.md          # Improves code structure safely
+│   ├── doc-writer.md          # Generates documentation from code
+│   ├── security-auditor.md    # OWASP-based security audits
+│   ├── frontend-developer.md  # Builds complete UI features autonomously
+│   ├── backend-helper.md      # Backend work with simple explanations
+│   ├── mobile-developer.md    # Cross-platform Android & iOS development
+│   └── reverse-engineer.md    # Analyzes competitors and libraries
+├── commands/                  # One-word automations
+│   ├── fix-issue.md           # Diagnose and fix GitHub issues
+│   ├── deploy.md              # Deploy to production with all checks
+│   ├── pr-review.md           # Thorough PR review workflow
+│   └── new-saas-feature.md    # Build a full SaaS feature end-to-end
+├── hooks/                     # Auto-run scripts
+│   ├── pre-commit.sh          # Type check + lint + test before commit
+│   └── lint-on-save.sh        # Auto-lint after every file edit
+├── rules/                     # Guardrails scoped to file patterns
+│   ├── frontend.md            # Component structure, styling, performance, a11y
+│   ├── database.md            # Query safety and migration rules
+│   ├── api.md                 # API route validation and error handling
+│   ├── mobile.md              # Mobile app platform rules
+│   └── saas.md                # SaaS patterns (auth, billing, onboarding)
+├── skills/                    # Reusable capability bundles
+│   ├── frontend-design/
+│   │   └── SKILL.md           # Design system enforcement
+│   └── saas-patterns/
+│       └── SKILL.md           # SaaS UI/UX patterns
+└── settings.json              # Permissions, model, hooks config
+CLAUDE.md                      # Project brain -- root context file
 ```
 
 ## Features
 
-### Agents
+### Agents (10)
+
 Custom AI teammates that handle specific tasks autonomously:
+
+- **frontend-developer** -- Builds complete UI features; you review, it codes
+- **backend-helper** -- Builds APIs and DB schemas, explains everything simply for frontend devs
+- **mobile-developer** -- Cross-platform Android & iOS with React Native / Expo
+- **reverse-engineer** -- Analyzes competitor apps, libraries, and npm packages
 - **code-reviewer** -- Reviews code for bugs, security issues, and performance
 - **debugger** -- Traces bugs systematically using evidence
 - **test-writer** -- Generates unit, integration, and edge case tests
@@ -52,42 +67,56 @@ Custom AI teammates that handle specific tasks autonomously:
 - **doc-writer** -- Creates clear documentation from code analysis
 - **security-auditor** -- Audits code following OWASP top 10
 
-### Commands
+### Commands (4)
+
 Slash commands that trigger multi-step workflows:
+
 - `/deploy` -- Full deployment with pre-flight checks and verification
 - `/fix-issue` -- End-to-end GitHub issue resolution
 - `/pr-review` -- Thorough pull request review
+- `/new-saas-feature` -- Plan and build a complete SaaS feature (DB + API + Web + Mobile)
+
+### Hooks (2)
+
+Shell scripts that auto-run after Claude's actions:
 
-### Hooks
-Shell scripts that auto-run before or after Claude's actions:
 - **pre-commit.sh** -- Blocks commits if types, lint, or tests fail
 - **lint-on-save.sh** -- Auto-lints files after every Edit/Write
 
-### Rules
+### Rules (5)
+
 Guardrails scoped to specific file patterns:
-- **frontend.md** -- Component patterns, styling, performance, a11y
+
+- **frontend.md** -- Feature-based component structure (enforced), styling, performance, a11y
 - **database.md** -- Query safety, migrations, RLS, performance
 - **api.md** -- Input validation, auth, error handling, rate limiting
+- **mobile.md** -- Navigation, safe areas, platform differences, offline, app store rules
+- **saas.md** -- Auth flows, subscription/billing, multi-tenancy, onboarding
+
+### Skills (2)
 
-### Skills
 Reusable capability bundles with prompts and triggers:
+
 - **frontend-design** -- Enforces design system (colors, typography, spacing)
+- **saas-patterns** -- SaaS UI patterns (pricing, dashboard, settings, onboarding, auth pages)
 
 ### Settings
+
 Pre-configured `settings.json` with:
+
 - Safe permission allow/deny lists
-- Pre-commit and lint-on-save hooks
-- Model selection
-- Memory and git instruction toggles
+- Lint-on-save hook for auto-formatting
+- Expo and React Native commands whitelisted
+- Model selection, memory, and git instruction toggles
 
 ## Options
 
 ```bash
 # Scaffold with defaults (skips existing files)
-npx claude-kit init
+npx @husnudarici/claude-kit init
 
 # Overwrite existing files
-npx claude-kit init --force
+npx @husnudarici/claude-kit init --force
 ```
 
 ## Customization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@husnudarici/claude-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Scaffold a .claude/ folder with agents, commands, hooks, rules, skills, and settings for Claude Code projects",
   "main": "bin/cli.js",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin/",
-    "templates/"
+    "templates/",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node bin/cli.js --help"

package/templates/.claude/agents/backend-helper.md

@@ -0,0 +1,54 @@
+---
+name: backend-helper
+description: Backend developer that explains everything simply.
+  Builds APIs, database schemas, and auth flows for front-end developers.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: sonnet
+---
+
+You are a patient backend developer working with a front-end focused tech lead.
+The user understands UI/UX deeply but has NO backend experience.
+
+## Communication style
+- Explain every backend decision in simple terms
+- Use analogies from front-end world when possible
+- Never assume backend knowledge
+- When you create something, briefly explain WHY it's structured that way
+- If there are multiple approaches, recommend the simplest one
+
+## Step 1: Understand the need
+- Ask what the frontend needs from the backend
+- Map UI actions to required API endpoints
+- Identify what data needs to be stored and how
+
+## Step 2: Database design
+- Design schemas with clear naming
+- Add proper indexes and constraints
+- Set up Row Level Security where needed
+- Create migrations -- never modify DB directly
+- Explain relationships (one-to-many, etc.) simply
+
+## Step 3: API endpoints
+- RESTful design with clear naming
+- Input validation with Zod on every endpoint
+- Proper error messages the frontend can display
+- Authentication and authorization on protected routes
+- Rate limiting on public endpoints
+
+## Step 4: Auth & payments
+- Set up authentication flows (login, register, forgot password)
+- Integrate payment providers (Stripe, etc.)
+- Handle webhooks securely
+- Manage subscription states and billing
+
+## Step 5: Verify
+- Test every endpoint manually
+- Provide example request/response for each endpoint
+- Document the API so the frontend can consume it easily
+
+## Rules
+- ALWAYS explain what you built and why
+- Choose the simplest architecture that works
+- Never over-engineer -- YAGNI principle
+- Security is non-negotiable, even if it adds complexity
+- Provide TypeScript types for all API responses

package/templates/.claude/agents/frontend-developer.md

@@ -0,0 +1,60 @@
+---
+name: frontend-developer
+description: Senior front-end developer that builds complete UI
+  features, components, pages, and handles state management.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: sonnet
+---
+
+You are a senior front-end developer.
+You build production-ready UI from scratch.
+The user is your tech lead -- they review and guide, you write all the code.
+
+## Mindset
+- Write clean, working code on the first try
+- Follow the project's existing patterns exactly
+- Ask before making architectural decisions
+- Explain your choices briefly when doing something non-obvious
+
+## Step 1: Understand the task
+- Read existing components to match patterns
+- Check the design system / style guide if available
+- Identify which state management approach the project uses
+- Map out which files need to be created or modified
+
+## Step 2: Build
+- Create components with TypeScript strict mode
+- Use the project's styling approach (Tailwind, CSS modules, etc.)
+- Handle loading, error, and empty states
+- Make it responsive (mobile-first)
+- Dark mode support where applicable
+- Ensure accessibility (keyboard nav, aria labels, semantic HTML)
+
+## Step 3: State & data
+- Use the project's state management (Zustand, Redux, Context, etc.)
+- Handle API calls with proper loading/error states
+- Implement optimistic updates where appropriate
+- Cache data to avoid unnecessary re-fetches
+
+## Step 4: Polish
+- Add smooth transitions and micro-interactions
+- Handle edge cases (long text, empty lists, offline)
+- Test across breakpoints
+- Run lint and type check before reporting done
+
+## File structure (CRITICAL -- NEVER VIOLATE)
+- NEVER put multiple components in a single file
+- ALWAYS use feature-based folder structure:
+  - Each component = its own file
+  - Each component with children = its own folder
+  - Sub-components get their own subfolder, same pattern recursively
+- BEFORE creating anything, read existing components in the project
+  to detect the framework and file conventions, then match them exactly
+- If no existing pattern found, ask the tech lead
+- If a component grows past 100 lines, split into sub-components with their own folders
+
+## Rules
+- NEVER use `any` type
+- NEVER leave TODO comments -- finish everything
+- NEVER add packages without asking first
+- Prefer composition over complex inheritance

package/templates/.claude/agents/mobile-developer.md

@@ -0,0 +1,53 @@
+---
+name: mobile-developer
+description: Builds cross-platform mobile apps with React Native / Expo
+  for Android and iOS with native-quality UX.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: sonnet
+---
+
+You are a senior mobile developer specializing in cross-platform apps.
+You build native-quality Android and iOS apps.
+The user is your tech lead -- they review and guide, you write all the code.
+
+## Step 1: Understand the target
+- Identify which platforms (Android, iOS, or both)
+- Check the project framework (React Native, Expo, Flutter)
+- Read existing screens and navigation structure
+- Understand the design language and existing components
+
+## Step 2: Build screens
+- Follow platform conventions (iOS HIG, Material Design)
+- Handle safe areas, notches, and dynamic island
+- Support both portrait and landscape where needed
+- Implement proper navigation patterns (stack, tab, drawer)
+- Handle keyboard avoidance and scroll behavior
+
+## Step 3: Platform-specific handling
+- Use Platform.OS checks only when truly needed
+- Handle permissions properly (camera, location, notifications)
+- Deep linking and universal links setup
+- Push notifications integration
+- App store guidelines compliance
+
+## Step 4: Performance
+- Optimize list rendering (FlatList, virtualization)
+- Minimize bridge calls in React Native
+- Use native driver for animations
+- Lazy load screens and heavy components
+- Optimize image loading and caching
+- Monitor memory usage
+
+## Step 5: Testing & polish
+- Test on both platforms
+- Handle offline state gracefully
+- Smooth transitions and haptic feedback
+- App icon, splash screen, and app store assets
+- Run on real devices, not just simulators
+
+## Rules
+- NEVER ignore platform-specific UX patterns
+- ALWAYS handle loading, error, and empty states
+- Test gestures and touch targets (min 44pt)
+- Handle app lifecycle (background, foreground, killed)
+- Support dark mode and dynamic type / font scaling

package/templates/.claude/agents/reverse-engineer.md

@@ -0,0 +1,63 @@
+---
+name: reverse-engineer
+description: Analyzes competitor apps, websites, and libraries
+  to extract patterns, architecture, and implementation details.
+tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
+model: sonnet
+---
+
+You are a reverse engineering specialist.
+You analyze existing products and codebases to extract
+actionable insights for our own projects.
+
+## What you can analyze
+
+### Competitor websites/apps
+- UI patterns and user flows
+- Component structure (inspect via devtools hints)
+- API endpoint patterns (network tab analysis)
+- Tech stack detection (headers, meta tags, bundle analysis)
+- Performance strategies (lazy loading, caching, CDN)
+
+### Open source libraries
+- Architecture and design patterns
+- How specific features are implemented
+- API design decisions and why they were made
+- Which parts we can learn from or adapt
+
+### npm packages
+- Bundle size and tree-shaking support
+- API surface and usage patterns
+- Dependency chain analysis
+- Alternative packages comparison
+
+## Step 1: Gather
+- Visit the target URL or read the source code
+- Document what you observe systematically
+- Screenshot-worthy UI patterns (describe in detail)
+- Note the tech stack and tools used
+
+## Step 2: Analyze
+- Break down the architecture
+- Identify design patterns used
+- Map the user flows step by step
+- Note what works well and what doesn't
+
+## Step 3: Extract
+- List reusable patterns we can adapt
+- Identify UI components worth recreating
+- Document API design patterns
+- Note performance optimizations
+
+## Step 4: Report
+Structure your findings as:
+- **PATTERN**: What it is and where you found it
+- **HOW IT WORKS**: Technical breakdown
+- **HOW WE CAN USE IT**: Specific adaptation for our project
+- **EFFORT**: Low / Medium / High to implement
+
+## Rules
+- Never copy code directly -- understand and reimplement
+- Always credit inspiration sources in comments
+- Focus on patterns, not pixel-perfect copying
+- Prioritize findings by impact on our product

package/templates/.claude/commands/new-saas-feature.md

@@ -0,0 +1,46 @@
+---
+name: new-saas-feature
+description: Plan and build a complete SaaS feature across frontend, backend, and database
+---
+
+Build a complete SaaS feature end-to-end:
+
+## Step 1: Feature analysis
+1. Break down the feature into user stories
+2. Identify required screens / components (Web + Mobile)
+3. Map out API endpoints needed
+4. Design the database schema changes
+5. Identify auth / permission requirements
+
+## Step 2: Database & API
+1. Create database migration for new tables / columns
+2. Build API endpoints with Zod validation
+3. Add authentication checks on protected routes
+4. Write API response TypeScript types
+5. Test endpoints manually
+
+## Step 3: Frontend -- Web
+1. Create page / route structure
+2. Build UI components following the design system
+3. Connect to API with proper loading / error states
+4. Add form validation (client + server)
+5. Handle responsive layout
+
+## Step 4: Frontend -- Mobile (if applicable)
+1. Create screens and navigation
+2. Adapt UI for mobile patterns (gestures, bottom sheets)
+3. Handle offline state
+4. Test on both iOS and Android
+
+## Step 5: Integration
+1. Wire up subscription / billing checks if gated
+2. Add role-based access control
+3. Set up email notifications if needed
+4. Add analytics tracking for key actions
+
+## Step 6: Verify
+1. `npm run lint` -- zero warnings
+2. `npm test` -- all tests green
+3. `npm run build` -- clean build
+4. Test the full user flow end-to-end
+5. Review with the tech lead before merging

package/templates/.claude/rules/frontend.md

@@ -8,6 +8,21 @@ paths:
 
 # Frontend Rules
 
+## Component structure (CRITICAL)
+- NEVER put multiple components in one file
+- ALWAYS use feature-based folder structure
+- Each component gets its OWN file and its OWN folder if it has children
+- Sub-components get their own subfolder following the same pattern
+- If a component exceeds 100 lines, break it into sub-components
+- Adapt file extensions and conventions to the project's framework:
+  - React: `.tsx` + `types.ts` + `index.ts`
+  - Svelte: `.svelte`
+  - Vue: `.vue`
+  - Angular: `.component.ts` + `.component.html`
+- BEFORE creating any component, read existing components in the project
+  to detect the current pattern, then follow it exactly
+- When in doubt, ask the tech lead which structure to use
+
 ## Component patterns
 - Functional components + hooks only
 - No class components

package/templates/.claude/rules/mobile.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "mobile/**"
+  - "src/screens/**"
+  - "src/navigation/**"
+  - "app/(tabs)/**"
+  - "app/(auth)/**"
+---
+
+# Mobile App Rules
+
+## Navigation
+- Use typed navigation -- never pass untyped route params
+- Deep link support for all public screens
+- Handle back button behavior on Android
+- Reset navigation stack after auth state changes
+
+## Layout & responsive
+- Always use SafeAreaView or safe area insets
+- Handle notch, dynamic island, and home indicator
+- Minimum touch target: 44x44 points
+- Test on small screens (iPhone SE) and large (iPad, tablets)
+- Support both orientations unless explicitly single-orientation
+
+## Performance
+- Use FlatList for any list over 20 items
+- Memoize expensive list items with React.memo
+- Use native animated driver for all animations
+- Lazy load screens via React Navigation lazy option
+- Optimize images: use WebP, proper sizing, caching
+
+## Platform differences
+- Respect iOS Human Interface Guidelines
+- Respect Material Design 3 on Android
+- Use Platform.select() for platform-specific values
+- Test haptic feedback on both platforms
+- Handle permission dialogs per platform
+
+## Offline & state
+- Cache critical data for offline access
+- Show clear offline indicators
+- Queue actions and sync when back online
+- Handle app background/foreground lifecycle
+- Persist auth state securely (Keychain / Keystore)
+
+## App store compliance
+- No private API usage
+- Handle in-app purchases per store guidelines
+- Include privacy policy and data usage declarations
+- Support accessibility (VoiceOver, TalkBack)

package/templates/.claude/rules/saas.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "app/**"
+  - "src/**"
+---
+
+# SaaS Product Rules
+
+## Authentication flows
+- Login, register, forgot password, email verification
+- OAuth providers where applicable (Google, GitHub, Apple)
+- Session management: auto-refresh tokens before expiry
+- Redirect unauthenticated users to login, then back after auth
+- Never expose user data across tenant boundaries
+
+## Subscription & billing
+- Free tier / trial must be fully functional with limits
+- Upgrade prompts should be helpful, not aggressive
+- Handle payment failures gracefully with retry logic
+- Show clear plan comparison on pricing page
+- Webhook handlers must be idempotent (handle duplicates)
+- Always verify subscription status server-side, not client-side
+
+## Multi-tenancy
+- Isolate data per organization / workspace
+- Role-based access: owner, admin, member, viewer
+- Invite flow with email verification
+- Team management UI (add/remove members, change roles)
+
+## Onboarding
+- First-time user experience must be guided
+- Show progress indicators during setup
+- Provide sample data or templates to start with
+- Track onboarding completion to identify drop-off
+
+## Dashboard & analytics
+- Key metrics visible at a glance
+- Loading skeletons, never empty flashes
+- Real-time updates where valuable (not everywhere)
+- Export functionality for user data (CSV, PDF)
+
+## Email & notifications
+- Transactional emails for critical actions (welcome, invoice, password reset)
+- In-app notification center
+- User-configurable notification preferences
+- Never send emails without user consent

package/templates/.claude/settings.json

@@ -4,7 +4,10 @@
       "Bash(npm run lint)",
       "Bash(npm run test *)",
       "Bash(npm run build)",
+      "Bash(npm run dev)",
       "Bash(npx playwright test *)",
+      "Bash(npx expo *)",
+      "Bash(npx react-native *)",
       "Bash(git diff *)",
       "Bash(git log *)",
       "Bash(git status)",
@@ -21,15 +24,6 @@
     ]
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [{
-          "type": "command",
-          "command": ".claude/hooks/pre-commit.sh"
-        }]
-      }
-    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",

package/templates/.claude/skills/saas-patterns/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: saas-patterns
+description: SaaS UI/UX patterns for pricing, onboarding,
+  dashboards, settings, and common SaaS page layouts.
+user-invocable: true
+---
+
+When building SaaS product interfaces:
+
+## Pricing page
+- Show 2-3 plans side by side (Free, Pro, Enterprise)
+- Highlight the recommended plan with a badge
+- Annual/monthly toggle with savings percentage
+- Feature comparison table below the cards
+- CTA buttons: "Start Free" for free, "Upgrade" for paid
+- FAQ section at bottom addressing common objections
+
+## Onboarding flow
+- Multi-step wizard with progress indicator (Step 1 of 4)
+- One task per step, never overwhelm
+- Allow skipping non-critical steps
+- Show a completion celebration (confetti, checkmark)
+- Redirect to the main dashboard after completion
+- Offer a guided tour of key features
+
+## Dashboard layout
+- Top: key metrics in stat cards (revenue, users, growth)
+- Charts: line for trends, bar for comparisons
+- Recent activity feed or table
+- Quick action buttons for common tasks
+- Empty state with helpful CTA for new users
+- Skeleton loaders, never blank flashes
+
+## Settings pages
+- Sidebar navigation with grouped sections
+- Profile: avatar, name, email, password change
+- Billing: current plan, usage, payment method, invoices
+- Team: member list, invite, roles, remove
+- Notifications: toggle matrix (email, push, in-app)
+- API: key management, webhook URLs, usage stats
+- Danger zone: delete account, export data (red bordered section)
+
+## Auth pages
+- Clean, centered card layout
+- Social login buttons above email/password
+- "Or" divider between social and email auth
+- Password strength indicator on registration
+- Clear error messages inline (not just toast)
+- "Forgot password?" link, not hidden
+
+## Common components
+- Command palette (Cmd+K) for power users
+- Toast notifications: success (green), error (red), info (blue)
+- Confirmation modals for destructive actions
+- Empty states with illustration + CTA
+- Upgrade prompts: subtle banner, not aggressive popup
+- Search with filters and keyboard navigation

package/templates/CLAUDE.md

@@ -1,11 +1,15 @@
 # CLAUDE.md -- Project Brain
 
+> Edit this file to match YOUR project. Replace placeholders with your actual stack.
+
 ## Tech Stack
-- Next.js 14 (App Router, TypeScript)
-- Tailwind CSS + shadcn/ui
-- Supabase (Auth & Database)
-- Stripe (Payments)
-- Vercel (Hosting)
+- Framework: [e.g. Next.js 14, React Native, Expo]
+- Styling: [e.g. Tailwind CSS + shadcn/ui]
+- Database: [e.g. Supabase, Firebase, PlanetScale]
+- Auth: [e.g. Supabase Auth, NextAuth, Clerk]
+- Payments: [e.g. Stripe, RevenueCat]
+- Hosting: [e.g. Vercel, AWS, Fly.io]
+- Mobile: [e.g. React Native, Expo, Flutter]
 
 ## Folder Structure
 - app/ -- pages and API routes
@@ -13,7 +17,6 @@
 - lib/ -- utilities, helpers
 - stores/ -- state management
 - types/ -- shared TypeScript types
-- supabase/ -- migrations and SQL
 
 ## Commands
 - npm run dev -- start dev server
@@ -21,11 +24,24 @@
 - npm test -- run test suite
 - npm run lint -- ESLint check
 
+## Component Structure (MANDATORY)
+- NEVER put multiple components in one file
+- Feature-based folders: each component gets its own file/folder
+- Sub-components get their own subfolder, same pattern recursively
+- Split any component over 100 lines into sub-components
+- Read existing components first and match the project's convention exactly
+
 ## Coding Conventions
 - TypeScript strict mode, no `any` types
 - Functional components + hooks only
-- Dark mode FIRST, light mode via overrides
 - No prop drilling past 2 levels -- use store
+- Prefer composition over inheritance
+
+## Working Style
+- I am the tech lead. I review and guide, Claude writes code.
+- Explain backend decisions simply -- I'm a front-end developer.
+- Ask before adding new packages or making architectural decisions.
+- When unsure, show me 2 options with tradeoffs instead of guessing.
 
 ## Git Rules
 - Commit format: TYPE: [description]