Working with Cursor

The Cursor integration provides three powerful components:

• Slash Commands - Quick commands for creating specs and breaking down work
• Always-On Rules - Automatic BrainGrid context without manual activation
• AGENTS.md Integration - Persistent workflow guidance throughout your Cursor session

Installation

npm install -g @braingrid/cli

braingrid login

braingrid init

braingrid setup cursor

What Gets Installed

The setup command installs four key components:

Slash Commands

Located in .cursor/commands/, these commands provide quick access to BrainGrid features:

In Cursor's Agent input type / to see all available commands. BrainGrid commands appear alongside Cursor's built-in commands.

Always-On Rules

Located in .cursor/rules/braingrid.mdc, this file teaches Cursor about BrainGrid automatically:

• No explaining needed - Cursor already knows what BrainGrid is
• Context-aware responses - Cursor understands PROJ-X, REQ-Y, TASK-Z references
• Workflow guidance - Cursor suggests next steps in the BrainGrid workflow
• Better task execution - Cursor follows BrainGrid task prompts more accurately

The rules are always active (alwaysApply: true) - no manual activation required.

AGENTS.md Integration

Located at your repository root, this file provides BrainGrid guidance:

• Automatically loaded - No manual activation needed
• Persistent context - Available throughout your Cursor session
• Consistent guidance - Same BrainGrid workflow across all projects

Typical Workflow

Here's how to use BrainGrid with Cursor:

/specify Add dark mode toggle in settings with theme persistence

/breakdown REQ-1

git checkout -b feature/REQ-1-dark-mode

/build REQ-1

MCP Server Installation

Prefer native tool integration? Install BrainGrid as an MCP server:

See the MCP vs CLI section below to choose the right approach, and visit the MCP Server documentation for detailed installation instructions.

MCP vs CLI

Prefer the CLI when:

• Don't want to bloat your context with more MCP servers.
• Speed matters, the CLI calls end up being faster than the MCP calls.
• You need to script custom workflows.

Prefer the MCP when:

• When you are in an environment that does not support the CLI.
• You are more comfortable with the MCPs than CLIs

Tips for Effective Use

Writing Good Prompts for /specify

Include these elements for best results:

• Problem - What are you trying to solve?
• Context - Why is this needed? What's the background?
• Constraints - Any technical or business limitations?
• Users - Who will use this feature?
• Success Criteria - How will you know it's done?

Example:

/specify Add user authentication for our web app. We need OAuth2 support
for Google and GitHub. Must work with our existing Express backend and
React frontend. Users should stay logged in for 30 days. Success means
users can sign up and log in without creating passwords.

Using Additional Instructions with /build

Provide specific guidance for task implementation:

/build REQ-123 Use TypeScript for all new code.
Follow the existing repository pattern in src/repositories/.
Include unit tests for all business logic.

Git Branch Workflow

Name your branches with the requirement ID for automatic detection:

# Good - auto-detects REQ-42
git checkout -b feature/REQ-42-stripe-integration

# Also works
git checkout -b fix/REQ-42-payment-bug
git checkout -b REQ-42-any-description

# Won't auto-detect
git checkout -b add-stripe-payments

Learn More