todo-task-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Command arguments: $ARGUMENTS

命令参数: $ARGUMENTS

Usage

使用方法

/todo-task-planning <file_path> [--pr] [--branch <name>]

/todo-task-planning <file_path> [--pr] [--branch <name>]

Arguments

参数说明

```
file_path
```
(required): Path to the file for task planning execution
```
--pr
```
(optional): Create a pull request after task completion. When specified, tasks will include branch creation (auto-generated if --branch not specified), commits, and PR creation
```
--branch <name>
```
(optional): Branch name to create and use for task execution. Creates the specified branch and commits all changes to it. Can be used independently or with --pr option

```
file_path
```
（必填）：用于执行任务规划的文件路径
```
--pr
```
（可选）：任务完成后创建Pull Request。指定该参数时，任务将包含分支创建（若未指定--branch则自动生成）、提交和PR创建步骤
```
--branch <name>
```
（可选）：创建并用于任务执行的分支名称。会创建指定分支并将所有变更提交至该分支。可独立使用或与--pr选项配合使用

Command Overview

命令概述

This command reads the specified file ($ARGUMENTS) and performs comprehensive task planning. It can be executed repeatedly on the same file and also manages, confirms, and updates questions.

Important: This command is designed to be executed repeatedly. Do not question the fact that the same command will be executed multiple times; analyze and plan with a fresh perspective each time.

Important: The file specified in $ARGUMENTS will be the TODO management file. Avoid including specifications and research results in this file as much as possible; use docs/memory to store research results. Also, do not excessively abbreviate research results; retain them. Check each time whether you have researched something in the past. Do not neglect checking to avoid duplicating research results and tasks.

本命令读取指定文件（$ARGUMENTS）并执行全面的任务规划。可对同一文件重复执行，同时管理、确认和更新问题。

重要提示：本命令设计为可重复执行。请勿质疑同一命令多次执行的合理性，每次执行都要以全新视角进行分析和规划。

重要提示：$ARGUMENTS中指定的文件为TODO管理文件。请尽量避免在该文件中包含规格说明和研究结果；请使用docs/memory存储研究结果。同时，不要过度简化研究结果，需完整保留。每次执行时请检查是否曾进行过相关研究，避免重复研究和任务。

Branch and PR Options Usage

分支与PR选项使用说明

Option Behavior

选项行为

--branch [branch_name]
option:

Adds a branch creation task at the beginning of the task list
If
```
branch_name
```
is provided: Uses the specified branch name
If
```
branch_name
```
is omitted: Auto-generates branch name following Git naming conventions
All commits during task execution will be made to this branch
Can be used independently without
```
--pr
```
Useful when you want to work on a feature branch but don't need a PR yet

Branch name auto-generation rules:

Analyzes TODO file content to determine branch type and purpose
Follows Git naming conventions:
```
{type}/{descriptive-name}
```
Types:
```
feature/
```
,
```
bugfix/
```
,
```
refactor/
```
,
```
chore/
```
,
```
docs/
```
Format: lowercase, hyphen-separated, English
Example:
```
feature/actionlog-email-notification
```

--pr
option:

Includes all
```
--branch
```
functionality (branch creation and commits)
Adds a pull request creation task at the end of the task list
If
```
--branch
```
is not specified, a branch name will be auto-generated
The PR will include all changes made during task execution
If PR template instructions exist in CLAUDE.md or similar files, those templates will be used

--branch [branch_name]
选项：

在任务列表开头添加分支创建任务
若提供
```
branch_name
```
：使用指定的分支名称
若省略
```
branch_name
```
：遵循Git命名规范自动生成分支名称
任务执行期间的所有提交都将提交至该分支
可独立使用，无需配合
```
--pr
```
适用于需要在功能分支上工作但暂不需要PR的场景

分支名称自动生成规则：

分析TODO文件内容以确定分支类型和用途
遵循Git命名规范：
```
{type}/{descriptive-name}
```
类型包括：
```
feature/
```
,
```
bugfix/
```
,
```
refactor/
```
,
```
chore/
```
,
```
docs/
```
格式：小写、连字符分隔、英文
示例：
```
feature/actionlog-email-notification
```

--pr
选项：

