dotbot architecture and directory layout

dotbot is a pure PowerShell framework with three cooperating systems: an MCP server that exposes tools to the AI agent, a web UI that gives the team visibility and control, and a runtime that manages AI process lifecycle, git worktree isolation, and two-phase execution. Framework files live in the dotbot install directory pointed to by $env:DOTBOT_HOME and are resolved at runtime by a layered content resolver - no framework code is copied into your project by default. Running dotbot init creates only the project’s .bot/workspace/ tree (tracked in git) and a .bot/.gitignore.

Three core systems

MCP server

A pure PowerShell stdio MCP server implementing protocol version 2024-11-05. Tools are auto-discovered from src/mcp/tools/{tool-name}/ subdirectories, and no registration is needed. The server exposes 31 tools across task management, session management, plans, decisions, steering, workflow control, and dev lifecycle. Because tools are file-based, you can add custom tools by dropping a metadata.json and script.ps1 into a new subfolder.

Web UI

A pure PowerShell HTTP server with a vanilla JS frontend. Seven tabs: Overview, Product, Roadmap, Processes, Decisions, Workflow, Settings. The default port is 8686; the server auto-selects the next available port if 8686 is busy. Launch the UI with dotbot go from your project root.

Runtime

Manages AI CLI invocations as tracked processes. The runtime handles git worktree isolation and coordinates two-phase execution (analysis then execution) for each task. AI provider invocations are normalised through a pluggable adapter layer in Dotbot.Harness, which ships adapters for Claude Code, Codex, Antigravity, Copilot, and OpenCode. An HTTP control plane (Dotbot.Runtime) exposes workflow run state over a local endpoint consumed by the dashboard, CLI commands, and the MCP server.

`.bot/` directory layout

dotbot init creates two items: a workspace/ tree tracked in git, and a .gitignore that excludes machine-local state.

.bot/
├── workspace/                    # Version-controlled project state
│   ├── tasks/
│   │   ├── workflow-runs/        # Tasks owned by a workflow run
│   │   └── standalone/           # Tasks run outside a workflow
│   ├── sessions/
│   │   ├── history/              # Completed session audit trails (tracked)
│   │   └── runs/                 # Active session logs (gitignored)
│   ├── plans/                    # Implementation plan files
│   ├── product/                  # Product docs (mission, tech stack, entity model)
│   ├── decisions/
│   │   ├── accepted/
│   │   ├── deprecated/
│   │   ├── proposed/
│   │   └── superseded/
│   ├── pilot/                    # Pilot experiment artifacts
│   └── reports/                  # Generated cost and progress reports
└── .gitignore                    # Excludes .control/, .handoffs/, session run logs

Three optional directories appear under .bot/ under specific conditions.

Directory	When it appears
`.control/`	Created and gitignored when the runtime starts or when a workflow/stack is selected during `dotbot init`. Holds `settings.json`, `runtime.json`, port files, and logs.
`content/`	Populated when a workflow or stack ships project-tier overrides, or when content is installed from a registry. Overrides under `.bot/content/<type>/<name>/` take precedence over the matching framework content in `$env:DOTBOT_HOME`.
`runtime/`	Populated only when `dotbot init --copy-runtime` is used. Contains a self-contained copy of the framework for projects that cannot rely on a shared `$env:DOTBOT_HOME`.

Content resolution

Framework content (agents, skills, prompts, workflows, stacks, MCP tools, hooks) lives in the dotbot install directory at $env:DOTBOT_HOME. The layered content resolver checks .bot/content/<type>/<name>/ first; if no project-level override exists, it falls back to $env:DOTBOT_HOME/content/<type>/<name>/. Your project only needs to include the files it wants to customise. Stacks follow the same pattern. A stack like dotnet-blazor declares extends: dotnet in its manifest; the resolver applies settings in dependency order and deep-merges them: framework defaults, then workflow settings, then stack settings. Settings declared closer to the project always win.

Runtime modules

The runtime is implemented as 19 PowerShell modules under src/runtime/Modules/ in the dotbot install directory.

