用途:openspec-propose 用于快速把用户想构建或修复的内容转化为一份完整的 OpenSpec 变更提案。它仅生成规划类产物,不编辑项目代码;即使用户在请求中要求直接构建或修复,本次工作流也只授权规划。产物完成后应停止,等待用户新的请求再启动 apply 工作流。
主要能力:按所配置 schema(默认 spec-driven)定义的产物生成变更文档,默认包括 proposal.md(做什么与为什么)、specs/<capability-path>/spec.md(系统必须做什么的增量规范,而非主规范)、design.md(如何实现)和 tasks.md(实施步骤)。<capability-path> 是相对 specs/ 的规范目录,如 user-auth 或 identity/user-auth;已有能力保留完整路径,新能力遵循项目既有组织方式。
使用方式:用户请求应包含 kebab-case 变更名或对要构建内容的描述;若输入不明确,技能会询问“What change do you want to work on? Describe what you want to build or fix.”。从描述推导名称(如 add user authentication → add-user-auth)。若用户指定了 store(本机注册的独立 OpenSpec 仓库),先运行 openspec store list --json 获取 id,并在读写规范与变更的后续命令上加 --store <id>。使用默认 schema 时运行 openspec new change "<name>";显式指定 schema 时加 --schema "<schema-name>"。随后运行 openspec status --change "<name>" --json 获取 applyRequires、artifacts、requires 依赖边及路径上下文;对每个就绪产物运行 openspec instructions <artifact-id> --change "<name>" --json 获取 context、rules、template、instruction、resolvedOutputPath 和依赖,读取已完成的依赖文件(从磁盘重新读取),按模板写入产物;若 instruction 委派给特定技能或命令,则调用它并验证文件存在。循环直至 applyRequires 及其传递依赖的全部产物完成,最后运行 openspec status --change "<name>" 展示状态。
适用场景:需要快速从想法得到结构化变更提案、把需求拆成规范增量与实施任务、在编码前统一范围与设计时使用。
限制:仅规划,不实施、不编辑代码、不启动 apply;无明确输入时不继续;重大歧义需先询问用户,次要细节可合理假设并记录;同名变更已存在时询问继续还是新建;status 仅反映文件是否存在,需按 requires 依赖边构建必需产物集合;声明 skip_specs 的变更中 specs 不得创建;条件性产物仅在 instruction 标注可选时跳过。