包含
```
--branch
```
的所有功能（分支创建和提交）
在任务列表末尾添加Pull Request创建任务
若未指定
```
--branch
```
，将自动生成分支名称
PR将包含任务执行期间的所有变更
若CLAUDE.md或类似文件中存在PR模板说明，将使用这些模板

Usage Examples

使用示例

bash

undefined

bash

undefined

Example 1: Create branch with auto-generated name (no PR)

示例1：使用自动生成的名称创建分支（不创建PR）

/todo-task-planning TODO.md --branch

→ Generates branch name like: feature/actionlog-notification

→ 生成类似如下的分支名称：feature/actionlog-notification

Example 2: Create branch with specific name (no PR)

示例2：使用指定名称创建分支（不创建PR）

/todo-task-planning docs/todos/feature-x.md --branch feature/user-auth

Example 3: Create PR with auto-generated branch name

示例3：使用自动生成的分支名称创建PR

/todo-task-planning docs/todos/feature-x.md --pr

→ Auto-generates branch name and creates PR

→ 自动生成分支名称并创建PR

Example 4: Create PR with specific branch name

示例4：使用指定分支名称创建PR

/todo-task-planning docs/todos/feature-x.md --pr --branch feature/user-auth

Example 5: Basic task planning (no branch, no PR)

示例5：基础任务规划（无分支、无PR）

/todo-task-planning docs/todos/feature-x.md

undefined

/todo-task-planning docs/todos/feature-x.md

undefined

Implementation Guidance

实现指南

When these options are specified, the task planning should include:

For
--branch
option:

Branch Name Determination:
- If branch name is provided: Use as-is (validate against naming conventions)
- If branch name is omitted: Auto-generate following this logic:
  1. Read TODO file title and content
  2. Determine branch type based on task nature:
    - feature/
      - New functionality implementation
    - bugfix/
      - Bug fixes, issue resolution
    - refactor/
      - Code restructuring without behavior change
    - chore/
      - Development environment, dependencies, tooling
    - docs/
      - Documentation updates
  3. Extract key feature/issue name from TODO (2-4 words max)
  4. Convert to lowercase, hyphen-separated English
  5. Format:
```
{type}/{descriptive-name}
```
  6. Example: "ActionLog Email Notification" →
```
feature/actionlog-email-notification
```
Task to create the determined/generated branch at the beginning
All modification tasks should indicate they will be committed to this branch
No PR-related tasks

For
--pr
option:

Task to create a branch (using specified name or auto-generated)
All modification tasks with commit instructions
Final task to create a pull request with proper description
PR description should summarize all changes made

当指定这些选项时，任务规划应包含以下内容：

对于
--branch
选项：

分支名称确定：
- 若提供分支名称：直接使用（需验证是否符合命名规范）
- 若省略分支名称：按照以下逻辑自动生成：
  1. 读取TODO文件标题和内容
  2. 根据任务性质确定分支类型：
    - feature/
      - 新功能实现
    - bugfix/
      - 缺陷修复、问题解决
    - refactor/
      - 代码重构（不改变功能）
    - chore/
      - 开发环境、依赖项、工具相关
    - docs/
      - 文档更新
  3. 从TODO中提取关键功能/问题名称（最多2-4个词）
  4. 转换为小写、连字符分隔的英文格式
  5. 格式：
```
{type}/{descriptive-name}
```
  6. 示例："ActionLog Email Notification" →
```
feature/actionlog-email-notification
```
在任务列表开头添加创建确定/生成的分支的任务
所有修改任务需注明将提交至该分支
不包含PR相关任务

对于
--pr
选项：

添加创建分支的任务（使用指定名称或自动生成）
所有修改任务需包含提交说明
最后添加创建Pull Request的任务，需包含合适的描述
PR描述应总结所有已做变更

Reference Documentation

参考文档

todo-task-run skill
key-guidelines skill

todo-task-run 技能
key-guidelines 技能

Core Guidelines

核心指南

Phase 0 reads and applies

/key-guidelines

at the start of every execution

第0阶段：在每次执行开始时读取并应用

/key-guidelines

[CRITICAL]Important Implementation Requirements

[CRITICAL]重要实现要求

