Skip to main content
dotbot integrates testing directly into the task lifecycle through verify hooks - numbered PowerShell scripts that run automatically after each AI task completes. Before marking a task as done and squash-merging it to your main branch, dotbot runs every verify hook in ascending filename order. If any hook exits with a non-zero code, the task is flagged and the merge is blocked.

​
How verify hooks work

When a task transitions to done, dotbot builds a merged hook chain from two directories:
  • Framework hooks at <DOTBOT_HOME>/src/hooks/verify/ - shipped with dotbot and managed by the framework.
  • Project hooks at .bot/hooks/verify/ - added by installed stacks or written by your team.
Scripts from both directories are merged by filename. When a project hook has the same filename as a framework hook, the project hook runs instead. Scripts with unique filenames from both directories all run. The final chain is sorted by filename, so the numeric prefix convention (00-, 01-, …) determines execution order. The five framework hooks included with every dotbot installation are: When you install the dotnet stack, it adds two additional scripts to .bot/hooks/verify/. Because their filenames differ from the framework scripts, all seven scripts run in order: Hooks from all installed stacks run together in a single ordered sequence, giving you a composable quality gate pipeline.

​
Adding a custom verify hook

To add your own test step, create a numbered PowerShell script in .bot/hooks/verify/. Choose a number higher than the built-in hooks to ensure your tests run after the standard checks:
Use a prefix between 10 and 99 for custom hooks so there is room to add more standard hooks later without renumbering your scripts.

​
Viewing hook results

Verify hook output is captured in the task’s session log and shown in the dashboard. When a hook fails:
  1. The task stays in in-progress - it is not marked done
  2. The failure reason and hook output appear in the session log under .bot/workspace/sessions/
  3. The Workflow tab in the dashboard shows the task as blocked with the hook’s exit code
To investigate, open the session log for the failed task and look for the hook name and the error output it produced.

​
Skipping verify hooks

script, mcp, task_gen, barrier, and interview task types skip verify hooks automatically. These task types are dispatched directly by the runtime executor without going through the task_set_status MCP path that fires the verify chain. Verify hooks always run for prompt and prompt_template tasks before the task is considered complete.
Run dotbot doctor to check whether verify hooks in your project have any syntax issues or reference missing commands. Doctor scans hook scripts and reports problems before you start a workflow run.

​
Running the dev environment for tests

Some verify hooks require a running development server. dotbot provides two MCP tools - dev_start and dev_stop - that the AI agent calls at the start and end of task execution when a running dev environment is needed. See Plans & Steering for details on these tools.