From 74d9bb4b2b70a341673849a1df704f6eac70c3de Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Thu, 19 Jun 2025 13:02:17 -0500 Subject: [PATCH] feat: add file resolution context for IDE agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- bmad-core/agents/sm.md | 39 ++++++++++ bmad-core/utils/file-resolution-context.md | 87 ++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 bmad-core/utils/file-resolution-context.md diff --git a/bmad-core/agents/sm.md b/bmad-core/agents/sm.md index 3d5cb7a1..83a89963 100644 --- a/bmad-core/agents/sm.md +++ b/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 diff --git a/bmad-core/utils/file-resolution-context.md b/bmad-core/utils/file-resolution-context.md new file mode 100644 index 00000000..ba7e99c0 --- /dev/null +++ b/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 \ No newline at end of file