MANDATORY: This command MUST update the $ARGUMENTS file (the file specified as a parameter)

Main Claude executor (not a subagent) uses Edit or Write tool to update files
After calling subagents in Phase 1, update the $ARGUMENTS file with those results in Phase 5
Add new task planning results in a structured format while preserving existing content
After file update is complete, confirm, verify, and report the updated content
CRITICAL: The $ARGUMENTS file update is NOT optional - it must be executed in every run

强制要求：本命令必须更新$ARGUMENTS文件（作为参数指定的文件）

主Claude执行器（而非子代理）使用Edit或Write工具更新文件
在第1阶段调用子代理后，第5阶段需用这些结果更新$ARGUMENTS文件
在保留现有内容的同时，以结构化格式添加新的任务规划结果
文件更新完成后，需确认、验证并报告更新后的内容
CRITICAL：更新$ARGUMENTS文件并非可选操作——每次执行都必须执行

Processing Flow

处理流程

[CRITICAL]Phase Dependency and Execution Rules

[CRITICAL]阶段依赖与执行规则

[PROHIBITED]PROHIBITED PHASE SHORTCUTS - MUST FOLLOW SEQUENTIAL FLOW ⛔

The following phase shortcuts are STRICTLY PROHIBITED:

[NG]Phase 1 → Phase 5 direct transition (MOST COMMON VIOLATION)
[NG]Phase 1 → Phase 6 direct transition
[NG]Phase 2 → Phase 5 direct transition (skipping Phase 3-4)
[NG]Phase 3 → Phase 5 direct transition (skipping Phase 4)

Why These Shortcuts Are Dangerous:

Data Loss: Phase 2 existing task analysis will be ignored
No Integration: New tasks won't integrate with existing TODO.md content
Missing Validation: User questions won't be asked, leading to incorrect assumptions
File Creation Failures: docs/memory files won't be created at proper time

[PROHIBITED]禁止阶段跳转——必须遵循顺序流程 ⛔

以下阶段跳转是严格禁止的：

[NG]直接从第1阶段跳至第5阶段（最常见违规）
[NG]直接从第1阶段跳至第6阶段
[NG]直接从第2阶段跳至第5阶段（跳过第3-4阶段）
[NG]直接从第3阶段跳至第5阶段（跳过第4阶段）

这些跳转的危害：

数据丢失：将忽略第2阶段的现有任务分析
无集成：新任务无法与现有TODO.md内容集成
缺少验证：不会询问用户问题，导致错误假设
文件创建失败：docs/memory文件无法在正确时间创建

📊 Phase Dependency Flow Chart

📊 阶段依赖流程图

┌─────────────────────────────────────────────────────────────────┐
│                    PHASE EXECUTION FLOW                         │
│                 (MUST FOLLOW SEQUENTIAL ORDER)                  │
└─────────────────────────────────────────────────────────────────┘

Phase 0: Key Guidelines Reading → [詳細](PHASE-0-KEY-GUIDELINES.md)    [OK]MANDATORY
└─ Read and apply key-guidelines skill
   └─ Output: guidelines_loaded
              ↓
Phase 1: TODO File Reading → [詳細](PHASE-1-TODO-READING.md)          [OK]MANDATORY
└─ Read and parse $ARGUMENTS file
   └─ Parse --pr and --branch options
   └─ Output: HAS_PR_OPTION, HAS_BRANCH_OPTION, BRANCH_NAME
              ↓
Phase 2: Explore Subagent → [詳細](PHASE-2-EXPLORE.md)                [OK]MANDATORY
└─ Call Task tool (Explore)
   └─ Output: exploration_results
              ↓
Phase 3: Plan Subagent → [詳細](PHASE-3-PLAN.md)                      [OK]MANDATORY
└─ Call Task tool (Plan) with exploration_results
   └─ Output: planning_results
              ↓
Phase 4: project-manager skill → [詳細](PHASE-4-PROJECT-MANAGER.md)   [OK]MANDATORY
└─ Call Skill tool (project-manager) with exploration + planning results
   └─ Output: strategic_plan
              ↓
Phase 5: Verification → [詳細](PHASE-5-VERIFICATION.md)               [OK]MANDATORY
└─ Verify all subagents completed successfully
   └─ Verify: exploration_results, planning_results, strategic_plan exist
              ↓
