claude-code-standards 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# claude-code-standards
+
+Reusable Claude Code agents, rules, and conventions for any project. Auto-detects your tech stack and generates a tailored `CLAUDE.md` + specialized agents.
+
+## Install
+
+```bash
+npm install -D claude-code-standards
+```
+
+## Initialize
+
+```bash
+npx claude-code-standards init
+```
+
+This will:
+1. Read your `package.json` to detect your tech stack
+2. Generate a `CLAUDE.md` with relevant rules for your stack
+3. Install agents to `.claude/agents/` (code-guardian, figma-builder, figma-validator)
+4. Install docs to `.claude/docs/`
+
+## What gets detected
+
+| Dependency | Rules Applied |
+|---|---|
+| `next` | App Router conventions, layout patterns, route organization |
+| `@reduxjs/toolkit` | RTK Query service patterns, tag constants, Object.values |
+| `@radix-ui/react-slot` | Shadcn/UI read-only rule, wrapper pattern |
+| `@nestjs/core` | Module structure, DTO validation, guard patterns |
+| `zod` | Centralized validation schemas |
+| `@ebay/nice-modal-react` | ModalConstant pattern, barrel registration |
+| `tailwindcss` | Tailwind conventions |
+| And more... | Stripe, LiveKit, TypeORM, Prisma, etc. |
+
+## Agents
+
+### code-guardian
+Run **first** before any task. Audits the codebase against CLAUDE.md rules and discovers undocumented patterns.
+
+### figma-builder (frontend only)
+Builds pixel-perfect components from Figma frames. Extracts all assets, preserves exact styling.
+
+### figma-validator (frontend only)
+Validates built components against Figma screenshots. Catches missing assets, wrong colors, spacing issues.
+
+## Customization
+
+After `init`, edit `CLAUDE.md` to add project-specific rules. The generated file is a starting point — customize it for your project's unique conventions.
+
+## License
+
+MIT

package/bin/init.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { detectStack } = require('../lib/detect');
+const { generateClaudeMd, installAgents, installDocs } = require('../lib/install');
+
+const projectDir = process.cwd();
+
+console.log('\n🔍 Claude Code Standards — Initializing...\n');
+console.log(`Project: ${projectDir}\n`);
+
+// Step 1: Detect stack
+console.log('Detecting tech stack...');
+const stack = detectStack(projectDir);
+
+const detected = [];
+if (stack.nextjs) detected.push('Next.js');
+if (stack.react && !stack.nextjs) detected.push('React');
+if (stack.nestjs) detected.push('NestJS');
+if (stack.express) detected.push('Express');
+if (stack.rtkQuery) detected.push('RTK Query');
+if (stack.tailwind) detected.push('Tailwind CSS');
+if (stack.shadcn) detected.push('Shadcn/UI');
+if (stack.niceModal) detected.push('nice-modal-react');
+if (stack.zod) detected.push('Zod');
+if (stack.typeorm) detected.push('TypeORM');
+if (stack.prisma) detected.push('Prisma');
+if (stack.stripe) detected.push('Stripe');
+
+console.log(`  Detected: ${detected.join(', ') || 'No specific stack detected'}`);
+console.log(`  Type: ${stack.isFrontend ? 'Frontend' : ''}${stack.isFrontend && stack.isBackend ? ' + ' : ''}${stack.isBackend ? 'Backend' : ''}`);
+console.log('');
+
+// Step 2: Generate CLAUDE.md
+console.log('Generating CLAUDE.md...');
+generateClaudeMd(projectDir, stack);
+console.log('  Created CLAUDE.md');
+
+// Step 3: Install agents
+console.log('\nInstalling agents...');
+installAgents(projectDir, stack);
+
+// Step 4: Install docs
+console.log('\nInstalling docs...');
+installDocs(projectDir, stack);
+
+console.log('\n✅ Done! Claude Code Standards initialized.');
+console.log('\nNext steps:');
+console.log('  1. Review CLAUDE.md and customize project-specific sections');
+console.log('  2. Run the code-guardian agent to audit your codebase');
+console.log('  3. Commit .claude/ directory to your repo\n');

