Implement new `plan` command #1072

New issue

Open

opened 2025-10-14 16:47:00 -06:00 by navan · 0 comments

navan commented

2025-10-14 16:47:00 -06:00

Owner

Originally created by @eyaltoledano on 4/1/2025

"We need a new plan command that appends a detailed, step-by-step implementation plan directly into the task or subtask details. This command should outline actionable items clearly enough for immediate AI execution."

Motivation

Creating low-level, actionable plans directly within tasks or subtasks helps streamline AI-driven development. Frontloading these implementation plans into tasks reduces ambiguity, provides immediate clarity on the next steps, and enhances the productivity and accuracy of AI-driven task execution.

What's more, implementation plans sometimes need to change. If I create a new task or subtask, and then update or expand it, my implementation plan needs to change. The AI could probably figure it out (and it does) off the task or subtask only, but providing the clear step-by-step reduces ai soul-searching post-prompt, reduces token usage and context window waste, and generally reduces variance in the ai responses.

You want the AI's first reply to your prompt to be "Let's implement ..." not "Let me understand how we..."

Proposed Solution

Introduce a new CLI command: task-master plan --id=<task|subtask_ids> [--research] [--all]

This command generates and appends an <implementation_plan> XML-tagged section with a timestamp to the existing task or subtask's details, very similarly to add-subtask (which appends details rather than completely rewrites them).
The plan includes clear, step-by-step, low-level actions ready for immediate AI execution, such as:
- Searching specific existing files
- Creating specific new files
- Modifying specific existing files and functions
- Importing or updating specific functions to specific files
- and other low-level details for completing the task while keeping to a minimum the number of implementation plan steps. The goal is specificity without needless complexity or scope creep.
The command will accept the --research flag to optionally utilize the Perplexity API for research-backed planning; otherwise, it defaults to Claude.
The command will support an additional --all flag, mimicking the behavior of update --all, to generate and append implementation plans for all tasks/subtasks.
Users can specify multiple task or subtask IDs, comma-separated, to generate implementation plans for specific groups of tasks/subtasks.

Updating Implementation Plans on Task/Subtask Changes

Any time a task or subtask is updated or expanded, its implementation plan should also be refreshed accordingly. The most recent task and/or subtask details and structure must be passed as context when generating the new implementation plan. This ensures that the implementation plan remains accurate and aligned with the current state of tasks and subtasks.

For subtasks, the implementation plan will scope itself specifically to that subtask while being aware of how other tasks and subtasks fit into the broader context.

High-Level Workflow

Parse the provided task/subtask IDs (support single, multiple comma-separated, or --all).
Extract existing details from both tasks.json and the individual task/subtask files.
Construct a system prompt to generate a precise implementation plan.
Call the selected AI service (Claude or Perplexity, based on --research) to generate the plan.
Append the AI-generated plan to the existing task/subtask details within <implementation_plan> tags, including timestamp, research status, and AI service used.
Save the updated details back to the task files and tasks.json.
Display a confirmation card indicating the successful creation and appending of the plan.

Key Elements

Command syntax:

task-master plan --id=<id[,id2,...]> [--research] [--all]

XML format for appended content:

<implementation_plan as of="2025-04-01T12:00:00" researched="true" ai_service="Perplexity">
  1. Step one details...
  2. Step two details...
  ...
</implementation_plan>

Integration with existing logic from update-subtask for consistent behavior.

Example Workflow

# Generate and append implementation plan using Claude for single task
task-master plan --id=15

# Generate and append research-backed implementation plan using Perplexity for multiple tasks/subtasks
task-master plan --id=8.3,9,12.1 --research

# Generate and append implementation plans for all tasks/subtasks
task-master plan --all

Example appended details:

<implementation_plan as of="2025-04-01T12:00:00" researched="true" ai_service="Perplexity">
  1. Search `utils.js` for the helper function `parseData()`.
  2. Modify `parseData()` to include error handling for null inputs.
  3. Create a new test file `parseData.test.js` under the `tests/` directory.
  4. Write unit tests for the updated `parseData()` function.
</implementation_plan>

Implementation Considerations

Ensure the plan clearly identifies actionable file operations or immediate implementation steps.
Validate IDs robustly to differentiate between tasks and subtasks.
Maintain consistency with the existing update-subtask command logic, leveraging similar patterns.
Ensure compatibility with milestone-based task scoping when applicable.
Provide clear CLI feedback to users upon successful plan creation.
Implement robust handling and clear messaging when using --all or multiple IDs.
Add MCP support immediately

Out of Scope (Future Considerations)

Plan validation or manual approval workflows
CLI support for editing implementation plans (just make a new one, the time stamp will tell the AI to use the latest one).

