workflow.json schema reference for dotbot

Every dotbot workflow is defined by a workflow.json file at the root of the workflow directory, alongside a manifest.json file that provides a short identity summary. Together these files describe the workflow’s identity, the kickstart form presented in the dashboard, external dependencies, and the ordered task 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.

`manifest.json` fields

The manifest.json file provides a lightweight identity record for the workflow. The dashboard and dotbot list use it when displaying installed workflows.

Field	Type	Description
`name`	string	Internal workflow identifier. Must match the `name` field in `workflow.json`.
`description`	string	Human-readable summary shown in the dashboard and `dotbot list`.

{
  "name": "start-from-prompt",
  "description": "Full project workflow — creates product documents for new projects, then generates architectural decisions, task groups, and an expanded roadmap."
}

`workflow.json` top-level fields

Field	Type	Description
`name`	string	Internal workflow identifier. Must be unique within a project.
`version`	string	Version string (e.g. `"3.5"`).
`description`	string	Human-readable summary of what the workflow does.
`icon`	string	Lucide icon name shown in the dashboard (e.g. `"search"`).
`min_dotbot_version`	string	Minimum dotbot version required to run this workflow (e.g. `"3.5"`).
`form`	object	Kickstart dialog configuration. See form object.
`requires`	object	Runtime dependency declarations. See requires object.
`tasks`	array	Ordered pipeline definition. See tasks array.
`domain`	object	Workflow-specific configuration block. Structure is defined by each workflow. See domain object.

`form` object

The form object configures the kickstart dialog shown when you start a workflow from the dashboard. Workflows with conditional UI states use a modes array. Simpler single-state workflows declare form properties directly on the form object.

Flat form properties

When a workflow has one unconditional kickstart state, place these properties directly on form.

description

string

Explanatory text shown in the kickstart card.

interview_label

string

Label for the interview toggle control (e.g. "Research via Atlassian first").

interview_hint

string

Hint text shown below the interview toggle.

prompt_placeholder

string

Placeholder text for the free-text prompt input field.

`modes` array

When a workflow needs different UI states, for example one state for a new project and another that suppresses the dialog once the project is initialised, use the modes array. Each entry describes one state.

string

required

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

condition

string | array of strings

File-existence expression that determines 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/mission.md" activates the mode when that file does not yet exist.

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. "LAUNCH PROJECT").

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.

show_prompt

boolean

When true, the dialog shows the free-text prompt input.

hidden

boolean

When true, this mode is never shown in the UI. Use this to suppress 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. "atlassian").

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. "git").

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 entry describes 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 using the prompt file named by workflow.
prompt_template - AI-executed using a compiled template prompt named by prompt.
script - Runs a PowerShell script named by script with no AI involvement.
task_gen - Runs a prompt that dynamically creates sub-tasks in the queue.
barrier - Waits until all tasks in its depends_on chain are done before proceeding. Performs 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. "01-plan-product.md").

prompt

string

Path to the compiled template prompt file. Used with the prompt_template type (e.g. "prompts/00-fast-prompt.md").

script

string

Path to the PowerShell script to run. Used with the script type (e.g. "Scripts/Expand-TaskGroups.ps1").

post_script

string

Path to a PowerShell script run after the main task completes (e.g. "Scripts/Complete-TaskGroupsPhase.ps1").

description

string

Human-readable description of what this task does. Shown in the dashboard.

acceptance_criteria

array of strings

List of conditions that define task completion. The AI executor uses these to self-evaluate the result.

outputs

array of strings