package/lib/detect.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detect the tech stack of a project by reading its package.json
+ * Returns an object with boolean flags for each detected technology
+ */
+function detectStack(projectDir) {
+  const pkgPath = path.join(projectDir, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    console.error('No package.json found in', projectDir);
+    process.exit(1);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  const has = (dep) => !!allDeps[dep];
+
+  return {
+    // Frameworks
+    nextjs: has('next'),
+    react: has('react'),
+    nestjs: has('@nestjs/core'),
+    express: has('express'),
+
+    // State management
+    rtkQuery: has('@reduxjs/toolkit'),
+    redux: has('react-redux') || has('@reduxjs/toolkit'),
+    zustand: has('zustand'),
+    tanstackQuery: has('@tanstack/react-query'),
+
+    // UI
+    tailwind: has('tailwindcss'),
+    shadcn: has('@radix-ui/react-slot') || has('class-variance-authority'),
+    niceModal: has('@ebay/nice-modal-react'),
+
+    // Validation
+    zod: has('zod'),
+    yup: has('yup'),
+    classValidator: has('class-validator'),
+
+    // ORM / Database
+    typeorm: has('typeorm'),
+    prisma: has('@prisma/client'),
+    drizzle: has('drizzle-orm'),
+
+    // Auth
+    passport: has('passport'),
+    nextAuth: has('next-auth'),
+
+    // Payments
+    stripe: has('stripe') || has('@stripe/react-stripe-js'),
+
+    // Real-time
+    livekit: has('@livekit/components-react') || has('livekit-server-sdk'),
+    socketio: has('socket.io') || has('socket.io-client'),
+
+    // Testing
+    jest: has('jest'),
+    vitest: has('vitest'),
+    playwright: has('@playwright/test'),
+
+    // Meta
+    isMonorepo: fs.existsSync(path.join(projectDir, 'packages')) ||
+                fs.existsSync(path.join(projectDir, 'apps')) ||
+                has('turborepo') || has('lerna'),
+    isFrontend: has('react') || has('vue') || has('svelte') || has('next') || has('nuxt'),
+    isBackend: has('@nestjs/core') || has('express') || has('fastify') || has('hono'),
+
+    // Package info
+    name: pkg.name || 'unknown',
+    description: pkg.description || '',
+  };
+}
+
+module.exports = { detectStack };

package/lib/install.js

@@ -0,0 +1,130 @@
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+/**
+ * Copy a file from templates to project, creating directories as needed
+ */
+function copyTemplate(templatePath, destPath) {
+  const dir = path.dirname(destPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.copyFileSync(
+    path.join(TEMPLATES_DIR, templatePath),
+    destPath
+  );
+}
+
+/**
+ * Generate CLAUDE.md from template with stack-aware sections
+ */
+function generateClaudeMd(projectDir, stack) {
+  const template = fs.readFileSync(
+    path.join(TEMPLATES_DIR, 'CLAUDE.md.template'),
+    'utf-8'
+  );
+
+  let output = template;
+
+  // Replace placeholders
+  output = output.replace(/\{\{PROJECT_NAME\}\}/g, stack.name);
+  output = output.replace(/\{\{PROJECT_DESCRIPTION\}\}/g, stack.description);
+
+  // Build tech stack table
+  const techStack = [];
+  if (stack.nextjs) techStack.push('| Framework | Next.js (App Router) |');
+  else if (stack.react) techStack.push('| Framework | React |');
+  else if (stack.nestjs) techStack.push('| Framework | NestJS |');
+  else if (stack.express) techStack.push('| Framework | Express |');
+
+  if (stack.tailwind) techStack.push('| Styling | Tailwind CSS |');
+  if (stack.shadcn) techStack.push('| UI Components | Shadcn/UI |');
+  if (stack.rtkQuery) techStack.push('| State | Redux Toolkit + RTK Query |');
+  else if (stack.zustand) techStack.push('| State | Zustand |');
+  else if (stack.tanstackQuery) techStack.push('| Data Fetching | TanStack Query |');
+  if (stack.zod) techStack.push('| Validation | Zod |');
+  else if (stack.classValidator) techStack.push('| Validation | class-validator |');
+  if (stack.typeorm) techStack.push('| ORM | TypeORM |');
+  else if (stack.prisma) techStack.push('| ORM | Prisma |');
+  if (stack.stripe) techStack.push('| Payments | Stripe |');
+
+  output = output.replace('{{TECH_STACK_TABLE}}', techStack.join('\n'));
+
+  // Conditional sections
+  const conditionalSections = {
+    '{{#IF_RTK_QUERY}}': stack.rtkQuery,
+    '{{#IF_NEXTJS}}': stack.nextjs,
+    '{{#IF_SHADCN}}': stack.shadcn,
+    '{{#IF_ZOD}}': stack.zod,
+    '{{#IF_NICE_MODAL}}': stack.niceModal,
+    '{{#IF_NESTJS}}': stack.nestjs,
+    '{{#IF_FRONTEND}}': stack.isFrontend,
+    '{{#IF_BACKEND}}': stack.isBackend,
+  };
+
+  for (const [tag, condition] of Object.entries(conditionalSections)) {
+    const endTag = tag.replace('#IF_', '/IF_');
+    const regex = new RegExp(`${escapeRegex(tag)}([\\s\\S]*?)${escapeRegex(endTag)}`, 'g');
+
+    if (condition) {
+      // Keep the content, remove the tags
+      output = output.replace(regex, '$1');
+    } else {
+      // Remove the entire section including content
+      output = output.replace(regex, '');
+    }
+  }
+
+  // Clean up empty lines
+  output = output.replace(/\n{3,}/g, '\n\n');
+
+  const destPath = path.join(projectDir, 'CLAUDE.md');
+  if (fs.existsSync(destPath)) {
+    // Backup existing
+    fs.copyFileSync(destPath, destPath + '.backup');
+    console.log('  Backed up existing CLAUDE.md → CLAUDE.md.backup');
+  }
+  fs.writeFileSync(destPath, output);
+}
+
+/**
+ * Install agents based on detected stack
+ */
+function installAgents(projectDir, stack) {
+  const agentsDir = path.join(projectDir, '.claude', 'agents');
+
+  // Always install code-guardian
+  copyTemplate('agents/code-guardian.md', path.join(agentsDir, 'code-guardian.md'));
+  console.log('  Installed agent: code-guardian');
+
+  // Frontend-only agents
+  if (stack.isFrontend) {
+    copyTemplate('agents/figma-builder.md', path.join(agentsDir, 'figma-builder.md'));
+    copyTemplate('agents/figma-validator.md', path.join(agentsDir, 'figma-validator.md'));
+    console.log('  Installed agent: figma-builder');
+    console.log('  Installed agent: figma-validator');
+  }
+}
+
+/**
+ * Install docs based on detected stack
+ */
+function installDocs(projectDir, stack) {
+  const docsDir = path.join(projectDir, '.claude', 'docs');
+
+  copyTemplate('docs/architectural_patterns.md', path.join(docsDir, 'architectural_patterns.md'));
+  console.log('  Installed doc: architectural_patterns');
+
+  if (stack.isFrontend && stack.shadcn) {
+    copyTemplate('docs/dashboard_redesign.md', path.join(docsDir, 'dashboard_redesign.md'));
+    console.log('  Installed doc: dashboard_redesign');
+  }
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { generateClaudeMd, installAgents, installDocs, copyTemplate };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "claude-code-standards",
+  "version": "1.0.0",
+  "description": "Reusable Claude Code agents, rules, and conventions for any project. Auto-detects your tech stack and generates CLAUDE.md + agents.",
+  "bin": {
+    "claude-code-standards": "./bin/init.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "code-quality",
+    "agents",
+    "standards",
+    "conventions"
+  ],
+  "author": "CoTrain",
+  "license": "MIT"
+}

package/templates/CLAUDE.md.template

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+## Project Overview
+
+{{PROJECT_NAME}} — {{PROJECT_DESCRIPTION}}
+
+## Commands
+
+```bash
+npm run dev         # Dev server
+npm run build       # Production build (ALWAYS run after changes to verify)
+npm run lint        # Linting
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+{{TECH_STACK_TABLE}}
+
+## Key Conventions
+
+- **Import alias**: Use `@/*` or configured path alias for imports. Avoid deep relative paths.
+- **Component organization** — organize by what the component IS:
+  - `ui/` — UI library primitives (READ-ONLY if using shadcn/ui)
+  - `sidebar/` — shell navigation (sidebar, header)
+  - `cards/` — reusable card components
+  - `banners/` — hero/banner sections
+  - `widgets/` — floating/interactive widgets
+  - `sections/` — page sections that compose cards/banners
+  - `pages/` — full page-level content views
+  - `modal/` — modal dialogs
+  - Think about what the component IS, not what page it appears on.
+{{#IF_SHADCN}}
+- **`src/components/ui/` is READ-ONLY** — never modify UI library primitives directly. Create wrappers in feature directories that import and extend them.
+{{/IF_SHADCN}}
+{{#IF_ZOD}}
+- **Form validation**: All Zod schemas go in a dedicated validation directory. Never define validation inline in components.
+{{/IF_ZOD}}
+{{#IF_NICE_MODAL}}
+- **Modals**: Use `@ebay/nice-modal-react` with centralized `ModalConstant` for IDs. Each modal uses `NiceModal.create()` + UI Dialog. Register in barrel file.
+{{/IF_NICE_MODAL}}
+{{#IF_NEXTJS}}
+- **Routing**: Each major section should be a page route. Layouts provide persistent shells. Use `usePathname()` + `<Link>` for navigation.
+{{/IF_NEXTJS}}
+
+{{#IF_RTK_QUERY}}
+## Service Layer
+
+- **`src/services/api/`** — RTK Query services ONLY. Each file extends the base API factory. One service per domain.
+- **Base service** — Network setup only (JWT injection, error handling). Do NOT add business logic.
+- **Service registry** — When adding a new service, register in 3 places: reducers, middleware, and re-export.
+- **Tag constants** — All RTK cache tags in a centralized constant file. Never define tags inline. Use `Object.values()` for tag arrays.
+- **Request/Response types** — All DTOs in dedicated model directories. Never define types inline in service files.
+- **Service wrappers** — Optional convenience hooks wrapping RTK mutations. Only create when the same logic is reused across components.
+{{/IF_RTK_QUERY}}
+
+{{#IF_NESTJS}}
+## Backend Conventions
+
+- **Module structure**: One module per domain. Each module has controller, service, and DTOs.
+- **DTOs**: All in dedicated DTO files with class-validator decorators. Never accept raw objects.
+- **Guards**: Use guards for auth. Mark public endpoints explicitly.
+- **Pipes**: Use ValidationPipe globally. DTOs handle validation.
+- **Interceptors**: Use for response transformation and logging.
+{{/IF_NESTJS}}
+
+## Bug Fixing
+
+Identify the EXACT file and component before patching. After fixing, grep the codebase for similar patterns that may need the same fix.
+
+{{#IF_FRONTEND}}
+## Figma-to-Code Rules
+
+When building from Figma designs:
+- **Never neglect backgrounds** — apply every gradient, color, shadow
+- **Always read UI library source** — check for default styles that override yours
+- **Exact spacing** — match gap, padding, margin from the design exactly
+- **Check every surface** — background, box-shadow, border, border-radius must all match
+- **Use figma-builder and figma-validator agents** for pixel-perfect implementation
+- **Visual compare** — always compare rendered output against the design
+{{/IF_FRONTEND}}
+
+## Agents
+
+Run **code-guardian** FIRST before starting any task.
+
+- `.claude/agents/code-guardian.md` — Audits rule compliance, finds violations, discovers undocumented patterns
+{{#IF_FRONTEND}}
+- `.claude/agents/figma-builder.md` — Builds pixel-perfect components from Figma
+- `.claude/agents/figma-validator.md` — Validates components against Figma designs
+{{/IF_FRONTEND}}
+
+## Additional Documentation
+
+- `.claude/docs/architectural_patterns.md` — Recurring patterns and conventions

package/templates/agents/code-guardian.md

@@ -0,0 +1,138 @@
+---
+name: code-guardian
+description: Audits the codebase against CLAUDE.md rules and discovers undocumented patterns. Run this FIRST before starting any task. This agent is curious — it enforces rules AND actively looks for new patterns worth documenting.
+---
+
+You are the Code Guardian — an auditor and curious observer of this codebase.
+
+## Your Mission
+1. **Enforce** — check that all CLAUDE.md rules are being followed
+2. **Discover** — find patterns, conventions, and issues not yet documented
+3. **Report** — produce a clear, actionable report
+
+## Setup
+1. Read `CLAUDE.md` at the project root — this is your source of truth
+2. Read `package.json` to understand the tech stack
+3. Check `.claude/docs/` for additional documented patterns
+
+## Universal Checks (All Projects)
+
+### Types & Interfaces
+```bash
+# Inline types in service/API files (should be in a models/types directory)
+grep -rn "^export interface\|^export type\|^interface \|^type " src/services/ --include="*.ts" 2>/dev/null | grep -v "export type {"
+```
+
+### Constants
+```bash
+# Hardcoded string constants that should be centralized
+grep -rn "const.*=\s*['\"]" src/services/ --include="*.ts" 2>/dev/null | grep -v "import\|require\|from\|//" | head -20
+```
+
+### Dead Code
+```bash
+# Console.log left in code
+grep -rn "console\.log\|console\.warn" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "node_modules\|_archive" | head -20
+
+# TODO/FIXME comments
+grep -rn "TODO\|FIXME\|HACK\|XXX" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "node_modules\|_archive" | head -20
+
+# Large files (>300 lines)
+find src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -20
+```
+
+### Import Hygiene
+```bash
+# Relative imports deeper than 2 levels (should use alias)
+grep -rn "from '\.\./\.\.\.\." src/ --include="*.tsx" --include="*.ts" 2>/dev/null | head -10
+```
+
+## Stack-Specific Checks
+
+Read `package.json` and run only the relevant checks:
+
+### If RTK Query (`@reduxjs/toolkit` in dependencies)
+```bash
+# Inline tag constants in service files
+grep -rn "^const.*TAGS\s*=" src/services/api/ --include="*.ts" 2>/dev/null
+
+# Tag arrays not using Object.values()
+grep -rn "RTKTagsConstant\.\w*\.\w*," src/services/api/ --include="*.ts" 2>/dev/null | head -10
+
+# TanStack Query usage (forbidden if RTK Query is primary)
+grep -rn "@tanstack/react-query" src/ --include="*.ts" --include="*.tsx" 2>/dev/null
+```
+
+### If Next.js (`next` in dependencies)
+```bash
+# Pages missing 'use client' or 'use server' directive
+find app/ -name "page.tsx" 2>/dev/null | head -20
+
+# Layout files
+find app/ -name "layout.tsx" 2>/dev/null
+```
+
+### If Shadcn/UI (`@radix-ui/react-slot` in dependencies)
+```bash
+# Modified shadcn files (ui/ should be read-only)
+grep -rn "// custom\|// modified\|// added" src/components/ui/ --include="*.tsx" 2>/dev/null
+```
+
+### If Zod (`zod` in dependencies)
+```bash
+# Inline Zod schemas (should be in validation directory)
+grep -rn "z\.object\|z\.string().min" src/components/ app/ --include="*.tsx" 2>/dev/null | grep -v "import" | head -10
+```
+
+### If NestJS (`@nestjs/core` in dependencies)
+```bash
+# Controllers without guards
+grep -rL "@UseGuards\|@Public" src/**/*.controller.ts 2>/dev/null
+
+# Services without proper injection
+grep -rn "new.*Service()" src/ --include="*.ts" 2>/dev/null | head -10
+
+# DTOs without class-validator decorators
+find src/ -name "*.dto.ts" 2>/dev/null | head -20
+```
+
+## Discovery Mode
+
+After running checks, observe:
+
+```bash
+# Component directory structure
+ls src/components/ 2>/dev/null
+
+# Naming convention consistency
+find src/components -name "*.tsx" 2>/dev/null | head -30
+
+# Export patterns (named vs default)
+grep -rn "^export default\|^export function\|^export const" src/components/ --include="*.tsx" 2>/dev/null | head -20
+
+# Barrel exports
+find src/ -name "index.ts" -o -name "index.tsx" 2>/dev/null | head -20
+
+# Hardcoded colors (potential design tokens)
+grep -rn "#[0-9a-fA-F]\{6\}" src/components/ --include="*.tsx" 2>/dev/null | wc -l
+```
+
+## Report Format
+
+### VIOLATIONS (Must Fix)
+Issues that break documented rules.
+- Rule violated
+- File:line
+- What's wrong → How to fix
+
+### SUGGESTIONS (Should Consider)
+Code that works but could be better.
+- What was found → Why it matters → Suggested improvement
+
+### DISCOVERIES (Document This)
+New patterns not yet in CLAUDE.md.
+- Pattern description → Where it appears → Add to CLAUDE.md?
+
+---
+
+**You are READ-ONLY. Never modify files. Only observe and report.**

package/templates/agents/figma-builder.md

@@ -0,0 +1,62 @@
+---
+name: figma-builder
+description: Builds pixel-perfect React components from Figma frames. Extracts all assets, downloads them locally, and produces components that exactly match the design.
+---
+
+You are a pixel-perfect Figma-to-code builder.
+
+## Your Task
+You will be given a **Figma node ID** and an **output file path**.
+
+### 1. Extract the design
+Call `get_design_context` with the Figma file key and node ID. This returns:
+- Reference React+Tailwind code
+- Asset URLs as constants
+- A screenshot of the design
+
+### 2. Download ALL assets
+For **every** asset URL in the response:
+- Download using `curl -sL "{url}" -o public/assets/{name}.{ext}`
+- Check file type with `file` command, use correct extension
+- Name descriptively: `icon-home.svg`, `illustration-discover.png`, etc.
+- **Do NOT skip any asset**
+
+### 3. Build the component
+Using the Figma-generated code as reference:
+- Use the project's UI component library as base
+- Replace ALL Figma temporary URLs with local `/assets/` paths
+- Preserve **EXACT** values: colors, spacing, fonts, border-radius, dimensions
+- **NEVER substitute icons** — use the actual extracted assets
+- **NEVER approximate** — if the design says `text-[14px] tracking-[-0.15px]`, use exactly that
+
+### 4. Component library awareness
+Before using any UI library component:
+- **Read the source file** to check for default styles
+- Identify defaults that conflict with the design
+- Override them explicitly
+
+### 5. Background & surface styles
+- **NEVER neglect backgrounds** — apply every gradient, color, shadow from the design
+- Check every container's background, box-shadow, border, border-radius
+
+### 6. Spacing in grids
+- Match `gap`, `padding`, `margin` exactly from the design
+- Don't use framework defaults when the design specifies exact pixel values
+
+### 7. Component placement
+Place each component in the directory that matches its role:
+- `sidebar/` — navigation components
+- `cards/` — reusable card components
+- `banners/` — hero/banner sections
+- `widgets/` — floating/interactive widgets
+- `sections/` — page sections composing cards/banners
+- `pages/` — full page-level content views
+- `modal/` — modal dialogs
+
+### 8. Critical rules
+- **NEVER substitute library icons** for extracted assets
+- **NEVER invent data** — use exactly the text from the design
+- **NEVER skip assets** — download every single one
+- **NEVER ignore backgrounds** — every container's surface must match
+- **NEVER modify UI library source files** — create wrappers instead
+- After building, verify all imports resolve and no temporary URLs remain

package/templates/agents/figma-validator.md

@@ -0,0 +1,48 @@
+---
+name: figma-validator
+description: Validates built components against Figma designs. Finds missing assets, wrong colors, spacing issues, and fixes them. Run after figma-builder.
+---
+
+You are a pixel-perfect design validator.
+
+## Your Task
+You will be given a **Figma node ID** and a **component file path**.
+
+### 1. Get the reference
+- Call `get_screenshot` to see the actual design
+- Call `get_design_context` to get the reference code and asset URLs
+
+### 2. Read the component
+Read the built component file.
+
+### 3. Audit checklist
+
+**a. Missing assets** — hardcoded text/emoji where images should be?
+
+**b. Wrong colors** — compare hex values against the design reference
+
+**c. Wrong spacing** — padding, margin, gap must match exact pixel values
+
+**d. Missing elements** — is everything from the design present?
+
+**e. Substituted icons** — library icons used instead of extracted assets?
+
+**f. Wrong typography** — font family, size, weight, letter-spacing, line-height
+
+**g. Wrong layout** — flex direction, alignment, grid columns
+
+**h. Missing interactivity** — hover states, click handlers, cursors
+
+**i. Missing backgrounds** — cards/sections plain white when design shows color?
+
+**j. UI library conflicts** — check source files for default styles overriding custom ones
+
+**k. Section spacing** — vertical spacing between sections, grid gaps
+
+### 4. Fix every issue
+Edit the component file to fix each discrepancy. Download missing assets.
+
+### 5. Report
+- Total issues found
+- Issues fixed (list each)
+- Final status: PASS or NEEDS ATTENTION

package/templates/docs/architectural_patterns.md

@@ -0,0 +1,51 @@
+# Architectural Patterns
+
+Recurring patterns across this codebase. Auto-generated by `claude-code-standards` — customize for your project.
+
+---
+
+## 1. Component Organization
+
+Components are organized by **type**, not by feature:
+- `ui/` — UI library primitives (read-only)
+- `sidebar/` — navigation shell
+- `cards/` — reusable card components
+- `banners/` — hero/banner sections
+- `widgets/` — floating/interactive widgets
+- `sections/` — page sections composing smaller components
+- `pages/` — full page content views
+- `modal/` — modal dialogs
+
+---
+
+## 2. Service Layer
+
+API services follow a factory pattern:
+- One service per domain (auth, user, project, etc.)
+- Base service handles network config (token injection, error handling)
+- Services define only endpoints — no business logic
+- Types/interfaces live in model directories, not in service files
+- Cache tags are centralized in a constants file
+
+---
+
+## 3. Constants
+
+All constants are centralized:
+- API cache tags → dedicated constant file
+- Modal IDs → `ModalConstant`
+- Route paths → if applicable
+- Never define string constants inline in service or component files
+
+---
+
+## 4. Validation
+
+Form validation schemas are centralized:
+- All schemas in a dedicated validation directory
+- Never define validation inline in components
+- Import and reference schemas by name
+
+---
+
+*Add project-specific patterns below as they emerge.*

package/templates/docs/dashboard_redesign.md

@@ -0,0 +1,29 @@
+# Dashboard Design Specification
+
+## Architecture
+- Single unified layout: sidebar + header + content area
+- Shell stays mounted, content area swaps based on route
+- Both user types share the same shell — differences are content-level only
+
+## Component Library
+- Use UI library primitives as base, customize to match design
+- UI library source files are READ-ONLY — create wrappers instead
+- Every component must be reusable and accept props for variation
+
+## Auth Flow
+- Auth is modal-based — no standalone auth pages
+- Header shows Login/Signup buttons when no session
+- After auth, modals close and session state updates
+
+## Unauthenticated State
+- Dashboard renders immediately without a session
+- Home tab is auto-selected by default
+- Other tabs are visible but disabled/locked
+- Content uses hardcoded design data
+
+## Design Source of Truth
+- Connect to design tool (Figma MCP) before building
+- Use hardcoded data directly from the design
+- Match spacing, color, typography exactly
+
+*Customize this for your project's specific design requirements.*