# plan 命令

当用户输入 `$pm-workflow plan`、"开始规划"、"开发规划"、"任务拆解" 或类似意图时，使用本命令。

## 负责角色

必须启动当前 CLI 结构下的开发规划子 agent 执行开发任务规划：Codex 使用 `.codex/agents/dev-planner.toml`，Claude Code 使用 `.claude/agents/dev-planner.md`。

如果当前环境无法启动开发规划子 agent，必须停止开发任务规划，不生成或修改 `docs/dev-tasks.md` 和 `docs/workflow-state.json`，并提示用户在支持项目子 agent 调度的 CLI 中打开当前工作室目录后重试。

## 输入

- `docs/prd.md`
- `docs/tech-architecture.md`
- `docs/ui-design.md`
- `prototype/`

## 必须执行的流程

1. 先检查上游产物是否完整，发现阻塞问题时先报告。
2. 生成 Kiro 风格单文件 `docs/dev-tasks.md`，使用 `- [ ] 1. 任务名` checklist，不新增任务目录。
3. 第一个任务必须锁定语言/框架版本、包管理器、依赖文件形态、脚手架命令、安装命令、启动命令和测试命令。
4. 如果上游没有明确这些技术基线，必须列为阻塞确认项，不得自行默认。
5. 将实现工作拆成环境配置、脚手架创建或校验、依赖/测试框架、模块数据结构、数据访问、业务逻辑、接口/页面入口、回归测试等连续小任务。
6. 每个编号任务必须是用户可见、可独立验证的最小可执行任务；一个任务只处理一个清晰目标。
7. 每个编号任务下保留 3-6 条具体动作，最后一条必须是测试/验收动作。
8. 每个编号任务必须用 `_需求: ..._` 追溯 PRD 功能编号或工程准备项。
9. 如果任务拆解发现环境、脚手架、框架版本、模块边界、接口、页面路径、验收标准、测试策略或技术约束与上游不一致，必须先回写对应 PRD/架构/UI/handoff 文档，不能只在任务中新增或修正。
10. 写入或更新 `docs/dev-tasks.md`。
11. 在 `docs/dev-tasks.md` 填写 `## 文档同步检查`，至少检查并引用 `docs/prd.md`、`docs/tech-architecture.md`、`docs/ui-design.md`；列明已同步文档或不需要同步原因，不得留空或写 `待补充`。
12. 更新 `docs/workflow-state.json`，记录阶段产物和文档同步检查结论，并把 `recommended_next` 设置为 `review plan` 或 `deliver`。

## 必须具备的追溯关系

每个编号任务必须包含：

- checklist 状态和连续编号
- 任务名称
- 具体开发动作
- 测试/验收动作
- `_需求: ..._` 追溯
- 文档同步检查：技术基线、环境、脚手架、模块任务、测试策略和验收标准必须能追溯到 PRD/架构/UI 来源；计划阶段修正前文时必须列出回写文档。

## 禁止事项

- 不得保留 `待补充`、`TODO`、`类似上一步`、`写相关测试`、`处理边界情况` 等空泛语句。
- 不得生成“实现完整模块、完成全部接口、搭建整个项目、创建所有测试、接入完整业务流程”这类过粗任务。
- 不得生成没有测试/验收动作或没有 `_需求: ..._` 追溯的编号任务。
- 不得自行默认 Python 版本、Node 版本、框架版本、包管理器、依赖文件或脚手架创建方式。
- 不得在用户要求 `uv` 时生成 `requirements.txt` 方案；不得在 Next.js 新项目中绕过官方脚手架手写 `package.json` 和目录结构。

## 收尾引导

结束时询问用户：是否要先做任务规划审核、修改任务，还是打包交付。
