Brainforge Knowledge

00-how-to-use-cursor

7 min read

How to Use Cursor (Setup and Walkthrough)

Cursor is the main tool we use to write faster, think better, and reuse knowledge across Brainforge.
You do not need to know how to code.

This guide matches our workflow:

  • Cursor = writing + AI help across files
  • GitHub Desktop = cloning + fetch/pull + commit/push
  • Multi-repo workspace = open multiple repos at once
  • Agent modes = choose the safest mode for what you’re doing

Agent Modes (Which One to Use)

Ask mode (read-only)

Use when you want to:

  • understand what a repo contains
  • find the right template or prompt
  • summarize a doc or transcript
  • answer questions without changing any files

Safe default for non-technical users.

Plan mode (creates a plan first)

Use when you want to:

  • produce a structured plan before making edits
  • restructure multiple docs
  • create a repeatable workflow / SOP
  • make changes that affect multiple files

Plan mode gives you a reviewable plan before anything is built.

Agent mode (makes changes)

Use when you want Cursor to:

  • draft or edit files for you
  • create new documents based on templates
  • apply consistent formatting across docs
  • do multi-file edits (with your review)

If you’re unsure, start in Plan or Ask.

Debug mode (technical troubleshooting)

Use when you have:

  • a tricky bug/regression
  • performance issues
  • problems that need reproduction + logs

Most non-technical users will rarely need this.

PART 1 — OPENING REPOS (SINGLE REPO VS MULTI-REPO WORKSPACE)

Option A: Open a single repo (simple mode)

Mode: Ask (recommended)

  1. Open Cursor
  2. Click Open Folder
  3. Select a repo folder (example: client-eden/)
  4. Cursor can now read everything in that repo

Use Ask mode to orient yourself:

  • “What are the key folders in this repo and what is each for?”
  • “Where do SOW drafts live in this repo?”

Mode: Ask (recommended)

Use this when you want to reference:

  • client-<name>/ + brainforge-platform/ (which contains standards/ and knowledge/) at the same time

Create a multi-repo workspace

  1. Open Cursor
  2. File → Open Folder (open your primary repo first, e.g. client-eden/)
  3. File → Add Folder to Workspace…
  4. Select the brainforge-platform repo (contains standards/ and knowledge/)
  5. Repeat Add Folder to Workspace… for any other repos you need

Now your sidebar will show multiple top-level folders.

Save the workspace

Mode: Ask (recommended)

  1. File → Save Workspace As…
  2. Name it: eden + playbook.code-workspace
  3. Save it somewhere easy to find (example: bf-repos/workspaces/)

Reopen the workspace later

  • File → Open Recent → select the workspace

PART 2 — USING CHAT (YOUR HOME BASE)

Step: Ask questions and reference files across repos

Mode: Ask (recommended)

Examples:

  • “Find the SOW template in playbook.”
  • “Summarize the latest meeting notes in client-eden into action items.”
  • “Compare this client PRD to the playbook PRD template and list gaps.”

Tip: include the repo folder name in requests to avoid ambiguity:

  • “Use standards/.../sow-template.md to guide client-eden/.../sow-draft.md.”

PART 3 — CREATING OR EDITING DOCUMENTS (WRITING WORK)

Step: Draft a new doc from a template

Mode: Plan → Agent (recommended for non-technical users)

Plan (review first)

Use Plan mode when you want a safe, reviewable approach:

  • “Create a plan to draft a client SOW using the playbook template. Include which files you will reference and which file you will create.”

Review the plan. Adjust if needed.

Agent (execute the plan)

Then switch to Agent mode and request:

  • “Now draft the SOW in client-eden/sow/sow-draft.md using the playbook template and our latest meeting notes.”

Step: Small edits to an existing doc

Mode: Agent (or Ask if you only want suggestions)

  • Ask mode if you want guidance without edits:
    • “Suggest edits to make this section clearer and more client-friendly.”
  • Agent mode if you want it applied to the file:
    • “Rewrite this section for clarity and concision, preserving meaning.”

PART 4 — USING THE PLAYBOOK PROMPTS (REUSE BEST PRACTICES)

Step: Apply a standard prompt to your work