Phase 6: File Analysis → [詳細](PHASE-6-ANALYSIS.md)                  [OK]MANDATORY
└─ Read $ARGUMENTS file
   └─ Output: existingTasks, taskProgress
              ↓
Phase 7: Task Analysis & Breakdown → [詳細](PHASE-7-BREAKDOWN.md)     [OK]MANDATORY
└─ Input: Phase 1-5 results + Phase 6 results
   └─ Output: Task breakdown, feasibility analysis
              ↓
Phase 8: Question Management → [詳細](PHASE-8-QUESTIONS.md)           [WARNING]CONDITIONAL
├─ CONDITION A: Questions exist         [OK]MANDATORY
│  └─ Execute AskUserQuestion tool
│  └─ Wait for user responses
│  └─ Create questions.md file
│  └─ Output: User decisions recorded
├─ CONDITION B: No questions            [OK]ALLOWED (Must document reason)
│  └─ Proceed to Phase 9
│  └─ Document why no questions needed
└─ [PROHIBITED]GATE: Phase 9 entrance checkpoint
              ↓
Phase 9: File Update → [詳細](PHASE-9-UPDATE.md)                      [OK]MANDATORY
├─ Create docs/memory files (exploration, planning, questions)
├─ Update $ARGUMENTS file with task checklist
├─ Conditional branch/PR task insertion:
│  └─ Evaluate HAS_BRANCH_OPTION and HAS_PR_OPTION
│  └─ Insert branch creation task if needed (beginning)
│  └─ Insert PR creation task if needed (end)
└─ Output: Complete TODO.md with all tasks
              ↓
Phase 10: Verification & Feedback → [詳細](PHASE-10-VERIFICATION.md)  [OK]MANDATORY
└─ Verify file updates, AskUserQuestion execution
   └─ Report to user

┌─────────────────────────────────────────────────────────────────┐
│                    阶段执行流程                                 │
│                 (必须遵循顺序执行)                              │
└─────────────────────────────────────────────────────────────────┘

Phase 0: 核心指南读取 → [詳細](PHASE-0-KEY-GUIDELINES.md)    [OK]强制要求
└─ 读取并应用key-guidelines技能
   └─ 输出: guidelines_loaded
              ↓
Phase 1: TODO文件读取 → [詳細](PHASE-1-TODO-READING.md)          [OK]强制要求
└─ 读取并解析$ARGUMENTS文件
   └─ 解析--pr和--branch选项
   └─ 输出: HAS_PR_OPTION, HAS_BRANCH_OPTION, BRANCH_NAME
              ↓
Phase 2: 探索子代理 → [詳細](PHASE-2-EXPLORE.md)                [OK]强制要求
└─ 调用Task工具（Explore）
   └─ 输出: exploration_results
              ↓
Phase 3: 规划子代理 → [詳細](PHASE-3-PLAN.md)                      [OK]强制要求
└─ 传入exploration_results调用Task工具（Plan）
   └─ 输出: planning_results
              ↓
Phase 4: project-manager技能 → [詳細](PHASE-4-PROJECT-MANAGER.md)   [OK]强制要求
└─ 传入探索+规划结果调用Skill工具（project-manager）
   └─ 输出: strategic_plan
              ↓
Phase 5: 验证 → [詳細](PHASE-5-VERIFICATION.md)               [OK]强制要求
└─ 验证所有子代理已成功完成
   └─ 验证: exploration_results, planning_results, strategic_plan已存在
              ↓
Phase 6: 文件分析 → [詳細](PHASE-6-ANALYSIS.md)                  [OK]强制要求
└─ 读取$ARGUMENTS文件
   └─ 输出: existingTasks, taskProgress
              ↓
Phase 7: 任务分析与拆分 → [詳細](PHASE-7-BREAKDOWN.md)     [OK]强制要求
└─ 输入: 第1-5阶段结果 + 第6阶段结果
   └─ 输出: 任务拆分、可行性分析
              ↓
