workflow.yaml schema reference for dotbot

Every dotbot workflow is defined by a workflow.yaml manifest at the root of the workflow directory. This file describes the workflow’s identity, the agents and skills it activates, the kickstart form presented in the dashboard, the external dependencies it requires, and the ordered list of tasks that make up the pipeline. When you run dotbot init, workflow files are installed into .bot/workflows/<name>/. Use dotbot init -Force at any time to receive framework updates while preserving your workspace data.

Top-level metadata fields

Field	Type	Description
`name`	string	Internal workflow identifier. Must be unique within a project.
`version`	string	SemVer string (e.g. `"3.5.0"`).
`description`	string	Human-readable summary shown in `dotbot list` and the dashboard.
`icon`	string	Lucide icon name shown in the dashboard (e.g. `terminal`).
`license`	string	SPDX license identifier (e.g. `MIT`).
`tags`	array of strings	Free-form tags for search and filtering.
`categories`	array of strings	Grouping categories (e.g. `["Development", "AI"]`).
`repository`	string	URL to the workflow’s source repository.
`homepage`	string	URL to documentation or README.
`min_dotbot_version`	string	Minimum dotbot version required to run this workflow.
`author.name`	string	Author display name.
`author.url`	string	Author URL (GitHub profile, etc.).

`agents` array

Lists the AI agent personas activated for this workflow. Each value maps to a prompt file in .bot/recipes/agents/. Valid values: implementer, planner, reviewer, tester.

agents:
  - implementer
  - planner
  - reviewer
  - tester

`skills` array

Lists the reusable skill modules that are loaded during execution. Each value maps to a skill directory under .bot/recipes/skills/. Valid values: status, verify, write-test-plan, write-unit-tests.

skills:
  - status
  - verify
  - write-test-plan
  - write-unit-tests

`form` object

The form object configures the kickstart dialog shown when you start a workflow from the dashboard. It contains a modes array where each entry describes a distinct UI state — typically one mode for a new project and one that hides the form once the project is initialised.

`modes` array fields

string

required

Unique identifier for this form mode (e.g. new_project, has_docs).

condition

string | array of strings

File-existence expression(s) that determine when this mode is active. A plain string path means “file exists”; prefix with ! to mean “file does not exist”. When multiple conditions are listed, all must be satisfied. Example: "!.bot/workspace/product/product.md" — active when no product doc exists yet.

label

string

Button label shown in the kickstart card (e.g. "New Project").

description

string

Explanatory text shown below the label.

button

string

Call-to-action text on the primary button (e.g. "CREATE PRODUCT DOC").

prompt_placeholder

string

Placeholder text for the free-text prompt input field.

show_interview

boolean

When true, the kickstart dialog shows the guided requirements-gathering interview flow.

show_files

boolean

When true, the dialog shows a file-upload area.

hidden

boolean

When true, this mode is never shown in the UI. Useful for suppressing the kickstart form once a project is already initialised.

`requires` object

Declares runtime dependencies that must be satisfied before the workflow can run. dotbot checks these on startup and reports missing items in the dashboard.

`env_vars` array

var

string

Environment variable name (e.g. ANTHROPIC_API_KEY).

name

string

Human-readable label for the variable.

message

string

Error message shown when the variable is missing.

hint

string

Guidance on how to set the variable.

`mcp_servers` array

name

string

MCP server name (e.g. playwright).

message

string

Error message shown when the server is not configured.

hint

string

Configuration instructions.

`cli_tools` array

name

string

CLI tool executable name (e.g. jq).

message

string

Error message shown when the tool is not installed.

hint

string

Installation instructions.

`tasks` array

The tasks array is the ordered pipeline definition. Each task entry is a structured object describing what the runtime executes, in which order, and under what conditions.

name

string

required

Human-readable task name. Must be unique within the workflow. Used to resolve depends_on references.

type

string

Task execution type. One of:

prompt — AI-executed via the configured provider CLI (default).
script — Runs a PowerShell script with no LLM involvement. Auto-promotes past analysis, skips worktree isolation.
mcp — Calls a single MCP tool directly. Auto-promotes past analysis, skips worktree isolation.
task_gen — Runs a script that dynamically creates sub-tasks in the queue.
barrier — Waits until all preceding tasks in its depends_on chain are done before proceeding. No execution of its own.

