feat: add cursor rules

[Copilot]

Adds comprehensive Cursor IDE rules to improve AI-generated code quality by enforcing repository conventions. Rules are organized into focused, composable files following Cursor's best practices with frontmatter metadata for intelligent application.

Structure

Created .cursorrules/ directory with 8 focused rule files (~823 total lines):

1. README.md (49 lines) - Main entry point and overview
2. naming-conventions.md (94 lines) - File and variable naming with real codebase examples
3. testing.md (92 lines) - Testing requirements per package
4. styling.md (108 lines) - Frontend styling with Tailwind v4 semantic tokens
5. validation.md (88 lines) - Zod validation patterns
6. development.md (146 lines) - Development workflow and commands
7. accessibility.md (160 lines) - Accessibility standards referencing skills/a11y-audit/SKILL.md
8. git-conventions.md (82 lines) - Branch and commit conventions

All rules are under 500 lines and include concrete examples from the actual codebase.

Intelligent Application Modes

Each rule includes YAML frontmatter metadata following Cursor's official guidelines:

Always Apply (alwaysApply: true) - Applied to every chat session:

• README.md - Project overview
• naming-conventions.md - Naming standards
• testing.md - Testing requirements

Apply Intelligently (agent decides based on description):

• development.md - Workflow and commands
• git-conventions.md - Branch and commit conventions

Apply to Specific Files (globs pattern matching):

• styling.md → packages/web/**/*.{ts,tsx,css}
• validation.md → packages/backend/**/*.ts and validators
• accessibility.md → packages/web/**/*.{ts,tsx}

Key Rules

Naming Conventions

• Hooks: camelCase (useSupertokensAuth.ts)
• TypeScript files: period-separated (compass.event.parser.ts, not compassEventParser.ts)
• Booleans: is prefix (isLoading, isError)
• Functions: Prefer arrow functions (const fn = () => ...) over traditional function declarations

Testing Requirements

• yarn test:web for web changes (~15s)
• yarn test:backend for backend changes (~15s)
• yarn test:core for core changes (~2s)
• All tests must pass before completion

Code Style

