deep-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Planning Skill

Orchestrates a multi-step planning process: Research → Interview → External LLM Review → TDD Plan

协调多步骤规划流程：调研 → 访谈 → 外部LLM评审 → TDD计划

CRITICAL: First Actions

重要提示：初始操作

BEFORE using any other tools, do these in order:

在使用任何其他工具之前，请按以下顺序执行操作：

1. Print Intro and Validate Environment

1. 打印介绍信息并验证环境

Print intro banner immediately:

⚠️  CONTEXT WARNING: This workflow is token-intensive. Consider compacting first.

═══════════════════════════════════════════════════════════════
DEEP-PLAN: AI-Assisted Implementation Planning
═══════════════════════════════════════════════════════════════
Research → Interview → External LLM Review → TDD Plan

DEEP-PLAN starts by running `validate-env.sh`. This script:
  - Checks env for external LLM auth values
  - Validates external LLM access by running tiny prompt(s) programmatically

SECURITY:
  - `validate-env.sh` reads secret auth values in order to validate LLM access
  - It never publishes these values or exposes them to claude
  
 Note: DEEP-PLAN will write many .md files to the planning directory you pass it

CRITICAL: Locate plugin root BEFORE running any scripts.

The SessionStart hook injects

DEEP_PLUGIN_ROOT=<path>

into your context. Look for it now — it appears alongside

DEEP_SESSION_ID

in your context from session startup. Use it as

plugin_root

for all script paths.

If
DEEP_PLUGIN_ROOT
is in your context, run validate-env.sh directly:

bash

bash <DEEP_PLUGIN_ROOT value>/scripts/checks/validate-env.sh

Only if
DEEP_PLUGIN_ROOT
is NOT in your context (hook didn't run), fall back to search:

bash

find "$(pwd)" -name "validate-env.sh" -path "*/scripts/checks/*" -type f 2>/dev/null | head -1

If not found:

find ~ -name "validate-env.sh" -path "*/scripts/checks/*" -path "*deep*plan*" -type f 2>/dev/null | head -1

Then run:

bash <found_path>

Parse the JSON output:

json

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "gemini_auth": "api_key",
  "openai_auth": true,
  "plugin_root": "/path/to/plugin"
}

Store
plugin_root
from the JSON output - it's used throughout the workflow.

立即打印介绍横幅：

⚠️  上下文警告：此工作流会消耗大量token。请先考虑精简内容。

═══════════════════════════════════════════════════════════════
DEEP-PLAN：AI辅助实施规划
═══════════════════════════════════════════════════════════════
调研 → 访谈 → 外部LLM评审 → TDD计划

DEEP-PLAN 会先运行 `validate-env.sh` 脚本。该脚本：
  - 检查环境中的外部LLM认证信息
  - 通过程序化运行小型prompt来验证外部LLM的访问权限

安全说明：
  - `validate-env.sh` 会读取保密的认证信息以验证LLM访问权限
  - 它绝不会发布这些信息或将其暴露给Claude
  
 注意：DEEP-PLAN会在你指定的规划目录中创建多个.md文件

重要提示：在运行任何脚本前先找到插件根目录。

SessionStart钩子会将

DEEP_PLUGIN_ROOT=<路径>

注入到你的上下文中。现在就找到它——它会和

DEEP_SESSION_ID

一起出现在会话启动时的上下文中。将其作为所有脚本路径的

plugin_root

使用。

如果上下文中存在
DEEP_PLUGIN_ROOT
，直接运行validate-env.sh：

bash

bash <DEEP_PLUGIN_ROOT value>/scripts/checks/validate-env.sh

仅当上下文中不存在
DEEP_PLUGIN_ROOT
时（钩子未运行），使用搜索作为备选方案：

bash

find "$(pwd)" -name "validate-env.sh" -path "*/scripts/checks/*" -type f 2>/dev/null | head -1

如果未找到：

find ~ -name "validate-env.sh" -path "*/scripts/checks/*" -path "*deep*plan*" -type f 2>/dev/null | head -1

然后运行：

bash <找到的路径>

解析JSON输出：

json

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "gemini_auth": "api_key",
  "openai_auth": true,
  "plugin_root": "/path/to/plugin"
}

保存JSON输出中的
plugin_root
- 它会在整个工作流中被使用。

2. Handle Environment Errors

2. 处理环境错误

valid == false

Show the errors to the user

If errors are critical (uv not installed, plugin root not found):

Stop the workflow. User must fix these before proceeding.

If errors are ONLY about missing LLM credentials (gemini_auth is null AND openai_auth is false):

AskUserQuestion:
  question: "No external LLMs configured. How should plan review be handled?"
  options:
    - label: "Use Claude Opus for review (Recommended)"
      description: "Launch an Opus subagent to review the plan"
    - label: "Exit to configure LLMs"
      description: "Stop to set up Gemini/OpenAI credentials"
    - label: "Skip external review"
      description: "Proceed without any external plan review"

Store the choice as
review_mode
:

"Use Claude Opus" →
```
review_mode = "opus_subagent"
```
"Skip external review" →
```
review_mode = "skip"
```
Default (LLMs available) →
```
review_mode = "external_llm"
```

Environment validated:
  Gemini: {gemini_auth or "not configured"}
  OpenAI: {openai_auth ? "configured" : "not configured"}
  Review mode: {review_mode}

如果

valid == false

：

向用户展示错误信息

如果是严重错误（未安装uv、未找到插件根目录）：

停止工作流。用户必须先修复这些问题才能继续。

如果错误仅为缺少LLM凭证（gemini_auth为null且openai_auth为false）：

AskUserQuestion:
  question: "未配置外部LLM。应如何处理计划评审？"
  options:
    - label: "使用Claude Opus进行评审（推荐）"
      description: "启动Opus子代理来评审计划"
    - label: "退出以配置LLMs"
      description: "停止操作以设置Gemini/OpenAI凭证"
    - label: "跳过外部评审"
      description: "不进行任何外部计划评审，直接继续"

将选择结果保存为
review_mode
：

"使用Claude Opus" →
```
review_mode = "opus_subagent"
```
"跳过外部评审" →
```
review_mode = "skip"
```
默认（LLM可用） →
```
review_mode = "external_llm"
```

环境验证结果：
  Gemini: {gemini_auth或"未配置"}
  OpenAI: {openai_auth ? "已配置" : "未配置"}
  评审模式: {review_mode}

3. Validate Spec File Input

3. 验证规格文件输入

Check if user provided @file at invocation AND it's a spec file (ends with
.md
).

If NO @file was provided OR the path doesn't end with

.md

, output this and STOP:

═══════════════════════════════════════════════════════════════
DEEP-PLAN: Spec File Required
═══════════════════════════════════════════════════════════════

This skill requires a markdown spec file path (must end with .md).
The planning directory is inferred from the spec file's parent directory.

To start a NEW plan:
  1. Create a markdown spec file describing what you want to build
  2. It can be as detailed or as vague as you like
  3. Place it in a directory where deep-plan can save planning files
  4. Run: /deep-plan @path/to/your-spec.md

To RESUME an existing plan:
  1. Run: /deep-plan @path/to/your-spec.md

Example: /deep-plan @planning/my-feature-spec.md
═══════════════════════════════════════════════════════════════

Do not continue. Wait for user to re-invoke with a .md file path.

检查用户在调用时是否提供了@file参数，且该文件是规格文件（以.md结尾）。

如果未提供@file参数，或路径不以.md结尾，输出以下内容并停止：

═══════════════════════════════════════════════════════════════
DEEP-PLAN：需要规格文件
═══════════════════════════════════════════════════════════════

此技能需要一个markdown规格文件路径（必须以.md结尾）。
规划目录会从规格文件的父目录推断得出。

要启动新规划：
  1. 创建一个markdown规格文件，描述你想要构建的内容
  2. 文件内容可详细可简略
  3. 将其放在deep-plan可以保存规划文件的目录中
  4. 运行：/deep-plan @path/to/your-spec.md

要恢复现有规划：
  1. 运行：/deep-plan @path/to/your-spec.md

示例：/deep-plan @planning/my-feature-spec.md
═══════════════════════════════════════════════════════════════

请勿继续。等待用户提供带.md后缀的文件路径后重新调用。

4. Setup Planning Session

4. 设置规划会话

First, check for session_id in your context. Look for

DEEP_SESSION_ID=xxx

which was set by the SessionStart hook. This appears in your context from when the session started.

Run setup-planning-session.py with the spec file, plugin root, review mode, and session ID:

bash

uv run {plugin_root}/scripts/checks/setup-planning-session.py \
  --file "<file_path>" \
  --plugin-root "{plugin_root}" \
  --review-mode "{review_mode}" \
  --session-id "{DEEP_SESSION_ID}"

IMPORTANT: If

DEEP_SESSION_ID

is in your context, you MUST pass it via

--session-id

. This ensures tasks work correctly after

/clear

commands. If it's not in your context, omit

--session-id

(fallback to env var).

Note:

review_mode

is from Step 2. If LLMs are available, use

external_llm

(or omit the flag).

Parse the JSON output:

This script:

Validates the spec file exists and has content

Creates

deep_plan_config.json

in the planning directory with

plugin_root

planning_dir

, and

initial_file

Detects whether this is a new or resume session
Writes task files directly to
```
~/.claude/tasks/<task_list_id>/
```
If
```
sections/index.md
```
exists, also writes section tasks (positions 22+)

If
success == false
: The script failed validation. Display the error and stop:

═══════════════════════════════════════════════════════════════
DEEP-PLAN: Setup Failed
═══════════════════════════════════════════════════════════════
Error: {error}

Please fix the issue and re-run: /deep-plan @path/to/your-spec.md
═══════════════════════════════════════════════════════════════

Do not continue. Wait for user to fix the issue and re-invoke.

Common errors:

"Spec file not found" → User provided a path to a file that doesn't exist
"Spec file is empty" → User provided an empty file with no content
"Expected a spec file, got a directory" → User provided a directory path instead of a file

Handle conflict (if present):

conflict

is present in output, this means

CLAUDE_CODE_TASK_LIST_ID

was set and the task list already has tasks. Use

AskUserQuestion

Question: "CLAUDE_CODE_TASK_LIST_ID is set to '{task_list_id}' which already contains {existing_task_count} tasks. Proceeding will overwrite these tasks with the deep-plan workflow. Continue?"
Options:
- "Proceed and overwrite existing tasks" - Re-run with
```
--force
```
  flag
- "Exit" - Stop here, user can unset CLAUDE_CODE_TASK_LIST_ID and retry

If user chooses "Exit": Stop and tell user to

unset CLAUDE_CODE_TASK_LIST_ID

If user chooses "Proceed": Re-run setup-planning-session.py with

--force

flag added.

Handle no task list ID (mode == "no_task_list"):

mode == "no_task_list"

, this is a fatal error. The workflow cannot proceed without a task list ID. Use

AskUserQuestion

Question: "Cannot proceed: No task list ID available. The SessionStart hook may not have run. How would you like to proceed?"
Options:
  - "Start a fresh session" (Recommended) - Exit Claude and start a new session
  - "Show troubleshooting steps" - Display the error_details.troubleshooting steps

If user chooses "Start a fresh session":

Please exit this Claude session and start a new one. The SessionStart hook
will capture the session ID on startup.

Command: claude --plugin-dir <plugin_path>

If user chooses "Show troubleshooting steps": Display each item from

error_details.troubleshooting

and STOP.

DO NOT PROCEED past step 4 if this error occurs.

Verify tasks are visible:

After the script completes successfully, run

TaskList

to verify the workflow tasks are visible. The output

tasks_written

shows how many task files were written.

Reading session context: After task writing, the task list includes context tasks with values in their subjects:

```
plugin_root=...
```
- extract path after
```
=
```
```
planning_dir=...
```
- extract path after
```
=
```
```
initial_file=...
```
- extract path after
```
=
```
```
review_mode=...
```
- extract value after
```
=
```

Print status:

Planning directory: {planning_dir}
Mode: {mode}

mode == "resume"

Resuming from step {resume_from_step}
To start fresh, delete the planning directory files.

If resuming, skip to step {resume_from_step} in the workflow below.

首先，检查上下文中是否存在session_id。 查找由SessionStart钩子设置的

DEEP_SESSION_ID=xxx

，它会在会话启动时出现在你的上下文中。

运行setup-planning-session.py，传入规格文件、插件根目录、评审模式和会话ID：

bash

uv run {plugin_root}/scripts/checks/setup-planning-session.py \
  --file "<file_path>" \
  --plugin-root "{plugin_root}" \
  --review-mode "{review_mode}" \
  --session-id "{DEEP_SESSION_ID}"

重要提示： 如果上下文中存在

DEEP_SESSION_ID

，必须通过

--session-id

参数传入。这确保在执行

/clear

命令后任务仍能正常工作。如果上下文中不存在该参数，则省略

--session-id

（回退到环境变量）。

注意：

review_mode

来自步骤2。如果LLM可用，使用

external_llm

（或省略该标志）。

解析JSON输出：

该脚本会：

验证规格文件是否存在且包含内容

在规划目录中创建

deep_plan_config.json

，包含

plugin_root

、

planning_dir

和

initial_file

信息

检测这是新会话还是恢复会话
将任务文件直接写入
```
~/.claude/tasks/<task_list_id>/
```
如果
```
sections/index.md
```
存在，还会写入章节任务（从第22位开始）

如果
success == false
：脚本验证失败。显示错误信息并停止：

═══════════════════════════════════════════════════════════════
DEEP-PLAN：设置失败
═══════════════════════════════════════════════════════════════
错误：{error}

请修复问题后重新运行：/deep-plan @path/to/your-spec.md
═══════════════════════════════════════════════════════════════

请勿继续。等待用户修复问题后重新调用。

常见错误：

"Spec file not found" → 用户提供的文件路径不存在
"Spec file is empty" → 用户提供的文件为空
"Expected a spec file, got a directory" → 用户提供的是目录路径而非文件路径

处理冲突（如果存在）：

如果输出中存在

conflict

，意味着

CLAUDE_CODE_TASK_LIST_ID

已被设置，且任务列表中已有任务。使用

AskUserQuestion

：

问题："CLAUDE_CODE_TASK_LIST_ID已设置为'{task_list_id}'，该列表已包含{existing_task_count}个任务。继续操作将用deep-plan工作流覆盖这些任务。是否继续？"
选项：
- "继续并覆盖现有任务" - 添加
```
--force
```
  标志重新运行
- "退出" - 停止操作，用户可以取消设置CLAUDE_CODE_TASK_LIST_ID后重试

如果用户选择"退出"：停止操作并告知用户执行

unset CLAUDE_CODE_TASK_LIST_ID

如果用户选择"继续"：添加

--force

标志重新运行setup-planning-session.py

处理无任务列表ID的情况（mode == "no_task_list"）：

如果

mode == "no_task_list"

，这是致命错误。没有任务列表ID，工作流无法继续。使用

AskUserQuestion

：

问题："无法继续：无可用任务列表ID。SessionStart钩子可能未运行。你希望如何处理？"
选项：
  - "启动新会话"（推荐） - 退出Claude并启动新会话
  - "显示故障排除步骤" - 显示error_details.troubleshooting中的步骤

如果用户选择"启动新会话"：

请退出当前Claude会话并启动新会话。SessionStart钩子会在启动时捕获会话ID。

命令：claude --plugin-dir <plugin_path>

如果用户选择"显示故障排除步骤"：显示

error_details.troubleshooting

中的每一项并停止。

如果出现此错误，请勿继续执行步骤4之后的操作。

验证任务是否可见：

脚本成功完成后，运行

TaskList

验证工作流任务是否可见。输出中的

tasks_written

显示已写入的任务文件数量。

读取会话上下文： 任务写入完成后，任务列表会包含上下文任务，其主题中包含以下值：

```
plugin_root=...
```
- 提取
```
=
```
后的路径
```
planning_dir=...
```
- 提取
```
=
```
后的路径
```
initial_file=...
```
- 提取
```
=
```
后的路径
```
review_mode=...
```
- 提取
```
=
```
后的值

打印状态：

规划目录: {planning_dir}
模式: {mode}

如果

mode == "resume"

：

从步骤{resume_from_step}恢复
要重新开始，请删除规划目录中的文件。

如果是恢复会话，直接跳转到工作流中的步骤{resume_from_step}。

Workflow

工作流

Note: All scripts use

{plugin_root}

from step 1's validate-env.sh output.

注意： 所有脚本都使用步骤1中validate-env.sh输出的

{plugin_root}

。

6. Research Decision

6. 调研决策

Read

{plugin_root}/skills/deep-plan/references/research-protocol.md

for details.

Read the spec file (find task with subject starting with
```
initial_file=
```
and extract path)
Extract potential research topics from the spec content (technologies, patterns, integrations)
Ask user about codebase research needs (existing code to analyze?)
Ask user about web research needs (present derived topics as multi-select options)
Record which research types to perform in step 7

Always include testing - either research existing test setup (codebase) or ask about preferences (new project).

阅读

{plugin_root}/skills/deep-plan/references/research-protocol.md

了解详细信息。

读取规格文件（找到主题以
```
initial_file=
```
开头的任务，提取路径）
从规格文件内容中提取潜在的调研主题（技术、模式、集成方案）
询问用户关于代码库调研的需求（是否需要分析现有代码？）
询问用户关于网络调研的需求（将推导的主题作为多选选项展示）
记录步骤7中要执行的调研类型

务必包含测试相关内容 - 要么调研现有测试设置（代码库），要么询问偏好（新项目）。

7. Execute Research

7. 执行调研

Read

{plugin_root}/skills/deep-plan/references/research-protocol.md

for details.

Based on decisions from step 6, launch research subagents:

Codebase research:
```
Task(subagent_type=Explore)
```

Web research:

Task(subagent_type=web-search-researcher)

If both are needed, launch both Task tools in parallel (single message with multiple tool calls).

Important: Subagents return their findings - they do NOT write files directly. After collecting results from all subagents, combine them and write to

<planning_dir>/claude-research.md

Skip this step entirely if user chose no research in step 6.

阅读

{plugin_root}/skills/deep-plan/references/research-protocol.md

了解详细信息。

根据步骤6的决策，启动调研子代理：

代码库调研：
```
Task(subagent_type=Explore)
```

网络调研：

Task(subagent_type=web-search-researcher)

如果两者都需要，在单个消息中并行启动两个Task工具（包含多个工具调用）。

重要提示： 子代理仅返回调研结果 - 不会直接写入文件。收集所有子代理的结果后，将其合并并写入

<planning_dir>/claude-research.md

。

如果用户在步骤6中选择不进行任何调研，直接跳过此步骤。

8. Detailed Interview

8. 详细访谈

Read

{plugin_root}/skills/deep-plan/references/interview-protocol.md

for details.

Run in main context (AskUserQuestion requires it). The interview should be informed by:

The initial spec (from
```
initial_file
```
)
Research findings (from step 7, if any research was done)

阅读

{plugin_root}/skills/deep-plan/references/interview-protocol.md

了解详细信息。

在主上下文中运行（AskUserQuestion需要主上下文）。访谈内容应基于：

初始规格文件（来自
```
initial_file
```
）
调研结果（如果执行了步骤7）

9. Save Interview Transcript

9. 保存访谈记录

Write Q&A to

<planning_dir>/claude-interview.md

将问答内容写入

<planning_dir>/claude-interview.md

10. Write Initial Spec

10. 编写初始规格文档

Combine into

<planning_dir>/claude-spec.md

Initial input (read the file from task with subject
```
initial_file=...
```
)
Research findings (if step 7 was done)
Interview answers (from step 8)

This synthesizes the user's raw requirements into a complete specification.

将以下内容合并到

<planning_dir>/claude-spec.md

：

初始输入（读取主题为
```
initial_file=...
```
的任务中的文件）
调研结果（如果执行了步骤7）
访谈答案（来自步骤8）

这会将用户的原始需求合成为完整的规格文档。

11. Generate Implementation Plan

11. 生成实施计划

Read

{plugin_root}/skills/deep-plan/references/plan-writing.md

before writing anything.

Create detailed plan →

<planning_dir>/claude-plan.md

CRITICAL CONSTRAINTS (from plan-writing.md):

Plans are prose documents, not code
ZERO full function implementations - that's deep-implement's job

Write for an unfamiliar reader. The plan must be fully self-contained - an engineer or LLM with no prior context should understand what we're building, why, and how just from reading this document. But it does not need to see full code implementations

在编写任何内容之前，先阅读

{plugin_root}/skills/deep-plan/references/plan-writing.md

。

创建详细计划并写入

<planning_dir>/claude-plan.md

关键约束（来自plan-writing.md）：

计划是散文式文档，而非代码
禁止完整函数实现 - 这是deep-implement的职责

编写时假设读者不了解背景信息。计划必须完全自包含 - 没有任何前置知识的工程师或LLM仅通过阅读此文档就能理解我们要构建什么、为什么构建以及如何构建。但无需包含完整的代码实现。

12. Context Check (Pre-External Review)

12. 上下文检查（外部评审前）

Run:

bash

uv run {plugin_root}/scripts/checks/check-context-decision.py \
  --planning-dir "<planning_dir>" \
  --upcoming-operation "External LLM Review"

Read

{plugin_root}/skills/deep-plan/references/context-check.md

for handling the output.

If user chooses "Continue", proceed to step 13
If user chooses "/clear + re-run", they will restart with fresh context (file-based recovery resumes here)

运行：

bash

uv run {plugin_root}/scripts/checks/check-context-decision.py \
  --planning-dir "<planning_dir>" \
  --upcoming-operation "External LLM Review"

阅读

{plugin_root}/skills/deep-plan/references/context-check.md

了解输出处理方式。

如果用户选择"继续"，进入步骤13
如果用户选择"/clear + 重新运行"，将使用全新上下文重启（基于文件的恢复会在此处继续）

13. External LLM Review

13. 外部LLM评审

Read

{plugin_root}/skills/deep-plan/references/external-review.md

for the full protocol.

Check

review_mode

from task with subject

review_mode=...

and follow the appropriate path:

```
external_llm
```
→ Run review.py script
```
opus_subagent
```
→ Launch opus-plan-reviewer subagent
```
skip
```
→ Skip to step 16

阅读

{plugin_root}/skills/deep-plan/references/external-review.md

了解完整流程。

查找主题为

review_mode=...

的任务，获取

review_mode

并遵循相应流程：

```
external_llm
```
→ 运行review.py脚本
```
opus_subagent
```
→ 启动opus-plan-reviewer子代理
```
skip
```
→ 跳转到步骤16

14. Integrate External Feedback

14. 整合外部反馈

Analyze the suggestions in

<planning_dir>/reviews/

Remember that you are the authority on what to integrate or not. It's OK if you decide to not integrate anything.

Step 1: Write

<planning_dir>/claude-integration-notes.md

documenting:

What suggestions you're integrating and why
What suggestions you're NOT integrating and why

Step 2: Update

<planning_dir>/claude-plan.md

with the integrated changes.

分析

<planning_dir>/reviews/

中的建议。

请记住你是决定是否整合建议的权威。即使你决定不整合任何建议也是合理的。

步骤1： 编写

<planning_dir>/claude-integration-notes.md

，记录：

你要整合哪些建议，以及原因
你不整合哪些建议，以及原因

步骤2： 根据整合的修改更新

<planning_dir>/claude-plan.md

。

15. User Review of Integrated Plan

15. 用户评审整合后的计划

Use AskUserQuestion:

The plan has been updated with external feedback. You can now review and edit claude-plan.md.

If you want Claude's help editing the plan, open a separate Claude session - this session
is mid-workflow and can't assist with edits until the workflow completes.

When you're done reviewing, select "Done" to continue.

Options: "Done reviewing"

Wait for user confirmation before proceeding.

使用AskUserQuestion：

计划已结合外部反馈完成更新。你现在可以评审并编辑claude-plan.md。

如果你需要Claude帮助编辑计划，请打开一个独立的Claude会话 - 当前会话处于工作流中途，在工作流完成前无法提供编辑协助。

评审完成后，选择“完成”继续。

选项：“评审完成”

等待用户确认后再继续。

16. Apply TDD Approach

16. 应用TDD方法

Read

{plugin_root}/skills/deep-plan/references/tdd-approach.md

for details.

Verify testing context exists in

claude-research.md

. If missing, research (existing codebase) or recommend (new project).

Create

claude-plan-tdd.md

mirroring the plan structure with test stubs for each section.

阅读

{plugin_root}/skills/deep-plan/references/tdd-approach.md

了解详细信息。

验证

claude-research.md

中是否存在测试上下文。如果缺失，进行调研（现有代码库）或给出建议（新项目）。

创建

claude-plan-tdd.md

，镜像计划结构，为每个章节添加测试桩。

17. Context Check (Pre-Section Split)

17. 上下文检查（章节拆分前）

Run:

bash

uv run {plugin_root}/scripts/checks/check-context-decision.py \
  --planning-dir "<planning_dir>" \
  --upcoming-operation "Section splitting"

Read

{plugin_root}/skills/deep-plan/references/context-check.md

for handling the output.

If user chooses "Continue", proceed to step 18
If user chooses "/clear + re-run", they will restart with fresh context (file-based recovery resumes here)

运行：

bash

uv run {plugin_root}/scripts/checks/check-context-decision.py \
  --planning-dir "<planning_dir>" \
  --upcoming-operation "Section splitting"

阅读

{plugin_root}/skills/deep-plan/references/context-check.md

了解输出处理方式。

如果用户选择"继续"，进入步骤18
如果用户选择"/clear + 重新运行"，将使用全新上下文重启（基于文件的恢复会在此处继续）

18. Create Section Index

18. 创建章节索引

Read

{plugin_root}/skills/deep-plan/references/section-index.md

for details.

Read

claude-plan.md

and

claude-plan-tdd.md

. Identify natural section boundaries and create

<planning_dir>/sections/index.md

CRITICAL: index.md MUST start with a SECTION_MANIFEST block. See the reference for format requirements and examples.

Write

index.md

before proceeding to section file creation.

阅读

{plugin_root}/skills/deep-plan/references/section-index.md

了解详细信息。

阅读

claude-plan.md

和

claude-plan-tdd.md

。识别自然的章节边界并创建

<planning_dir>/sections/index.md

。

重要提示： index.md必须以SECTION_MANIFEST块开头。请参考文档了解格式要求和示例。

在创建章节文件之前先编写index.md。

19. Generate and Write Section Tasks

19. 生成并写入章节任务

Run generate-section-tasks.py to write section tasks directly to disk:

bash

uv run {plugin_root}/scripts/checks/generate-section-tasks.py \
  --planning-dir "<planning_dir>" \
  --session-id "{DEEP_SESSION_ID}"

IMPORTANT: If

DEEP_SESSION_ID

is in your context, you MUST pass it via

--session-id

. This ensures tasks work correctly after

/clear

commands. If it's not in your context, omit

--session-id

(fallback to env var).

What this script does:

Reads sections/index.md to get the section list
INSERTs batch and section tasks starting at position 19
SHIFTS Final Verification and Output Summary to positions after section tasks
Updates all dependencies to reflect new positions

Handle based on result:

If
```
success == false
```
: Read
```
error
```
and fix the issue (common: missing/invalid SECTION_MANIFEST in index.md, no DEEP_SESSION_ID). Re-run until successful.
If
```
state == "complete"
```
: All sections already written, skip to Final Verification.
Otherwise: Tasks were written successfully.

Verify section tasks are visible:

After the script completes successfully, run

TaskList

to see the updated task structure. The output

tasks_written

shows how many task files were written (section tasks + Final Verification + Output Summary).

Task positions after insertion:

Position 19+: Batch and section tasks
Final Verification: Position
```
19 + section_task_count
```
Output Summary: Position
```
19 + section_task_count + 1
```

Task list includes batch coordination tasks (subjects like "Run batch 1 section subagents") and section tasks (subjects like "Write section-01-setup.md"). Sections are blocked by their batch task, enabling parallel execution within each batch.

运行generate-section-tasks.py将章节任务直接写入磁盘：

bash

uv run {plugin_root}/scripts/checks/generate-section-tasks.py \
  --planning-dir "<planning_dir>" \
  --session-id "{DEEP_SESSION_ID}"

重要提示： 如果上下文中存在

DEEP_SESSION_ID

，必须通过

--session-id

参数传入。这确保在执行

/clear

命令后任务仍能正常工作。如果上下文中不存在该参数，则省略

--session-id

（回退到环境变量）。

该脚本的作用：

读取sections/index.md获取章节列表
在第19位开始插入批量任务和章节任务
将最终验证和输出摘要移动到章节任务之后的位置
更新所有依赖项以反映新的位置

根据结果处理：

如果
```
success == false
```
：读取
```
error
```
并修复问题（常见问题：index.md中缺少/无效的SECTION_MANIFEST，无DEEP_SESSION_ID）。重新运行直到成功。
如果
```
state == "complete"
```
：所有章节已写入，跳转到最终验证步骤。
其他情况：任务写入成功。

验证章节任务是否可见：

脚本成功完成后，运行

TaskList

查看更新后的任务结构。输出中的

tasks_written

显示已写入的任务文件数量（章节任务 + 最终验证 + 输出摘要）。

插入后的任务位置：

第19位及以后：批量任务和章节任务
最终验证：位置
```
19 + section_task_count
```
输出摘要：位置
```
19 + section_task_count + 1
```

任务列表包含批量协调任务（主题如"Run batch 1 section subagents"）和章节任务（主题如"Write section-01-setup.md"）。章节任务会被其批量任务阻塞，从而支持每个批次内的并行执行。

20. Write Section Files (Parallel Subagents)

20. 编写章节文件（并行子代理）

Read

{plugin_root}/skills/deep-plan/references/section-splitting.md

for the batch execution loop.

For each batch:

Mark batch task in_progress (find by subject "Run batch N section subagents")

Run

generate-batch-tasks.py --batch-num N

→ get JSON with

prompt_files

array

Launch Task calls for ALL prompt files in a single message (parallel execution)

Each Task:

subagent_type="section-writer"

prompt="Read {prompt_file} and execute the instructions."

Wait for all subagents to complete
Verify section files were written (SubagentStop hook writes them automatically)
Mark each section task completed (find by subject "Write {filename}")
Mark batch task completed
If more batches remain, repeat from step 1 with next batch number

Validation After Each Batch:

Hooks execute in isolation - Claude doesn't see success/failure. After subagents complete:

bash

ls {planning_dir}/sections/section-*.md | wc -l

Compare count to expected sections. If any files are missing:

Re-run the missing section's subagent
If still failing, fall back to manual: parse subagent response JSON and Write the file

阅读

{plugin_root}/skills/deep-plan/references/section-splitting.md

了解批量执行循环。

对于每个批次：

将批量任务标记为in_progress（找到主题为"Run batch N section subagents"的任务）

运行

generate-batch-tasks.py --batch-num N

→ 获取包含

prompt_files

数组的JSON

在单个消息中为所有prompt文件启动Task调用（并行执行）

每个Task：

subagent_type="section-writer"

prompt="Read {prompt_file} and execute the instructions."

等待所有子代理完成
验证章节文件已写入（SubagentStop钩子会自动写入）
将每个章节任务标记为completed（找到主题为"Write {filename}"的任务）
将批量任务标记为completed
如果还有剩余批次，从步骤1开始重复执行下一批次

每批完成后的验证：

钩子独立执行 - Claude无法看到执行成功/失败。子代理完成后：

bash

ls {planning_dir}/sections/section-*.md | wc -l

将结果与预期章节数量对比。如果有文件缺失：

重新运行缺失章节的子代理
如果仍然失败，手动处理：解析子代理响应的JSON并写入文件

21. Final Status & Cleanup

21. 最终状态检查与清理

Verify all section files were created successfully by running

check-sections.py

one final time. Confirm state is "complete".

通过最终运行

check-sections.py

验证所有章节文件是否已成功创建。确认状态为"complete"。

22. Output Summary

22. 输出摘要

Print generated files and next steps.

打印生成的文件和后续步骤。

Resuming After Compaction

压缩后恢复会话

CRITICAL: When resuming this workflow after context compaction, the detailed instructions from this file are lost. The task list is preserved but may not have enough detail. Follow these rules:

ALWAYS read the reference file for your current step before proceeding
- Task descriptions include hints like "(read section-index.md)" - follow them
- Reference files are in
```
{plugin_root}/skills/deep-plan/references/
```
- Get
```
plugin_root
```
  from task with subject
```
plugin_root=...
```
NEVER skip steps - follow the task list exactly in order
- If a task says "Run generate-section-tasks.py", run the script
- If a task says "use section-writer subagents", use subagents (don't write files directly)
- You can always re-read in the /deep-plan skill if unsure
If message says "MISSING PREREQUISITE" - a required file is missing but later files exist
- This means a step was skipped but later steps ran anyway
- Resume from the indicated step and OVERWRITE any subsequent files
- Example: if
```
claude-plan-tdd.md
```
  is missing but
```
sections/index.md
```
  exists, create the TDD plan, then recreate the index (the old index was made without TDD context)
Key reference files by step:
- Step 6-7:
```
research-protocol.md
```
- Step 8:
```
interview-protocol.md
```
- Step 11:
```
plan-writing.md
```
- Step 13:
```
external-review.md
```
- Step 16:
```
tdd-approach.md
```
- Step 18:
```
section-index.md
```
  (CRITICAL - has required format)
- Step 20:
```
section-splitting.md
```
  (subagent workflow)

重要提示： 上下文压缩后恢复此工作流时，此文件中的详细说明会丢失。任务列表会保留，但可能不够详细。请遵循以下规则：

继续前务必阅读当前步骤的参考文件
- 任务描述包含提示，如"(read section-index.md)" - 请遵循这些提示
- 参考文件位于
```
{plugin_root}/skills/deep-plan/references/
```
- 从主题为
```
plugin_root=...
```
  的任务中获取
```
plugin_root
```
绝不跳过步骤 - 严格按照任务列表顺序执行
- 如果任务要求"Run generate-section-tasks.py"，请运行该脚本
- 如果任务要求"use section-writer subagents"，请使用子代理（不要直接写入文件）
- 如果不确定，可以重新读取/deep-plan技能的说明
如果消息显示"MISSING PREREQUISITE" - 缺少必要文件但后续文件已存在
- 这意味着某个步骤被跳过但后续步骤已执行
- 从指定步骤恢复，并覆盖所有后续文件
- 示例：如果
```
claude-plan-tdd.md
```
  缺失但
```
sections/index.md
```
  存在，先创建TDD计划，然后重新创建索引（旧索引是在没有TDD上下文的情况下创建的）
各步骤的关键参考文件：
- 步骤6-7:
```
research-protocol.md
```
- 步骤8:
```
interview-protocol.md
```
- 步骤11:
```
plan-writing.md
```
- 步骤13:
```
external-review.md
```
- 步骤16:
```
tdd-approach.md
```
- 步骤18:
```
section-index.md
```
  （重要 - 包含必填格式）
- 步骤20:
```
section-splitting.md
```
  （子代理工作流）