workflow

string

Path to the workflow-step prompt file, relative to the workflow directory. Used with prompt and task_gen types (e.g. "02a-plan-internet-research.md").

outputs

array of strings

Expected output file names, relative to the workflow’s output directory. Checked for existence after execution (e.g. ["product.md"]).

outputs_dir

string

Directory where generated output files are written (e.g. "tasks/todo").

depends_on

array of strings

Names of other tasks in the same workflow that must reach done status before this task starts.

optional

boolean

When true, the workflow continues even if this task produces no output or is skipped.

condition

string

File-existence expression evaluated at runtime. The task is skipped if the condition is not met.

commit.paths

array of strings

Workspace-relative paths to include in the automatic git commit after this task completes.

commit.message

string

Commit message for the automatic commit (e.g. "chore(kickstart): product document").

priority

integer

Execution priority within the workflow. Lower numbers run first (0 runs before 1).

on_failure

string

Action to take if the task fails. Default is to halt the workflow.

min_output_count

integer

Minimum number of output files required for the task to be considered successful. Relevant for task_gen tasks.

front_matter_docs

array of strings

Output files whose YAML front matter should be extracted and surfaced as structured product metadata.

Complete annotated example

The following is the workflow.yaml for the built-in default workflow, showing all major sections in use.

name: default
version: "3.5.0"
author:
  name: "Andre Sharpe"
  url: "https://github.com/andresharpe"
description: >-
  Lightweight kickstart workflow — generates a single product document
  from a user prompt, with optional internet research.
icon: terminal
license: MIT
tags: [core, framework]
categories: [Development, AI]
repository: https://github.com/andresharpe/dotbot
homepage: https://github.com/andresharpe/dotbot#readme
min_dotbot_version: "3.5.0"

agents:
  - implementer
  - planner
  - reviewer
  - tester

skills:
  - status
  - verify
  - write-test-plan
  - write-unit-tests

form:
  modes:
    # Shown when no product.md exists yet
    - id: new_project
      condition:
        - "!.bot/workspace/product/product.md"
      label: "New Project"
      description: "Describe your project and let Claude create a product document capturing your vision, goals, and approach."
      button: "CREATE PRODUCT DOC"
      prompt_placeholder: "What are you building? What problem does it solve? Who is it for?"
      show_interview: true
      show_files: true

    # Suppresses the kickstart form once a product doc exists
    - id: has_docs
      condition: ".bot/workspace/product/product.md"
      hidden: true

requires: {}

tasks:
  # Step 1: Generate product.md from the user's prompt
  - name: "Product Document"
    type: prompt
    workflow: "01-generate-product.md"
    outputs: ["product.md"]
    front_matter_docs: ["product.md"]
    commit:
      paths: ["workspace/product/"]
      message: "chore(kickstart): product document"
    priority: 0

  # Step 2: Optionally plan internet research sub-tasks
  - name: "Plan Internet Research"
    type: task_gen
    workflow: "02a-plan-internet-research.md"
    depends_on: ["Product Document"]
    optional: true
    outputs_dir: "tasks/todo"
    min_output_count: 1
    commit:
      paths: ["workspace/tasks/"]
      message: "chore(kickstart): internet research task created"
    priority: 1

  # Step 3: Barrier — waits for research tasks to complete
  - name: "Execute Research"
    type: barrier
    depends_on: ["Plan Internet Research"]
    optional: true
    priority: 2

CLI

MCP Tools

Architecture

workflow.yaml schema reference for dotbot

Top-level metadata fields

`agents` array

`skills` array

`form` object

`modes` array fields

`requires` object

`env_vars` array

`mcp_servers` array

`cli_tools` array

`tasks` array

Complete annotated example

CLI

MCP Tools

Architecture

​Top-level metadata fields

​agents array

​skills array

​form object

​modes array fields

​requires object

​env_vars array

​mcp_servers array

​cli_tools array

​tasks array

​Complete annotated example

Top-level metadata fields

`agents` array

`skills` array

`form` object

`modes` array fields

`requires` object

`env_vars` array

`mcp_servers` array

`cli_tools` array

`tasks` array

Complete annotated example