plan-importer

计划导入器

使用此技能将现有项目规划材料转换为 PlanWeave 计划包。

命令入口

写入文件前，先确定命令：

1. 如果用户提供了命令，则使用该命令。
2. 否则，尝试全局 planweave。
3. 在 PlanWeave 仓库中，优先使用 pnpm --filter @planweave-ai/cli planweave。
4. 如果仓库定义了其他本地脚本，则使用该脚本的确切入口，并在报告中注明。

将示例写为 <pw> ...，其中 <pw> 是已确定的命令。

写入文件前，使用 CLI 确定目标工作区：

<pw> init --json
<pw> paths --json
<pw> validate --json

在此工作流中，使用 CLI 进行命令发现、工作区/路径解析和验证。将导入内容写入 CLI 返回的 PlanWeave 工作区路径下的包文件中。

工作区

• 从目标项目根目录运行 <pw>，不要从 PlanWeave 仓库运行，除非 PlanWeave 本身就是目标项目。
• 不要在目标项目中手动创建或写入 ./.planweave。
• 如果设置了 PLANWEAVE_HOME，PlanWeave 会将项目计划存储在该位置；否则默认为：
  • macOS：~/.planweave
  • Linux：~/.planweave
  • Windows：%USERPROFILE%\.planweave
• 通过 <pw> init --json 和 <pw> paths --json 获取准确的工作区路径。
• 只能写入 CLI 返回的 PlanWeave 工作区路径，例如 workspaceRoot、projectGraphPath 以及该工作区下的包目录。
• 对于指定了明确且已存在的目标画布的单画布导入，只能写入该画布的包目录。
• 对于未指定目标画布的单画布导入，不要覆盖现有默认/当前画布。应在 project-graph.json 中创建新的正式画布条目，分配一个不冲突的画布 ID，并将导入的包写入该画布的包目录。
• 对于正式的多画布计划，在返回的项目/工作区根目录下写入 project-graph.json，并且仅将每个画布包写入该项目图中指定的包目录。
• 将 CLI 返回的项目/工作区目录和包目录视为唯一可写入的 PlanWeave 位置。

计划文件编辑边界

• 使用 CLI/运行时命令执行机械性工作区操作：创建画布、分配路径、去重 ID、选择活动画布、验证、恢复事务，以及更改运行时状态/结果。
• 直接在 CLI 返回的工作区路径下编辑 Plan Package 语义文件：project-graph.json 中的画布意图和依赖项、各画布 manifest.json 中的任务/区块/边/验收标准/提示词路径，以及源提示词 Markdown。
• 如果窄范围的 CLI 编辑命令能准确表达语义变更，则使用该命令；否则，直接更新源包文件和提示词。
• 直接编辑计划后，对已编辑的画布执行画布范围内的验证；如果 project-graph.json、画布边或 crossTaskEdges 发生更改，则执行项目验证。

导入工作流

1. 扫描 README、规划文档、ADR、问题、规格说明、领域笔记和引用的源文件。
2. 写入前记录已扫描的源文件列表。
3. 提取 PlanWeave 包结构：项目图、画布、任务、区块、依赖关系、提示词位置、布局提示和验证策略。
4. 不要创建上下文节点。将目标、要求、约束、风险、参考资料和架构关卡放入项目／全局提示词、任务验收标准、任务提示词或区块提示词中。
5. 写入前运行下方的计划质量关卡。建立覆盖映射：每项任务都有具体的验收标准，每个区块都有可验证的完成标准，关键要求都有明确的提示词位置。
6. 明确选择现有画布、新建的单一导入画布，或正式的多画布项目图。如果用户未明确要求替换现有画布，请新建画布，而不是写入 default。
7. 运行 <pw> init --json 和 <pw> paths --json；以这些输出为工作区位置的权威依据。
8. 生成计划：创建新画布或多画布计划时更新 project-graph.json，然后在声明的包目录下写入各画布的 manifest.json、任务提示词和区块提示词。
9. 运行 <pw> validate --json；修复验证错误和导入器生成的薄弱覆盖内容。
10. 输出计划导入报告，列出源文档、命令入口、项目图路径（如有）、包路径、提示词位置、画布策略、审查策略和验证结果。

计划质量门禁

