Cursor IDE Guide #

Cursor is our primary development environment. This guide covers automation commands, extensions, and best practices to maximize your productivity.

💡 Pro Tip: Use Cursor commands to automate repetitive tasks! These commands understand the BonsAI codebase and can save you hours of work.

🤖 Automation Commands #

Cursor commands are stored in .cursor/commands/ and provide AI-powered automation for common development tasks. Use these frequently to speed up your workflow!

Quick Reference #

/release-note - Automated Release Notes #

Analyzes your staged changes and automatically creates Hasami release notes.

This command:

• ✅ Reviews ALL existing release notes from your branch
• ✅ Consolidates related changes into concise entries
• ✅ Determines the correct project, type, and bump level
• ✅ Generates user-focused descriptions (max 50 words)
• ✅ Executes hasami add command automatically

Usage:

# 1. Stage your changes
git add <files>

# 2. Run the command in Cursor
/release-note

# 3. Review and approve the generated release note

The command automatically:

• Detects project from file paths (apps/webapp/ → webapp project)
• Determines type (feature, bugfix, misc)
• Suggests appropriate bump level (major, minor, patch)
• Consolidates multiple related changes into one note

Example Output:

# Command generates:
hasami add --project webapp --type feature --bump minor "Added AI-powered folder configuration for Google Drive and SharePoint integrations"

Best Practices:

• Run this before every commit to keep release notes up to date
• Review existing notes in .hasami/ and consolidate duplicates
• Keep descriptions concise and user-focused (5-15 words is ideal)
• One topic per project - combine related changes

See: .cursor/commands/release-note.md

/commit - Automated Conventional Commits #

Analyzes staged changes and creates proper conventional commit messages automatically.

This command:

• ✅ Analyzes staged files to determine commit type and scope
• ✅ Generates conventional commit messages
• ✅ Executes git commit automatically
• ⚠️ Only commits files already staged with git add

Usage:

# 1. Stage your changes
git add <files>

# 2. Run the command in Cursor
/commit

# 3. Review and approve the commit message

Commit Type Detection:

Example Output:

# Changes in apps/webapp/src/features/review/
# Command generates:
git commit -m "feat(webapp): add title field to invoice form validation"

Best Practices:

• Stage only related files together for focused commits
• Review the generated message before confirming
• Use manual override if automatic detection is incorrect
• Run after /release-note for complete automation

See: .cursor/commands/commit.md

/test-api - API Testing Automation #

Generates complete API test commands with credentials, authentication, and verification queries.

This command:

• ✅ Retrieves API credentials from Doppler
• ✅ Finds Clerk IDs from the database
• ✅ References OpenAPI spec for endpoint details
• ✅ Generates working curl commands
• ✅ Provides database verification queries
• ✅ Includes troubleshooting guide

Usage:

/test-api Test the create invoice endpoint

Example Output:

# Get credentials
doppler secrets get API_KEY

# Create invoice
curl -X POST https://dev-api.gotofu.com/api/v1/invoices \
  -H "Authorization: Bearer $CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "..."}'

# Verify in database
SELECT * FROM invoice WHERE entity_id = '...' ORDER BY created_at DESC LIMIT 1;

Best Practices:

• Use this when manually testing API endpoints
• Keep the generated commands in a scratch file for reuse
• Update OpenAPI spec first for accurate command generation
• Test in dev environment before production

See: .cursor/commands/test-api.md

/plan - Implementation Planning #

Creates comprehensive implementation plans using Context Engineering principles.

This command:

• ✅ Applies context engineering layers for thorough analysis
• ✅ Integrates with internal documentation
• ✅ Creates structured plans in .implementation/ folder
• ✅ Follows BonsAI project conventions
• ✅ Identifies dependencies and risks

Usage:

/plan Create an implementation plan for adding webhook support to the API

When to Use:

• Starting a complex feature (3+ days of work)
• Working on unfamiliar parts of the codebase
• Need to coordinate changes across multiple services
• Want to validate approach before coding

Best Practices:

• Run this at the start of a Linear issue
• Review the plan with the team before implementing
• Update the plan as requirements change
• Reference the plan in your PR description

See: .cursor/commands/plan.md

