~plan

Trigger: ~plan [description]

~plan 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案写入；直接显式执行 ~plan 时，默认停在“形成可执行方案”，只有用户明确授权继续时才继续执行。 执行 ~plan 时，通用阶段边界按当前已加载的 HelloAGENTS 规则执行；本 skill 负责补充 ~plan 的需求澄清、方案确认、方案包写入与继续执行要求。 .helloagents/ 在本 skill 中统一按项目级存储路径理解：状态文件只使用 state_path；会话证据使用当前 state_path 所在目录下的 artifacts/*.json；若 project_store_mode=repo-shared，知识库、DESIGN.md 与 plans/ / archive/ 按当前上下文中已注入的项目知识/方案目录解析。

铁律

• 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
• 需求澄清阶段不读取实现类技能（hello-ui / hello-test / qa-review 等），需求明确后再按需读取
• 方案必须整理为可执行产物，不停留在泛化建议
• 若当前任务来自 ~auto，则“开始执行”视为已包含在 ~auto 授权内；方案包写入后默认继续执行，只有命中阻塞判定时才停下。~design 是 ~plan 的兼容别名，只有在 ~auto 内触发其语义时才默认继续进入 ~build
• 涉及 UI 时，当前方案包中的 UI 决策优先于 .helloagents/DESIGN.md；.helloagents/DESIGN.md（按当前项目存储模式解析）优先于已读取的 hello-ui 规则；同时所有 UI 任务都必须满足 UI 质量基线

流程

1. 上下文收集与需求澄清准备

已有项目：

• 按当前已加载的 HelloAGENTS 规则恢复上下文，并遵循“.helloagents/ 文件读取优先级”和“项目文件”要求；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 state_path，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
• 在需求澄清前，至少确认 .helloagents/context.md、.helloagents/guidelines.md（按当前项目存储模式解析）；涉及 UI 时，如存在 .helloagents/DESIGN.md（按当前项目存储模式解析），一并读取现有设计契约
• 只扫描与当前需求直接相关的代码文件，用于形成假设和识别约束

全新项目（无 .helloagents/ 目录）：

• 跳过项目级上下文读取，直接进入需求澄清

2. 需求澄清

目标：通过自然对话明确目的、约束、成功标准与验收边界。

默认使用交互澄清，一问一答逐条确认：

• 每次只问一个问题，优先使用选择题；选项使用数字编号，用户回复数字即可选择
• 每个问题给出推荐选项和理由；格式遵循全局「选择确认」规则
• 只确认真正影响执行路径的关键决策
• 已有代码库时，先静默读 5-15 个相关文件，基于代码证据形成假设，再以选择题形式逐条确认
• 发现用户用词与 .helloagents/context.md 的领域语言冲突时，立即澄清并统一术语

快速通道：用户明确说"直接做，不用问我"、"按默认来"时，跳过逐条交互，基于代码证据直接形成方案。低置信度假设仍必须明确询问。

涉及视觉/交互/体验的问题时：

• 选项必须体现当前前沿水准
• 每个选项都要有具体、可执行的视觉特征描述

3. 方案确认

基于已确认需求，给出 2-3 个可行方案：

• 每个方案说明架构思路与关键取舍
• 标注推荐方案及理由
• 方案使用数字编号，用户回复数字即可选择；格式遵循全局「选择确认」规则

涉及 UI 的方案：

• 读取 hello-ui SKILL.md
• 将视觉、交互、设计系统要求纳入方案
• 区分“本次 feature 的 UI 决策”和“项目级稳定设计契约”：前者写入 plan.md，后者同步到 .helloagents/DESIGN.md（按当前项目存储模式解析）

4. 方案细化

用户确认方向后，一次性输出完整可执行方案：

• 架构与文件结构
• 完成定义（功能完成时必须为真的条件、关键验收点、qaMode、qaFocus、进入收尾前必须补齐的质量证据）
• 数据流与错误处理
• 验证策略
• 涉及 UI 时的设计方向、状态覆盖与 DESIGN.md 更新点
• 涉及项目特有概念时，同步确认标准术语、避免用语和关键关系，必要时更新 .helloagents/context.md 的“领域语言”区块（按当前项目存储模式解析）

5. 写入方案包

将确认的方案写入本地项目：

• 按当前已加载的 HelloAGENTS 规则建立 .helloagents/ 与最小流程状态
• 创建方案包目标目录：.helloagents/plans/YYYYMMDDHHMM_{feature}/（按当前项目存储模式解析；repo-shared 时写入当前项目方案目录）
• 以 {HELLOAGENTS_READ_ROOT}/templates/plans/ 为源模板，在上述方案包目标目录内写入：
  • requirements.md
  • plan.md
  • tasks.md
  • contract.json
• 写 contract.json 时，至少落成以下字段：qaMode、qaFocus；涉及 UI 时再写 ui.required、ui.designContract 与 ui.sourcePriority
• 只有在 UI 方向确需先明确时，才额外写 ui.styleAdvisor.required、ui.styleAdvisor.reason 与 ui.styleAdvisor.focus；它复用当前会话 artifacts/advisor.json，不是默认常驻步骤
• 只有在 UI 验收确有收益时，才额外写 ui.visualValidation.required、ui.visualValidation.reason、ui.visualValidation.screens 与 ui.visualValidation.states；不要把视觉验收扩成所有 UI 任务的固定步骤
• 只有在 T3、非 UI 的高风险审查或确需额外跨模型建议时，才写 advisor.required、advisor.reason、advisor.focus 与 advisor.preferredSources；不要把 advisor 变成默认常驻流程
• 使用 scripts/plan-contract.mjs write 写 contract.json，不要让后续检查脚本再从 plan.md 的自然语言说明里猜验证主路径
• 在 tasks.md 中保留 “Codex /goal 执行入口”，内容必须引用当前方案包路径、AFK/HITL 边界，并明确 /goal -> ~auto -> ~qa 这条链路；不要把普通 PRD 原文当作 /goal 目标
• 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
• 重写 state_path，其中“主线目标”写本次规划要完成的目标，不保留其他任务的内容

知识库完整创建与归档按当前已加载的 HelloAGENTS 规则继续处理。

6. 执行决策

展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：

• 开始执行 → 继续进入 ~build
• 修改方案 → 返回方案细化
• 暂不执行，保留方案 → 更新 state_path；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”

如果用户已明确表示继续执行，则视为授权成立，可直接继续执行。 如果当前任务来自 ~auto，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 ~build，不再追加一次“是否开始执行”的询问。 如果当前任务是显式 ~plan 或 ~design，且尚未获得执行授权，最终回复按通用输出格式使用等待输入态：正文说明方案包与验证结果，🔄 下一步 写清待确认动作。

方案包要求

方案包中的 tasks.md 必须满足：

• 每个任务默认是端到端垂直切片，能交付一个可验证行为；除非确有技术前置，否则不按“数据库 / API / UI / 测试”横向拆分
• 每个任务标注 AFK 或 HITL：AFK 表示代理可独立完成，HITL 表示需要用户决策、外部凭据、人工视觉确认或手动验收
• 明确文件路径、预期变更、完成标准、验证方式与依赖关系
• 每个任务可独立验证；厚任务必须拆成更薄的可验收切片
• “Codex /goal 执行入口”只作为长程执行提示，不计入任务列表；入口必须让 Codex 按已拆好的 tasks.md 执行，默认主执行命令是 ~auto，最终必须进入 ~qa，而不是直接消费未拆分需求文档

方案包中的 contract.json 必须满足：

• qaMode 只能是 standard 或 deep
• qaFocus 必填
• 涉及 UI 时显式写出 UI 契约来源优先级
• 若启用 ui.styleAdvisor，必须写清触发原因与 focus
• 若启用 ui.visualValidation，必须写清触发原因，以及至少一组关键 screens 或 states
• 仅在明确需要独立 advisor 时，才填写 advisor 区块；填写后必须写清触发原因、focus 与优先来源