> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# workflow.json schema reference for dotbot

> Full schema reference for workflow.json and manifest.json - top-level fields, form configuration, the requires section, task types, and the domain object.

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`.              |

```json theme={null}
{
  "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](#form-object).                                                   |
| `requires`           | object | Runtime dependency declarations. See [requires object](#requires-object).                                          |
| `tasks`              | array  | Ordered pipeline definition. See [tasks array](#tasks-array).                                                      |
| `domain`             | object | Workflow-specific configuration block. Structure is defined by each workflow. See [domain object](#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`.

<ParamField path="description" type="string">
  Explanatory text shown in the kickstart card.
</ParamField>

<ParamField path="interview_label" type="string">
  Label for the interview toggle control (e.g. `"Research via Atlassian first"`).
</ParamField>

<ParamField path="interview_hint" type="string">
  Hint text shown below the interview toggle.
</ParamField>

<ParamField path="prompt_placeholder" type="string">
  Placeholder text for the free-text prompt input field.
</ParamField>

### `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.

<ParamField path="id" type="string" required>
  Unique identifier for this form mode (e.g. `"new_project"`, `"has_docs"`).
</ParamField>

<ParamField path="condition" type="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.
</ParamField>

<ParamField path="label" type="string">
  Button label shown in the kickstart card (e.g. `"New Project"`).
</ParamField>

<ParamField path="description" type="string">
  Explanatory text shown below the label.
</ParamField>

<ParamField path="button" type="string">
  Call-to-action text on the primary button (e.g. `"LAUNCH PROJECT"`).
</ParamField>

<ParamField path="prompt_placeholder" type="string">
  Placeholder text for the free-text prompt input field.
</ParamField>

<ParamField path="show_interview" type="boolean">
  When `true`, the kickstart dialog shows the guided requirements-gathering interview flow.
</ParamField>

<ParamField path="show_files" type="boolean">
  When `true`, the dialog shows a file-upload area.
</ParamField>

<ParamField path="show_prompt" type="boolean">
  When `true`, the dialog shows the free-text prompt input.
</ParamField>

<ParamField path="hidden" type="boolean">
  When `true`, this mode is never shown in the UI. Use this to suppress the kickstart form once a project is already initialised.
</ParamField>

***

## `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

<ParamField path="var" type="string">
  Environment variable name (e.g. `"ANTHROPIC_API_KEY"`).
</ParamField>

<ParamField path="name" type="string">
  Human-readable label for the variable.
</ParamField>

<ParamField path="message" type="string">
  Error message shown when the variable is missing.
</ParamField>

<ParamField path="hint" type="string">
  Guidance on how to set the variable.
</ParamField>

### `mcp_servers` array

<ParamField path="name" type="string">
  MCP server name (e.g. `"atlassian"`).
</ParamField>

<ParamField path="message" type="string">
  Error message shown when the server is not configured.
</ParamField>

<ParamField path="hint" type="string">
  Configuration instructions.
</ParamField>

### `cli_tools` array

<ParamField path="name" type="string">
  CLI tool executable name (e.g. `"git"`).
</ParamField>

<ParamField path="message" type="string">
  Error message shown when the tool is not installed.
</ParamField>

<ParamField path="hint" type="string">
  Installation instructions.
</ParamField>

***

## `tasks` array

The `tasks` array is the ordered pipeline definition. Each entry describes what the runtime executes, in which order, and under what conditions.

<ParamField path="name" type="string" required>
  Human-readable task name. Must be unique within the workflow. Used to resolve `depends_on` references.
</ParamField>

<ParamField path="type" 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.
</ParamField>

<ParamField path="workflow" type="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"`).
</ParamField>

<ParamField path="prompt" type="string">
  Path to the compiled template prompt file. Used with the `prompt_template` type (e.g. `"prompts/00-fast-prompt.md"`).
</ParamField>

<ParamField path="script" type="string">
  Path to the PowerShell script to run. Used with the `script` type (e.g. `"Scripts/Expand-TaskGroups.ps1"`).
</ParamField>

<ParamField path="post_script" type="string">
  Path to a PowerShell script run after the main task completes (e.g. `"Scripts/Complete-TaskGroupsPhase.ps1"`).
</ParamField>

<ParamField path="description" type="string">
  Human-readable description of what this task does. Shown in the dashboard.
</ParamField>

<ParamField path="acceptance_criteria" type="array of strings">
  List of conditions that define task completion. The AI executor uses these to self-evaluate the result.
</ParamField>

<ParamField path="outputs" type="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"]`).
</ParamField>

<ParamField path="outputs_dir" type="string">
  Directory where generated output files are written (e.g. `"tasks/todo"`).
</ParamField>

<ParamField path="depends_on" type="array of strings">
  Names of other tasks in the same workflow that must reach `done` status before this task starts.
</ParamField>

<ParamField path="optional" type="boolean">
  When `true`, the workflow continues even if this task produces no output or is skipped.
</ParamField>

<ParamField path="condition" type="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"`).
</ParamField>

<ParamField path="commit.paths" type="array of strings">
  Workspace-relative paths to include in the automatic git commit after this task completes.
</ParamField>

<ParamField path="commit.message" type="string">
  Commit message for the automatic commit (e.g. `"chore(workflow): phase 1 — product documents"`).
</ParamField>

<ParamField path="priority" type="integer">
  Execution priority within the workflow. Lower numbers run first (`0` runs before `1`).
</ParamField>

<ParamField path="on_failure" type="string">
  Action to take if the task fails. Use `"halt"` to stop the workflow on failure.
</ParamField>

<ParamField path="min_output_count" type="integer">
  Minimum number of output files required for the task to be considered successful. Relevant for `task_gen` tasks.
</ParamField>

<ParamField path="front_matter_docs" type="array of strings">
  Output files whose front matter should be extracted and surfaced as structured product metadata.
</ParamField>

<ParamField path="effort" type="string">
  Effort estimate for the task, used by the dashboard for display (e.g. `"XS"`, `"S"`, `"M"`, `"L"`).
</ParamField>

<ParamField path="category" type="string">
  Task category used for grouping and filtering in the dashboard (e.g. `"implementation"`, `"research"`).
</ParamField>

***

## `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.

```json theme={null}
"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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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
    }
  ]
}
```