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

# Plans and operator steering MCP reference

> Reference for dotbot's plan management tools, the steering_heartbeat operator whisper mechanism, and the dev_start and dev_stop environment control tools.

dotbot exposes three categories of supporting MCP tools beyond task and session management: implementation plan management, operator steering, and development environment control. Plans are markdown documents linked to tasks that capture the implementation approach before execution begins. The steering heartbeat lets an operator inject guidance into a running autonomous session without stopping it. The dev tools start and stop the project's development environment via project-specific hook scripts.

***

## Plans

Implementation plans are stored in `.bot/workspace/plans/` and linked to their parent task by ID. The agent writes a plan before beginning implementation work, producing a detailed, reviewable approach document before making any code changes.

### `plan_create`

Creates an implementation plan for a task and links it to the task record. The plan is written as markdown and typically includes the goal, affected files, implementation approach, key patterns to follow, risks, and step-by-step instructions. **Required:** `task_id`, `content`.

<ParamField path="task_id" type="string" required>
  The task ID to create a plan for (e.g. `"task-a1b2c3d4"`).
</ParamField>

<ParamField path="content" type="string" required>
  The full markdown content of the plan. Typically includes: goal, affected files, implementation approach, key patterns to follow, risks, and step-by-step instructions.
</ParamField>

***

### `plan_get`

Retrieves the implementation plan for a task. The agent calls this at the start of execution to load the plan without re-running exploration. **Required:** `task_id`.

<ParamField path="task_id" type="string" required>
  The task ID whose plan to retrieve.
</ParamField>

Returns the full markdown content of the plan.

***

### `plan_update`

Replaces the content of an existing implementation plan. Use this when the agent refines the approach after initial planning, or when an operator reviews and revises the plan before execution begins. **Required:** `task_id`, `content`.

<ParamField path="task_id" type="string" required>
  The task ID whose plan to update.
</ParamField>

<ParamField path="content" type="string" required>
  The new markdown content of the plan. Replaces the existing content in full.
</ParamField>

***

## Steering

The steering mechanism is dotbot's human-in-the-loop channel for autonomous sessions. Rather than stopping the AI process to give feedback, you send a "whisper" message through the dashboard's Processes tab. The agent picks up the message at its next heartbeat and incorporates the guidance before proceeding.

### `steering_heartbeat`

Updates the process registry with a heartbeat and current status, and checks for operator whisper messages. The agent must call this tool between major steps during autonomous execution so that the operator can inject guidance without interrupting the session.

When a whisper is pending (set via the dashboard's Processes tab or the `steering.ps1` hook), `steering_heartbeat` returns the whisper text and clears it from the queue. The agent is expected to incorporate the guidance before proceeding to its next action. **Required:** `session_id`, `process_id`, `status`.

<ParamField path="session_id" type="string" required>
  The current session ID, obtained from `session_initialize`.
</ParamField>

<ParamField path="process_id" type="string" required>
  The process registry ID for this execution slot (e.g. `proc-a1b2c3`). This ID is passed to the agent via the launch prompt.
</ParamField>

<ParamField path="status" type="string" required>
  A short human-readable description of what the agent is currently doing (e.g. `"Analysing task d5093..."`). Shown in real time on the dashboard's Processes tab.
</ParamField>

<ParamField path="next_action" type="string">
  What the agent plans to do next (e.g. `"Check dependencies"`). Shown in the dashboard's Processes tab alongside the current status.
</ParamField>

<Tip>
  Call `steering_heartbeat` before and after each significant action - reading files, running tests, preparing a commit. Frequent heartbeats give operators real-time visibility and a tighter feedback loop for whispers.
</Tip>

***

## Development environment

The dev tools delegate entirely to project-specific hook scripts in `.bot/dev-scripts/`. The exact behaviour - starting a local server, running a file watcher, opening browser tabs - is defined by your project's stack, not by dotbot itself.

### `dev_start`

Starts or restarts the project's development environment by invoking `.bot/dev-scripts/Start-Dev.ps1`.

<ParamField path="noLayout" type="boolean">
  When `true`, skips opening any dev layout windows (terminal panes, browser tabs). Useful in CI or headless environments.
</ParamField>

***

### `dev_stop`

Stops the development environment by invoking `.bot/dev-scripts/Stop-Dev.ps1`. Takes no parameters.

<Note>
  `dev_start` and `dev_stop` delegate entirely to project-specific hook scripts. If your project does not have `Start-Dev.ps1` or `Stop-Dev.ps1` in `.bot/dev-scripts/`, these tools will do nothing.
</Note>