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

# Workflows and stacks in dotbot

> Learn how dotbot uses workflow.json pipelines and technology stacks — with task types, stack inheritance, settings merge order, and install commands.

Workflows and stacks are the two building blocks you use to configure dotbot for a project. A workflow describes *what dotbot does* — a sequence of typed tasks wired together with dependencies, form configuration, and commit rules. A stack describes *what technology your project uses* — adding skills, verify scripts, and MCP tools relevant to a specific tech. You can install multiple workflows and multiple stacks in the same project and they all coexist independently.

## What workflows are

A workflow is a named pipeline defined by two JSON files: `workflow.json` holds the pipeline (form, requirements, and tasks) and `manifest.json` holds the metadata used by `dotbot list`. dotbot ships with these built-in workflows:

| Workflow            | Purpose                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `start-from-prompt` | Default workflow — takes a prompt and optional attached files and generates product documents, architectural decisions, task groups, and an expanded roadmap |
| `start-from-repo`   | Onboards an existing codebase by analysing its structure and git history into product docs, a changelog, a retrospective roadmap, and gap-analysis tasks     |
| `start-from-pr`     | Reads a GitHub or Azure DevOps pull request and derives mission, roadmap, and follow-up tasks from it                                                        |
| `start-from-jira`   | Research-driven workflow with Atlassian and Azure DevOps integration; fetches Jira context, runs multi-source research, and plans implementation             |
| `fast-prompt`       | Runs one submitted prompt as a single task with a minimal execution prompt                                                                                   |
| `smoke-test`        | Headless workflow that validates runtime execution without launching the UI or calling a provider                                                            |

`start-from-prompt` is the default workflow recorded for a new project. Each workflow declares its name and version, a `form` configuration for the launch dialog, environment and tooling `requires`, and a `tasks` list.

## Anatomy of a workflow\.json

The `start-from-prompt` workflow shows the structure. Each task names a `type`, the prompt file or script it runs, its dependencies, and how its output is committed:

```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.",
        "button": "LAUNCH PROJECT",
        "show_interview": true,
        "show_files": true
      }
    ]
  },
  "requires": {},
  "tasks": [
    {
      "name": "Product Documents",
      "type": "prompt",
      "workflow": "01-plan-product.md",
      "outputs": ["mission.md", "tech-stack.md", "entity-model.md"],
      "commit": {
        "paths": ["workspace/product/"],
        "message": "chore(workflow): phase 1 — product documents"
      },
      "priority": 0
    },
    {
      "name": "Task Group Expansion",
      "type": "script",
      "script": "Scripts/Expand-TaskGroups.ps1",
      "depends_on": ["Task Groups"],
      "outputs_dir": "tasks/todo",
      "min_output_count": 1,
      "priority": 4
    }
  ]
}
```

More complex workflows like `start-from-jira` also declare environment variables, MCP server dependencies, and CLI tool requirements under a `requires` block:

```json theme={null}
"requires": {
  "env_vars": [
    {
      "var": "AZURE_DEVOPS_PAT",
      "name": "Azure DevOps PAT",
      "message": "Azure DevOps PAT is 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 'dotbot init --force' to re-register the server"
    }
  ],
  "cli_tools": [
    {
      "name": "git",
      "message": "git CLI is required for repository cloning"
    }
  ]
}
```

## Task types

Every entry in `tasks` has a `type` field that selects the executor dotbot uses to run it. Executors are a plugin system indexed by `task_type`, so each type has its own contract.

| Type              | What it does                                                                                                   | Uses a provider session |
| ----------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `prompt`          | Runs the provider with a workflow-specific prompt file; the most common type                                   | Yes                     |
| `prompt_template` | A `prompt` variant whose prompt is supplied when the workflow launches; runs through the same path as `prompt` | Yes                     |
| `interview`       | Runs the interactive interview loop and checks that an interview summary was produced                          | Yes                     |
| `script`          | Runs a PowerShell script declared on the task; succeeds or fails on the script exit code                       | No                      |
| `mcp`             | Calls an MCP tool with the arguments declared on the task                                                      | No                      |
| `task_gen`        | Runs a generator script that writes new task JSON files; validated against `min_output_count`                  | No                      |
| `barrier`         | Completes once all its `depends_on` tasks are satisfied; used to synchronise parallel branches                 | No                      |

<Note>
  The `script`, `mcp`, `task_gen`, and `barrier` types run deterministically without a provider session and skip verification hooks. They still run inside the task's isolated git worktree, so their output is committed the same way as any other task.
</Note>

## What stacks are

A stack is a named extension that overlays technology-specific content on top of a workflow. Stacks can add:

* **Skills** — reusable guidance injected into the agent prompt, for example how to write Entity Framework migrations
* **Hooks** — `Start-Dev.ps1`, `Stop-Dev.ps1`, and numbered verify scripts
* **MCP tools** — additional tools the MCP server discovers
* **Recipes** — agent personas and prompts tailored to the technology

dotbot ships with three built-in stacks:

| Stack           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `dotnet`        | .NET skills, hooks, dev environment, and MCP tools               |
| `dotnet-blazor` | Blazor-specific skills and component patterns                    |
| `dotnet-ef`     | Entity Framework migrations, design patterns, and database tools |

## How stacks compose with extends

Stacks can declare an `extends` field to automatically pull in a parent stack. `dotnet-blazor` and `dotnet-ef` both extend `dotnet`:

```json theme={null}
{
  "name": "dotnet-blazor",
  "description": "Blazor-specific skills, component patterns, and rendering guidance",
  "extends": "dotnet"
}
```

```json theme={null}
{
  "name": "dotnet-ef",
  "description": "Entity Framework migrations, design patterns, and database tools",
  "extends": "dotnet"
}
```

When you install `dotnet-blazor`, dotbot resolves and applies the `dotnet` parent first. You do not need to list both.

## Settings merge order

Each workflow and stack can ship its own `settings/settings.default.json`. These overlay through a deep merge, with later layers taking precedence:

```
default → workflows → stacks → project
```

Your workflow can override a default setting, and a stack can override both the default and the workflow setting. Project-level state in `.bot/.control/settings.json` wins last.

<Tip>
  Run `dotbot doctor` to confirm the resolved settings for your project. It reports whether the merged configuration is valid and carries both the `execution` and `analysis` blocks.
</Tip>

## Installing workflows and stacks

Use `dotbot init` with `--workflow` and `--stack` flags to install into a project:

```powershell theme={null}
# Install a stack
dotbot init --stack dotnet

# Install both a workflow and a stack together
dotbot init --workflow start-from-jira --stack dotnet-blazor

# List all available workflows and stacks
dotbot list
```

Installed workflows are materialised under `.bot/content/workflows/<name>/`, and stacks under `.bot/content/stacks/<name>/`. You can add, remove, list, and run workflows independently:

```powershell theme={null}
dotbot workflow add start-from-jira
dotbot workflow list
dotbot run start-from-jira
```

You can also source workflows and stacks from enterprise registries. Use `dotbot registry add` to link a git-hosted or local registry, then list and update registered registries with `dotbot registry list` and `dotbot registry update`.