@mikulgohil/ai-kit 1.0.0

package/guides/when-to-use-ai.md

@@ -0,0 +1,44 @@
+# When to Use AI (and When Not To)
+
+## Great for AI ✅
+
+| Task | Why |
+|------|-----|
+| Scaffolding components/pages | Repetitive structure, follows patterns |
+| Writing tests | Tedious, pattern-based |
+| Bug investigation | AI can trace data flow faster than reading |
+| Code review | Catches things humans miss |
+| Refactoring | Structural changes with clear rules |
+| Understanding unfamiliar code | AI explains faster than reading docs |
+| Boilerplate (types, configs, API clients) | Pattern-heavy, low creativity needed |
+| Documentation | Summarizing what code does |
+
+## Not Great for AI ❌
+
+| Task | Why |
+|------|-----|
+| Architecture decisions | Needs business context AI doesn't have |
+| Complex state machines | Hard to describe in a prompt |
+| Design/UX decisions | AI can implement designs, not create them |
+| Security-critical auth flows | Too risky to trust AI alone |
+| Performance tuning (without data) | Needs profiling, not guessing |
+| Merge conflict resolution | AI doesn't know your intent |
+
+## Decision Flow
+
+```
+Is this task...
+├── Repetitive/Pattern-based? → Use AI
+├── Creative/Design? → Do it yourself, use AI to implement
+├── Security-critical? → Do it yourself, use AI to review
+├── Investigation? → Use AI to explore, verify yourself
+└── Architectural? → Discuss with team, use AI for implementation
+```
+
+## Cost-Effective Usage
+
+1. **One focused task per conversation** — don't let conversations drift
+2. **Point to files** — "read src/X.tsx" is cheaper than pasting code
+3. **Use slash commands** — they include the right context automatically
+4. **Don't iterate forever** — if AI can't get it in 2 tries, take over
+5. **Review before accepting** — faster to fix during review than debug later

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mikulgohil/ai-kit",
+  "version": "1.0.0",
+  "description": "AI-assisted development setup kit. Auto-detects your tech stack and generates tailored CLAUDE.md, .cursorrules, slash commands, and developer guides.",
+  "type": "module",
+  "bin": {
+    "ai-kit": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "commands",
+    "guides",
+    "docs-scaffolds"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "claude-code",
+    "cursor",
+    "developer-tools",
+    "cli",
+    "nextjs",
+    "tailwind",
+    "sitecore"
+  ],
+  "author": "Mikul Gohil",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mikulgohil/ai-kit.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "fs-extra": "^11.0.0",
+    "ora": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/claude-md/base.md