• 将每项权威目标映射到任务、区块、验收项或提示词；标记被遗漏、弱化或错误延后的要求。
• 除非用户明确限定范围，否则不要将演示子集视为完整交付。
• 识别核心对象，并追踪其创建、结构、验证、转换、状态、存储、使用方、副作用、最终输出、失败、重试、回滚和人工干预。
• 确保生产方和使用方之间的架构、类型、API、CLI 标志、事件、文件及提示词输入／输出保持一致。
• 变更契约的任务必须在相关时覆盖调用方、测试、固定数据、文档和迁移；不要用回退逻辑、默认值、any 或仅模拟路径来掩盖缺失的契约。
• 按真实执行顺序建模：并行任务必须彼此独立，顺序门禁必须明确，每个画布都必须对应一个阶段、能力领域、子系统、工作流或并行工作组。
• 导入多画布计划时，默认设置 crossTaskEdges: []。
• 对于多画布导入，画布级顺序必须编码为正式项目图边。添加跨任务边之前，先将紧密耦合的任务移至同一画布，或将阶段级顺序提升为画布依赖边。
• 仅当任务阻塞关系稀疏、无法再简化，且涉及彼此内聚并可独立执行的画布时，才使用显式的 crossTaskEdges；并记录为何任务迁移或画布边不合适。
• 将同一画布之间密集或重复的跨任务边、以任务边表示的阶段级顺序，以及与画布顺序冗余的任务边视为画布边界缺陷；在编写计划前重新划分任务，或提升依赖层级。
• 不要仅依赖项目／全局提示词中的文字来表示画布顺序或跨画布阻塞关系。
• 拒绝虚假的完成项，例如没有运行时用途的架构、没有调用方的 API、没有行为的 UI、从未读取的配置、没有实际客户端的提供方抽象、没有使用方的队列、没有对应文件的路径、没有真实执行路径的试运行，或仅测试固定数据。
• 当领域需要可靠执行时，覆盖错误、重试、取消、超时、权限失败、部分成功、外部服务中断、人工审核失败和恢复。
• 每个区块都必须指明具体的验证方式：命令、测试、输出产物、可观察的状态变更或端到端流程。
• 复杂区块的完成标准必须说明架构边界、测试位置、配置／环境变量处理、适用时对 README 或 .env.example 的更新，以及真实提供方与模拟／试运行的预期。
• 除非目标代码库明确要求，否则不要将其他项目的技能、引导规则或提示词惯例复制到此计划中。
• 在报告中区分计划缺陷与 PlanWeave 工具链缺陷。

提示词放置位置

• PlanWeave 全局提示词／项目提示词：跨领域规则、架构约束、参考文件、编码规范、共享风险。
• 任务提示词：任务局部上下文、验收依据、依赖关系、可能涉及的文件。
• 区块提示词：具体执行说明、验证命令、输出／报告预期。
• 不要将渲染后的提示词输出写回源提示词文件。渲染后的提示词由 <pw> prompt <ref> 生成，属于派生产物。
• 不要将区块提示词留空。如果区块无需单独说明，应注明其继承任务／项目上下文，并列出具体完成条件。

任务与区块粒度

• 不要为了拆分而拆分。应根据数据流、所有权边界、依赖关系、风险或可独立验证的验收条件来拆分。
• 合并过小、无法独立认领、测试或汇报的任务。
• 使用 implementation 区块执行工作，并在完成标准、验证命令或评审关卡中明确编码验证要求。
• 仅对复杂代码、跨契约变更、数据库／架构迁移、提供方集成、安全／隐私、架构变更或高风险用户可见行为添加评审区块。
• 除非用户要求，否则不要为简单文档、配置微调、局部文案编辑或低风险的单文件变更添加评审区块。

多画布策略

• 对于小型计划，使用一个 package 画布。
• 对于大型计划，尤其是包含 100 个以上任务／节点的计划，按阶段、能力领域、子系统、工作流或负责人拆分为多个任务画布。
• 确保每个画布易于浏览；若源计划允许，通常包含 10–30 个任务。
• 将大型或多阶段导入内容物化为正式的 project-graph.json，并为每个画布提供一个 manifest.json。
• 使用项目图中的画布依赖边表示画布级顺序。
• 除非某个稀疏且不可约的阻塞项通过 Plan Quality Gate，否则将 crossTaskEdges 留空。
• 保持单画布 manifest.json 的语义不变；不要将跨画布边放入画布清单。
• 项目／全局提示词可以说明策略，但不能作为强制执行依赖关系的依据。
• 不同画布不会自动并行；应根据项目图边 和 crossTaskEdges 推导出必须遵循的顺序。使用 parallel.sharedResources 记录可能的资源重叠；这仅供参考，不得表述为会阻止执行。

项目图结构

编写正式的多画布计划时，须包含：

• PlanWeave 项目／工作区根目录下的 project-graph.json。
• canvases 条目，其中包含稳定的 id、标题、package 目录，以及架构要求的状态／结果路径，且不包含不可见的旧版专用画布记录。
• 表示阶段、能力、子系统或工作流顺序的画布依赖边。
• 仅在存在文档记录的稀疏例外，且无法通过任务放置或画布依赖边表示时，才使用明确的 crossTaskEdges。
• 不包含上下文节点、反馈节点、运行时状态或仅用于布局的图镜像。

写入后，使用 <pw> validate --json 进行验证；必须先修复项目图架构／读取／编译诊断问题（例如缺少画布引用、缺少跨任务引用和循环依赖），再报告成功。

区块结构

每个区块都需要包含 id、type、title、prompt、depends_on、可选的 parallel.sharedResources 提示、完成标准、验证要求和汇报预期。如果确有必要进行评审，则应在实现区块之后添加 R-001，并设置 review.required: true，同时提供清晰的评审提示词。

规则

• 将 project-graph.json（若存在）、每个画布的 manifest.json、源提示词以及任务／区块提示词文件视为计划内容的唯一事实来源。
• 如果用户提供了现有的 package 格式文件，请验证其结构，并将其直接物化到目标工作区文件中。
• 不要创建 feedback 区块类型；反馈属于运行时状态。
• 不要在清单中写入实现状态。
• 仅将 state.json 用于运行时任务／区块／反馈状态。
• 不要创建运行时图镜像、.plan/、SQLite 存储、HTTP API、Docker 服务或 MCP 服务。
• 不要用 Plan Import Report 替代清单边、任务验收条件或提示词内容。