*Originally created by @eyaltoledano on 4/1/2025* > "We need a new `plan` command that appends a detailed, step-by-step implementation plan directly into the task or subtask details. This command should outline actionable items clearly enough for immediate AI execution." --- ### Motivation Creating low-level, actionable plans directly within tasks or subtasks helps streamline AI-driven development. Frontloading these implementation plans into tasks reduces ambiguity, provides immediate clarity on the next steps, and enhances the productivity and accuracy of AI-driven task execution. What's more, implementation plans sometimes need to change. If I create a new task or subtask, and then update or expand it, my implementation plan needs to change. The AI could probably figure it out (and it does) off the task or subtask only, but providing the clear step-by-step reduces ai soul-searching post-prompt, reduces token usage and context window waste, and generally reduces variance in the ai responses. You want the AI's first reply to your prompt to be "Let's implement ..." not "Let me understand how we..." --- ### Proposed Solution Introduce a new CLI command: `task-master plan --id=<task|subtask_ids> [--research] [--all]` - This command generates and appends an `<implementation_plan>` XML-tagged section with a timestamp to the existing task or subtask's details, very similarly to `add-subtask` (which appends details rather than completely rewrites them). - The plan includes clear, step-by-step, low-level actions ready for immediate AI execution, such as: - Searching specific existing files - Creating specific new files - Modifying specific existing files and functions - Importing or updating specific functions to specific files - and other low-level details for completing the task while keeping to a minimum the number of implementation plan steps. The goal is specificity without needless complexity or scope creep. - The command will accept the `--research` flag to optionally utilize the Perplexity API for research-backed planning; otherwise, it defaults to Claude. - The command will support an additional `--all` flag, mimicking the behavior of `update --all`, to generate and append implementation plans for all tasks/subtasks. - Users can specify multiple task or subtask IDs, comma-separated, to generate implementation plans for specific groups of tasks/subtasks. ### Updating Implementation Plans on Task/Subtask Changes Any time a task or subtask is updated or expanded, its implementation plan should also be refreshed accordingly. The most recent task and/or subtask details and structure must be passed as context when generating the new implementation plan. This ensures that the implementation plan remains accurate and aligned with the current state of tasks and subtasks. - For subtasks, the implementation plan will scope itself specifically to that subtask while being aware of how other tasks and subtasks fit into the broader context. --- ### High-Level Workflow 1. Parse the provided task/subtask IDs (support single, multiple comma-separated, or `--all`). 2. Extract existing details from both `tasks.json` and the individual task/subtask files. 3. Construct a system prompt to generate a precise implementation plan. 4. Call the selected AI service (Claude or Perplexity, based on `--research`) to generate the plan. 5. Append the AI-generated plan to the existing task/subtask details within `<implementation_plan>` tags, including timestamp, research status, and AI service used. 6. Save the updated details back to the task files and `tasks.json`. 7. Display a confirmation card indicating the successful creation and appending of the plan. --- ### Key Elements - Command syntax: ```shell task-master plan --id=<id[,id2,...]> [--research] [--all] ``` - XML format for appended content: ```xml <implementation_plan as of="2025-04-01T12:00:00" researched="true" ai_service="Perplexity"> 1. Step one details... 2. Step two details... ... </implementation_plan> ``` - Integration with existing logic from `update-subtask` for consistent behavior. --- ### Example Workflow ```shell # Generate and append implementation plan using Claude for single task task-master plan --id=15 # Generate and append research-backed implementation plan using Perplexity for multiple tasks/subtasks task-master plan --id=8.3,9,12.1 --research # Generate and append implementation plans for all tasks/subtasks task-master plan --all ``` Example appended details: ```xml <implementation_plan as of="2025-04-01T12:00:00" researched="true" ai_service="Perplexity"> 1. Search `utils.js` for the helper function `parseData()`. 2. Modify `parseData()` to include error handling for null inputs. 3. Create a new test file `parseData.test.js` under the `tests/` directory. 4. Write unit tests for the updated `parseData()` function. </implementation_plan> ``` --- ### Implementation Considerations - Ensure the plan clearly identifies actionable file operations or immediate implementation steps. - Validate IDs robustly to differentiate between tasks and subtasks. - Maintain consistency with the existing `update-subtask` command logic, leveraging similar patterns. - Ensure compatibility with milestone-based task scoping when applicable. - Provide clear CLI feedback to users upon successful plan creation. - Implement robust handling and clear messaging when using `--all` or multiple IDs. - Add MCP support immediately --- ### Out of Scope (Future Considerations) - Plan validation or manual approval workflows - CLI support for editing implementation plans (just make a new one, the time stamp will tell the AI to use the latest one).