用途:openspec-propose 是 OpenSpec 的规划工作流技能,用于把用户想构建或修复的需求,一次性生成完整的变更提案与规划产物。它只做规划,不修改项目代码;即使用户请求中包含实现或修复指令,该请求也只授权规划。产物完成后应停止,等待用户新的请求再启动 apply 工作流。
主要能力:按所选 schema 生成产物。默认 spec-driven schema 包括 proposal.md(做什么与为什么)、specs/<capability-path>/spec.md(系统必须做什么,是增量而非主 spec)、design.md(怎么做)、tasks.md(实现步骤)。<capability-path> 是相对 specs/ 的目录路径,例如 user-auth 或 identity/user-auth;已有能力需保留完整路径,新能力遵循项目既有组织方式。
使用方式:输入需包含 kebab-case 变更名或需求描述,例如“add user authentication”可推导为 add-user-auth。若输入不清,需先询问用户想构建或修复什么,理解前不得继续。若存在会实质影响范围、外部可观察行为、兼容性或验收标准的歧义,先询问;次要细节可合理假设并记录在产物中。
若用户指定 store(本机注册的独立 OpenSpec 仓库),先运行 openspec store list --json 获取 id,再在读写 spec 与 change 的命令上追加 --store <id>(如 new change、status、instructions、list、show、validate、archive、doctor、context、view),选定后保持粘性;其他命令不接受该参数。未指定 store 时,命令作用于最近的本地 openspec/ 根目录。
创建流程:用 openspec new change "<name>" 创建变更目录(显式指定 schema 时加 --schema "<schema-name>");用 openspec status --change "<name>" --json 获取 applyRequires、artifacts 及其 requires 依赖边、planningHome、changeRoot、artifactPaths、actionContext;按依赖顺序,对就绪产物运行 openspec instructions <artifact-id> --change "<name>" --json 获取 context、rules、template、instruction、resolvedOutputPath、dependencies,读取已完成依赖文件(需从磁盘重读),按 template 写入 resolvedOutputPath;若 instruction 委托给特定技能或命令,则调用它并确认文件存在。每创建一个产物后重跑 status。
限制:status 只反映文件是否存在,applyRequires 显示 done 不代表依赖已存在,须按 requires 边传递闭包确定必需集合(spec-driven 覆盖 proposal、specs、design、tasks)。status 为 skipped 的产物视为已满足,不得创建。仅当 instruction 标注为可选(如 design.md)或 status 为 skipped 时才可跳过,并告知用户。context 与 rules 是给执行者的约束,不得写入产物文件。同名变更已存在时,询问用户是继续还是新建。全部完成后运行 openspec status --change "<name>",汇总变更名与位置、产物清单及跳过原因,提示用户可运行 $openspec-apply-change(Codex)或 /openspec-apply-change(其他 agent)或请求应用该变更。