Cursor Rules Template

# Cursor Rules Template

A reusable, modular Cursor ruleset template for consistent development workflows across projects.

## Table of Contents

- [What This Repo Is](#what-this-repo-is)
- [What Problems It Solves](#what-problems-it-solves)
- [Quick Start](#quick-start)
  - [Option 1: Native Project Rules & Commands](#option-1-native-project-rules--commands-recommended)
  - [Option 2: AGENTS.md](#option-2-agentsmd-simpler-alternative)
- [Modular Rule Structure](#modular-rule-structure)
  - [nextjs-stack](#nextjs-stack)
  - [ui-a11y](#ui-a11y)
  - [backend-security](#backend-security)
  - [quality-bar](#quality-bar)
- [Recommended Workflow](#recommended-workflow)
- [Available Commands](#available-commands)
- [How to Customize Safely](#how-to-customize-safely)
- [Adapting for Other Stacks](#adapting-for-other-stacks)
- [Contentstack Vibe Docs Integration](#contentstack-vibe-docs-integration)
- [License](#license)

## What This Repo Is

This repository contains a complete "Cursor rules kit" with:

- **Modular Project Rules**: Focused, scoped standards organized by concern
- **Project Commands**: Reusable workflows for common development tasks
- **AGENTS.md**: Simple alternative for projects preferring a single file

## What Problems It Solves

- **Consistency**: Enforces the same standards across all projects
- **Speed**: Pre-configured commands for common tasks
- **Quality**: Built-in checks for build, lint, types, and accessibility
- **Modularity**: Rules are focused and scoped, making them easier for Cursor to reason about
- **Onboarding**: Clear structure and templates for new contributors

## Quick Start

### Option 1: Native Project Rules & Commands (Recommended)

1. **Copy the `.cursor` folder** into your project:

   ```bash
   cp -r .cursor /path/to/your/project/
   ```

2. **Cursor will automatically detect**:

   - Rules in `.cursor/rules/*/RULE.md`
   - Commands in `.cursor/commands/*.md`

3. **Use commands** by typing `/` in chat (e.g., `/plan`, `/implement`, `/dod`)

### Option 2: AGENTS.md (Simpler Alternative)

1. **Copy AGENTS.md** to your project root:

   ```bash
   cp AGENTS.md /path/to/your/project/
   ```

2. **Copy commands folder**:

   ```bash
   cp -r .cursor/commands /path/to/your/project/.cursor/
   ```

3. **Cursor will automatically detect**:

   - `AGENTS.md` in your project root
   - Commands in `.cursor/commands/*.md`

4. **Use commands** by typing `/` in chat (e.g., `/plan`, `/implement`, `/dod`)

## Modular Rule Structure

Rules are organized into focused modules, each with a specific purpose and scope:

### `nextjs-stack`

**Purpose**: Next.js 16 App Router standards and TypeScript requirements

**When it applies**: Always (core framework rules)

**Covers**:

- Next.js 16 with App Router
- TypeScript everywhere
- Server components preference
- Server Actions and Route Handlers
- Tailwind CSS v4

**Scoped to**: All TypeScript/JavaScript files

### `ui-a11y`

**Purpose**: UI component standards, semantic HTML, and accessibility

**When it applies**: When working with UI components and pages

**Covers**:

- shadcn/ui as primary component system
- lucide-react for icons
- Semantic HTML
- WCAG compliance
- Keyboard navigation
- ARIA attributes

**Scoped to**: Component files and page layouts

### `backend-security`

**Purpose**: Backend security, validation, and error handling

**When it applies**: Always (security is non-negotiable)

**Covers**:

- Server-side input validation
- Secrets handling (never expose to client)
- Explicit error handling
- Data access layers
- Contained side effects

**Scoped to**: API routes, Server Actions, Route Handlers

### `quality-bar`

**Purpose**: Code quality standards and architecture principles

**When it applies**: Always (quality is non-negotiable)

**Covers**:

- DRY, concise, intentional structure
- Build, lint, typecheck must pass
- No `any` type
- No unit tests by default
- Clear architecture over quick solutions
- Separation of concerns

**Scoped to**: All code

## Recommended Workflow

Use this workflow for feature development:

1. **`/plan`** - Create a short implementation plan, ask clarifying questions
2. **`/implement`** - Implement in small, safe diffs following all rules
3. **`/dod`** - Verify implementation (build, lint, types, accessibility)
4. **`/prepare-pr`** - Generate PR summary with changes, risks, and test steps

For debugging:

1. **`/debug`** - Find root cause, propose fix, implement, validate

For code maintenance:

- **`/refactor`** - Improve code structure without changing behavior
- **`/cleanup`** - Remove unused code, fix formatting
- **`/audit-a11y`** - Review accessibility compliance
- **`/deps`** - Review and justify dependency changes

## Available Commands

Commands are stored as individual `.md` files in `.cursor/commands/`. Cursor automatically detects them when you type `/` in the chat input box.

**Core workflow commands:**

- `/plan` - Create short implementation plan and ask clarifying questions
- `/i

... (truncated)