Phase 8: 问题管理 → [詳細](PHASE-8-QUESTIONS.md)           [WARNING]条件触发
├─ 条件A: 存在问题         [OK]强制要求
│  └─ 执行AskUserQuestion工具
│  └─ 等待用户回复
│  └─ 创建questions.md文件
│  └─ 输出: 已记录用户决策
├─ 条件B: 无问题            [OK]允许（必须记录原因）
│  └─ 进入第9阶段
│  └─ 记录无需提问的原因
└─ [PROHIBITED]关卡: 第9阶段入口检查点
              ↓
Phase 9: 文件更新 → [詳細](PHASE-9-UPDATE.md)                      [OK]强制要求
├─ 创建docs/memory文件（探索、规划、问题）
├─ 用任务清单更新$ARGUMENTS文件
├─ 条件性插入分支/PR任务:
│  └─ 评估HAS_BRANCH_OPTION和HAS_PR_OPTION
│  └─ 若需要则在开头插入分支创建任务
│  └─ 若需要则在末尾插入PR创建任务
└─ 输出: 包含所有任务的完整TODO.md
              ↓
Phase 10: 验证与反馈 → [詳細](PHASE-10-VERIFICATION.md)  [OK]强制要求
└─ 验证文件更新、AskUserQuestion执行情况
   └─ 向用户报告

🔐 Phase Requirement Markers

🔐 阶段要求标记

Phase	Status	Skippable?	Dependencies	Critical Output
Phase 0	[OK]MANDATORY	🚫 NO	None	guidelines_loaded
Phase 1	[OK]MANDATORY	🚫 NO	Phase 0	HAS_PR_OPTION, HAS_BRANCH_OPTION, BRANCH_NAME
Phase 2	[OK]MANDATORY	🚫 NO	Phase 1	exploration_results
Phase 3	[OK]MANDATORY	🚫 NO	Phase 2	planning_results
Phase 4	[OK]MANDATORY	🚫 NO	Phase 3	strategic_plan
Phase 5	[OK]MANDATORY	🚫 NO	Phase 4	Verification status
Phase 6	[OK]MANDATORY	🚫 NO	Phase 5	existingTasks, taskProgress
Phase 7	[OK]MANDATORY	🚫 NO	Phase 1-6	Task breakdown, feasibility
Phase 8	[WARNING]CONDITIONAL	🚫 NO (See conditions)	Phase 7	User decisions (if questions exist)
Phase 9	[OK]MANDATORY	🚫 NO	Phase 1-8	Updated $ARGUMENTS file, docs/memory files, branch/PR tasks inserted
Phase 10	[OK]MANDATORY	🚫 NO	Phase 9	Verification report

Phase 8 Conditions:

[OK]Questions exist: MUST execute AskUserQuestion tool and wait for responses
[OK]No questions: MUST proceed to Phase 9 and document reason in Phase 10

阶段	状态	是否可跳过?	依赖项	关键输出
Phase 0	[OK]强制要求	🚫 否	无	guidelines_loaded
Phase 1	[OK]强制要求	🚫 否	Phase 0	HAS_PR_OPTION, HAS_BRANCH_OPTION, BRANCH_NAME
Phase 2	[OK]强制要求	🚫 否	Phase 1	exploration_results
Phase 3	[OK]强制要求	🚫 否	Phase 2	planning_results
Phase 4	[OK]强制要求	🚫 否	Phase 3	strategic_plan
Phase 5	[OK]强制要求	🚫 否	Phase 4	验证状态
Phase 6	[OK]强制要求	🚫 否	Phase 5	existingTasks, taskProgress
Phase 7	[OK]强制要求	🚫 否	Phase 1-6	任务拆分、可行性分析
Phase 8	[WARNING]条件触发	🚫 否（见条件）	Phase 7	用户决策（若存在问题）
Phase 9	[OK]强制要求	🚫 否	Phase 1-8	更新后的$ARGUMENTS文件、docs/memory文件、已插入的分支/PR任务
Phase 10	[OK]强制要求	🚫 否	Phase 9	验证报告

Phase 8条件:

[OK]存在问题: 必须执行AskUserQuestion工具并等待回复
[OK]无问题: 必须进入第9阶段并在第10阶段记录原因

[WARNING]Critical Phase Transition Rules

[WARNING]关键阶段转换规则

