Skip to main content
A dotbot workflow defines a multi-step pipeline that the AI executes in your project. Workflows are declared in a workflow.yaml manifest and can include AI-driven prompt tasks, deterministic script tasks, MCP tool calls, dynamic task generators, and synchronisation barriers. A project can have multiple workflows installed simultaneously — each is run and re-run independently with dotbot run <name>.

​
When to create a custom workflow

Use a custom workflow when the built-in workflows do not match your process. Common reasons include:
  • Your pipeline requires a specific sequence of AI and deterministic steps
  • You want to integrate with an internal system (e.g. an internal Jira project or custom API)
  • You need conditional tasks that only run when specific files or states exist
  • You want to distribute a standardised engineering process across multiple teams
If a built-in workflow covers your use case, prefer it — custom workflows require maintenance as your process evolves.

​
Anatomy of workflow.yaml

Every workflow.yaml is built from the same set of top-level fields. The annotated example below covers each field:
workflow.yaml
# Identity
name: my-workflow            # Unique identifier used in dotbot run <name>
version: "1.0.0"             # Semver string
description: >-              # Plain-text description shown in the dashboard
  What this workflow does.
icon: terminal               # Lucide icon name shown on the workflow card
tags: [core, research]       # Free-form tags for filtering
categories: [Development]    # Dashboard category grouping
min_dotbot_version: "3.5.0"  # Enforced compatibility check on install

# Agents and skills
agents:
  - implementer              # AI persona used during execution
  - planner
  - reviewer
  - tester

skills:
  - status                   # Reusable capability injected into prompts
  - verify
  - write-unit-tests

# Kickstart form shown in the dashboard
form:
  description: "Shown at the top of the kickstart dialog"
  modes:
    - id: new_project
      condition:
        - "!.bot/workspace/product/product.md"  # Show when file does NOT exist
      label: "New Project"
      description: "Describe your project and dotbot will create a product document."
      button: "CREATE PRODUCT DOC"
      prompt_placeholder: "What are you building?"
      show_interview: true
      show_files: true

    - id: has_docs
      condition: ".bot/workspace/product/product.md"  # Show when file EXISTS
      hidden: true

# Environment requirements validated before a workflow run
requires:
  env_vars:
    - var: AZURE_DEVOPS_PAT
      name: "Azure DevOps PAT"
      message: "Required for repo operations"
      hint: "Set AZURE_DEVOPS_PAT in .env.local"
  mcp_servers:
    - name: atlassian
      message: "Atlassian MCP server must be registered"
      hint: "Run 'claude mcp add atlassian'"
  cli_tools:
    - name: git
      message: "git CLI is required"
      hint: "Install from https://git-scm.com/"

# Task pipeline
tasks:
  - name: "My First Task"
    type: prompt              # Task type — see below
    workflow: "01-step.md"   # Prompt file in the workflow's recipes/ directory
    depends_on: []            # Names of tasks that must complete first
    outputs: ["output.md"]   # Files the task is expected to produce
    optional: false           # If true, pipeline continues on failure
    condition: ".bot/workspace/product/mission.md"  # Run only if file exists
    model: Opus               # Override the process-level model for this task
    commit:
      paths: ["workspace/product/"]
      message: "chore: generated output"
    priority: 1               # Execution order within a dependency level

​
Task types

dotbot has five task types. Choose the type based on what the task needs to do.
TypeDescription
promptTwo-phase AI execution: the analysis phase explores the codebase and builds context; the implementation phase writes code. This is the most common type.
scriptRuns a deterministic PowerShell script with no LLM involved. Use for setup steps, data transforms, and anything where the output must be predictable.
mcpMakes a direct MCP tool call with structured arguments. Use when you need to invoke a tool without an AI deciding how to call it.
task_genAsks the AI to produce a set of child task files, then queues them for execution. Use this to dynamically expand a pipeline based on what the AI discovers.
barrierWaits for a named group of parallel tasks to complete before the pipeline continues. Does not execute any code itself.
script, mcp, and task_gen tasks bypass the AI for their own execution — they auto-promote past the analysis phase, skip worktree isolation, and skip verification hooks. This lets you embed deterministic pipeline stages inside an AI-orchestrated workflow.

​
Adding dependencies between tasks

Use the depends_on field to declare which tasks must complete before a given task starts. Reference tasks by their name value: 
tasks:
  - name: "Fetch Jira Context"
    type: prompt
    workflow: "00-kickstart-interview.md"
    priority: 1

  - name: "Generate Product Documents"
    type: prompt
    workflow: "01-plan-product.md"
    depends_on: ["Fetch Jira Context"]
    priority: 2

  - name: "Plan Atlassian Research"
    type: task_gen
    workflow: "02b-plan-atlassian-research.md"
    depends_on: ["Generate Product Documents"]
    optional: true
    priority: 4
Use a barrier task to wait for a group of parallel tasks before continuing: 
  - name: "Execute Research"
    type: barrier
    depends_on: ["Plan Internet Research", "Plan Atlassian Research", "Plan Sourcebot Research"]
    optional: true
    priority: 6

​
Configuring the kickstart form

The form block controls what users see when they open the workflow in the dashboard before running it. Each entry in modes renders a different form state based on a file-existence condition:
  • A condition without ! is truthy when the file exists
  • A condition with ! prefix is truthy when the file does not exist
Set hidden: true on a mode to suppress the form entirely when that condition is met — useful when a subsequent run should skip the interview because the project is already set up.
Use show_interview: true on the initial mode to prompt users for project details on first run. Set the follow-up mode to hidden: true so repeat runs go straight to execution without re-showing the form.

​
Workflow directory structure

When you add a workflow, dotbot creates this layout inside .bot/workflows/<name>/: 
.bot/workflows/<name>/
├── workflow.yaml      # Pipeline manifest
├── recipes/           # Prompt templates (.md files referenced by task workflow fields)
├── hooks/             # Lifecycle scripts (dev start/stop, verify)
├── settings/          # Workflow-specific settings overrides
└── systems/           # Optional additional MCP tools for this workflow
Recipes are Markdown files that serve as structured prompts. The runtime injects context — task description, product documents, codebase index — before passing them to the AI provider.

​
Installing and running the workflow

1

Install the workflow during project initialisation

Pass the workflow name to dotbot init:
dotbot init -Workflow kickstart-via-jira
2

Add a workflow to an existing project

Use dotbot workflow add after the project has already been initialised:
dotbot workflow add <name>
3

Install from an enterprise registry

Prefix the workflow name with the registry name and a colon:
dotbot init -Workflow myorg:custom-workflow
4

Run the workflow

Start a workflow run from the dashboard, or run it directly from the CLI:
dotbot run <name>
The requires block is validated before a workflow runs. If a required environment variable, MCP server, or CLI tool is missing, dotbot surfaces a clear error with the hint text so you know exactly what to configure before retrying.