Skip to content

Commit 3b7006f

Browse files
hannesrudolphhannesrudolph
authored
feat: Add run_slash_command tool and update related documentation (#330)
- Introduced the run_slash_command tool for executing predefined slash commands, enhancing workflow automation. - Updated release notes for version 3.26.6 to include details about the new tool and its capabilities. - Modified existing documentation to reference the new tool and its usage. - Removed the version_only interaction from user interactions as it is no longer needed. - Updated sidebars to include links to the new run_slash_command documentation.
1 parent 0ad8e78 commit 3b7006f

File tree

9 files changed

+506
-134
lines changed

9 files changed

+506
-134
lines changed

‎.roo/rules-release-notes-writer/1_main_workflow.xml‎

Lines changed: 104 additions & 115 deletions
Large diffs are not rendered by default.

‎.roo/rules-release-notes-writer/3_user_interactions.xml‎

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -147,24 +147,6 @@ Would you like to create a PR or make any final adjustments?</question>
147147
</point>
148148
</confirmation_points>
149149

150-
<version_only_interaction>
151-
<trigger>User provides only version number</trigger>
152-
<workflow>
153-
<step>Extract PR list via subtask</step>
154-
<step>Present options to user</step>
155-
</workflow>
156-
<template><![CDATA[
157-
<ask_followup_question>
158-
<question>I've extracted [COUNT] PRs for version [VERSION]. How would you like to proceed?</question>
159-
<follow_up>
160-
<suggest>Create full release notes with all PRs</suggest>
161-
<suggest>Show me the PR list first</suggest>
162-
<suggest>Let me specify which PRs to include</suggest>
163-
<suggest>Cancel - I just needed the PR list</suggest>
164-
</follow_up>
165-
</ask_followup_question>
166-
]]></template>
167-
</version_only_interaction>
168150

169151
<latest_version_interaction>
170152
<trigger>User says "latest"</trigger>

‎docs/advanced-usage/available-tools/run-slash-command.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
description: Execute predefined slash commands that provide templated instructions for common tasks, with support for built-in, global, and project-specific commands in Roo Code.
3+
keywords:
4+
- run_slash_command
5+
- slash commands
6+
- command templates
7+
- Roo Code tools
8+
- workflow automation
9+
- instruction templates
10+
- custom commands
11+
- experimental feature
12+
image: /img/social-share.jpg
13+
---
14+
15+
# run_slash_command
16+
17+
:::warning Experimental Feature
18+
The `run_slash_command` tool is an experimental feature that must be explicitly enabled in settings. Navigate to Settings > Experimental Settings and enable "Run Slash Command" to use this tool.
19+
:::
20+
21+
The `run_slash_command` tool executes predefined slash commands to retrieve specific instructions or content templates. These commands act as reusable instruction sets for common tasks, providing detailed guidance that Roo can interpret and execute. Commands can be defined at three levels with a clear priority hierarchy: project > global > built-in.
22+
23+
---
24+
25+
## Parameters
26+
27+
The tool accepts these parameters:
28+
29+
- `command` (required): Name of the slash command to execute (without the leading slash)
30+
- `args` (optional): Additional arguments or context to pass to the command
31+
32+
---
33+
34+
## What It Does
35+
36+
This tool retrieves and executes instruction templates defined as markdown files in command directories. It enables standardized workflows, reusable task instructions, and team-wide consistency through shared command templates. The tool validates experimental flag status, resolves commands through the priority hierarchy, and returns formatted instructions for Roo to interpret.
37+
38+
---
39+
40+
## When is it used?
41+
42+
- When executing standardized workflows that require consistent steps
43+
- When retrieving project-specific or team-wide instruction templates
44+
- When initializing codebases with analysis and documentation
45+
- When accessing complex multi-step processes as single commands
46+
- When maintaining consistency across team development practices
47+
48+
---
49+
50+
## Key Features
51+
52+
- **Three-Level Command System**: Built-in, global (~/.roo/commands/), and project-specific (.roo/commands/) commands
53+
- **Priority Hierarchy**: Project commands override global, which override built-in commands
54+
- **Markdown-Based Templates**: Simple `.md` files with optional YAML frontmatter for metadata
55+
- **Dynamic Arguments**: Pass context-specific arguments to customize command execution
56+
- **Automatic Discovery**: Commands are automatically found from their respective directories
57+
- **Safe Execution**: Commands are text-only instructions requiring user approval, not executable code
58+
- **Metadata Support**: Optional frontmatter for descriptions and argument hints
59+
- **Error Recovery**: Graceful handling with helpful error messages and command suggestions
60+
- **No Registration Required**: Simply place `.md` files in command directories
61+
62+
---
63+
64+
## Requirements
65+
66+
This tool requires explicit enablement:
67+
68+
1. Open VS Code Settings
69+
2. Navigate to Experimental Settings
70+
3. Enable "Run Slash Command"
71+
4. Restart VS Code if necessary
72+
73+
---
74+
75+
## Limitations
76+
77+
- **Experimental Status**: Feature is disabled by default and requires opt-in
78+
- **Text-Only Instructions**: Commands provide instructions, not direct code execution
79+
- **Approval Required**: All command executions require user approval
80+
- **Directory-Based**: Commands must be in specific directory locations
81+
- **Case-Sensitive**: Command names are matched with case sensitivity
82+
- **Single Command**: Can only execute one command per tool invocation
83+
84+
---
85+
86+
## How It Works
87+
88+
When the `run_slash_command` tool is invoked, it follows this process:
89+
90+
1. **Experimental Flag Validation**:
91+
- Checks if the `runSlashCommand` experiment is enabled
92+
- Returns descriptive error if feature is disabled
93+
- Provides instructions for enabling the feature
94+
95+
2. **Parameter Processing**:
96+
- Validates the required `command` parameter
97+
- Captures optional `args` for command customization
98+
- Increments mistake counter for missing parameters
99+
100+
3. **Command Resolution**:
101+
- Searches project directory first (`.roo/commands/`)
102+
- Falls back to global directory (`~/.roo/commands/`)
103+
- Finally checks built-in commands
104+
- Returns undefined if command doesn't exist
105+
106+
4. **Command Loading**:
107+
- Reads the markdown file for the command
108+
- Parses optional YAML frontmatter using `gray-matter`
109+
- Extracts description and argument hints if present
110+
- Returns command content without frontmatter
111+
112+
5. **Response Formatting**:
113+
- Includes command name and source location
114+
- Adds description and argument hints if available
115+
- Shows provided arguments for context
116+
- Returns the full command content for interpretation
117+
118+
6. **Error Handling**:
119+
- Lists available commands if requested command not found
120+
- Provides helpful error messages with alternatives
121+
- Tracks consecutive mistakes for error patterns
122+
123+
---
124+
125+
## Command Structure
126+
127+
### File Format
128+
129+
Commands are markdown files placed in designated directories:
130+
131+
```markdown
132+
---
133+
description: Brief description of what this command does
134+
argument-hint: What arguments this command accepts
135+
---
136+
137+
# Command Content
138+
139+
Detailed instructions for the task go here.
140+
This can include:
141+
- Step-by-step procedures
142+
- Code templates
143+
- Configuration examples
144+
- Best practices
145+
```
146+
147+
### Naming Convention
148+
149+
- File name becomes the command name
150+
- Use `.md` extension
151+
- Example: `deploy.md` creates `/deploy` command
152+
- Case-sensitive matching
153+
154+
### Directory Locations
155+
156+
1. **Built-in Commands**: Hardcoded in source code
157+
2. **Global Commands**: `~/.roo/commands/`
158+
3. **Project Commands**: `<project-root>/.roo/commands/`
159+
160+
---
161+
162+
## Built-in Commands
163+
164+
### /init Command
165+
166+
The only current built-in command analyzes your codebase and creates documentation:
167+
168+
- Analyzes project structure and architecture
169+
- Creates AGENTS.md documentation files
170+
- Identifies coding patterns and conventions
171+
- Documents non-obvious implementation details
172+
- Provides AI-friendly project context
173+
174+
---
175+
176+
## Creating Custom Commands
177+
178+
### Step-by-Step Guide
179+
180+
1. **Create Command Directory**:
181+
```bash
182+
# For project-specific commands
183+
mkdir -p .roo/commands
184+
185+
# For global commands
186+
mkdir -p ~/.roo/commands
187+
```
188+
189+
2. **Create Command File**:
190+
```bash
191+
# Create a deployment command
192+
touch .roo/commands/deploy.md
193+
```
194+
195+
3. **Add Command Content**:
196+
```markdown
197+
---
198+
description: Deploy application to production environment
199+
argument-hint: environment name (staging, production)
200+
---
201+
202+
## Deployment Process
203+
204+
1. Run test suite to ensure all tests pass
205+
2. Build production bundle with optimizations
206+
3. Update environment variables for target
207+
4. Deploy to specified environment
208+
5. Run post-deployment health checks
209+
6. Update deployment documentation
210+
```
211+
212+
4. **Use the Command**:
213+
The command is immediately available for use without registration.
214+
215+
---
216+
217+
## Command Priority System
218+
219+
When multiple commands with the same name exist:
220+
221+
1. **Project Level** (highest priority)
222+
- Located in `.roo/commands/`
223+
- Allows project-specific overrides
224+
- Committed to version control for team sharing
225+
226+
2. **Global Level** (medium priority)
227+
- Located in `~/.roo/commands/`
228+
- Shared across all projects
229+
- User-specific customizations
230+
231+
3. **Built-in Level** (lowest priority)
232+
- Hardcoded in the extension
233+
- Provides default functionality
234+
- Always available as fallback
235+
236+
---
237+
238+
## Examples When Used
239+
240+
- When initializing a new project, Roo executes `/init` to analyze the codebase structure and create comprehensive documentation.
241+
- When deploying applications, Roo retrieves standardized deployment instructions specific to the project's infrastructure.
242+
- When implementing features, Roo accesses team-agreed patterns and best practices through custom commands.
243+
- When setting up development environments, Roo follows project-specific setup instructions consistently.
244+
- When performing code reviews, Roo uses standardized review checklists defined as commands.
245+
246+
---
247+
248+
## Usage Examples
249+
250+
Executing the built-in initialization command:
251+
```xml
252+
<run_slash_command>
253+
<command>init</command>
254+
</run_slash_command>
255+
```
256+
257+
Running a custom deployment command with arguments:
258+
```xml
259+
<run_slash_command>
260+
<command>deploy</command>
261+
<args>production environment with zero-downtime strategy</args>
262+
</run_slash_command>
263+
```
264+
265+
Executing a test command with specific focus:
266+
```xml
267+
<run_slash_command>
268+
<command>test</command>
269+
<args>focus on integration tests for authentication module</args>
270+
</run_slash_command>
271+
```
272+
273+
Running a project-specific build command:
274+
```xml
275+
<run_slash_command>
276+
<command>build</command>
277+
<args>optimized for production with source maps</args>
278+
</run_slash_command>
279+
```
280+
281+
Accessing team coding standards:
282+
```xml
283+
<run_slash_command>
284+
<command>standards</command>
285+
<args>TypeScript and React best practices</args>
286+
</run_slash_command>
287+
```
288+
289+
---
290+
291+
## Best Practices
292+
293+
### Command Design
294+
295+
1. **Clear Naming**: Use descriptive, action-oriented names
296+
2. **Comprehensive Instructions**: Include all necessary steps
297+
3. **Argument Flexibility**: Design commands to work with or without arguments
298+
4. **Metadata Usage**: Always include description and argument hints
299+
5. **Version Control**: Commit project commands for team consistency
300+
301+
### Organization Strategies
302+
303+
1. **Categorization**: Group related commands with prefixes (e.g., `test-unit`, `test-integration`)
304+
2. **Documentation**: Maintain a README in command directories
305+
3. **Templates**: Create template commands for common patterns
306+
4. **Overrides**: Use project-level to customize global commands
307+
5. **Maintenance**: Regularly review and update command content
308+
309+
### Team Collaboration
310+
311+
1. **Standardization**: Define team-wide commands in global directory
312+
2. **Project Specifics**: Override with project-level customizations
313+
3. **Documentation**: Document available commands and their usage
314+
4. **Review Process**: Include command changes in code reviews
315+
5. **Training**: Share command knowledge across team members
316+
317+
---
318+
319+
## Troubleshooting
320+
321+
### Common Issues
322+
323+
**Feature Not Enabled**:
324+
- Error: "Run slash command is an experimental feature that must be enabled in settings"
325+
- Solution: Enable 'Run Slash Command' in Experimental Settings
326+
327+
**Command Not Found**:
328+
- Error: "Command 'X' not found. Available commands: Y, Z"
329+
- Solution: Check command name spelling and available commands list
330+
331+
**Missing Parameters**:
332+
- Error tracked in consecutive mistake counter
333+
- Solution: Provide required `command` parameter
334+
335+
### Debugging Commands
336+
337+
1. **Verify File Location**: Ensure `.md` file is in correct directory
338+
2. **Check File Name**: Command name must match filename without extension
339+
3. **Validate Frontmatter**: Ensure YAML frontmatter is properly formatted
340+
4. **Test Resolution**: Try same command name at different levels to test priority
341+
5. **Review Content**: Ensure command content is properly formatted markdown

‎docs/advanced-usage/available-tools/tool-use-overview.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,12 @@ Tools are organized into logical groups based on their functionality:
3131
| **Search Group** | Pattern and semantic searching | [search_files](/advanced-usage/available-tools/search-files), [codebase_search](/advanced-usage/available-tools/codebase-search) | Finding code patterns and functionality |
3232
| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [insert_content](/advanced-usage/available-tools/insert-content), [search_and_replace](/advanced-usage/available-tools/search-and-replace), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation |
3333
| **Browser Group** | Web automation | [browser_action](/advanced-usage/available-tools/browser-action) | Web testing and interaction |
34-
| **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command) | Running scripts, building projects |
34+
| **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command), [run_slash_command](/advanced-usage/available-tools/run-slash-command)* | Running scripts, building projects, executing command templates |
3535
| **MCP Group** | External tool integration | [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool), [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) | Specialized functionality through external servers |
3636
| **Workflow Group** | Mode and task management | [switch_mode](/advanced-usage/available-tools/switch-mode), [new_task](/advanced-usage/available-tools/new-task), [ask_followup_question](/advanced-usage/available-tools/ask-followup-question), [attempt_completion](/advanced-usage/available-tools/attempt-completion) | Context switching and task organization |
3737

38+
*_Experimental feature - requires explicit enablement in settings_
39+
3840
### Always Available Tools
3941

4042
Certain tools are accessible regardless of the current mode:
@@ -78,6 +80,7 @@ These tools help Roo interact with web applications:
7880
These tools help Roo execute commands:
7981

8082
- [execute_command](/advanced-usage/available-tools/execute-command) - Runs system commands and programs
83+
- [run_slash_command](/advanced-usage/available-tools/run-slash-command) - Executes predefined slash commands for templated instructions *(Experimental - requires enablement)*
8184

8285
### MCP Tools
8386
These tools help Roo connect with external services:

‎docs/features/experimental/experimental-features.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ The following experimental features are currently available:
3636
- [Power Steering](/features/experimental/power-steering) - Enhanced consistency in AI responses
3737
- [Background Editing](/features/experimental/background-editing) - Work uninterrupted while Roo edits files in the background
3838
- [Image Generation](/features/image-generation) - Generate images from text prompts and save them to your workspace
39+
- [Run Slash Command](/advanced-usage/available-tools/run-slash-command) - Execute predefined slash commands for templated instructions and workflow automation
3940

4041
---
4142

0 commit comments

Comments
 (0)