| name | hplan |
| version | 1.0.0 |
| description | 分层持久化计划管理，适用于复杂的多阶段开发任务。当用户要求进行涉及多文件修改、 架构重构、系统设计等需要详细规划的任务时使用（超过5次工具调用的任务）。 创建分层的计划目录结构：overview.md（全局摘要）+ 每个阶段独立目录（详细规格、 调用链、检查清单）。触发词包括：开始规划、制定计划、任务分解。
|
| user-invocable | true |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep"] |
| hooks | {"UserPromptSubmit":[{"hooks":[{"type":"command","command":"sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/recover-context.sh\""}]}],"PreToolUse":[{"matcher":"Write|Edit|Bash|Read|Grep|Glob","hooks":[{"type":"command","command":"sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/inject-overview.sh\""}]}],"PostToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/post-edit-remind.sh\""}]}],"Stop":[{"hooks":[{"type":"command","command":"sh \"${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/hplan}/scripts/check-complete.sh\""}]}]} |
hplan — 分层持久化计划管理
用文件系统作为持久化工作记忆。overview.md 保持精简（≤25行），详细规格按阶段拆分到独立目录中。
核心原则
上下文窗口 = RAM（易失、有限）
文件系统 = 磁盘（持久、无限）
→ 重要信息必须写入磁盘
→ 被 hook 注入的内容必须精简
→ 被深度参考的内容必须详尽
→ 二者分离，互不冲突
如果感觉上下文缺失，主动读取 .plan/ 下的相关文件即可。所有计划信息都持久化在磁盘文件中，不会因上下文变化而丢失。
目录结构
所有计划文件存放在项目根目录的 .plan/ 目录下：
.plan/
├── overview.md ← 全局摘要（精简，被 hook 反复注入）
├── decisions.md ← 所有决策记录
├── errors.md ← 所有错误记录
└── phases/
├── phase1_xxx/
│ ├── spec.md ← 该阶段详细规格（修改文件、代码变更）
│ ├── call_chain.md ← 调用链 / 架构图（可选）
│ └── checklist.md ← 逐项完成状态
├── phase2_xxx/
│ ├── spec.md
│ ├── call_chain.md
│ └── checklist.md
└── ...
关键约束
overview.md 必须保持精简
overview.md 是被 PreToolUse hook 每次注入到上下文的文件。严格控制在 25 行以内。格式如下：
# [项目名称]
current_phase: phase2_xxx
## Goal
[一句话描述最终目标]
## Phases
- [x] phase1_xxx: [阶段描述] → complete
- [ ] phase2_xxx: [阶段描述] → in_progress (2/4)
- [ ] phase3_xxx: [阶段描述] → pending
## Blockers
[当前阻塞项，没有则写 None]
## Last Decision
[最近一条重要决策的一句话摘要]
## Last Error
[最近一条错误的一句话摘要，没有则写 None]
绝对不要在 overview.md 里放详细的文件清单、代码片段、调用链。那些内容属于 phase 目录。
详细内容放在 phase 目录中
每个 phases/phaseN_xxx/ 目录包含该阶段的完整信息：
spec.md — 该阶段的详细规格：
- 需要修改哪些文件、每个文件的具体变更内容
- 新增文件的接口设计、数据结构定义
- 依赖关系和前置条件
spec.md 控制在 60 行以内。 当用户发送新消息时，如果有进行中的阶段，当前阶段的 spec.md 会被自动注入到上下文。如果一个阶段的 spec 写出来超过 60 行，说明这个阶段的粒度太粗，应该拆分成两个或更多阶段。拆分时保持每个阶段的 spec 聚焦于一组相关的修改，而非堆砌所有细节。
call_chain.md（可选）— 调用链 / 架构变更图：
- 修改前后的调用关系对比
- 用文本或 Mermaid 语法绘制
checklist.md — 该阶段的逐项检查清单：
# Phase 2: 后端接口改造 — 检查清单
- [x] 新建 src/auth/token.py
- [x] 修改 src/auth/routes.py
- [ ] 修改 src/middleware/auth.py
- [ ] 修改 config/auth.yaml
- [ ] 运行单元测试确认无回归
工作流
1. 创建计划（必须在开始执行前完成）
收到复杂任务后：
- 创建
.plan/ 目录结构（可运行 sh scripts/init-plan.sh 快速初始化）
- 用模板创建 overview.md（参考 templates/overview.md）
- 为每个阶段创建 phase 目录和 spec.md / checklist.md
- 如果涉及架构变更，创建 call_chain.md
- 创建 decisions.md 和 errors.md
参考模板文件：
2. 用户确认（不可跳过）
计划创建完成后，必须停下来等待用户确认，严禁自行开始执行。
向用户展示以下内容并请求确认：
- overview.md 的完整内容（目标和阶段划分）
- 每个阶段的 spec.md 摘要（修改哪些文件、核心变更）
- 总阶段数和预估工作量
明确询问用户：
- 阶段划分是否合理？是否需要增减或拆分阶段？
- 每个阶段的修改范围是否正确？是否遗漏了文件或变更点？
- 是否可以开始执行？
只有在用户明确表示同意后，才能进入执行阶段。 如果用户提出调整意见，修改计划文件后再次展示并请求确认。
修改计划时必须保持 overview.md 与 phases/ 目录同步
在确认阶段与用户反复调整计划时，任何对阶段的增删改都必须同时更新两个地方：
- 新增阶段：在 overview.md 中添加条目，同时创建
phases/phaseN_xxx/ 目录及 spec.md、checklist.md
- 删除阶段：从 overview.md 中移除条目，同时删除对应的
phases/phaseN_xxx/ 目录
- 重命名阶段：更新 overview.md 中的 phase ID，同时重命名
phases/ 下的目录（不要保留旧目录）
- 拆分阶段：删除原阶段目录，创建拆分后的多个新目录，更新 overview.md
每次修改计划后，运行 sh scripts/validate-plan.sh 校验一致性。该脚本会检查：
- overview.md 中的每个阶段是否有对应目录
- 每个目录中是否包含 spec.md 和 checklist.md
- phases/ 下是否有 overview.md 未引用的残留目录
3. 执行阶段
用户确认计划后，进入工作循环：
- 开始新阶段前：必须先读取该阶段的 spec.md 全文（和 call_chain.md，如有），完整理解要做什么。这一步不可跳过。
- 执行工作：按 checklist.md 逐项推进
- 完成子任务后：更新 checklist.md（
[ ] → [x]）
- 阶段全部完成后：
- 更新 overview.md：标记该阶段 complete，更新
current_phase 指向下一阶段
- 可运行
sh scripts/advance-phase.sh 辅助切换
- 将该阶段的重要发现记录到 decisions.md
4. 切换阶段
当 overview.md 中 current_phase 变更后：
- PreToolUse hook 会继续注入 overview.md，确保目标感知
- 必须主动读取新阶段的 spec.md 和 checklist.md，确认工作范围
5. 错误处理
第1次失败：诊断并修复 → 记录到 errors.md
第2次失败：换一种方法 → 记录到 errors.md
第3次失败：重新审视假设 → 更新 spec.md
第3次后仍失败：向用户说明情况，请求指导
6. 完成验证
Stop hook 会自动检查 overview.md 中所有阶段的完成状态。如果存在未完成的阶段，会提示你检查剩余任务。用户可以随时通过删除 .plan/ 目录来退出计划。
7. 自主完成原则
应尽量亲自执行 checklist 中的每一项，而非将工作交给用户手动执行。
如果某个子任务你无法完成（例如需要外部服务的密钥、需要物理设备操作），应当：
- 在 errors.md 中记录具体原因
- 在 overview.md 的 Blockers 中标注
- 向用户明确说明你被什么阻塞了，请求用户提供必要的信息或操作
- 等待用户回应后继续完成，而不是跳过
以下行为应避免：
- 将 checklist 中的子任务描述为"建议用户手动执行"
- 列出剩余步骤的说明后结束，而非实际执行这些步骤
- 将可以通过代码完成的操作（创建文件、修改配置、运行测试等）推给用户
8. 完成后的修改
计划全部完成后，用户可能提出修改意见。根据修改的复杂度选择不同的处理方式：
直接修复（修改涉及 ≤2 个文件，不改变架构）：
- 不启动新计划，直接修改代码
- 在 decisions.md 中记录修改内容
追加阶段（修改涉及 3+ 个文件，或需要调整调用链）：
- 在现有
.plan/ 上追加新的 phase 目录（如 phase10_fix_xxx）
- 更新 overview.md：添加新阶段条目，设置
current_phase 指向新阶段
- 向用户展示新增阶段的 spec 并请求确认，确认后执行
- 运行
sh scripts/validate-plan.sh 校验一致性
全新计划（修改的性质是推翻原设计）：
- 将现有
.plan/ 重命名为 .plan.archived/（保留记录）
- 启动全新的 hplan 流程：创建计划 → 用户确认 → 执行
判断标准：如果用户的修改意见可以表述为"在现有架构上修 N 个问题"，追加阶段；如果必须表述为"重新设计 XXX 模块"，全新计划。
何时使用
使用：
- 多阶段开发任务（3+ 阶段）
- 涉及多文件修改的重构
- 需要记录调用链/架构变更的任务
- 跨会话的长期项目
不使用：
读写决策矩阵
| 场景 | 操作 | 原因 |
|---|
| 刚写完文件 | 不读 | 内容还在上下文中 |
| 开始新阶段 | 读 spec.md + checklist.md | 完整理解工作范围 |
| 做重要决策前 | 读 overview.md + 相关 spec | 确保目标对齐 |
| 遇到错误 | 读 errors.md | 避免重复失败 |
反模式
| 不要 | 应该 |
|---|
| 在 overview.md 里放详细信息 | 放在 phase 目录的 spec.md 里 |
| overview.md 超过 25 行 | 精简到只有摘要 |
| spec.md 超过 60 行 | 拆分为多个阶段，每个阶段的 spec 保持聚焦 |
| 跳过创建计划直接执行 | 先创建完整的 .plan/ 目录 |
| 忘记更新 checklist.md | 每完成一项立即更新 |
| 在 spec.md 里更新状态 | 状态在 checklist.md，规格在 spec.md |
| 重复同样的失败操作 | 记录错误，变换方法 |
| 把未完成的子任务交给用户手动执行 | 尽量自己执行，遇到阻塞时请求用户提供必要信息 |
| 列出剩余步骤的说明后结束 | 尽量实际执行这些步骤，完成后再结束 |
| 创建计划后直接开始执行 | 展示计划并等待用户确认后才执行 |
| 修改 overview.md 后不同步 phases/ 目录 | 增删改阶段时同时更新两处，用 validate-plan.sh 校验 |