@@ -0,0 +1,173 @@
+# Core Rules
+
+## Workflow
+1. **Read before writing** — always read existing files before modifying
+2. **Understand → Plan → Code** — never jump straight to implementation
+3. **Ask when unclear** — if the task is ambiguous, ask clarifying questions before proceeding
+4. **Stay in scope** — only change what was requested, no unsolicited refactors
+
+## Prompt Quality Guard
+
+When a developer's request is vague or missing critical context, you MUST push back before proceeding. This prevents wasted time and bad output.
+
+**If the request is missing a target file or scope**, ask:
+> "Which file or component should I focus on?"
+
+**If the request is ambiguous** (e.g., "fix this", "make it work", "improve this"), ask 1-2 targeted questions:
+> "What specifically is broken — what's the expected vs actual behavior?"
+
+**If the request could produce very different outputs** (e.g., "create a component"), ask for constraints:
+> "Should this be a Server or Client Component? What props does it need?"
+
+**Never guess when you can ask.** A 10-second clarification saves 10 minutes of wrong output.
+
+### Self-Enforcement Rules
+- When creating or modifying a component with >50 lines or >3 props, you MUST create/update its `.docs.md` file — do not skip this even if the developer doesn't ask for it
+- When fixing a bug, you MUST add a test that reproduces the bug before fixing it
+- When generating code, you MUST add JSDoc comments to all exported functions
+- After completing a task that modifies a documented component, you MUST append an entry to the component's Change Log
+- When you encounter a `// TODO` without a ticket number, flag it to the developer
+
+## Coding Standards
+
+These standards are enforced across all projects to ensure consistency.
+
+### Naming Conventions
+- **Components**: PascalCase (`ProductCard.tsx`, `HeroBanner.tsx`)
+- **Utilities/Hooks**: camelCase (`useAuth.ts`, `formatDate.ts`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_RETRY_COUNT`)
+- **CSS classes**: kebab-case for custom classes, Tailwind utilities where available
+- **Files**: Match the default export name — one component per file
+
+### Code Structure
+- Keep components under 200 lines — split into sub-components if larger
+- Colocate related files (component, types, tests, styles, docs) in the same directory
+- Separate business logic from UI — use custom hooks for logic
+- Props interface defined directly above or alongside the component
+
+### Component Documentation
+- **Doc file required for complex components** — components over 50 lines OR with more than 3 props must have a colocated `ComponentName.docs.md` or `docs/components/ComponentName.md`
+- **Simple components** (≤50 lines AND ≤3 props) — a JSDoc comment above the component is sufficient; no separate doc file needed
+- **Doc file reference in component** — when a doc file exists, add a comment at the top:
+  ```
+  // Docs: ./ComponentName.docs.md
+  ```
+- **Doc file contents** — include: purpose, props table, usage examples, edge cases, design decisions
+- **Update log** — every modification to a documented component must be logged at the bottom of its doc file:
+  ```
+  ## Change Log
+  - YYYY-MM-DD: [what changed] — [why]
+  ```
+- If a complex component lacks a doc file when you modify it, create one
+
+### Code Comments
+- Add a brief JSDoc comment above every exported function and component explaining its purpose
+- Comment non-obvious logic — if you had to think about it, the next developer will too
+- Use `// TODO(author):` with a name for anything intentionally deferred
+- Do NOT add obvious comments like `// increment counter` — comment the *why*, not the *what*
+- Add `@example` in JSDoc for utility functions showing input → output
+
+### Import Order
+1. External packages (`react`, `next/...`, third-party)
+2. Internal shared utilities (`@/lib`, `@/utils`, `@/hooks`)
+3. Local relative imports (`./`, `../`)
+4. Type imports (use `import type` for type-only imports)
+
+### Error Handling
+- Always handle error states in components — never show blank screens
+- Use error boundaries for unexpected failures
+- Log errors with context (what failed, what input caused it)
+- Show user-friendly messages, not raw error strings
+
+### Accessibility
+- Use semantic HTML (`<button>`, `<nav>`, `<main>`, `<section>`)
+- Add `alt` text to all images
+- Ensure keyboard navigation works for interactive elements
+- Use ARIA labels when semantic HTML isn't sufficient
+- Maintain color contrast ratio of at least 4.5:1
+
+### Git Practices
+- Write descriptive commit messages: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+- One logical change per commit
+- Never commit `.env`, secrets, or `node_modules`
+- Pull and rebase before pushing
+
+### Performance Awareness
+- Avoid unnecessary re-renders — memoize expensive computations with `useMemo`, callbacks with `useCallback`
+- Lazy load heavy components and below-the-fold content
+- Prefer Server Components for data-heavy, non-interactive sections
+- Watch for N+1 data fetching — batch where possible
+- Images must use `next/image` or equivalent with proper width/height/loading attributes
+
+### Dependency Discipline
+- Do NOT add new packages without checking if an existing dependency already solves the problem
+- Prefer native browser APIs over utility libraries when reasonable (e.g., `URLSearchParams` over `qs`)
+- Pin dependency versions — avoid `^` or `~` for critical packages
+- When adding a new dependency, note the reason in the component's doc file or PR description
+
+## Code Quality
+- Match existing patterns, naming conventions, and file structure
+- Keep changes minimal — don't refactor surrounding code unless asked
+- No placeholder or TODO comments — write complete, working code
+- Handle edge cases at system boundaries (user input, API responses)
+- No unnecessary abstractions — 3 similar lines > premature helper function
+
+## Safety
+- Never commit secrets, API keys, or credentials — use environment variables
+- Never run destructive git commands without confirmation
+- Check for XSS, injection, and OWASP Top 10 vulnerabilities in any code you write
+- Validate all external input; trust internal function contracts
+
+### Testing Expectations
+- Every new component and utility should have a corresponding test file
+- Test file colocated: `ComponentName.test.tsx` or `utilName.test.ts`
+- Cover: happy path, error states, edge cases, accessibility (role queries)
+- Use React Testing Library — test behavior, not implementation details
+- Mock external dependencies, not internal functions
+
+## File Conventions
+- Prefer editing existing files over creating new ones
+- Maximum 3–7 files changed per task unless explicitly approved
+- Document significant changes in `docs/` if the directory exists
+- When modifying a component, update its doc file's change log
+
+## Commands
+Available at: `.claude/commands/`
+
+**Getting Started**
+- `/prompt-help` — Interactive prompt builder (start here if unsure how to ask)
+- `/understand` — Explain code in detail
+
+**Building**
+- `/new-component` — Scaffold a new component with proper structure
+- `/new-page` — Scaffold a new page/route
+- `/api-route` — Scaffold an API route with validation, error handling, and auth
+- `/error-boundary` — Generate error boundaries, loading states, and fallback UI
+- `/extract-hook` — Extract component logic into a reusable custom hook
+- `/figma-to-code` — Structured Figma-to-code implementation workflow
+- `/design-tokens` — Design token management and mapping
+
+**Quality & Review**
+- `/review` — Deep code review following team standards
+- `/pre-pr` — Pre-PR checklist (type safety, console cleanup, a11y, security)
+- `/test` — Generate tests for a file or function
+- `/accessibility-audit` — WCAG 2.1 AA compliance check
+- `/security-check` — XSS, injection, secrets, and OWASP Top 10 review
+- `/responsive-check` — Responsive design audit (breakpoints, touch targets, overflow)
+- `/type-fix` — Fix TypeScript issues (replace `any`, add null checks, generate types)
+
+**Maintenance**
+- `/fix-bug` — Guided bug fix workflow
+- `/refactor` — Safe refactoring (split components, extract hooks, remove duplication)
+- `/optimize` — Performance optimization review
+- `/migrate` — Guided migration helper (Next.js, Tailwind, Sitecore upgrades)
+- `/dep-check` — Dependency audit (unused, outdated, security, bundle size)
+- `/sitecore-debug` — Sitecore XM Cloud debugging (placeholders, fields, GraphQL)
+
+**Workflow**
+- `/document` — Generate documentation for existing code
+- `/commit-msg` — Generate conventional commit message from staged changes
+- `/env-setup` — Generate .env.example and validate environment variables
+
+## Scripts
+{{scripts}}

package/templates/claude-md/figma.md

@@ -0,0 +1,62 @@
+# Figma-to-Code Workflow
+
+## Before Writing Any Code from a Figma Design
+
+1. **Extract design context** — Use Figma MCP `get_design_context` with the Figma node URL to get structured layout, colors, typography, and spacing
+2. **Get a visual reference** — Use `get_screenshot` to see what you're building
+3. **Identify reusable components** — Check `src/components/` for existing components that match parts of the design. Reuse, don't recreate.
+4. **Map design tokens** — Match Figma colors, spacing, and typography to the project's Tailwind theme tokens. Never hardcode values.
+
+## Design Token Rules
+
+- **Colors**: Use semantic tokens (`bg-primary-500`, `text-neutral-800`) — never hardcode hex values (`#3b82f6`)
+- **Spacing**: Use scale tokens (`p-4`, `gap-6`, `mt-12`) — never use arbitrary values (`mt-[47px]`)
+- **Typography**: Use type scale tokens (`text-h1`, `text-b1`) — never set raw `font-size`
+- **Border radius**: Use named tokens (`rounded-card`, `rounded-button`) — not arbitrary `rounded-[8px]`
+- **Shadows/Effects**: Use predefined shadow tokens if available
+
+If a Figma value doesn't match any existing token, use the **nearest** token — don't create arbitrary values. Flag to the developer that the design uses an off-scale value.
+
+## Component Mapping
+
+Before creating a new component:
+1. Read existing components in `src/components/` to check for matches
+2. Map Figma component variants to React props (e.g., Figma variant "Style=Primary" → `variant="primary"`)
+3. Match Figma layer names to semantic HTML elements (`<nav>`, `<section>`, `<article>`, `<button>`)
+4. Preserve Figma Auto Layout as flexbox/grid — do not use absolute positioning
+5. Figma's "Spacing between items" = CSS `gap`, Figma's "Padding" = CSS `padding`
+
+## Content Container Pattern
+
+Full-width backgrounds with constrained content:
+```tsx
+<div className="w-full bg-neutral-100">
+  <div className="max-w-[1320px] mx-auto w-full px-4 md:px-6 lg:px-0">
+    {/* content */}
+  </div>
+</div>
+```
+
+## Responsive Implementation
+
+- **Never assume** mobile is "desktop but smaller" — check every breakpoint in Figma separately
+- Mobile may have completely different layouts (row → stack, hidden elements, different spacing)
+- Implement mobile-first: base styles → `sm:` → `md:` → `lg:` → `xl:`
+- Verify all breakpoints independently against Figma
+
+## Visual Verification (Mandatory)
+
+After generating a component from Figma:
+1. Compare your output visually against the Figma design
+2. Check: layout/spacing accuracy (95%+), color accuracy (98%+), typography (90%+)
+3. Verify both desktop (1440px) and mobile (375px) if responsive
+
+## Common Figma-to-Code Mistakes
+
+- Don't hardcode colors — use design tokens
+- Don't use arbitrary Tailwind values when a token exists
+- Don't ignore Auto Layout — it maps directly to flex/grid
+- Don't skip visual verification
+- Don't create new components when existing ones can be reused
+- Don't forget hover/focus/active states shown in Figma variants
+- Don't ignore spacing between sections — Figma padding/gap = CSS padding/gap

package/templates/claude-md/monorepo.md

@@ -0,0 +1,17 @@
+# Monorepo
+
+## Structure
+- This is a monorepo — be aware of package boundaries
+- Shared packages live in `packages/` — app-specific code lives in `apps/`
+- Import shared code through package names, not relative paths across boundaries
+
+## Rules
+- Changes to shared packages affect all consumers — be cautious
+- Run commands from the repo root using the workspace tool (e.g., `{{packageManager}} run build --filter=<package>`)
+- Don't duplicate dependencies across packages — hoist shared deps to root
+- Check which packages are affected before making cross-cutting changes
+
+## Common Mistakes to Avoid
+- Don't use relative imports (`../../packages/ui`) — use package names (`@scope/ui`)
+- Don't modify shared packages without checking downstream impact
+- Don't forget to update the workspace dependency if you change a shared package's exports

package/templates/claude-md/nextjs-app-router.md

@@ -0,0 +1,29 @@
+# Next.js App Router
+
+## Conventions
+- Use Server Components by default — only add `'use client'` when needed (event handlers, hooks, browser APIs)
+- Colocate `loading.tsx`, `error.tsx`, and `not-found.tsx` alongside `page.tsx`
+- Use `generateMetadata` for SEO — never hardcode `<title>` or `<meta>` tags
+- Prefer `fetch()` with `next: { revalidate }` for data fetching in Server Components
+- Use Route Handlers (`app/api/`) for API endpoints, not Pages Router API routes
+
+## Data Fetching
+- Server Components: fetch directly at the component level, no `useEffect`
+- For mutations: use Server Actions (`'use server'`) or Route Handlers
+- Always handle loading and error states with Suspense boundaries or file conventions
+
+## File Structure
+```
+app/
+  layout.tsx          ← Root layout (wrap with providers here)
+  page.tsx            ← Home page
+  (group)/            ← Route groups for organization
+  [slug]/page.tsx     ← Dynamic routes
+  api/                ← Route Handlers
+```
+
+## Common Mistakes to Avoid
+- Don't use `useEffect` for data fetching in Server Components
+- Don't import server-only code in Client Components
+- Don't use `router.push` for simple navigation — use `<Link>`
+- Don't forget to add `loading.tsx` for route transitions

package/templates/claude-md/nextjs-pages-router.md

@@ -0,0 +1,28 @@
+# Next.js Pages Router
+
+## Conventions
+- Use `getStaticProps` for static data, `getServerSideProps` for per-request data
+- Keep API routes in `pages/api/` — use proper HTTP method checking
+- Use `next/head` for page-level `<title>` and `<meta>` tags
+- Use `next/link` and `next/image` for navigation and images
+
+## Data Fetching
+- `getStaticProps` → build-time data (use `revalidate` for ISR)
+- `getServerSideProps` → per-request server-side data
+- `getStaticPaths` → pre-render dynamic routes
+- Client-side: use SWR or React Query, not raw `useEffect` + `fetch`
+
+## File Structure
+```
+pages/
+  _app.tsx            ← App wrapper (providers, global styles)
+  _document.tsx       ← Custom HTML document
+  index.tsx           ← Home page
+  [slug].tsx          ← Dynamic routes
+  api/                ← API routes
+```
+
+## Common Mistakes to Avoid
+- Don't mix App Router and Pages Router patterns unless this is a hybrid project
+- Don't return large payloads from `getServerSideProps` — serialize only what the page needs
+- Don't forget to handle the `fallback` prop in `getStaticPaths`

package/templates/claude-md/sitecore-xmc.md

@@ -0,0 +1,46 @@
+# Sitecore XM Cloud
+
+## Architecture
+- This is a headless CMS project using Sitecore XM Cloud with Next.js as the rendering host
+- Components receive data through Sitecore Layout Service via `ComponentRendering` props
+- Use `@sitecore-jss/sitecore-jss-nextjs` or `@sitecore-content-sdk/nextjs` for component bindings
+
+## Component Patterns
+```typescript
+// Standard Sitecore component pattern
+import { Text, RichText, Image, Link } from '@sitecore-jss/sitecore-jss-nextjs';
+import type { ComponentRendering, ComponentFields } from '@sitecore-jss/sitecore-jss-nextjs';
+
+interface MyComponentFields extends ComponentFields {
+  heading: Field<string>;
+  body: Field<string>;
+}
+
+type MyComponentProps = {
+  rendering: ComponentRendering;
+  fields: MyComponentFields;
+};
+
+const MyComponent = ({ fields }: MyComponentProps): JSX.Element => (
+  <div>
+    <Text field={fields.heading} tag="h2" />
+    <RichText field={fields.body} />
+  </div>
+);
+
+export default MyComponent;
+```
+
+## Rules
+- Always use Sitecore field helpers (`<Text>`, `<RichText>`, `<Image>`, `<Link>`) — never render field values directly
+- This enables Experience Editor / Pages inline editing
+- Component names must match Sitecore rendering item names exactly
+- Place components in `src/components/` following existing naming patterns
+- Use `withDatasourceCheck` HOC for components that require a datasource
+- GraphQL queries go in `.graphql` files alongside components
+
+## Common Mistakes to Avoid
+- Don't render `fields.heading.value` directly — use `<Text field={fields.heading} />`
+- Don't hardcode content that should come from Sitecore fields
+- Don't forget to register new components in the component factory
+- Don't use `getStaticProps` directly — use Sitecore's built-in SSG/SSR integration

package/templates/claude-md/tailwind.md

@@ -0,0 +1,18 @@
+# Tailwind CSS
+
+## Conventions
+- Use Tailwind utility classes — avoid writing custom CSS unless absolutely necessary
+- Follow mobile-first responsive design: `base` → `sm:` → `md:` → `lg:` → `xl:`
+- Use the project's design tokens from `tailwind.config` (colors, spacing, fonts) — don't use arbitrary values like `text-[#ff0000]` when a token exists
+- Group utility classes logically: layout → spacing → typography → colors → effects
+
+## Patterns
+- Use `cn()` or `clsx()` for conditional classes if available in the project
+- Extract repeated class combinations into component props, not `@apply`
+- Use `@apply` sparingly — only in global styles for base elements
+
+## Common Mistakes to Avoid
+- Don't use inline styles when a Tailwind class exists
+- Don't use arbitrary values (`w-[347px]`) — use nearest standard value or define a token
+- Don't forget dark mode variants if the project supports it
+- Don't mix Tailwind with component-library CSS — pick one approach per component

package/templates/claude-md/typescript.md

@@ -0,0 +1,19 @@
+# TypeScript
+
+## Conventions
+- Use explicit types for function parameters and return values
+- Prefer `interface` for object shapes, `type` for unions and intersections
+- Use `unknown` over `any` — narrow types with type guards
+- No `@ts-ignore` or `@ts-expect-error` without a comment explaining why
+
+## Patterns
+- Define prop types directly above or alongside the component
+- Use `satisfies` for type-safe object literals when the type is known
+- Use discriminated unions for state management (loading/success/error)
+- Prefer `as const` for literal type inference
+
+## Common Mistakes to Avoid
+- Don't use `any` to bypass type errors — fix the underlying type issue
+- Don't create unnecessary generic types — use them only when the type genuinely varies
+- Don't duplicate types — import from a shared types file
+- Don't use optional chaining as a substitute for proper null checking

package/templates/cursorrules/base.md

@@ -0,0 +1,84 @@
+# Project Rules
+
+You are working on **{{projectName}}** — a {{framework}} project.
+
+## Prompt Quality Guard
+- If the request is vague (e.g., "fix this", "make it work"), ask 1-2 clarifying questions before proceeding
+- If no target file is specified, ask which file to focus on
+- Never guess when you can ask — a quick clarification saves rework
+
+## Self-Enforcement
+- When creating/modifying complex components (>50 lines or >3 props), always create/update the `.docs.md` file
+- When fixing bugs, add a regression test before fixing
+- Always add JSDoc to exported functions in generated code
+- After modifying a documented component, append to its Change Log
+- Flag `// TODO` comments without ticket numbers
+
+## Coding Standards
+
+These standards are enforced across all projects.
+
+### Naming
+- Components: PascalCase (`ProductCard.tsx`) | Utilities/Hooks: camelCase (`useAuth.ts`)
+- Constants: UPPER_SNAKE_CASE | CSS: kebab-case for custom, Tailwind where available
+- Files match default export name — one component per file
+
+### Structure
+- Components under 200 lines — split if larger
+- Colocate related files (component, types, tests, styles, docs)
+- Separate logic from UI — custom hooks for business logic
+- Import order: external → internal shared → local relative → type imports
+
+### Component Documentation
+- **Complex components** (>50 lines OR >3 props) must have a colocated doc file (`ComponentName.docs.md`)
+- **Simple components** (≤50 lines AND ≤3 props) — a JSDoc comment is sufficient; no separate doc file needed
+- When a doc file exists, add reference comment at top: `// Docs: ./ComponentName.docs.md`
+- Doc file includes: purpose, props, usage examples, edge cases, design decisions
+- Every modification to a documented component must be logged in the doc file's Change Log section
+- If a complex component lacks a doc file when modifying, create one
+
+### Code Comments
+- JSDoc comment above every exported function/component explaining purpose
+- Comment the *why*, not the *what* — skip obvious comments
+- Use `// TODO(author):` with a name for deferred items
+- Add `@example` in JSDoc for utility functions
+
+### Testing
+- Every new component/utility needs a colocated test file
+- Cover: happy path, error states, edge cases, accessibility
+- React Testing Library — test behavior, not implementation
+- Mock external deps, not internal functions
+
+### Performance
+- Memoize expensive computations (`useMemo`) and callbacks (`useCallback`)
+- Lazy load heavy/below-fold components
+- Use `next/image` with proper width/height/loading
+- Watch for N+1 data fetching — batch where possible
+
+### Dependencies
+- Check if an existing dep solves the problem before adding new ones
+- Prefer native browser APIs over utility libraries when reasonable
+- Note the reason for new dependencies in the doc file or PR
+
+### Quality
+- Read existing code before modifying — match patterns, naming, and structure
+- Keep changes minimal and scoped to the request
+- No placeholder TODOs — write complete, working code
+- Handle edge cases at boundaries (user input, APIs), trust internal code
+- Maximum 3–7 files per change unless approved
+- Always handle error states — never show blank screens
+- Use semantic HTML, add alt text, ensure keyboard navigation
+- When modifying a component, update its doc file's change log
+
+### Safety
+- Never commit secrets or credentials
+- Check for XSS, injection, and OWASP Top 10 vulnerabilities
+- Use environment variables for all config values
+
+### Git
+- Commit messages: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`
+- One logical change per commit
+- Never commit `.env`, secrets, or `node_modules`
+
+## Scripts
+{{scripts}}

package/templates/cursorrules/figma.md

@@ -0,0 +1,32 @@
+# Figma-to-Code Rules
+
+## Workflow
+1. Extract design context from Figma (MCP or screenshot) before coding
+2. Map Figma values to project's Tailwind design tokens — never hardcode hex/px
+3. Check `src/components/` for reusable components before creating new ones
+4. Preserve Auto Layout as flexbox/grid — no absolute positioning
+5. Verify output visually against Figma (desktop 1440px + mobile 375px)
+
+## Token Mapping
+- Colors: semantic tokens (`bg-primary-500`) not hex (`#3b82f6`)
+- Spacing: scale tokens (`p-4`, `gap-6`) not arbitrary (`mt-[47px]`)
+- Typography: type scale (`text-h1`, `text-b1`) not raw font-size
+- Border radius: named tokens (`rounded-card`) not arbitrary
+
+## Component Mapping
+- Figma variants → React props (e.g., "Style=Primary" → `variant="primary"`)
+- Figma layer names → semantic HTML (`<nav>`, `<section>`, `<button>`)
+- Figma spacing = CSS gap/padding, Figma constraints = flexbox alignment
+- Reuse existing components — don't recreate what already exists
+
+## Responsive
+- Never assume mobile = smaller desktop — check each breakpoint in Figma
+- Implement mobile-first: base → sm → md → lg → xl
+- Mobile may have different layout, hidden elements, different spacing
+
+## Mistakes to Avoid
+- No hardcoded colors or spacing — always use tokens
+- No skipping visual verification
+- No arbitrary Tailwind values when a token exists
+- No absolute positioning where flex/grid works
+- No new components when existing ones match

package/templates/cursorrules/monorepo.md

@@ -0,0 +1,7 @@
+# Monorepo Rules
+
+- Respect package boundaries — import through package names, not relative paths
+- Changes to shared packages affect all consumers — be cautious
+- Run commands from root: `{{packageManager}} run build --filter=<package>`
+- Don't duplicate dependencies — hoist shared deps to root
+- Check downstream impact before modifying shared packages

package/templates/cursorrules/nextjs-app-router.md

@@ -0,0 +1,8 @@
+# Next.js App Router Rules
+
+- Default to Server Components — only use `'use client'` for interactivity
+- Use `generateMetadata` for SEO, not hardcoded `<head>` tags
+- Colocate `loading.tsx`, `error.tsx`, `not-found.tsx` with pages
+- Data fetching: use `fetch()` in Server Components, Server Actions for mutations
+- Use `<Link>` for navigation, `next/image` for images
+- No `useEffect` for data fetching in Server Components

package/templates/cursorrules/nextjs-pages-router.md

@@ -0,0 +1,7 @@
+# Next.js Pages Router Rules
+
+- Use `getStaticProps` for static data, `getServerSideProps` for per-request data
+- API routes in `pages/api/` with proper HTTP method checking
+- Use `next/head` for page metadata, `next/link` for navigation
+- Client-side data: use SWR or React Query, not raw `useEffect` + `fetch`
+- Handle `fallback` in `getStaticPaths` for dynamic routes

package/templates/cursorrules/sitecore-xmc.md

@@ -0,0 +1,9 @@
+# Sitecore XM Cloud Rules
+
+- Use Sitecore field helpers (`<Text>`, `<RichText>`, `<Image>`, `<Link>`) — never render `.value` directly
+- Component names must match Sitecore rendering items exactly
+- Use `withDatasourceCheck` HOC for datasource-dependent components
+- Register new components in the component factory
+- GraphQL queries go in `.graphql` files alongside components
+- Don't use `getStaticProps` directly — use Sitecore's SSG/SSR integration
+- Don't hardcode content that should come from Sitecore fields