• Tailwind semantic colors only (bg-bg-primary, text-text-light, never raw colors like bg-blue-300)
• Zod for validation
• Module aliased imports (@web/*, @backend/*, @core/*)
• No barrel files (index.ts)

Accessibility

• Comprehensive a11y standards referencing skills/a11y-audit/SKILL.md
• Semantic HTML, keyboard navigation, ARIA labels
• Testing with semantic queries

Additional Context

• Project structure (monorepo packages)
• Branch naming patterns (feature/, bug/, hotfix/, refactor/, docs/)
• Commit conventions (conventional commits)
• Development commands with expected timings
• Environment requirements

Examples

// Good: Hook naming
useSupertokensAuth.ts

// Good: TypeScript file naming
onboarding.storage.util.ts
compass.event.parser.ts

// Bad: TypeScript file naming
onboardingStorageUtil.ts
compassEventParser.ts

// Good: Function declarations
const handleClick = () => { ... }
const calculateTotal = (items: Item[]) => { ... }

// Bad: Function declarations
function handleClick() { ... }
function calculateTotal(items: Item[]) { ... }

// Good: Styling with semantic tokens
<div className="bg-bg-primary text-text-light border-border-primary">

// Bad: Styling with raw colors
<div className="bg-blue-300 text-gray-100">

Benefits

• Modular: Each rule focuses on a single concern
• Maintainable: Easy to update individual rules without affecting others
• Practical: Concrete examples from the actual codebase
• Composable: Rules can be referenced and reused in different contexts
• Complete: Covers naming, testing, styling, validation, a11y, and git conventions
• Intelligent: Context-aware application reduces noise and improves relevance
• Flexible: Support for always-apply, intelligent, file-specific, and manual (@-mention) modes

Original prompt

---

This section details on the original issue you should resolve

<issue_title>add cursor rules</issue_title>
<issue_description>### Priority

Medium (nice to have)

Feature Description

Create cursor rules files to help streamline code generation while using Cursor.

Include the following information, in addition to what is already in AGENTS.md

Naming Conventions
Hooks: camel-case. For example: useSupertokensAuth.ts and useSupertokensAuth.test.ts

Typescript: periods between works.

• Good example: compass.event.parser.ts and compass.event.parser.test.ts
• Bad example: onboardingStorage.util.ts. It should be onboarding.storage.util.ts

(+ the existing conventions listed in agents.md

Testing
If changed a file in packages/web, ensure all web tests pass before completion: yarn test web

If changed a file in packages/backend, ensure all backend tests pass before completion: yarn test backend

If changed a file in packages/core, ensure all core tests pass before completion: yarn test core

Use Case

This'll save Cursor users time by having the LLMs generate higher quality code

Additional Context

https://cursor.com/docs/context/rules#rule-folder-structure</issue_description>

<agent_instructions>Take some liberties to help make sane defaults to ensure code quality. review the existing conventions, compare it to the best practices listed in the cursor site, and make your best judgement after thinking hard. please</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes add cursor rules #1405

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[tyler-dane]

@copilot Break this out into separate rules according to guidelines

Keep rules under 500 lines
Split large rules into multiple, composable rules
Provide concrete examples or referenced files
Avoid vague guidance. Write rules like clear internal docs
Reuse rules when repeating prompts in chat

---

Also add a rule to address the accessibility requirements, refer the a11y SKILL.md

---

Example of rule for Standards for components for frontend validation

This rule provides standards for frontend components:

When working in components directory:

Always use Tailwind for styling
Use Framer Motion for animations
Follow component naming conventions
This rule enforces validation for API endpoints:

In API directory:

Use zod for all validation
Define return types with zod schemas
Export types generated from schemas

[tyler-dane]

not true, remove this line

[tyler-dane]

@copilot remove the following - Do NOT run yarn test (full suite) - it fails in restricted environments due to MongoDB

[Copilot]

Done in commit 7d3742b. Removed the line about MongoDB test failures from the testing rules.

[tyler-dane]

@copilot remove the following - Do NOT run yarn test (full suite) - it fails in restricted environments due to MongoDB

[tyler-dane]

@copilot

Break this out into separate rules according to guidelines

Keep rules under 500 lines
Split large rules into multiple, composable rules
Provide concrete examples or referenced files
Avoid vague guidance. Write rules like clear internal docs
Reuse rules when repeating prompts in chat

Also add a rule to address the accessibility requirements, refer the a11y SKILL.md

Example of rule for Standards for components for frontend validation

This rule provides standards for frontend components:

When working in components directory:

Always use Tailwind for styling
Use Framer Motion for animations
Follow component naming conventions
This rule enforces validation for API endpoints:

In API directory:

Use zod for all validation
Define return types with zod schemas
Export types generated from schemas

[Copilot]

Done in commits da6b060 and 7d3742b.

Split .cursorrules into 8 composable rule files:

• README.md (44 lines) - Main entry point
• naming-conventions.md (65 lines) - File/variable naming with codebase examples
• testing.md (81 lines) - Testing requirements per package
• styling.md (95 lines) - Tailwind semantic colors with concrete tokens
• validation.md (79 lines) - Zod validation patterns
• development.md (139 lines) - Dev workflow and commands
• accessibility.md (146 lines) - A11y standards referencing skills/a11y-audit/SKILL.md
• git-conventions.md (76 lines) - Branch/commit conventions

All rules are under 500 lines, include concrete examples from the codebase, and follow Cursor's guidelines for composable rules.

[Copilot]

@copilot Break this out into separate rules according to guidelines

Keep rules under 500 lines
...

Done in commits da6b060 and 7d3742b.

Created 8 focused, composable rule files following Cursor's guidelines:

• All rules under 500 lines (largest is 146 lines)
• Concrete examples from actual codebase files
• Added accessibility rule referencing skills/a11y-audit/SKILL.md
• Each rule focuses on a single concern
• Followed the validation/component pattern you provided

[tyler-dane]

@copilot

update the rules to follow the guidelines here:

https://cursor.com/docs/context/rules#how-rules-work

ensure they match the recommended rule anatomy, which use their frontmatter metadata and content. For example,

Always Apply	Apply to every chat session
Apply Intelligently	When Agent decides it's relevant based on description
Apply to Specific Files	When file matches a specified pattern
Apply Manually	When @-mentioned in chat (e.g., @my-rule)

[Copilot]

@copilot

update the rules to follow the guidelines here:
...

Done in commit 0bc5fad.

Updated all 8 rule files with frontmatter metadata following Cursor's official guidelines:

Application Modes:

• Always Apply (alwaysApply: true): README.md, naming-conventions.md, testing.md
• Apply Intelligently (no flag, agent decides): development.md, git-conventions.md
• Apply to Specific Files (globs patterns):
  • styling.md → packages/web/**/*.{ts,tsx,css}
  • validation.md → packages/backend/**/*.ts and validators
  • accessibility.md → packages/web/**/*.{ts,tsx}

Each rule now includes:

• description - Clear summary of rule content
• alwaysApply - Boolean for core rules
• globs - File patterns for context-specific application

[tyler-dane]

update to prefer arrow functions (const xyz = () ...) over function xyz()

[Copilot]

update to prefer arrow functions (const xyz = () ...) over function xyz()

Done in commit 420279c.

Added function declaration preference to naming-conventions.md:

• ✅ Prefer: const handleClick = () => { ... }
• ❌ Avoid: function handleClick() { ... }

Includes rationale (lexical this binding, consistent syntax) and exceptions for utility functions where hoisting is beneficial.

[Copilot]

Pull request overview

This PR adds comprehensive Cursor IDE rules to improve AI-generated code quality by enforcing repository conventions. The rules are organized into 8 focused, composable files (totaling ~823 lines) in a new .cursorrules/ directory, following Cursor's best practices with YAML frontmatter metadata for intelligent application.

Key Changes:

• Created structured rule files covering naming conventions, testing requirements, styling standards, validation patterns, development workflow, accessibility, and git conventions
• Implemented intelligent application modes using frontmatter (alwaysApply, globs patterns, and agent-decided)
• Included concrete examples from the actual codebase for practical guidance

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.cursorrules/README.md	Main entry point providing project overview and rule organization
.cursorrules/naming-conventions.md	Defines file and variable naming standards (hooks, TypeScript files, booleans, functions)
.cursorrules/testing.md	Specifies testing requirements per package with semantic query best practices
.cursorrules/styling.md	Frontend styling standards with Tailwind semantic tokens and module imports
.cursorrules/validation.md	Zod validation patterns for API endpoints and shared types
.cursorrules/development.md	Development workflow including setup, servers, testing, and environment requirements
.cursorrules/accessibility.md	Accessibility standards referencing skills/a11y-audit/SKILL.md
.cursorrules/git-conventions.md	Branch naming and commit message conventions with examples

[Copilot]

The pattern description is incorrect. Based on the index.css file, the actual pattern is: CSS variable --color-{category}-{name} maps to Tailwind class {property}-{category}-{name}. For example, --color-bg-primary becomes bg-bg-primary (not {category}-{category}-{name} as stated).

Suggested change

	The pattern is: CSS variable `--color-{category}-{name}` → Tailwind class `{category}-{category}-{name}`
	The pattern is: CSS variable `--color-{category}-{name}` → Tailwind class `{property}-{category}-{name}`

[Copilot]

The word "works" should be "words" in this context, as it refers to words being separated by periods.