Mode: Ask → Agent (recommended)

  1. Ask mode:
    • “Which playbook prompt should I use to turn meeting notes into a PRD update?”
  2. Agent mode:
    • “Use the identified prompt and apply it to client-eden/prd/prd.md.”

PART 5 — PREVIEWING MARKDOWN (SEE WHAT IT WILL LOOK LIKE ON GITHUB)

Markdown files (.md) are rendered (formatted) by GitHub. Cursor lets you preview that rendering while you write, so you can catch formatting issues early.

Step: Open Markdown Preview

Mode: Ask (recommended) or Agent (not required)

  1. Open the .md file you’re editing
  2. Open preview using one of these:
    • Right-click the file tab → Open Preview
    • Command Palette:
      • Mac: Cmd + Shift + P
      • Windows: Ctrl + Shift + P
      • Type: Markdown: Open Preview
  3. You should now see a rendered view (headings, bullets, tables, links) similar to GitHub

Step: Split view (edit + preview side-by-side)

Mode: Ask (recommended)

  1. With the Markdown file open, open Preview to the Side:
    • Command Palette → Markdown: Open Preview to the Side
  2. Now you can:
    • edit on the left
    • see the rendered result on the right

Step: What to check in preview (common GitHub formatting issues)

Mode: Ask (recommended)

  • Headings look correct (#, ##, ###)
  • Bullet lists nest properly (indentation matters)
  • Tables render correctly (pipes | aligned)
  • Links work and look right
  • Code blocks render properly:
    • triple backticks
    • correct language tag (e.g., ```markdown)

Tip: If preview looks wrong

Mode: Ask (recommended)

Ask Cursor:

  • “Why is this markdown not rendering correctly? Fix the formatting without changing the meaning.” If you want it to directly apply changes to the file, switch to Agent:
  • “Fix the markdown formatting in this file so it renders correctly on GitHub.”

PART 6 — SAVING YOUR WORK (UPDATED: GIT IS IN GITHUB DESKTOP)

Cursor is for writing. GitHub Desktop is for Git actions.

Step: Before you start working

Mode: Not applicable (done in GitHub Desktop)

In GitHub Desktop:

  1. Select the repo
  2. Click Fetch origin
  3. If updates exist, click Pull origin

Step: While you work

Mode: Ask / Plan / Agent (depends on task)

  • Ask: learn, locate, summarize, compare
  • Plan: create a multi-step plan for larger changes
  • Agent: write/edit files

Save files normally in Cursor.

Step: When you finish working

Mode: Not applicable (done in GitHub Desktop)

In GitHub Desktop:

  1. Review changes
  2. Write a commit message
  3. Commit
  4. Push origin

PART 7 — WHEN TO USE DEBUG MODE

Mode: Debug (only if technical troubleshooting)

Use Debug mode when:

  • a bug is reproducible but the cause is unclear
  • performance is slow and you need evidence (logs)
  • something inconsistent needs reproduction

If you are non-technical:

  • start with Ask mode to describe the issue and gather context
  • only switch to Debug if an engineer or lead asks for it

Quick Mode Guide (Memorize This)

  • Ask = read-only, safest default
  • Plan = propose a plan before changes
  • Agent = make edits / create files
  • Debug = technical bug investigation with reproduction + logs
  • Start in Ask
  • Use Plan for anything multi-step or multi-file
  • Use Agent when you are ready to draft/edit files
  • Use GitHub Desktop to fetch/pull/commit/push
  • Use Markdown Preview to confirm it will render correctly on GitHub

Cursor Skills (Available in Playbook Workspace)

When this repo (brainforge-platform) is in your workspace, you have access to Cursor skills that extend the agent’s capabilities.

Available Skills

  • Humanizer (/humanizer): Removes AI-generated writing patterns from text. Use before finalizing any prose (SOW, PRD, email, summary).

How to Use Skills

  1. Type /humanizer in Agent chat and paste or reference your text
  2. Or ask the agent: “Humanize this draft” or “Make this sound less AI-generated”

See .cursor/skills/README.md for full documentation.

Additional Resources

For comprehensive best practices on using Cursor agents effectively, see:

Graph View

Backlinks