Write workflows

Rover includes built-in workflows like the Software Engineer (swe) and Tech Writer (tech-writer), but you can also create custom workflows for use cases they don’t cover. This guide walks you through writing a custom workflow from scratch.

You will build a licensing-expert workflow that analyzes project dependencies and generates a report highlighting licensing issues and compliance concerns. By the end, you will know how to define inputs, outputs, steps, and configuration in a workflow YAML file, register it with Rover, and run it as a task.

For background on how workflows work, see the Workflow concept page.

The anatomy of a workflow

Workflows are defined in YAML and follow a pre-defined structure. Each file contains these top-level fields:

Field	Required	Description
`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 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
`config`	No	Timeout and error-handling settings

You can find the full schema in the Workflow YAML File reference.

Create a workflow file

Follow these steps to build the licensing-expert workflow piece by piece.

Building the licensing-expert workflow

Create a new file called licensing-expert.yml in your project directory.

Start with the required metadata:

version: '1.0'
name: 'licensing-expert'
description: 'Analyze project dependencies and generate a licensing compliance report'

Define the inputs so users can describe what they want analyzed:

inputs:
  - name: description
    description: 'Describe the licensing analysis you want performed'
    type: string
    required: true

Define the outputs to declare the report file the workflow produces:

outputs:
  - name: licensing_report
    description: 'Markdown report of licensing issues and compliance status'
    type: file
    filename: 'licensing_report.md'

Add defaults and config to set the AI tool and execution limits:

defaults:
  tool: claude

config:
  timeout: 3600
  continueOnError: false

Define the steps that the agent will execute sequentially:

steps:
  - id: analyze
    type: agent
    name: 'Analyze Dependencies'
    prompt: |
      Scan the project and identify all dependencies and their licenses.

      Focus on: {{inputs.description}}

      List every dependency with its license type. Flag any dependencies
      that use copyleft licenses (GPL, AGPL, LGPL), have no license,
      or have licenses that conflict with common permissive usage.
    outputs:
      - name: analysis
        description: 'Detailed dependency and license analysis'
        type: string

  - id: report
    type: agent
    name: 'Generate Report'
    prompt: |
      Using the analysis below, create a comprehensive licensing report.

      Analysis:
      {{steps.analyze.outputs.analysis}}

      The report must include:
      - Executive summary of licensing status
      - Table of all dependencies with their license types
      - List of flagged issues (copyleft, missing, or conflicting licenses)
      - Recommended actions to resolve each issue
    outputs:
      - name: licensing_report
        description: 'Markdown report of licensing issues and compliance status'
        type: file
        filename: 'licensing_report.md'

6

Verify that your file matches the complete example below.

Define inputs

Inputs declare the parameters users provide when running the workflow. Each input has a name, description, type, and whether it is required.

Property	Type	Required	Description
`name`	string	Yes	Unique identifier for the input
`description`	string	Yes	Explanation of what the input is for
`type`	enum	Yes	Data type: `string`, `number`, or `boolean`
`required`	boolean	Yes	Whether the user must provide this input
`default`	any	No	Default value (only for optional inputs)

The licensing-expert workflow uses a single required input:

inputs:
  - name: description
    description: 'Describe the licensing analysis you want performed'
    type: string
    required: true

Reference inputs in step prompts with the template syntax {{inputs.description}}. See Template syntax for details.

Define outputs

Outputs declare what the workflow produces. Output types can be string, number, boolean, or file. File outputs require a filename property that tells Rover which file to expect.

outputs:
  - name: licensing_report
    description: 'Markdown report of licensing issues and compliance status'
    type: file
    filename: 'licensing_report.md'

For full output properties, see the Workflow YAML File reference.

Define steps

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 for full command step documentation.

The licensing-expert workflow uses two steps:

Analyze Dependencies — Scans the project and catalogues every dependency with its license type
Generate Report — Takes the analysis output and writes a structured licensing_report.md file

Steps can declare their own outputs, which later steps reference through template syntax. In this workflow, the analyze step produces an analysis output that the report step consumes:

steps:
  - id: analyze
    type: agent
    name: 'Analyze Dependencies'
    prompt: |
      Scan the project and identify all dependencies and their licenses.

      Focus on: {{inputs.description}}

      List every dependency with its license type. Flag any dependencies
      that use copyleft licenses (GPL, AGPL, LGPL), have no license,
      or have licenses that conflict with common permissive usage.
    outputs:
      - name: analysis
        description: 'Detailed dependency and license analysis'
        type: string

  - id: report
    type: agent
    name: 'Generate Report'
    prompt: |
      Using the analysis below, create a comprehensive licensing report.

      Analysis:
      {{steps.analyze.outputs.analysis}}

      The report must include:
      - Executive summary of licensing status
      - Table of all dependencies with their license types
      - List of flagged issues (copyleft, missing, or conflicting licenses)
      - Recommended actions to resolve each issue
    outputs:
      - name: licensing_report
        description: 'Markdown report of licensing issues and compliance status'
        type: file
        filename: 'licensing_report.md'

You can override the AI tool or model for individual steps and set step-level timeouts or retries. See the Workflow YAML File reference for all step properties.

Template syntax

Templates use Mustache-style placeholders that Rover replaces at runtime:

Reference an input: {{inputs.input_name}}
Reference a step output: {{steps.step_id.outputs.output_name}}

Templates can only reference steps that are defined before the current step in the steps array. Forward references are not allowed.

Defaults and config

The defaults object sets the AI tool and model for all steps. Individual steps can override these values.

defaults:
  tool: claude

The config object controls workflow-level execution behavior:

Property	Type	Description
`timeout`	number	Maximum workflow execution time in seconds
`continueOnError`	boolean	Whether to continue when a step fails (default: `false`)

config:
  timeout: 3600
  continueOnError: false

Steps can also have their own config with timeout (default: 1800 seconds) and retries (default: 0).

Complete example

Here is the full licensing-expert.yml file:

version: '1.0'
name: 'licensing-expert'
description: 'Analyze project dependencies and generate a licensing compliance report'

inputs:
  - name: description
    description: 'Describe the licensing analysis you want performed'
    type: string
    required: true

outputs:
  - name: licensing_report
    description: 'Markdown report of licensing issues and compliance status'
    type: file
    filename: 'licensing_report.md'

defaults:
  tool: claude

config:
  timeout: 3600
  continueOnError: false

steps:
  - id: analyze
    type: agent
    name: 'Analyze Dependencies'
    prompt: |
      Scan the project and identify all dependencies and their licenses.

      Focus on: {{inputs.description}}

      List every dependency with its license type. Flag any dependencies
      that use copyleft licenses (GPL, AGPL, LGPL), have no license,
      or have licenses that conflict with common permissive usage.
    outputs:
      - name: analysis
        description: 'Detailed dependency and license analysis'
        type: string

  - id: report
    type: agent
    name: 'Generate Report'
    prompt: |
      Using the analysis below, create a comprehensive licensing report.

      Analysis:
      {{steps.analyze.outputs.analysis}}

      The report must include:
      - Executive summary of licensing status
      - Table of all dependencies with their license types
      - List of flagged issues (copyleft, missing, or conflicting licenses)
      - Recommended actions to resolve each issue
    outputs:
      - name: licensing_report
        description: 'Markdown report of licensing issues and compliance status'
        type: file
        filename: 'licensing_report.md'

Register the workflow

After creating the YAML file, register it with Rover so you can use it in tasks.

Registering the workflow

1
Navigate to your project directory
Terminal window
```
cd ~/my-project
```
2
Add the workflow to Rover
Terminal window
```
rover workflows add licensing-expert.yml
```
By default, the workflow is added locally to the current project. To make it available across all projects, add the --global flag.

Verify the workflow was registered

rover workflows list

You should see the new workflow alongside the built-in ones:

Name               Description                                                Steps Inputs
────────────────────────────────────────────────────────────────────────────────────────────────
swe                Complete software engineering workflow with ada...          6     description
tech-writer        Write documentation and tutorials for your tech...         4     description, audience, format
licensing-expert   Analyze project dependencies and generate a li...          2     description

Run the workflow

Create a task that uses your custom workflow.

Running the licensing-expert workflow

1
Create a task with the --workflow flag and provide the required input
Terminal window
```
rover task --workflow licensing-expert \
  "Analyze all project dependencies and identify any licensing conflicts or compliance issues"
```
The -y flag skips confirmation prompts and starts the task immediately.

Monitor the task progress. Assuming the task was assigned ID 1:

rover logs -f 1

The agent executes each step sequentially. You will see output similar to:

=======================================
🚀 Running Workflow
=======================================

Agent Workflow
├── Name: licensing-expert
└── Description: Analyze project dependencies and generate a licensing compliance report

Steps
├── 0. Analyze Dependencies
└── 1. Generate Report

🤖 Running Analyze Dependencies > claude
✓ Step 'Analyze Dependencies' completed successfully

🤖 Running Generate Report > claude
✓ Step 'Generate Report' completed successfully

Review results

After the task completes, inspect the generated report.

Reviewing the licensing report

Check the generated report.

rover inspect --file=licensing_report.md 1

2
If the report needs changes, iterate on the task
Terminal window
```
rover iterate 1 "Add a section covering transitive dependencies and their licenses"
```
See the Iterate on tasks guide for more on refining results.

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:

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

Workflow Discover how workflows guide coding agents

Task Learn about Rover tasks and how they work

Implement a new feature Create and assign tasks to AI coding agents

Iterate on tasks Refine and improve task implementations

Merge changes from tasks Integrate completed tasks into your codebase

Project Initialization Initialize Rover in your repository