The `planner` Tool
Relevant source files
The following files were used as context for generating this wiki page:
The planner tool is a core component of the Zen MCP server designed to break down complex projects, features, or tasks into structured, actionable plans. It functions as an expert planning consultant and systems architect, taking a high-level objective and decomposing it into a series of logical, sequential steps. The tool is interactive, allowing for iterative refinement and exploration of alternative approaches through branching.
The planner is a key part of larger development workflows, often used at the beginning of a feature cycle to create a roadmap for implementation. It can be followed by other tools like codereview and precommit to ensure a systematic approach to development. The output is a structured JSON object, making it machine-readable and easy to integrate with other automated agents or systems.
Sources: README.md, systemprompts/planner_prompt.py:4-12, examples/skills/full-feature-cycle/SKILL.md
Core Architecture
The planner tool is implemented as the PlannerTool class, which inherits from BaseTool and WorkflowMixin. This structure provides it with standard tool functionalities and the ability to manage multi-step, stateful interactions.
Sources: tools/planner.py:21
Class Structure
The diagram below shows the key properties and methods of the PlannerTool class.
Sources: tools/planner.py:21-41
Execution Flow
When the planner tool is invoked, it follows a workflow managed by the WorkflowMixin. The process involves constructing a system prompt, sending it to the selected AI model, and parsing the structured JSON response.
This sequence diagram illustrates the high-level interaction when the planner tool is run.
Planning Methodology and Principles
The planner tool's behavior is strictly defined by the PLANNER_PROMPT. The AI model is instructed to act as an expert planning consultant and systems architect, following a specific methodology.
Sources: systemprompts/planner_prompt.py:4-12
Methodology
The planning process is guided by a set of core principles:
| Principle | Description |
|---|---|
| DECOMPOSITION | Break down the main objective into logical, sequential steps. |
| DEPENDENCIES | Identify which steps depend on others and order them appropriately. |
| BRANCHING | When multiple valid approaches exist, create branches to explore alternatives. |
| ITERATION | Be willing to step back and refine earlier steps if new insights emerge. |
| COMPLETENESS | Ensure all aspects of the task are covered without gaps. |
Sources: systemprompts/planner_prompt.py:30-35
Step Structure
Each step generated by the planner must adhere to a defined structure to ensure clarity and actionability.
- Step number and branch identifier
- Clear, actionable description
- Prerequisites or dependencies
- Expected outcomes
- Potential challenges or considerations
- Alternative approaches (when applicable)
Sources: systemprompts/planner_prompt.py:38-45
Structured JSON Output
A critical requirement of the planner tool is its response format. It must return only a valid JSON object that conforms to a predefined schema. This ensures that the output can be reliably parsed and used by the Zen MCP server to manage the planning workflow.
Sources: systemprompts/planner_prompt.py:60-62
JSON Schema
The table below details the fields in the main JSON response object for a successful planning step.
| Field | Type | Description |
|---|---|---|
status | string | The status of the planning step. Must be "planning_success". |
step_number | integer | The current step number in the plan. |
total_steps | integer | The estimated total number of steps. |
next_step_required | boolean | Indicates if another planning step is needed. |
step_content | string | A detailed description of the current planning step. |
metadata | object | An object containing metadata about the step (see below). |
continuation_id | string | A thread ID for maintaining conversation continuity. |
planning_complete | boolean | Set to true only on the final step of the plan. |
plan_summary | string | A complete summary of the plan, included only when planning_complete is true. |
next_steps | string | Guidance for the agent on the next actions to take. |
previous_plan_context | string | Context from previous plans, used only on step 1 with a continuation_id. |
Sources: systemprompts/planner_prompt.py:73-95
Metadata Schema
The metadata object provides more context about the step's position within the overall plan, especially concerning branching and revisions.
| Field | Type | Description |
|---|---|---|
branches | array | A list of branch IDs, if any exist at this point. |
step_history_length | integer | The number of steps completed so far. |
is_step_revision | boolean | true if this step revises a previous one. |
revises_step_number | integer | The step number that this step revises. |
is_branch_point | boolean | true if this step introduces new branches. |
branch_from_step | integer | The step number from which this branch originates. |
branch_id | string | A unique identifier for the current branch. |
more_steps_needed | boolean | Indicates if more planning steps are anticipated. |
Sources: systemprompts/planner_prompt.py:79-87
Handling Missing Information
If the planner determines that it lacks sufficient information to create a meaningful plan, it must respond with a specific JSON structure to request the necessary files.
{
"status": "files_required_to_continue",
"mandatory_instructions": "<your critical instructions for the agent>",
"files_needed": ["[file name here]", "[or some folder/]"]
}
Sources: systemprompts/planner_prompt.py:21-26, systemprompts/planner_prompt.py:65-70
Usage
The planner tool is designed to be invoked from a CLI with a natural language prompt describing the task to be planned.
Basic Usage
Use planner to create implementation plan for [功能描述].
Sources: examples/prompts/tool-usage-examples.md:68-70
Detailed Usage
For more complex tasks, requirements and constraints can be provided.
Use planner to break down this task:
[任务描述]
Requirements:
- [需求1]
- [需求2]
Constraints:
- [约束条件]
Sources: examples/prompts/tool-usage-examples.md:73-82
Integration with clink
The planner can also be invoked as a specialized agent via the clink tool, using a dedicated system prompt to guide its output format.
Sources: systemprompts/clink/default_planner.txt, README.md:200-201
Summary
The planner tool is a powerful, workflow-driven component for systematic task decomposition. By enforcing a rigorous planning methodology and a strict JSON output schema, it provides a reliable and automatable way to generate detailed implementation plans. Its integration into larger workflows and its ability to handle complex scenarios with branching and iteration make it a cornerstone of the Zen MCP server's development capabilities.