Expected output file names, relative to the workflow’s output directory. Checked for existence after execution (e.g. ["mission.md", "tech-stack.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 (e.g. ".bot/workspace/product/research-repos.md").

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(workflow): phase 1 — product documents").

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. Use "halt" to stop the workflow on failure.

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 front matter should be extracted and surfaced as structured product metadata.

effort

string

Effort estimate for the task, used by the dashboard for display (e.g. "XS", "S", "M", "L").

`domain` object

The domain object holds workflow-specific runtime configuration. Its structure is defined by each workflow and is not enforced by the dotbot schema. Common uses include lists of valid task categories and service-specific settings.

"domain": {
  "task_categories": [
    "research",
    "analysis",
    "documentation",
    "implementation",
    "infrastructure"
  ],
  "atlassian": {
    "max_pages_to_read": 10
  },
  "azure_devops": {
    "branch_prefix": "initiative"
  }
}

Complete annotated example

The following shows the manifest.json and workflow.json for the built-in start-from-prompt workflow, with all major sections in use. manifest.json

{
  "name": "start-from-prompt",
  "description": "Full project workflow — creates product documents for new projects (via interview) or existing codebases (via repo scan), then generates architectural decisions, task groups, and an expanded roadmap."
}

workflow.json

{
  "name": "start-from-prompt",
  "version": "3.5",
  "description": "Full project workflow — takes a project spec (prompt + optional attached files) and generates foundational product documents, then architectural decisions, task groups, and an expanded roadmap.",
  "min_dotbot_version": "3.5",

  "form": {
    "modes": [
      {
        "id": "new_project",
        "condition": [
          "!.bot/workspace/product/mission.md"
        ],
        "label": "New Project",
        "description": "Describe your project and let Claude create your foundational product documents — mission, tech stack, and entity model.",
        "button": "LAUNCH PROJECT",
        "prompt_placeholder": "What are you building? What problem does it solve? What technologies are you using?",
        "show_interview": true,
        "show_files": true
      },
      {
        "id": "has_docs",
        "condition": ".bot/workspace/product/mission.md",
        "hidden": true
      }
    ]
  },

  "requires": {},

  "tasks": [
    {
      "name": "Product Documents",
      "type": "prompt",
      "workflow": "01-plan-product.md",
      "outputs": ["mission.md", "tech-stack.md", "entity-model.md"],
      "front_matter_docs": ["mission.md", "tech-stack.md", "entity-model.md"],
      "commit": {
        "paths": ["workspace/product/"],
        "message": "chore(workflow): phase 1 — product documents"
      },
      "priority": 0
    },
    {
      "name": "Generate Decisions",
      "type": "prompt",
      "workflow": "01b-generate-decisions.md",
      "depends_on": ["Product Documents"],
      "commit": {
        "paths": ["workspace/decisions/"],
        "message": "chore(workflow): phase 1b — architectural decisions"
      },
      "priority": 2
    },
    {
      "name": "Task Groups",
      "type": "prompt",
      "workflow": "03a-plan-task-groups.md",
      "depends_on": ["Generate Decisions"],
      "outputs": ["task-groups.json"],
      "post_script": "Scripts/Complete-TaskGroupsPhase.ps1",
      "commit": {
        "paths": ["workspace/product/"],
        "message": "chore(workflow): phase 2a — task groups and roadmap"
      },
      "priority": 3
    },
    {
      "name": "Task Group Expansion",
      "type": "script",
      "script": "Scripts/Expand-TaskGroups.ps1",
      "depends_on": ["Task Groups"],
      "outputs_dir": "tasks/todo",
      "min_output_count": 1,
      "commit": {
        "paths": ["workspace/tasks/"],
        "message": "chore(workflow): phase 2b — expanded task roadmap"
      },
      "priority": 4
    }
  ]
}

​manifest.json fields

​workflow.json top-level fields

​form object

​Flat form properties

​modes array

​requires object

​env_vars array

​mcp_servers array

​cli_tools array

​tasks array

​domain object

​Complete annotated example

`manifest.json` fields

`workflow.json` top-level fields

`form` object

Flat form properties

`modes` array

`requires` object

`env_vars` array

`mcp_servers` array

`cli_tools` array

`tasks` array

`domain` object

Complete annotated example