diff --git a/src/content/docs/rover/concepts/workflow.mdx b/src/content/docs/rover/concepts/workflow.mdx index 3621542..5cffb3b 100644 --- a/src/content/docs/rover/concepts/workflow.mdx +++ b/src/content/docs/rover/concepts/workflow.mdx @@ -40,7 +40,7 @@ Workflows are defined using YAML files that specify: 1. **Inputs**: The parameters required to start the workflow (e.g., description, audience, format) 2. **Outputs**: The expected results of the workflow (e.g., documentation files) 3. **Configuration**: Settings that control how the workflow operates (e.g., model settings, time limits) -4. **Steps**: The sequence of actions the agent will take to complete the workflow (e.g., research, draft, review, finalize) +4. **Steps**: The sequence of actions to complete the workflow. Steps can be **agent steps** that use AI coding agents (e.g., research, draft, review) or **command steps** that execute shell commands directly (e.g., build, test, lint) If you want to check a full workflow definition, checkout the Workflow File Reference. diff --git a/src/content/docs/rover/guides/write-workflows.mdx b/src/content/docs/rover/guides/write-workflows.mdx index ce98f91..b4e67c1 100644 --- a/src/content/docs/rover/guides/write-workflows.mdx +++ b/src/content/docs/rover/guides/write-workflows.mdx @@ -24,7 +24,7 @@ Workflows are defined in YAML and follow a pre-defined structure. Each file cont | `version` | **Yes** | Schema version (currently `'1.0'`) | | `name` | **Yes** | Unique workflow identifier | | `description` | **Yes** | Human-readable purpose of the workflow | -| `steps` | **Yes** | Ordered list of agent steps to execute | +| `steps` | **Yes** | Ordered list of steps to execute (agent or command) | | `inputs` | No | Parameters the user provides when running the workflow | | `outputs` | No | Files or values the workflow produces | | `defaults` | No | Default AI tool and model for all steps | @@ -169,7 +169,7 @@ For full output properties, see the [Workflow YAML File reference](/rover/refere ### Define steps -Steps are the sequential actions the agent executes. Each step has a unique `id`, a `type` (currently only `agent`), a `name`, and a `prompt` with instructions for the AI agent. +Steps are the sequential actions the workflow executes. Each step has a unique `id`, a `type`, and a `name`. Agent steps (`type: agent`) include a `prompt` with instructions for the AI agent. Command steps (`type: command`) include a `command` to execute directly without an agent. See the [Workflow YAML File reference](/rover/reference/workflow-file#command-step-configuration) for full command step documentation. The `licensing-expert` workflow uses two steps: @@ -428,6 +428,68 @@ After the task completes, inspect the generated report. +## Using command steps + +Not every step in a workflow needs an AI agent. Command steps let you run shell commands directly, which is useful for build tools, test suites, linters, or other CLI operations that don't require AI reasoning. + +A command step requires `type: command` and a `command` field instead of a `prompt`. You can optionally provide `args` as an array and set `allow_failure: true` to let the workflow continue even if the command fails. + +Here is an example workflow that builds a project, runs tests, and then uses an agent to analyze the results: + +```yaml +version: '1.0' +name: 'build-and-review' +description: 'Build the project, run tests, and review the results' + +inputs: + - name: description + description: 'Describe what to focus on during the review' + type: string + required: true + +outputs: + - name: review_report + description: 'Review report with findings and recommendations' + type: file + filename: 'review_report.md' + +steps: + - id: build + type: command + name: 'Build Project' + command: npm run build + + - id: test + type: command + name: 'Run Tests' + command: npm run test + allow_failure: true + + - id: review + type: agent + name: 'Review Results' + prompt: | + Review the build and test output for this project. + + Focus on: {{inputs.description}} + + Build output: + {{steps.build.outputs.stdout}} + + Test output: + {{steps.test.outputs.stdout}} + {{steps.test.outputs.stderr}} + + Write a review report summarizing the results and any issues found. + outputs: + - name: review_report + description: 'Review report with findings and recommendations' + type: file + filename: 'review_report.md' +``` + +Command steps capture `stdout` and `stderr` automatically, making them available to later steps through the template syntax. + By following this guide, you have created your own workflow. You can take existing workflows and adapt to your own needs, or create new workflows from scratch as we have done. Choose your own adventure! ## Relevant Concepts diff --git a/src/content/docs/rover/reference/workflow-file.mdx b/src/content/docs/rover/reference/workflow-file.mdx index 0c68f01..b5a63ee 100644 --- a/src/content/docs/rover/reference/workflow-file.mdx +++ b/src/content/docs/rover/reference/workflow-file.mdx @@ -5,7 +5,7 @@ sidebar: order: 5 --- -`workflow.yml` file format reference. You have more information about workflows on the [Workflow Concept](/rover/concepts/workflow) page. +`workflow.yml` file format reference. For background on how workflows work, see the [Workflow concept](/rover/concepts/workflow) page. ## File Structure @@ -162,7 +162,7 @@ Steps define the workflow's **execution sequence**. They are executed in the ord - Each step must have a **unique `id`** - Steps execute **sequentially** (one after another) - Later steps can **reference outputs** from earlier steps -- Currently, only **`agent`** type steps are supported +- Two step types are supported: **`agent`** (AI agent execution) and **`command`** (shell command execution) ```yaml steps: @@ -172,8 +172,13 @@ steps: prompt: 'Do something...' - id: step_two + type: command + name: 'Run Tests' + command: npm run test + + - id: step_three type: agent - name: 'Second Step' + name: 'Third Step' prompt: 'Do something else...' ``` @@ -230,13 +235,85 @@ Rover supports these AI tools: Specify the tool at the workflow level (in `defaults`) or override it per step. +## Command Step Configuration + +Command steps execute **shell commands directly** without invoking an AI agent. They are useful for running build tools, test suites, linters, or any other CLI commands as part of a workflow. + +### Command Step Properties + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `id` | string | **Yes** | Unique step identifier (used for referencing outputs) | +| `type` | literal | **Yes** | Must be `'command'` | +| `name` | string | **Yes** | Human-readable step name | +| `command` | string | **Yes** | The command to execute | +| `args` | array | No | Command arguments as an array of strings | +| `allow_failure` | boolean | No | Whether to continue the workflow if the command fails (default: `false`) | +| `outputs` | array | No | Outputs this step produces | + +### Command Execution + +The `command` field specifies the command to run. You can optionally provide `args` as a separate array for readability, or include all arguments directly in the `command` string — both forms are equivalent. + +Command steps automatically capture **`stdout`** and **`stderr`** as step outputs. Reference them in subsequent steps with the template syntax `{{steps.step_id.outputs.stdout}}` or `{{steps.step_id.outputs.stderr}}`. + +### Command Step Examples + +**Command with inline arguments**: +```yaml +steps: + - id: build + type: command + name: 'Build Project' + command: npm run build +``` + +**Command with separate arguments**: +```yaml +steps: + - id: test + type: command + name: 'Run Tests' + command: npm + args: + - run + - test +``` + +**Allow failure** (workflow continues even if the command exits with a non-zero code): +```yaml +steps: + - id: lint + type: command + name: 'Lint Code' + command: npm run lint + allow_failure: true +``` + +**Mixed workflow** (combine command and agent steps): +```yaml +steps: + - id: build + type: command + name: 'Build Project' + command: npm run build + + - id: analyze + type: agent + name: 'Analyze Build Output' + prompt: | + Review the build output and identify any warnings: + {{steps.build.outputs.stdout}} +``` + ## Step Outputs Step outputs make **data available to subsequent steps**. They use the same structure as workflow outputs. **Key points**: -- Define outputs in the step's `outputs` array -- Reference them in later steps using **template syntax** +- Agent steps define outputs in the step's `outputs` array +- Command steps automatically produce `stdout` and `stderr` outputs +- Reference outputs in later steps using **template syntax** - Output types: `string`, `number`, `boolean`, `file` - **File outputs require a `filename`** @@ -313,7 +390,7 @@ prompt: | ## Defaults -The `defaults` object sets **workflow-level configuration** that steps inherit. This avoids repetition when most steps use the same AI tool and model. +The `defaults` object sets **workflow-level configuration** that agent steps inherit. This avoids repetition when most agent steps use the same AI tool and model. Command steps ignore these defaults. ### Default Properties @@ -371,7 +448,7 @@ config: ## Step-Level Configuration -Each step can override timeout and retry behavior using its own `config` object. +Agent steps can override timeout and retry behavior using their own `config` object. ### Step Config Properties @@ -407,7 +484,8 @@ Rover validates workflow files against these rules: ### Required Fields - **`version`, `name`, `description`, and `steps`** must be present -- Each step must have **`id`, `type`, `name`, and `prompt`** +- Each agent step must have **`id`, `type`, `name`, and `prompt`** +- Each command step must have **`id`, `type`, `name`, and `command`** - Each input/output must have **`name`, `description`, and `type`** ### Unique Identifiers @@ -417,7 +495,7 @@ Rover validates workflow files against these rules: ### Type Constraints - **Input types**: `string`, `number`, `boolean` - **Output types**: `string`, `number`, `boolean`, `file` -- **Step types**: `agent` (other types not yet implemented) +- **Step types**: `agent`, `command` - **AI tools**: `claude`, `gemini`, `codex`, `qwen` ### Conditional Requirements @@ -458,6 +536,23 @@ steps: prompt: '...' ``` +❌ **Command step without `command` field**: +```yaml +steps: + - id: build + type: command # Error: missing command + name: 'Build Project' +``` + +✅ **Command step with required fields**: +```yaml +steps: + - id: build + type: command + name: 'Build Project' + command: npm run build +``` + ❌ **File output without filename**: ```yaml outputs: