用途
openspec-propose 用于在 OpenSpec 规范驱动开发流程中提出一个新的变更。当用户想快速描述要构建或修复的内容,并希望一次性获得完整提案时使用。该工作流只创建规划产物,不编辑项目代码。
主要能力
- 根据用户描述推导 kebab-case 变更名称(例如“add user authentication”对应 add-user-auth)。
- 使用默认规范驱动 schema 生成以下产物:
- proposal.md:做什么与为什么
- specs/<capability-path>/spec.md:系统必须做什么,是增量而非主规范
- design.md:如何实现
- tasks.md:实现步骤
- 支持通过 --schema 指定其他工作流 schema。
- 支持已注册的 store:通过 openspec store list --json 发现 store id,并在读写规范与变更的命令上附加 --store <id>,选定后在该工作流剩余步骤中保持粘性。
- 通过 openspec status --change "<name>" --json 获取产物构建顺序、依赖边、路径与作用域上下文。
- 通过 openspec instructions <artifact-id> --change "<name>" --json 获取每个产物的上下文、规则、模板、指令、输出路径与依赖。
使用方式
- 理解请求并澄清实质性歧义。若未提供明确输入,询问用户想处理什么变更。
- 确定工作流 schema:默认使用已配置的默认 schema;仅当用户明确按名称请求时才使用 --schema <schema-name>。
- 创建变更目录:
- 默认:openspec new change "<name>"
- 指定 schema:openspec new change "<name>" --schema "<schema-name>"
- 获取产物构建顺序:openspec status --change "<name>" --json,解析 applyRequires、artifacts、planningHome、changeRoot、artifactPaths 和 actionContext。
- 按依赖顺序创建所需集合中的每个产物:
- 获取指令:openspec instructions <artifact-id> --change "<name>" --json
- 从磁盘重新读取已完成的依赖文件作为上下文
- 若 instruction 字段委托给特定技能或命令,则调用它生成产物,并验证文件存在于 resolvedOutputPath
- 否则按 template 结构写入 resolvedOutputPath;若为 glob,按 instruction 选择具体路径
- context 和 rules 是约束,不得复制进文件
- 每创建一个产物后重新运行 openspec status --change "<name>" --json
- 所需集合为 applyRequires 加上从这些产物沿 requires 边可达的所有产物(规范驱动会闭包到 proposal、specs、design、tasks)。
- 仅当 status 已报告 skipped,或其自身 instruction 标记为可选时才跳过。
- 展示最终状态:openspec status --change "<name>"。
- 汇总变更名称与位置、已创建产物及简要说明、跳过的条件产物及原因,并提示用户产物已可供审阅,准备好后运行 $openspec-apply-change(Codex)或 /openspec-apply-change(其他代理)或要求应用该变更。
适用场景
- 用户希望快速描述要构建或修复的内容并获得完整提案。
- 需要在实现前生成规划产物,包括提案、增量规范、设计与任务。
- 使用 OpenSpec 规范驱动开发流程,并希望按 schema 定义的产物结构推进。
限制
- 该工作流仅授权规划,不实现变更、不启动 apply 工作流、不编辑项目代码。
- 即使初始请求要求构建或修复,也不得在同一响应中开始实现;需等待用户在产物呈现后提出新请求,再启动 apply 工作流。
- 必须创建 apply 阶段传递依赖的每个产物,而不仅是 apply.requires 中列出的 id。
- 创建新产物前必须从磁盘重新读取依赖产物,而非依赖对话记忆。
- 对会实质性改变范围、外部可观察行为、兼容性或验收标准的歧义必须询问用户;次要细节可做合理假设并记录。
- 若同名变更已存在,询问用户是继续还是新建。
- 写入后需验证每个产物文件存在再继续。
- status 仅检查文件是否存在,applyRequires 产物显示 done 不代表其依赖存在;应使用 requires 边构建所需集合。
- 已标记 skipped 的产物视为满足,不得创建其文件。
- 依赖是使能条件而非门禁:若必需产物仅因跳过了条件依赖而被阻塞,仍应写入。
- 关于收费、价格、平台、效果等事实,资料未提供。