Cursor Workflow

The boilerplate includes Cursor rules and commands in .cursor/ that accelerate development while maintaining code quality.

What's included

Rules (`.cursor/rules/`)

Rules are "prompt enhancers" that give Cursor context about your codebase conventions. Use them to keep AI output aligned with how this repo is organized and deployed.

app-layout.mdc: Keeps route groups, layouts, and nav consistent so pages slot in cleanly. If skipped, routes scatter, nav drifts, and moving pages becomes tedious.
auth-routes.mdc: Ensures protected routes use the right guards and redirect patterns. If skipped, you risk leaking private pages or breaking auth flows.
auth-magiclink.mdc: Aligns the magic link flow with the existing token + email patterns. If skipped, auth gets brittle and links can expire or validate incorrectly.
ai-chat.mdc: Keeps AI chat storage, limits, and routing consistent with the product. If skipped, you get performance regressions or data loss in chat history.
billing.mdc: Matches billing implementation with the subscription model and webhooks. If skipped, plans drift from the billing provider and access can be wrong.
db.mdc: Enforces Drizzle schema + query conventions for predictable data access. If skipped, schema and queries get inconsistent and migrations get risky.
email.mdc: Keeps templates, events, and sending rules aligned with the system. If skipped, emails go out with missing data or inconsistent branding.
landing-page.mdc: Guides edits to the marketing surface without breaking layout or SEO. If skipped, marketing pages become inconsistent and conversion drops.
seo.mdc: Ensures correct metadata, sitemap, and structured data. If skipped, pages may not index correctly or show rich previews.
hardening.mdc: Applies security headers, rate limits, and logging defaults. If skipped, you ship with avoidable security gaps and weak observability.
coding-standards.mdc: Reinforces naming, structure, and baseline code quality. If skipped, AI output drifts, creating churn and rework.

Commands (`.cursor/commands/`)

Commands are pre-defined prompts for common tasks. They reduce prompt fatigue and keep multi-step work aligned with the repo.

/add-protected-page: Creates protected routes with correct layout, guard, and nav wiring. If skipped, you might forget auth checks or nav entries.
/add-model: Generates Drizzle schema + CRUD helpers in the right locations. If skipped, you risk inconsistent table definitions and missing indexes.
/add-plan: Adds a billing plan that matches pricing config and webhook logic. If skipped, plans can drift from billing provider expectations.
/add-email-template: Standardizes email layout, variables, and sender config. If skipped, emails break or render poorly across clients.
/generate-env-secret: Produces a secure secret with the right length/format. If skipped, weak secrets can invalidate auth or increase risk.
/wire-email-to-event: Connects product events to email sends reliably. If skipped, emails fire at the wrong time or not at all.
/wire-magic-link-auth: Sets up the magic link flow using existing helpers. If skipped, users encounter broken sign-in links.
/seo-audit-page: Checks metadata, OG tags, and canonical URLs. If skipped, SEO issues linger and hurt discovery.
/security-audit: Scans for common misconfigurations and missing guards. If skipped, you ship avoidable vulnerabilities.
/generate-legal: Generates consistent legal pages with required sections. If skipped, you miss required disclosures or have incomplete docs.
/scaffold: Creates a feature scaffold that matches app structure and patterns. If skipped, new features become inconsistent or hard to move.
/refactor: Guides careful refactors with minimal churn. If skipped, diffs get noisy and regressions slip in.
/brainstorm: Produces options and converges on a clear plan. If skipped, you end up with vague requirements or ad-hoc changes.
/deslop: Removes fluff and aligns tone with your product. If skipped, output stays verbose or inconsistent with your brand.

How rules work

Rules are .mdc files with alwaysApply: true in the frontmatter. Cursor automatically includes them in context when you're working in the codebase.

Example rule structure:

cursor-rule.md

---
alwaysApply: true
---

# Rule Title

Description of when this applies.

## Key patterns

- Pattern 1
- Pattern 2

## Code examples

Using commands

Open Cursor chat
Type / to see available commands
Select a command (e.g., /add-protected-page)
Cursor will ask for required inputs (route name, title, etc.)
Follow the generated steps

Customizing rules

Rules are designed to be customized for your project:

Read the existing rule to understand its purpose
Update patterns to match your conventions
Add project-specific examples
Keep rules focused (one concern per rule)

Adding new rules

Create a new .mdc file in .cursor/rules/: