Workflows and stacks in dotbot

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:

{
  "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:

"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

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.

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:

{
  "name": "dotnet-blazor",
  "description": "Blazor-specific skills, component patterns, and rendering guidance",
  "extends": "dotnet"
}

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

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.

Installing workflows and stacks

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

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

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.

Get Started

Core Concepts

Guides

Dashboard

MCP Server

Workflows and stacks in dotbot

What workflows are

Anatomy of a workflow.json

Task types

What stacks are

How stacks compose with extends

Settings merge order

Installing workflows and stacks

​What workflows are

​Anatomy of a workflow.json

​Task types

​What stacks are

​How stacks compose with extends

​Settings merge order

​Installing workflows and stacks

What workflows are

Anatomy of a workflow.json

Task types

What stacks are

How stacks compose with extends

Settings merge order

Installing workflows and stacks