Rule 1: Sequential Execution Only

Each phase MUST complete before the next phase begins
No parallel execution of phases
No skipping of phases
Each Phase is independent and must be executed in a separate turn/message

Rule 2: Subagent Phases (2-4) Must Execute Sequentially

[NG]WRONG FLOW (Parallel Execution):
Phase 2 (Explore) + Phase 3 (Plan) + Phase 4 (project-manager) → Called in same message
                    ↓
            PARALLEL EXECUTION
                    ↓
    Result: Phase 3/4 start before Phase 2 completes, missing dependencies

[OK]CORRECT FLOW (Sequential Execution):
Phase 0 → Phase 1 → Phase 2 (wait) → Phase 3 (wait) → Phase 4 (wait) → Phase 5 → ...
   ↓         ↓         ↓                ↓                ↓                ↓
  Key-    TODO     Explore          Plan          project-mgr      Verify
 Guide   Reading   (output)       (needs P2)      (needs P2+P3)   (check all)

Rule 3: Never Skip to Phase 9 (File Update)

Phase 9 requires outputs from ALL previous phases
Skipping Phase 6-8 causes data loss and missing integration
Phase 6 (File Analysis) results are mandatory for Phase 7
Phase 8 (Questions) is the entrance gate to Phase 9

Rule 4: Phase 8 is a Mandatory Checkpoint

Even if no questions exist, Phase 8 MUST be executed to document this fact
Phase 9 entrance gate verifies Phase 8 completion

规则1: 仅允许顺序执行

每个阶段必须完成后才能开始下一个阶段
不允许并行执行阶段
不允许跳过阶段
每个阶段都是独立的，必须在单独的轮次/消息中执行

规则2: 子代理阶段（2-4）必须顺序执行

[NG]错误流程（并行执行）:
Phase 2 (Explore) + Phase 3 (Plan) + Phase 4 (project-manager) → 在同一条消息中调用
                    ↓
            并行执行
                    ↓
    结果: Phase 3/4在Phase 2完成前开始，缺少依赖项

[OK]正确流程（顺序执行）:
Phase 0 → Phase 1 → Phase 2（等待）→ Phase 3（等待）→ Phase 4（等待）→ Phase 5 → ...
   ↓         ↓         ↓                ↓                ↓                ↓
  核心   TODO文件   探索          规划          项目管理      验证
  指南    读取     (输出)       (需要P2结果)    (需要P2+P3结果)   (检查所有结果)

规则3: 切勿直接跳至第9阶段（文件更新）

第9阶段需要所有前序阶段的输出
跳过第6-8阶段会导致数据丢失和集成缺失
第6阶段（文件分析）的结果是第7阶段的强制要求
第8阶段（问题管理）是第9阶段的入口关卡

规则4: 第8阶段是强制检查点

即使没有问题，也必须执行第8阶段以记录该事实
第9阶段入口会验证第8阶段是否已完成

Variable Scope and Persistence

变量范围与持久性

IMPORTANT: Variables set in Phase 1 persist throughout all subsequent phases (Phase 2-10).

Phase 1 Variables Used in Later Phases:

```
HAS_PR_OPTION
```
,
```
HAS_BRANCH_OPTION
```
,
```
BRANCH_NAME
```
,
```
IS_AUTO_GENERATED
```
- Set in: Phase 1 Step 2 (argument parsing)
- Used in: Phase 9 (conditional task insertion)
- Scope: Available throughout entire skill execution

Variable Lifecycle:

Phase 1 → Set variables
    ↓
Phase 9 → Use variables for conditional logic

重要提示: 第1阶段设置的变量将在所有后续阶段（第2-10阶段）中保持有效。

第1阶段设置的变量将在后续阶段使用:

```
HAS_PR_OPTION
```
,
```
HAS_BRANCH_OPTION
```
,
```
BRANCH_NAME
```
,
```
IS_AUTO_GENERATED
```
- 设置于: 第1阶段第2步（参数解析）
- 使用于: 第9阶段（条件任务插入）
- 范围: 在整个技能执行期间有效

变量生命周期:

Phase 1 → 设置变量
    ↓
Phase 9 → 使用变量进行条件逻辑判断