🚀 Daily Workflow with Cursor Commands #

Here’s how to use Cursor commands together for maximum productivity:

Complete Feature Development Flow #

# 1. Start a new feature (if complex)
/plan Implement real-time notifications for invoice updates

# 2. Make your code changes
# ... coding happens here ...

# 3. Stage your changes
git add apps/webapp/src/features/notifications/
git add apps/bonsapi/src/controllers/notification_controller.rs

# 4. Generate release notes
/release-note

# 5. Create commit (after release notes)
/commit

# 6. Push and create PR
git push -u origin your-branch-name

Quick Bug Fix Flow #

# 1. Fix the bug
# ... make changes ...

# 2. Stage changes
git add apps/webapp/src/components/InvoiceForm.tsx

# 3. Generate release note and commit in one go
/release-note
# Review and confirm

/commit
# Review and confirm

# 4. Push
git push

API Testing Flow #

# 1. After implementing a new endpoint, test it
/test-api Test the new webhook endpoint

# 2. Copy the generated curl commands
# 3. Run them in your terminal
# 4. Verify results in database using provided queries

💡 Pro Tips #

Automation Best Practices #

1. Always run /release-note before /commit

   • Release notes help generate better commit messages
   • Keeps documentation in sync with code changes

2. Stage files intentionally

   • Only stage related files together
   • Makes automatic detection more accurate
   • Results in cleaner commits

3. Review before confirming

   • Cursor commands are smart but not perfect
   • Always review generated messages
   • Override if automatic detection is wrong

4. Use /plan for unfamiliar code

   • Saves time investigating architecture
   • Identifies potential issues early
   • Creates documentation for future reference

Time-Saving Shortcuts #

# Quick commit flow (after staging):
/release-note && /commit

# Test API endpoint quickly:
/test-api <endpoint-name>
# Copy generated curl commands
# Paste in terminal

# Plan complex features:
/plan <feature-description>
# Review plan
# Share with team for feedback

Common Patterns #

Multi-Service Changes #

# When changing multiple services:
git add apps/webapp/ apps/bonsapi/ apps/bonsai-invoice/

# Run release-note - it will detect all affected projects
/release-note

# Creates multiple consolidated release notes
# One per project (webapp, bonsapi, bonsai-invoice)

Consolidating Release Notes #

# If you have multiple release notes for the same topic:
ls .hasami/2025*.md

# Delete verbose/duplicate notes:
rm .hasami/20251016-webapp-misc-patch.md

# Create consolidated note:
hasami add --project webapp --type feature --bump minor "Added AI-powered folder configuration"

🎯 Command Decision Tree #

When should I use which command?

Starting work?
├─ Complex feature (3+ days)? → /plan
└─ Simple change? → Start coding

Done coding?
├─ Stage files → git add
├─ Generate release notes → /release-note
└─ Create commit → /commit

Need to test API?
└─ Generate test commands → /test-api

Creating a PR?
├─ Push changes → git push
├─ Create PR on GitHub
└─ Post to #eng-pr-review on Slack

Creating Custom Commands #

To create a new Cursor command:

1. Create a new .md file in .cursor/commands/
2. Follow the structure of existing commands
3. Document the command in this internal documentation
4. Test the command thoroughly before committing

Generating Tickets with Cursor #

Cursor can be used to generate well-formatted tickets for Linear based on code understanding.

Creating Feature Request Tickets #

1. Select the code or module that needs the feature
2. In Cursor, paste the prompt from the Feature prompt template, and replace the content in with the feature description

Example:

<feature>
Add a new feature to the app that allows users to do X, Y, and Z. Make sure to include a detailed description of the feature, and the benefits it will bring to the user.
</feature>

3. Review and edit the generated content
4. Copy the content to Linear’s issue content field

Extensions #

Required #

• Docker
• HashiCorp HCL
• Even Better TOML

Recommended #

• GitLens
• indent-rainbow

Front end #

• Prettier
• ESLint
• Tailwind CSS IntelliSense

Back end #

• HashiCorp Terraform

AI #

• Python
• Python for VSCode
• Python Extension Pack
• Python Indent

Additional Resources #

• Official Cursor Documentation
• Keyboard Shortcuts Cheatsheet