计划规范
标准化项目内的任务规划与执行，确保计划先落盘、执行可追溯、结果可回填。
调用与意图判断
- 仅当用户明确要求使用本技能，或通过运行环境提供的明确技能入口调用时使用（例如 OpenCode 的
/plan-spec、Codex 的$plan-spec）。普通任务规划、实现请求及项目文件的存在不构成调用。 - 根据当前用户意图和本次会话上下文判断目标，不单靠某个关键词：明确的新需求或新任务开启新计划，不沿用旧计划；明确的修改、补充、继续完善请求迭代其关联计划，不直接实现；明确指定计划并要求执行时优先执行指定计划。
- 只读规划模式下，有需求内容就按规范规划；无需求内容时询问用户输入需求。完善计划只更新会话中的草案；即使用户说“执行”或“开始”，也不得执行，只说明需要切换到允许写入的模式。
- 允许写入的执行模式下，若没有新需求或完善请求，用户说“执行”“开始”等明确的执行意图，或直接调用本技能，且当前会话存在由本技能形成、内容完整且可唯一识别的未完成计划，则继续执行该计划，不要求用户重复提供路径。收到明确的新需求时仍先规划；收到完善请求时先完善，不借此执行旧计划。
- 若当前会话没有可确认的计划、存在多个候选目标，或跨会话无法确定上下文，则先请用户提供需求或指定计划；不得按文件时间、最近提及的名称或模糊编号自行选取“最新计划”。
运行模式边界
- 只读规划模式（如 Plan Mode）：只做只读检查和计划草案，不写文件、不创建分支、不提交、不更新外部系统。
- 允许写入的执行模式（如 Build Mode）：规划阶段落盘计划；执行阶段按计划修改代码、测试并回填结果。不得仅凭技能或命令指令绕过运行环境的只读限制。
项目定位
项目安装时，以包含 .agents/skills/plan-spec/SKILL.md 的项目目录为根目录；从其子目录启动时向上定位该目录，不因外层 Git 仓库而上溯到仓库根。仅全局安装时以当前工作目录为准。技能无须项目启用配置；项目中的 OpenCode 标记仅影响安装器是否安装可选命令，不决定技能是否启用。技能执行时不自动修改或删除既有配置。
可选的 OpenCode 命令配置
通过 SkillHub 等渠道安装本技能后，不得仅因安装或加载技能而运行脚本、写入命令文件或修改项目配置。用户明确要求为当前项目配置 OpenCode 的 /plan-spec 命令时，先确认项目目录与写入权限；只读规划模式仅说明做法，不写文件。允许写入的模式下，经用户确认后可在目标项目运行 npx @wagzhi/plan-spec command install，或指定 --project-dir <目录>。此命令只安装 .opencode/commands/plan-spec.md，不接管已由 SkillHub 安装的技能，也不修改 AGENTS.md。安装器会拒绝覆盖已有或被用户修改的命令。用户明确要求撤销该命令时，使用 npx @wagzhi/plan-spec command uninstall；只有命令仍是受管且未修改时才移除，保留技能和其他项目文件。若 npm/安装器不可用，先说明阻碍，不要静默写入或声称安装成功。
计划阶段
- 只读检查当前分支与工作区状态。新任务优先从干净的
dev、main或master分支开始；已在任务分支时确认是否继续，工作区不干净时列出变更并询问是否继续，不得擅自处理原有变更。安装技能产生的未提交文件也算工作区变更。 - 计划应列出预计新增、修改或删除的文件名及变更内容；尚无法确定的文件标注待确认，收尾时核对实际文件清单。
执行前检查
- 记录当前分支、HEAD 与工作区状态，作为本次修改基线。
- 存在未提交或未跟踪文件时列出并询问是否继续；不得撤销或自动提交任务前修改。
- 允许写入的模式下，新任务首次落盘计划或执行只读规划模式的草案时，若干净工作区位于
dev、main或master，先创建feat/<brief_name>分支；已在任务分支时经确认后继续。只读规划模式只说明分支方案。
计划落盘与执行
- 允许写入的模式中，规划时将计划写到
spec/feats/NNN-brief-YYYYMMDD.md；只读规划模式只生成草案。规划到此为止，不修改实现文件。 - 继续完善时只更新已关联的计划：只读规划模式在对话中完善草案；允许写入的模式若已有本次关联的计划文件则更新该文件，若当前会话只有完整草案则先按规范落盘。用户未要求执行时不修改实现文件。
- 计划至少包含变更点、测试计划、假设与风险；完成后补充结果总结、文件清单、测试结果和后续跟进。
- 执行前确认计划内容、任务范围与分支。明确指定计划文件时读取该文件；同一会话从只读规划模式切至允许写入的模式且计划仍为完整、唯一的草案时，先按规范落盘该计划，再执行，不要求重复指定路径。无法确认完整计划时先询问，不得用旧计划代替。
- 计划文件由规划阶段为本任务生成且内容未被他人修改时，可计入本任务文件；任务开始前已有的其他修改仍须单独确认并排除。
任务收尾
- 对照任务基线与最终 Git 状态，准确汇总本次新增、修改、删除或重命名文件。
- 回填计划文件和最终答复；无法执行测试时如实记录原因。
- 仅当规划开始时工作区干净（或执行开始时仅有已确认的本任务计划文件）、当前为本任务分支、待提交内容全属本任务且测试通过时，才自动提交任务文件；仍只暂存本任务文件，并遵守当前运行环境的全局指令与权限。
- 其他情况列出文件、分支和测试结果并询问是否提交。不得自动推送、创建 PR 或混入任务前修改。
Git 操作
- Git 写操作按当前运行环境的全局指令、可用工具与权限执行；暂存和提交仅限本任务文件，不得撤销或混入任务前的变更。
- 只读规划模式下仅允许只读 Git 检查，不得执行 Git 写操作。