Module	Purpose
Dotbot.Content	Layered content resolver. Looks up agents, skills, prompts, workflows, stacks, and hooks from `.bot/content/` before falling back to `$env:DOTBOT_HOME/content/`.
Dotbot.Core	Foundation helpers: path resolution, workspace identity GUID, ANSI-escape sanitization, and absolute-path stripping for logs. No dependencies on other Dotbot.* modules.
Dotbot.Executor	Plugin executor discovery and dispatch. Reads `metadata.json` from each executor plugin folder to map task types to their handler. Adding a new task type requires only a new plugin folder.
Dotbot.Handoff	Task-scoped handoff artifacts for human-in-the-loop pauses. Writes a compact handoff before a task enters `needs-input`; the next session attempt resumes from that artifact without creating a new task.
Dotbot.Harness	Pluggable AI harness layer. Registers per-provider adapters (Claude Code, Codex, Antigravity, Copilot, OpenCode) that normalise process launch, stream parsing, and exit-code classification. Replaces the old Dotbot.Provider module.
Dotbot.Hook	Transition hook discovery and dispatch. Hooks live on disk under the project or framework hook directories and are discovered at dispatch time.
Dotbot.Logging	Structured JSONL logging with levels (Debug, Info, Warn, Error, Fatal) and automatic log rotation. Writes to `.bot/.control/logs/dotbot-{date}.jsonl`.
Dotbot.Notification	Client for external notifications (Teams, Email, Jira) via the DotbotServer surface. Used by the `needs-input` transition and the notification poller.
Dotbot.Process	Process lifecycle management: a business-level process registry for long-running runners and a platform-aware child process launcher used by `go` and the CLI launchers.
Dotbot.Runtime	Per-project HTTP control plane. Owns the listener loop, authentication, routing, and workflow-run state. Composed of HttpServer, ControlPlaneClient, EndpointDiscovery, and Lifecycle.
Dotbot.SessionTracking	Session ID tracking for AI provider session continuation when a task is paused for human input and later resumed.
Dotbot.Settings	Four-tier settings loader and deep-merge utilities: framework default, project override, user-level, and `.control/settings.json`. Missing files are silently skipped.
Dotbot.Task	Task lifecycle: prompt building, completion detection, crash recovery, post-script hooks, merge-failure escalation, and the interactive interview loop.
Dotbot.TaskFile	Atomic, lock-protected, retry-aware mutations for task JSON files. Writes are crash-safe via temp-file rename; cross-state moves are atomic-then-cleanup.
Dotbot.TaskIndex	On-demand task index that reads task files fresh from disk on each access, with no in-process caching.
Dotbot.TaskInput	Shared in-process transitions for accepting human input on tasks, using the same atomic task-file primitives as the rest of the runtime.
Dotbot.Theme	Console theme engine. Reads the selected theme from `.control/ui-settings.json` and provides themed output helpers used across CLI and runtime surfaces.
Dotbot.Workflow	Workflow manifest utilities: parse `workflow.json`, create initial task sets, and merge MCP server configurations. Used by init, workflow-add, and workflow-run.
Dotbot.Worktree	Git worktree lifecycle management. Creates per-task branches and worktrees at analysis start, squash-merges them to the main branch on completion, and cleans up the worktree directory.

HTTP runtime

Dotbot.Runtime runs as an in-process HTTP server when dotbot go or dotbot serve starts. It publishes its address to .bot/.control/runtime.json so the UI server, MCP server, and CLI commands like dotbot runtime-status can discover it without hard-coded ports.

HttpServer - listener loop, request routing, and token authentication.
ControlPlaneClient - outbound registration with an optional mothership dashboard in fleet mode.
EndpointDiscovery - resolves the runtime URL from environment variables, settings, or the connection file.
Lifecycle - start, stale-PID detection, and graceful shutdown.

Runtime state: `.bot/.control/` vs `.bot/workspace/`

dotbot separates ephemeral machine-local state from durable version-controlled state into two distinct directories.

`.bot/.control/` - gitignored, machine-local

This directory is always gitignored. It contains:

Item	Description
`settings.json`	Machine-local settings: active workflow and stack selections. Wins over `settings.default.json`.
`runtime.json`	Runtime PID, URL, and start timestamp. Written when the runtime starts; removed on clean shutdown.
`ui-port`	Port file written by the UI server after its listener binds.
`logs/`	Structured JSONL log files (retention controlled by `logging.retention_days`).
`processes/`	Process registry entries tracking active AI CLI invocations.

Do not commit anything from .bot/.control/.

`.bot/workspace/` - version-controlled

This directory is committed to git. Every team member sees the same task queue, session history, product documents, and plans through standard git history.

Directory	Contents
`tasks/workflow-runs/`	Tasks owned by a named workflow run, organised by status sub-folder (`todo/`, `analysing/`, `analysed/`, `in-progress/`, `done/`, `needs-input/`, `skipped/`, `split/`).
`tasks/standalone/`	Tasks run outside a workflow via `dotbot tasks run`. Same status sub-folder layout.
`sessions/history/`	Completed session audit trails with token counts, costs, turn boundaries, and errors.
`product/`	Product documents: mission statement, tech stack definition, entity model.
`plans/`	Implementation plan markdown files, linked to tasks by ID.
`decisions/`	Architecture decision records in four states: `proposed/`, `accepted/`, `deprecated/`, `superseded/`.
`pilot/`	Pilot experiment artifacts.
`reports/`	Generated reports (cost summaries, progress reports).

Committing workspace/ to git means every task, question, answer, decision, and code change is auditable by your entire team through standard git tooling.

Git worktree isolation

Each prompt and prompt_template task runs in its own git branch (task/{short-id}-{slug}) and a separate worktree directory (../worktrees/{repo}/task-{short-id}-{slug}/). On completion, the task branch is squash-merged back to the main branch and the worktree is cleaned up. This approach keeps the main working tree clean during concurrent execution and makes per-task rollback trivial. script, mcp, and task_gen tasks skip worktree isolation and run directly in the project root. This is safe because those task types do not invoke the AI and make deterministic, auditable changes that do not require branch isolation.

​Three core systems

​MCP server

​Web UI

​Runtime

​.bot/ directory layout

​Content resolution

​Runtime modules

​HTTP runtime

​Runtime state: .bot/.control/ vs .bot/workspace/

​.bot/.control/ - gitignored, machine-local

​.bot/workspace/ - version-controlled

​Git worktree isolation