How to Use @agent Commands in Cursor IDE?

[circusvoid]

You mentioned "Cursor IDE with @agent commands" — but how exactly do I reference it in Cursor?

Here’s my current folder structure:

.
├── .bmad
│   └── install-manifest.yml
├── .bmad-core
│   ├── .DS_Store
│   ├── agent-teams
│   ├── agents
│   ├── checklists
│   ├── data
│   ├── schemas
│   ├── tasks
│   ├── templates
│   ├── utils
│   ├── web-bundles
│   └── workflows
└── .cursor
└── rules

[bmadcode]

Good question - give me about 20 minutes and I will push an update that will automate it for cursor users @circus1990666

[circusvoid]

@bmadcode

Hi,

Here’s the workflow I followed:

In ChatGPT, I set the agent to web-bundles/agents/bmad-master.txt.

I created the prd and arch documents.

In Cursor, using the bmad-master agent, I ran the *shard-doc command on both prd and arch.

This successfully generated the prd and arch shards.

I then loaded the SM agent and attempted to create a story.

At this point, I encountered an error — the process was blocked due to a missing epic.

I reviewed tasks/create-next-story.md, which clearly states that an epic is required before stories can be created. However, I also reviewed tasks/shard-doc.md and found that it doesn't include any instructions or steps on how to create an epic.

So right now, I'm unsure how to properly generate an epic and would appreciate your guidance on this. Thank you!

[bmadcode]

Ah - so in your PRD - did it have a section with epics at level 2? something like:

## Epics
<list the epic titles>
## Epic 1 Foo
### Story 1
### Story 2...

## Epic 2 Bar
etc...

if so - when sharding it should create a file where you tell it to shard the destination, such as
docs/prd/epic-1-foo.md
docs/prd/epic-2-bar.md

The SM will look for the lowest numbered epic, and then the stories inside it. if docs/stories has no stories in it , it should start with epic 1 story 1. assume there are multiple complete stories in teh stories folder, it know from the naming and sequence to look for the next one following the similar convention.

[circusvoid]

@bmadcode

When I ran shard-doc on docs/prd.md, it generated files like docs/prd/prd-{section-title}.md, based on the level-2 headings in the PRD.

However, the filenames do not follow the epic-{n}-{description}.md pattern — there’s no epic prefix, and no numbering.
This makes me wonder:
Should shard-doc be generating files like docs/prd/epic-{n}-{section-title}.md instead?

I also checked the tasks/shard-doc.md documentation and didn’t find any reference to epic document generation or naming conventions. So I’m currently unsure whether this step is supposed to produce epics, or if there’s another process I should follow to create them.

Any clarification would be very helpful — thanks again!

[bmadcode]

Hmm - I hope there is not a problem with the prd template. What should happen is the PRD should have some level 2 sections that begin with the name Epic 1 Epic 2 Epic n... The sharding uses an NPM package if available, or else will do it with AI, it is just converting level 2 headings to file names.

If at some level in your PRD you have the epics, with stories under them, you could just either make them level 2 headings so they start with ## Epic N Title... and then shard. Or just create the files manually epic-1-title.md, epic-2-title.md etc...

Can you confirm that this was with version 3 or latest v4 - and was the PRD creating done in the web with gemini and one of the bundles?

[circusvoid]

@bmadcode

1. latest v4
2. I created a custom GPT in ChatGPT and uploaded only one file to its knowledge base:
   .bmad-core/web-bundles/agents/bmad-master.txt.
   Then, I used this custom GPT to generate the prd and arch documents.

---

Additionally, I found a bug in the markdown-tree-parser.
If a Markdown file in the docs folder contains headings written in Chinese, the generated output files are empty.

Here’s the buggy code I identified and fixed. I added support for additional character sets to handle non-Latin languages properly:

+++ b/bin/md-tree.js
@@ -107,7 +107,9 @@ class MarkdownCLI {
   sanitizeText(text) {
     return text
       .toLowerCase()
-      .replace(/[^a-z0-9\s-]/g, '')
+      // Preserve Chinese characters (U+4E00–U+9FFF), Japanese characters (U+3040–U+309F, U+30A0–U+30FF),
+      // Korean characters (U+AC00–U+D7AF), along with basic Latin characters, numbers, spaces, and hyphens
+      .replace(/[^a-z0-9\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af\s-]/g, '')
       .replace(/\s+/g, '-')
       .replace(/-+/g, '-')