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 a workflow.yaml manifest. dotbot ships with four built-in workflows:
| Workflow | Purpose |
|---|
default | Lightweight kickstart — generates a product document with optional internet research |
kickstart-from-scratch | Full project kickstart from a plain-text description |
kickstart-via-jira | Research-driven kickstart with Atlassian and Azure DevOps integration |
kickstart-via-pr | Kickstart driven by an existing pull request |
form configuration for the kickstart dialog, declares environment and tooling requires, and contains a tasks list.
Anatomy of a workflow.yaml
The default workflow shows the minimal structure:
name: default
version: "3.5.0"
description: >-
Lightweight kickstart workflow — generates a single product document
from a user prompt, with optional internet research.
icon: terminal
min_dotbot_version: "3.5.0"
agents:
- implementer
- planner
- reviewer
- tester
skills:
- status
- verify
- write-test-plan
- write-unit-tests
form:
modes:
- id: new_project
condition:
- "!.bot/workspace/product/product.md"
label: "New Project"
description: "Describe your project and let Claude create a product document..."
button: "CREATE PRODUCT DOC"
show_interview: true
show_files: true
tasks:
- name: "Product Document"
type: prompt
workflow: "01-generate-product.md"
outputs: ["product.md"]
commit:
paths: ["workspace/product/"]
message: "chore(kickstart): product document"
priority: 0
- name: "Plan Internet Research"
type: task_gen
workflow: "02a-plan-internet-research.md"
depends_on: ["Product Document"]
optional: true
outputs_dir: "tasks/todo"
min_output_count: 1
priority: 1
- name: "Execute Research"
type: barrier
depends_on: ["Plan Internet Research"]
optional: true
priority: 2
kickstart-via-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 'claude mcp add atlassian' or 'dotbot init --force'"
cli_tools:
- name: git
message: "git CLI is required for repository cloning"
Task types
Every entry in tasks has a type field that controls how dotbot executes it.
| Type | What it does | Uses AI | Notes |
|---|
prompt | Runs an AI agent with a workflow-specific prompt file | Yes | The most common type; produces outputs committed to the workspace |
script | Runs a PowerShell script with no LLM involvement | No | Auto-promoted past analysis; skips worktree isolation and verify hooks |
mcp | Calls an MCP tool directly | No | Deterministic; skips AI phases |
task_gen | Generates sub-tasks dynamically using AI | Yes | Writes task JSON files to outputs_dir; requires min_output_count |
prompt_template | AI with a workflow-specific templated prompt | Yes | Similar to prompt but the prompt is rendered per-workflow |
barrier | Waits for all depends_on tasks to complete before the pipeline continues | No | Used to synchronise parallel fan-out branches |
script, mcp, and task_gen tasks bypass AI entirely. They auto-promote past the analysis phase, skip worktree isolation, and skip verification hooks. This lets you embed deterministic pipeline stages inside an AI-orchestrated workflow.
What stacks are
A stack is a named extension that overlays technology-specific content on top of the default workflow. Stacks can add:
- Skills — reusable AI guidance injected into the agent prompt (e.g. how to write Entity Framework migrations)
- Hooks —
Start-Dev.ps1, Stop-Dev.ps1, and numbered verify scripts
- MCP tools — additional tools auto-discovered by the MCP server
- Recipes — agent personas and workflow 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, component patterns, and rendering guidance |
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:
# stacks/dotnet-blazor/manifest.yaml
name: dotnet-blazor
description: Blazor-specific skills, component patterns, and rendering guidance
extends: dotnet
# stacks/dotnet-ef/manifest.yaml
name: dotnet-ef
description: Entity Framework migrations, design patterns, and database tools
extends: dotnet
dotnet-blazor, dotbot automatically resolves and applies the dotnet parent first. You do not need to list both explicitly.
Settings merge order
Settings deep-merge in the following order, with later layers taking precedence:
default → workflows → stacks
Run dotbot doctor to inspect the resolved settings for your project. It reports the merged configuration alongside any integrity issues.
Installing workflows and stacks
Use dotbot init with -Workflow and -Stack flags to install into a project:
# Install a specific workflow
dotbot init -Workflow kickstart-via-jira
# Install one or more stacks (comma-separated)
dotbot init -Stack dotnet-blazor,dotnet-ef
# Install both a workflow and a stack together
dotbot init -Workflow kickstart-via-jira -Stack dotnet
# List all available workflows and stacks
dotbot list
.bot/workflows/ and can be run, re-run, and stopped independently:
dotbot run kickstart-via-jira
dotbot registry add to link a git-hosted or local registry, then install from it with:
dotbot init -Workflow myorg:custom-workflow