@husnudarici/claude-kit 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# 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.
+
+## Quick Start
+
+```bash
+npx claude-kit init
+```
+
+That's it. Your `.claude/` folder is ready.
+
+## What it creates
+
+```
+.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
+```
+
+## Features
+
+### Agents
+Custom AI teammates that handle specific tasks autonomously:
+- **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
+- **refactorer** -- Improves code structure without changing behavior
+- **doc-writer** -- Creates clear documentation from code analysis
+- **security-auditor** -- Audits code following OWASP top 10
+
+### Commands
+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
+
+### 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
+Guardrails scoped to specific file patterns:
+- **frontend.md** -- Component patterns, styling, performance, a11y
+- **database.md** -- Query safety, migrations, RLS, performance
+- **api.md** -- Input validation, auth, error handling, rate limiting
+
+### Skills
+Reusable capability bundles with prompts and triggers:
+- **frontend-design** -- Enforces design system (colors, typography, spacing)
+
+### 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
+
+## Options
+
+```bash
+# Scaffold with defaults (skips existing files)
+npx claude-kit init
+
+# Overwrite existing files
+npx claude-kit init --force
+```
+
+## Customization
+
+After scaffolding, customize everything for your project:
+
+1. **CLAUDE.md** -- Update tech stack, folder structure, and conventions
+2. **Agents** -- Modify review criteria, add project-specific checks
+3. **Rules** -- Adjust file path patterns to match your project structure
+4. **Commands** -- Update deploy steps for your CI/CD pipeline
+5. **Settings** -- Configure permissions for your specific tools
+6. **Skills** -- Update design tokens to match your brand
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const CYAN = "\x1b[36m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+
+const LOGO = `
+${CYAN}${BOLD}   ╔═══════════════════════════════════╗
+   ║         claude-kit                 ║
+   ║   .claude/ folder scaffolding      ║
+   ╚═══════════════════════════════════╝${RESET}
+`;
+
+function printHelp() {
+  console.log(LOGO);
+  console.log(`${BOLD}Usage:${RESET}`);
+  console.log(`  claude-kit init          Scaffold .claude/ folder in current directory`);
+  console.log(`  claude-kit init --force  Overwrite existing files`);
+  console.log(`  claude-kit --help        Show this help message`);
+  console.log(`  claude-kit --version     Show version`);
+  console.log();
+  console.log(`${BOLD}What it creates:${RESET}`);
+  console.log(`  ${DIM}.claude/${RESET}`);
+  console.log(`  ${DIM}├── agents/         ${RESET}${CYAN}Custom AI agents${RESET}`);
+  console.log(`  ${DIM}├── commands/        ${RESET}${CYAN}Slash command automations${RESET}`);
+  console.log(`  ${DIM}├── hooks/           ${RESET}${CYAN}Pre/post tool-use scripts${RESET}`);
+  console.log(`  ${DIM}├── rules/           ${RESET}${CYAN}Guardrails for file patterns${RESET}`);
+  console.log(`  ${DIM}├── skills/          ${RESET}${CYAN}Reusable capability bundles${RESET}`);
+  console.log(`  ${DIM}├── settings.json    ${RESET}${CYAN}Permissions, model, hooks config${RESET}`);
+  console.log(`  ${DIM}CLAUDE.md            ${RESET}${CYAN}Project brain${RESET}`);
+  console.log();
+}
+
+function copyDirRecursive(src, dest, force) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  fs.mkdirSync(dest, { recursive: true });
+
+  const results = { created: [], skipped: [] };
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      const sub = copyDirRecursive(srcPath, destPath, force);
+      results.created.push(...sub.created);
+      results.skipped.push(...sub.skipped);
+    } else {
+      if (fs.existsSync(destPath) && !force) {
+        results.skipped.push(destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        // Make .sh files executable
+        if (entry.name.endsWith(".sh")) {
+          try {
+            fs.chmodSync(destPath, 0o755);
+          } catch (_) {
+            // chmod may not work on Windows
+          }
+        }
+        results.created.push(destPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+function init(force) {
+  const cwd = process.cwd();
+  const templatesDir = path.join(__dirname, "..", "templates");
+
+  // Copy .claude/ folder
+  const claudeTemplateDir = path.join(templatesDir, ".claude");
+  const claudeDestDir = path.join(cwd, ".claude");
+
+  console.log(LOGO);
+  console.log(`${BOLD}Scaffolding .claude/ folder...${RESET}\n`);
+
+  const results = copyDirRecursive(claudeTemplateDir, claudeDestDir, force);
+
+  // Copy CLAUDE.md
+  const claudeMdSrc = path.join(templatesDir, "CLAUDE.md");
+  const claudeMdDest = path.join(cwd, "CLAUDE.md");
+
+  if (fs.existsSync(claudeMdDest) && !force) {
+    results.skipped.push(claudeMdDest);
+  } else {
+    fs.copyFileSync(claudeMdSrc, claudeMdDest);
+    results.created.push(claudeMdDest);
+  }
+
+  // Print results
+  if (results.created.length > 0) {
+    console.log(`${GREEN}${BOLD}Created:${RESET}`);
+    for (const f of results.created) {
+      const rel = path.relative(cwd, f);
+      console.log(`  ${GREEN}+${RESET} ${rel}`);
+    }
+    console.log();
+  }
+
+  if (results.skipped.length > 0) {
+    console.log(`${YELLOW}${BOLD}Skipped (already exists):${RESET}`);
+    for (const f of results.skipped) {
+      const rel = path.relative(cwd, f);
+      console.log(`  ${YELLOW}-${RESET} ${rel}`);
+    }
+    console.log(`  ${DIM}Use --force to overwrite${RESET}`);
+    console.log();
+  }
+
+  console.log(`${GREEN}${BOLD}Done!${RESET} Your .claude/ folder is ready.\n`);
+  console.log(`${BOLD}Next steps:${RESET}`);
+  console.log(`  1. Edit ${CYAN}CLAUDE.md${RESET} with your project details`);
+  console.log(`  2. Customize agents, rules, and commands for your workflow`);
+  console.log(`  3. Update ${CYAN}.claude/settings.json${RESET} permissions`);
+  console.log();
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const command = args[0];
+const force = args.includes("--force") || args.includes("-f");
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkg = require("../package.json");
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (args.includes("--help") || args.includes("-h") || !command) {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === "init") {
+  init(force);
+} else {
+  console.log(`${RED}Unknown command: ${command}${RESET}`);
+  console.log(`Run ${CYAN}claude-kit --help${RESET} for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@husnudarici/claude-kit",
+  "version": "1.0.0",
+  "description": "Scaffold a .claude/ folder with agents, commands, hooks, rules, skills, and settings for Claude Code projects",
+  "main": "bin/cli.js",
+  "bin": {
+    "claude-kit": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "scaffolding",
+    "cli",
+    "developer-tools",
+    "anthropic"
+  ],
+  "author": "husnudarici",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/husnu/claude-kit"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/templates/.claude/agents/code-reviewer.md

@@ -0,0 +1,44 @@
+---
+name: code-reviewer
+description: Reviews code for bugs, security issues,
+  and performance problems before merge.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+memory: project
+---
+
+You are the senior code reviewer.
+You review every PR as if it ships to
+thousands of users on day one.
+
+## Step 1: Understand the diff
+Run `git diff HEAD~1` to see all changes.
+Read every modified file top to bottom.
+Map which components/APIs were touched.
+
+## Step 2: Security scan
+- Grep for hardcoded API keys, tokens
+- Check .env files are in .gitignore
+- Verify Zod validation on all API inputs
+- Check for SQL injection in raw queries
+- Ensure no `dangerouslySetInnerHTML`
+- Verify Stripe webhook signature checks
+
+## Step 3: Performance check
+- No unnecessary re-renders (memo, useCallback)
+- Images use next/image with proper sizes
+- No blocking calls in Server Components
+- Canvas operations use requestAnimationFrame
+- Check bundle size impact of new deps
+
+## Step 4: Code quality
+- TypeScript strict: no `any`, no `as` casts
+- Functions under 50 lines
+- No duplicated logic (DRY)
+- Descriptive variable names
+- Error boundaries around async operations
+
+## Step 5: Report
+Format: CRITICAL / WARNING / SUGGESTION
+Always run `npm run build` before approving.
+Block the commit if any CRITICAL found.

package/templates/.claude/agents/debugger.md

@@ -0,0 +1,35 @@
+---
+name: debugger
+description: Diagnoses and fixes bugs by analyzing error traces,
+  logs, and code flow systematically.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You are an expert debugger.
+You systematically track down bugs using evidence, not guesswork.
+
+## Step 1: Reproduce
+- Read the error message/stack trace carefully
+- Identify the exact file and line number
+- Understand the expected vs actual behavior
+
+## Step 2: Trace the data flow
+- Start from the error location and work backwards
+- Check function inputs, state values, API responses
+- Look for null/undefined, type mismatches, race conditions
+
+## Step 3: Identify root cause
+- Don't fix symptoms, find the actual cause
+- Check recent git changes that may have introduced the bug
+- Verify assumptions about data shape and types
+
+## Step 4: Fix
+- Make the minimal change that fixes the root cause
+- Don't refactor unrelated code
+- Add error handling only where it prevents the specific bug
+
+## Step 5: Verify
+- Run the relevant test suite
+- Manually trace the fix to confirm it resolves the issue
+- Check for side effects in related code paths

package/templates/.claude/agents/doc-writer.md

@@ -0,0 +1,29 @@
+---
+name: doc-writer
+description: Generates clear documentation, JSDoc comments,
+  and README content from code analysis.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You write clear, useful documentation.
+Documentation should help developers understand WHY, not just WHAT.
+
+## Step 1: Understand the code
+- Read the source files thoroughly
+- Identify the public API and key concepts
+- Understand the architecture and data flow
+
+## Step 2: Write documentation
+- Start with a one-line summary
+- Explain the purpose and use cases
+- Document parameters, return values, and side effects
+- Include code examples for complex APIs
+- Note any gotchas or important caveats
+
+## Style guidelines
+- Use simple, direct language
+- Prefer examples over lengthy explanations
+- Keep JSDoc comments concise but complete
+- Link to related functions/components
+- Update existing docs rather than duplicating

package/templates/.claude/agents/refactorer.md

@@ -0,0 +1,32 @@
+---
+name: refactorer
+description: Improves code structure, readability, and
+  maintainability without changing behavior.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You refactor code to be cleaner and more maintainable.
+Never change behavior -- only improve structure.
+
+## Principles
+- Small, focused changes over big rewrites
+- Preserve all existing tests
+- If no tests exist, write them BEFORE refactoring
+- Each refactoring step should be independently verifiable
+
+## Common refactoring patterns
+- Extract long functions into smaller, named functions
+- Replace magic numbers/strings with named constants
+- Simplify complex conditionals
+- Remove dead code and unused imports
+- Consolidate duplicated logic
+- Improve variable and function naming
+
+## Process
+1. Read the target code thoroughly
+2. Run existing tests to establish baseline
+3. Plan specific refactoring steps
+4. Apply changes incrementally
+5. Run tests after each change
+6. Verify no behavioral changes

package/templates/.claude/agents/security-auditor.md

@@ -0,0 +1,41 @@
+---
+name: security-auditor
+description: Audits code for security vulnerabilities
+  following OWASP top 10 guidelines.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You are a security auditor.
+You find vulnerabilities before attackers do.
+
+## Step 1: Scan for common vulnerabilities
+- SQL injection in raw queries
+- XSS via unsanitized user input
+- CSRF token validation
+- Hardcoded secrets, API keys, tokens
+- Insecure direct object references
+
+## Step 2: Authentication & Authorization
+- Verify auth checks on all protected routes
+- Check session management and token expiry
+- Ensure password hashing (bcrypt/argon2)
+- Validate role-based access controls
+
+## Step 3: Data exposure
+- Check API responses don't leak sensitive data
+- Verify .env files are gitignored
+- Ensure error messages don't expose internals
+- Check logging doesn't include PII
+
+## Step 4: Dependencies
+- Check for known vulnerabilities (npm audit)
+- Review third-party package permissions
+- Verify dependency versions are maintained
+
+## Step 5: Report
+Format each finding as:
+- SEVERITY: CRITICAL / HIGH / MEDIUM / LOW
+- LOCATION: file:line
+- DESCRIPTION: What the vulnerability is
+- REMEDIATION: How to fix it

package/templates/.claude/agents/test-writer.md

@@ -0,0 +1,32 @@
+---
+name: test-writer
+description: Generates comprehensive test suites with unit,
+  integration, and edge case coverage.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You write thorough, maintainable tests.
+Every test should fail for exactly one reason.
+
+## Step 1: Analyze the code
+- Read the file to be tested completely
+- Identify public API, edge cases, error paths
+- Check existing test patterns in the project
+
+## Step 2: Plan test cases
+- Happy path: normal expected usage
+- Edge cases: empty inputs, boundaries, large data
+- Error cases: invalid inputs, network failures
+- Integration: component interactions
+
+## Step 3: Write tests
+- Use the project's existing test framework
+- Follow existing naming conventions
+- One assertion per test when possible
+- Use descriptive test names that explain the scenario
+
+## Step 4: Verify
+- Run the test suite to confirm all tests pass
+- Check coverage for the target file
+- Ensure no tests are flaky or order-dependent

package/templates/.claude/commands/deploy.md

@@ -0,0 +1,30 @@
+---
+name: deploy
+description: Deploy to production with all checks
+disable-model-invocation: true
+---
+
+Deploy the app to production:
+
+## Pre-flight checks
+1. `git status` -- no uncommitted changes
+2. `npm run lint` -- zero warnings
+3. `npm run build` -- clean production build
+4. `npm test` -- all tests green
+5. `npx playwright test` -- e2e passing
+
+## Deploy
+6. `git push origin main`
+7. Wait for CI/CD build to complete
+8. Verify deployment status
+
+## Post-deploy verification
+9. Hit production URL, check homepage loads
+10. Test one critical user flow
+11. Check webhook integrations are receiving events
+12. Verify /api/health returns 200
+
+## If anything fails
+- Do NOT force push or skip checks
+- Fix the issue, re-run all checks
+- Only authorized team members can approve rollbacks

package/templates/.claude/commands/fix-issue.md

@@ -0,0 +1,26 @@
+---
+name: fix-issue
+description: Diagnose and fix a GitHub issue end-to-end
+---
+
+Fix the given GitHub issue:
+
+## Step 1: Understand the issue
+1. Read the issue description and comments
+2. Reproduce the problem locally if possible
+3. Identify the root cause
+
+## Step 2: Implement the fix
+1. Make the minimal change that fixes the issue
+2. Follow existing code patterns and conventions
+3. Add or update tests to cover the fix
+
+## Step 3: Verify
+1. Run the full test suite
+2. Run the linter
+3. Run the build to ensure no regressions
+4. Verify the fix resolves the original issue
+
+## Step 4: Prepare for review
+1. Create a clear commit message referencing the issue
+2. Summarize the changes and reasoning

package/templates/.claude/commands/pr-review.md

@@ -0,0 +1,35 @@
+---
+name: pr-review
+description: Review a pull request thoroughly before merge
+---
+
+Review the given pull request:
+
+## Step 1: Understand the changes
+1. Read the PR description and linked issues
+2. Run `git diff` to see all changes
+3. Read every modified file top to bottom
+4. Map which components/APIs were touched
+
+## Step 2: Code quality checks
+- TypeScript strict: no `any`, no `as` casts
+- Functions under 50 lines
+- No duplicated logic (DRY)
+- Descriptive variable names
+- Proper error handling
+
+## Step 3: Security review
+- No hardcoded secrets or API keys
+- Input validation on all endpoints
+- No SQL injection vulnerabilities
+- No XSS vectors
+
+## Step 4: Testing
+- Verify test coverage for new code
+- Run the test suite
+- Check for edge cases
+
+## Step 5: Provide feedback
+- Format: CRITICAL / WARNING / SUGGESTION
+- Be constructive and specific
+- Suggest improvements with code examples

package/templates/.claude/hooks/lint-on-save.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# --------------------------------------------
+# Lint-on-save hook
+# Runs after every Edit/Write tool use.
+# Auto-formats and checks for lint errors.
+# --------------------------------------------
+
+RED="\033[0;31m"
+GREEN="\033[0;32m"
+NC="\033[0m"
+
+# Get the file that was just modified
+FILE="$1"
+
+if [ -z "$FILE" ]; then
+  echo "No file specified"
+  exit 0
+fi
+
+# Only lint TypeScript/JavaScript files
+if [[ "$FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then
+  echo "Linting $FILE..."
+  npx eslint "$FILE" --fix --quiet
+  if [ $? -ne 0 ]; then
+    echo -e "${RED}Lint errors in $FILE${NC}"
+    exit 1
+  fi
+  echo -e "${GREEN}Lint passed: $FILE${NC}"
+fi
+
+exit 0

package/templates/.claude/hooks/pre-commit.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# --------------------------------------------
+# Pre-commit hook
+# Runs tests + lint before EVERY commit.
+# If anything fails, the commit is blocked.
+# --------------------------------------------
+
+RED="\033[0;31m"
+GREEN="\033[0;32m"
+NC="\033[0m"
+
+# Step 1: Run TypeScript type check
+echo "Checking types..."
+npx tsc --noEmit
+if [ $? -ne 0 ]; then
+  echo -e "${RED}Type errors found. Fix before committing.${NC}"
+  exit 2
+fi
+
+# Step 2: Run ESLint on staged files
+echo "Linting staged files..."
+STAGED=$(git diff --cached --name-only --diff-filter=d | grep -E "\.(ts|tsx)$")
+if [ -n "$STAGED" ]; then
+  npx eslint $STAGED --quiet
+  if [ $? -ne 0 ]; then
+    echo -e "${RED}Lint errors. Run npm run lint to see details.${NC}"
+    exit 2
+  fi
+fi
+
+# Step 3: Run test suite
+echo "Running tests..."
+npm test -- --silent
+if [ $? -ne 0 ]; then
+  echo -e "${RED}Tests failed. Commit blocked.${NC}"
+  exit 2
+fi
+
+echo -e "${GREEN}All checks passed!${NC}"
+exit 0

package/templates/.claude/rules/api.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - "app/api/**"
+  - "src/app/api/**"
+---
+
+# API Route Rules
+
+## Input validation
+- Validate ALL inputs with Zod schemas
+- Parse request body: schema.parse(await req.json())
+- Validate URL params: z.string().uuid()
+- Return 400 with { error: "..." } on validation failure
+
+## Authentication
+- All protected routes: const user = await requireAuth()
+- requireAuth() throws 401 if no session
+- Never trust client-sent user IDs -- use auth.uid()
+
+## Error handling
+- Consistent format: { error: string, code?: string }
+- Never expose stack traces or internal errors
+- Log errors with context (route, user_id, input)
+- Return appropriate HTTP codes:
+  400 = bad input, 401 = no auth, 403 = forbidden
+  404 = not found, 429 = rate limited, 500 = server error
+
+## Rate limiting
+- All public endpoints: rateLimit(req, { max: 10 })
+- Payment endpoints: rateLimit(req, { max: 3 })
+- Export endpoints: rateLimit(req, { max: 5 })
+
+## Response
+- Always return NextResponse.json()
+- Set Cache-Control headers where appropriate
+- Webhooks: return 200 quickly, process async

package/templates/.claude/rules/database.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "supabase/**"
+  - "src/lib/db/**"
+  - "prisma/**"
+  - "drizzle/**"
+---
+
+# Database Rules
+
+## Query patterns
+- Always use parameterized queries, never string concatenation
+- Use transactions for multi-step operations
+- Add proper indexes for frequently queried columns
+- Limit result sets with pagination
+
+## Schema changes
+- Always create migrations, never modify the database directly
+- Include both up and down migrations
+- Test migrations on a copy before applying to production
+- Document breaking schema changes
+
+## Security
+- Never trust client-sent user IDs -- use auth.uid()
+- Row Level Security (RLS) on all user-facing tables
+- Sanitize all inputs before database operations
+- Never expose internal IDs in API responses
+
+## Performance
+- Use connection pooling
+- Cache frequently accessed, rarely changed data
+- Avoid N+1 queries -- use joins or batch loading
+- Monitor query performance and add indexes as needed

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

@@ -0,0 +1,34 @@
+---
+paths:
+  - "app/**"
+  - "src/app/**"
+  - "components/**"
+  - "src/components/**"
+---
+
+# Frontend Rules
+
+## Component patterns
+- Functional components + hooks only
+- No class components
+- Use TypeScript strict mode, no `any` types
+- No prop drilling past 2 levels -- use store or context
+
+## Styling
+- Use Tailwind CSS for all styling
+- Dark mode FIRST, light mode via overrides
+- Responsive design: mobile-first approach
+- Use CSS variables for theme values
+
+## Performance
+- Memoize expensive computations (useMemo)
+- Stabilize callback references (useCallback)
+- Use next/image with proper width/height
+- Lazy load components below the fold
+- No blocking operations in render path
+
+## Accessibility
+- All interactive elements must be keyboard accessible
+- Use semantic HTML elements
+- Include aria-labels where needed
+- Maintain proper heading hierarchy

package/templates/.claude/settings.json

@@ -0,0 +1,47 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run lint)",
+      "Bash(npm run test *)",
+      "Bash(npm run build)",
+      "Bash(npx playwright test *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git status)",
+      "Bash(gh issue *)",
+      "Bash(gh pr *)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(secrets/**)",
+      "Bash(rm -rf *)",
+      "Bash(git push --force *)",
+      "Bash(curl *)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": ".claude/hooks/pre-commit.sh"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{
+          "type": "command",
+          "command": ".claude/hooks/lint-on-save.sh"
+        }]
+      }
+    ]
+  },
+  "model": "claude-sonnet-4-6",
+  "autoMemoryEnabled": true,
+  "includeGitInstructions": true,
+  "respectGitignore": true
+}

package/templates/.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: frontend-design
+description: Enforces exact design standards
+  for all UI: colors, spacing, typography, layout.
+user-invocable: true
+---
+
+When building ANY UI for this product:
+
+## Brand colors
+- Primary: #FF6B35 (Electric Coral)
+- Primary Light: #FF8F6B (gradients)
+- Primary Soft: #FFB088 (gradient endpoints)
+- Teal accent: #00d4aa (cool complement)
+- Background: #0A0A0F (rich black, NOT flat #000)
+- Surface: rgba(255,255,255,0.04) (cards)
+- Surface hover: rgba(255,255,255,0.07)
+- Border: rgba(255,255,255,0.10)
+- Text primary: #FFFFFF
+- Text secondary: rgba(255,255,255,0.6)
+- Text muted: rgba(255,255,255,0.4)
+
+## Typography
+- Font: Inter (system fallback: -apple-system)
+- Headings: -0.02em letter-spacing, font-weight 700
+- Hero: 48-64px, gradient text optional
+- Section heading: 32-36px
+- Body: 15-16px, line-height 1.6
+- Code: Menlo 14px
+- Labels/badges: 11-12px uppercase, 0.08em tracking
+
+## Spacing & layout
+- Section gap: 64px (py-16)
+- Card padding: 24px
+- Inner content gap: 12-16px
+- Max content width: 1200px
+- Border radius: 16px cards, 12px modals, 8px buttons
+
+## Dark mode aesthetic
+- NEVER flat black. Use depth through:
+  - Subtle gradients (bg-gradient-to-b)
+  - Glow effects on hover (box-shadow coral)
+  - Border separators (rgba white 0.10)
+  - Surface elevation (slightly lighter bg)

package/templates/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md -- Project Brain
+
+## Tech Stack
+- Next.js 14 (App Router, TypeScript)
+- Tailwind CSS + shadcn/ui
+- Supabase (Auth & Database)
+- Stripe (Payments)
+- Vercel (Hosting)
+
+## Folder Structure
+- app/ -- pages and API routes
+- components/ -- React components
+- lib/ -- utilities, helpers
+- stores/ -- state management
+- types/ -- shared TypeScript types
+- supabase/ -- migrations and SQL
+
+## Commands
+- npm run dev -- start dev server
+- npm run build -- production build
+- npm test -- run test suite
+- npm run lint -- ESLint check
+
+## 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
+
+## Git Rules
+- Commit format: TYPE: [description]
+- Never push unless explicitly told to
+- Feature branches for 8+ file changes
+
+## Security
+- Never hardcode API keys or secrets
+- Always validate inputs with Zod
+- Use environment variables for all configs
+- .env files must be in .gitignore