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.

string

Explanatory text shown in the kickstart card.

string

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

string

Hint text shown below the interview toggle.

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

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.

string

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

string

Explanatory text shown below the label.

string

Call-to-action text on the primary button (e.g. "LAUNCH PROJECT").

string

Placeholder text for the free-text prompt input field.

boolean

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

boolean

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

boolean

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

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

string

Environment variable name (e.g. "ANTHROPIC_API_KEY").

string

Human-readable label for the variable.

string

Error message shown when the variable is missing.

string

Guidance on how to set the variable.

`mcp_servers` array

string

MCP server name (e.g. "atlassian").

string

Error message shown when the server is not configured.

string

Configuration instructions.

`cli_tools` array

string

CLI tool executable name (e.g. "git").

string

Error message shown when the tool is not installed.

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.

string

required

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

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.

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

string

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

string

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

string

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

string

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

array of strings

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

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

string

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

array of strings

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

boolean

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

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

array of strings

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

string

Commit message for the automatic commit (e.g. "chore(workflow): phase 1 — product documents").

integer

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

string

Action to take if the task fails. Use "halt" to stop the workflow on failure.

integer

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

array of strings

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

string

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

string

Task category used for grouping and filtering in the dashboard (e.g. "implementation", "research").

`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
    }
  ]
}

CLI

MCP Tools

Architecture

workflow.json schema reference for dotbot

`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

`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