feat: add file resolution context for IDE agents

- Added file resolution section to SM agent explaining path patterns
- Created reusable file-resolution-context.md utility
- Documents how agents resolve tasks/templates/checklists to file paths
- Provides natural language to command mapping examples
- Helps IDE agents understand file system structure

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

bmad-core/agents/sm.md

@@ -46,4 +46,43 @@ dependencies:
     - story-draft-checklist
   utils:
     - template-format
+    - file-resolution-context
 ```
+
+## File Resolution Context (IDE Integration)
+
+When working in an IDE environment, understand these file resolution patterns:
+
+### Base Path
+
+- The `root` field (line 6) defines the base path: `.bmad-core`
+- All file references are relative to this root directory
+
+### Dependency Resolution
+
+All items under `dependencies` follow a folder/file hierarchy pattern:
+
+- **Tasks**: `{root}/tasks/{task-name}.md`
+  - Example: `create-next-story` → `.bmad-core/tasks/create-next-story.md`
+- **Templates**: `{root}/templates/{template-name}.md`
+  - Example: `story-tmpl` → `.bmad-core/templates/story-tmpl.md`
+- **Checklists**: `{root}/checklists/{checklist-name}.md`
+  - Example: `story-draft-checklist` → `.bmad-core/checklists/story-draft-checklist.md`
+- **Utils**: `{root}/utils/{util-name}.md`
+  - Example: `template-format` → `.bmad-core/utils/template-format.md`
+
+### Command Mapping
+
+When users request actions, understand these equivalences:
+
+- "draft the next story" = `*draft` = `*create` = execute task at `.bmad-core/tasks/create-next-story.md`
+- "show story checklist" = `*checklist story-draft-checklist` = display `.bmad-core/checklists/story-draft-checklist.md`
+
+### Working with Files
+
+When executing tasks or accessing dependencies:
+
+1. Always resolve the full path from the dependency name
+2. Read the file content from the resolved path
+3. Execute the instructions contained within
+4. Reference templates using their full resolved paths

bmad-core/utils/file-resolution-context.md

@@ -0,0 +1,87 @@
+# File Resolution Context for IDE Integration
+
+This utility explains how BMAD agents should resolve file paths when working in IDE environments.
+
+## Core Concepts
+
+### Base Path Resolution
+
+- The `root` field in each agent's YAML configuration defines the base path (typically `.bmad-core`)
+- All file references in dependencies are relative to this root directory
+- IDE agents must understand this structure to properly access files
+
+### Dependency Path Patterns
+
+All items under `dependencies` in agent configurations follow a consistent folder/file hierarchy:
+
+| Dependency Type | Path Pattern | Example |
+|----------------|--------------|---------|
+| Tasks | `{root}/tasks/{task-name}.md` | `create-next-story` → `.bmad-core/tasks/create-next-story.md` |
+| Templates | `{root}/templates/{template-name}.md` | `story-tmpl` → `.bmad-core/templates/story-tmpl.md` |
+| Checklists | `{root}/checklists/{checklist-name}.md` | `story-draft-checklist` → `.bmad-core/checklists/story-draft-checklist.md` |
+| Utils | `{root}/utils/{util-name}.md` | `template-format` → `.bmad-core/utils/template-format.md` |
+| Data | `{root}/data/{data-name}.md` | `bmad-kb` → `.bmad-core/data/bmad-kb.md` |
+| Agents | `{root}/agents/{agent-name}.md` | `sm` → `.bmad-core/agents/sm.md` |
+
+### Natural Language to Command Mapping
+
+Agents should understand various ways users might request actions:
+
+#### Story Creation Examples
+
+- "draft the next story" → `*draft` or `*create`
+- "create a new story" → `*create`
+- "prepare a story" → `*draft`
+- All map to: `.bmad-core/tasks/create-next-story.md`
+
+#### Checklist Examples
+
+- "show story checklist" → `*checklist story-draft-checklist`
+- "run the story checklist" → `*checklist story-draft-checklist`
+- Maps to: `.bmad-core/checklists/story-draft-checklist.md`
+
+#### Template Examples
+
+- "use the story template" → Access `.bmad-core/templates/story-tmpl.md`
+- "show prd template" → Access `.bmad-core/templates/prd-tmpl.md`
+
+## Implementation Guidelines
+
+### For IDE Agents
+
+1. **Path Resolution**: Always construct full paths by combining:
+   - Root directory from YAML configuration
+   - Appropriate subfolder based on dependency type
+   - Dependency name with `.md` extension
+
+2. **File Access**: When executing tasks or using dependencies:
+   - Resolve the full file path
+   - Read the file content
+   - Parse and execute instructions
+   - Handle file-not-found errors gracefully
+
+3. **Cross-References**: When one file references another:
+   - Apply the same resolution rules
+   - Maintain context of the current working directory
+
+### For Task Execution
+
+When a user requests task execution:
+
+1. Parse the user's request to identify the task
+2. Check command aliases (e.g., `create` and `draft` both map to `create-next-story`)
+3. Resolve the task file path: `{root}/tasks/{task-name}.md`
+4. Read and execute the task instructions
+5. If the task references templates or other files, resolve those paths similarly
+
+### Error Handling
+
+- If a file doesn't exist at the resolved path, provide helpful feedback
+- Suggest similar files if there might be a typo
+- Never assume file locations outside the defined structure
+
+## Integration Notes
+
+- This resolution system ensures consistency across all agents
+- IDE-specific tools can leverage this structure for autocomplete and navigation
+- The pattern is extensible for new dependency types