openspec-propose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Propose a new change - create the change and generate all artifacts in one step.

Planning boundary: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.

I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:

proposal.md (what & why)
```
specs/<capability-path>/spec.md
```
(what the system must do - a delta, not the main spec)
design.md (how)
tasks.md (implementation steps)

<capability-path>

is the spec directory relative to

specs/

(for example,

user-auth

identity/user-auth

). Preserve an existing capability's full path and follow the project's established organization for new capabilities.

When the user is ready to implement, they must start the apply workflow explicitly.

Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run

openspec store list --json

to discover registered store ids, then pass

--store <id>

on the commands that read or write specs and changes (

new change

status

instructions

list

show

validate

archive

doctor

context

schemas

view

). Once selected, treat

--store <id>

as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run

openspec status --change "<name>" --json --store "<id>"

, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local

openspec/

root.

Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.

Steps

Understand the request and clarify material ambiguity

If no clear input is provided, ask the user (open-ended, no preset options):

"What change do you want to work on? Describe what you want to build or fix."
From their description, derive a kebab-case name (e.g., "add user authentication" →
```
add-user-auth
```
).
IMPORTANT: Do NOT proceed without understanding what the user wants to build.

If the request contains ambiguity that would materially affect scope, externally observable behavior, compatibility, or acceptance criteria, ask the user before creating the change. For minor details, make a reasonable assumption and record it in the planning artifacts.
Determine the workflow schema

Use the configured default schema unless the user explicitly requests a different workflow.

Use a different schema only if the user:
- Explicitly requests a specific schema by name → use
```
--schema <schema-name>
```
- Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running
```
openspec context --json
```
  from the current working directory. If the user explicitly selected a registered store, use
```
openspec context --json --store "<store-id>"
```
  . Then run
```
openspec schemas --json
```
  with its working directory set to the returned
```
root.path
```
  and let them choose. This preserves roots selected by a local
```
store:
```
  pointer or the global
```
defaultStore
```
  ; when a registered store was explicitly selected, append
```
--store "<store-id>"
```
  to
```
openspec schemas --json
```
  as well. If context reports only
```
no_openspec_root
```
  , run
```
openspec schemas --json
```
  from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
Otherwise, omit
```
--schema
```
to preserve the configured default.
Create the change directory
Choose one schema form below. If a registered store is selected, append
```
--store "<store-id>"
```
to that command and each later OpenSpec command shown below that accepts
```
--store
```
.
Using the configured default:
bash
```
openspec new change "<name>"
```
Using an explicitly requested schema:
bash
```
openspec new change "<name>" --schema "<schema-name>"
```
This creates a scaffolded change in the planning home resolved by the CLI with
```
.openspec.yaml
```
.
Get the artifact build order
bash
```
openspec status --change "<name>" --json
```
Parse the JSON to get:
- ```
applyRequires
```
  : array of artifact IDs needed before implementation (e.g.,
```
["tasks"]
```
  )
- ```
artifacts
```
  : list of all artifacts, each with its
```
status
```
  and its
```
requires
```
  edges (the artifact IDs it directly depends on)
- ```
planningHome
```
  ,
```
changeRoot
```
  ,
```
artifactPaths
```
  , and
```
actionContext
```
  : path and scope context. Use these instead of assuming repo-local paths.
Create every artifact in the required set

Use a todo list to track progress through the artifacts.

Loop through artifacts in dependency order (artifacts with no pending dependencies first):
a. For each artifact that is
ready
(dependencies satisfied):
- Get instructions:
  bash
```
openspec instructions <artifact-id> --change "<name>" --json
```
- The instructions JSON includes:
  - ```
  context
```
  : Project background (constraints for you - do NOT include in output)
- ```
rules
```
    : Artifact-specific rules (constraints for you - do NOT include in output)
  - ```
  template
```
  : The structure to use for your output file
- ```
instruction
```
    : Schema-specific guidance for this artifact type
  - ```
  skipped
```
  /
```
  warning
```
  : present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
- ```
resolvedOutputPath
```
    : Resolved path or pattern to write the artifact
  - ```
  dependencies
```
  : Completed artifacts to read for context
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
- If the
```
instruction
```
  field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at
```
resolvedOutputPath
```
- Otherwise create the artifact file using
```
template
```
  as the structure and write it to
```
resolvedOutputPath
```
  . If
```
resolvedOutputPath
```
  is a glob, follow
```
instruction
```
  to choose the concrete file path
- Apply
```
context
```
  and
```
rules
```
  as constraints - but do NOT copy them into the file
- Show brief progress: "Created <artifact-id>"
b. Continue until every artifact in the required set exists (not just
apply.requires
)
- After creating each artifact, re-run
```
openspec status --change "<name>" --json
```
- The required set is
```
applyRequires
```
  plus every artifact reachable from those by following the
```
requires
```
  edges in
```
status --json
```
  - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
- ```
status
```
  is file-existence only, so an
```
applyRequires
```
  artifact reading
```
done
```
  does NOT mean its dependencies exist - writing
```
tasks.md
```
  early marks
```
tasks
```
  done while
```
specs
```
  was never written. Use each artifact's
```
requires
```
  edges, not its
```
status
```
  , to build the required set: a
```
done
```
  artifact still lists what it depends on
- An artifact already reading
```
status: "skipped"
```
  is satisfied: the change declares
```
skip_specs
```
  in
```
.openspec.yaml
```
  , so its files must NOT exist. Never try to create one
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
- Skip one only when
```
status
```
  already reports it
```
skipped
```
  , or when its own
```
instruction
```
  says it is conditional: run
```
openspec instructions <artifact-id> --change "<name>" --json
```
  and skip only if its
```
instruction
```
  field marks it optional (e.g. "create only if..."). Spec-driven's
```
design.md
```
  qualifies;
```
specs
```
  qualifies only via the
```
skipped
```
  status above, never by your own judgment. Tell the user, and do not reconsider it
- Dependencies are enablers, not gates: if a required artifact is still
```
blocked
```
  only because you skipped a conditional dependency, write it anyway
- Stop when every artifact in the required set is
```
done
```
  ,
```
skipped
```
  , or was deliberately skipped
c. If an artifact requires user input (unclear context):
- Ask the user to clarify
- Then continue with creation
Show final status
bash
```
openspec status --change "<name>"
```

Output

After completing all artifacts, summarize:

Change name and location
List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
What's ready: "All artifacts needed for implementation are ready."
Prompt: "The artifacts are ready for review. When you are ready, run
```
/openspec-apply-change
```
or ask me to apply this change."

Artifact Creation Guidelines

Follow the
```
instruction
```
field from
```
openspec instructions
```
for each artifact type - it is the authoritative guidance, even for familiar artifact names
If the
```
instruction
```
field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
The schema defines what each artifact should contain - follow it
Read dependency artifacts for context before creating new ones
Use
```
template
```
as the structure for your output file - fill in its sections
IMPORTANT:
```
context
```
and
```
rules
```
are constraints for YOU, not content for the file
- Do NOT copy
```
<context>
```
  ,
```
<rules>
```
  ,
```
<project_context>
```
  blocks into the artifact
- These guide what you write, but should never appear in the output

Guardrails

The request that invoked this workflow authorizes planning only. Any implementation or apply instruction in that request does not carry forward. Do NOT implement the change, start the apply workflow, or edit project code during this workflow. After presenting the artifacts, stop and wait for a new user request to start the apply workflow
Create every artifact the apply phase transitively depends on, not just the ids listed in
```
apply.requires
```
Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
Ask about ambiguities that would materially change scope, externally observable behavior, compatibility, or acceptance criteria; for minor details, make reasonable assumptions and record them
If a change with that name already exists, ask if user wants to continue it or create a new one
Verify each artifact file exists after writing before proceeding to next

提出新变更——创建变更并一次性生成所有 artifacts。

规划边界：此工作流仅创建规划 artifacts。触发或选择此工作流的用户请求仅授权进行规划，即使请求中要求构建或修复某些内容也是如此。不要编辑项目代码。规划 artifacts 完成后即停止。不要在同一响应中开始实施，即使初始请求要求实施。请在展示 artifacts 后等待新的用户请求，然后再启动 apply 工作流。

我将按照你的 schema 定义创建一个包含相应 artifacts 的变更。在默认的 spec-driven schema 中，文件包括：

proposal.md（内容与原因）
```
specs/<capability-path>/spec.md
```
（系统必须执行的内容——增量规范，而不是主规范）
design.md（实现方式）
tasks.md（实施步骤）

<capability-path>

是相对于

specs/

的规范目录，例如

user-auth

或

identity/user-auth

。保留现有 capability 的完整路径，并为新 capability 遵循项目既定的组织结构。

准备好实施时，必须显式启动 apply 工作流。

Store 选择：如果你指定了某个 store（store 是注册在此机器上的独立 OpenSpec 仓库），或者工作位于某个 store 中，请运行

openspec store list --json

查找已注册的 store id，然后在读取或写入 specs 与 changes 的命令上传入

--store <id>

（

new change

、

status

、

instructions

、

list

、

show

、

validate

、

archive

、

doctor

、

context

、

schemas

、

view

）。选定后，在整个工作流的剩余步骤中持续使用

--store <id>

。以下所有未限定作用域的命令示例均为简写：运行前必须附加该标志。例如，应运行

openspec status --change "<name>" --json --store "<id>"

，而不是使用下面显示的未限定形式。其他命令不接受此标志。命令输出的提示已经包含该标志；后续操作应继续保留。如果没有 store，命令将作用于最近的本地

openspec/

根目录。

输入：用户请求应包含变更名称（kebab-case），或者包含对要构建内容的描述。

步骤

理解请求并澄清实质性歧义

如果没有提供明确输入，请向用户开放式提问，不要提供预设选项：

“你想进行什么变更？请描述你希望构建或修复的内容。”
根据用户描述推导出一个 kebab-case 名称（例如，“add user authentication” →
```
add-user-auth
```
）。
重要：在理解用户要构建什么之前，不要继续执行。

如果请求中的歧义会实质性影响范围、外部可观察行为、兼容性或验收标准，请在创建变更前询问用户。对于次要细节，可以作出合理假设，并将这些假设记录在规划 artifacts 中。
确定工作流 schema

除非用户明确要求使用其他工作流，否则使用已配置的默认 schema。

仅在以下情况下使用其他 schema：
- 用户明确按名称指定了特定 schema → 使用
```
--schema <schema-name>
```
- 用户要求“show workflows”或询问存在哪些“what workflows” → 从当前工作目录运行
```
openspec context --json
```
  ，解析权威根目录。如果用户明确选择了已注册的 store，请使用
```
openspec context --json --store "<store-id>"
```
  。然后将工作目录设置为返回的
```
root.path
```
  ，运行
```
openspec schemas --json
```
  ，让用户进行选择。这样可以保留由本地
```
store:
```
  指针或全局
```
defaultStore
```
  选择的根目录；当用户明确选择了已注册的 store 时，也必须为
```
openspec schemas --json
```
  附加
```
--store "<store-id>"
```
  。如果 context 仅报告
```
no_openspec_root
```
  ，则改为在当前工作目录运行
```
openspec schemas --json
```
  。对于无效或不可用的 store，不要使用此回退方案。
否则，省略
```
--schema
```
，以保留已配置的默认值。
创建变更目录
从下面的 schema 形式中选择一种。如果选择了已注册的 store，请为该命令及后续所有支持
```
--store
```
的 OpenSpec 命令附加
```
--store "<store-id>"
```
。
使用已配置的默认 schema：
bash
```
openspec new change "<name>"
```
使用用户明确指定的 schema：
bash
```
openspec new change "<name>" --schema "<schema-name>"
```
这会在 CLI 根据
```
.openspec.yaml
```
解析出的规划主目录中创建一个脚手架变更。
获取 artifacts 的生成顺序
bash
```
openspec status --change "<name>" --json
```
解析 JSON 以获取：
- ```
applyRequires
```
  ：实施前所需的 artifact ID 数组（例如
```
["tasks"]
```
  ）
- ```
artifacts
```
  ：所有 artifacts 的列表，每项包含其
```
status
```
  和
```
requires
```
  依赖边（该 artifact 直接依赖的 artifact ID）
- ```
planningHome
```
  、
```
changeRoot
```
  、
```
artifactPaths
```
  和
```
actionContext
```
  ：路径与作用域上下文。使用这些信息，不要假定仓库本地路径。
创建所需集合中的每个 artifact

使用待办列表跟踪 artifacts 的生成进度。

按依赖顺序循环处理 artifacts（先处理没有未满足依赖的 artifacts）：
a. 对于每个状态为
ready
的 artifact（依赖已满足）：
- 获取 instructions：
  bash
```
openspec instructions <artifact-id> --change "<name>" --json
```
- instructions JSON 包含：
  - ```
  context
```
  ：项目背景（供你遵守的约束——不要包含在输出中）
- ```
rules
```
    ：特定 artifact 的规则（供你遵守的约束——不要包含在输出中）
  - ```
  template
```
  ：输出文件应采用的结构
- ```
instruction
```
    ：此 schema 针对该 artifact 类型的指导信息
  - ```
  skipped
```
  /
```
  warning
```
  ：当变更声明了 skip_specs，且该 artifact 无需创建时出现——停止处理该 artifact 并选择另一个 artifact
- ```
resolvedOutputPath
```
    ：用于写入 artifact 的已解析路径或路径模式
  - ```
  dependencies
```
  ：可作为上下文读取的已完成 artifacts
- 读取任何已完成的依赖文件以获取上下文——始终从磁盘重新读取，即使之前已在对话中看到过，因为用户可能编辑过这些文件
- 如果
```
instruction
```
  字段指定使用特定 skill 或命令创建 artifact，则调用它来生成 artifact，而不是自行写入文件；随后验证 artifact 文件是否存在于
```
resolvedOutputPath
```
- 否则，以
```
template
```
  作为输出文件的结构，并将其写入
```
resolvedOutputPath
```
  。如果
```
resolvedOutputPath
```
  是 glob，请按照
```
instruction
```
  选择具体文件路径
- 将
```
context
```
  和
```
rules
```
  作为约束应用——但不要将其复制到文件中
- 显示简短进度：“已创建 <artifact-id>”
b. 持续执行，直到所需集合中的每个 artifact 都存在，而不只是满足
apply.requires
- 创建每个 artifact 后，重新运行
```
openspec status --change "<name>" --json
```
- 所需集合由
```
applyRequires
```
  加上从这些 artifacts 出发、沿
```
requires
```
  依赖边可传递到达的每个 artifact 组成——沿依赖关系进行传递遍历（spec-driven 会涵盖 proposal、specs、design 和 tasks）。不要处理该集合之外的 artifacts
- ```
status
```
  仅检查文件是否存在，因此
```
applyRequires
```
  中显示为
```
done
```
  的 artifact 并不意味着其依赖项已经存在——提前写入
```
tasks.md
```
  会将
```
tasks
```
  标记为
```
done
```
  ，即使从未写入
```
specs
```
  。请根据每个 artifact 的
```
requires
```
  依赖边构建所需集合，而不是根据其
```
status
```
  ；显示为
```
done
```
  的 artifact 仍会列出它所依赖的内容
- 显示为
```
status: "skipped"
```
  的 artifact 已视为满足要求：变更已在
```
.openspec.yaml
```
  中声明
```
skip_specs
```
  ，因此其文件不应存在。绝不要尝试创建此类 artifact
- 创建所需集合中每个缺失的 artifact，然后重新检查——创建一个 artifact 后可能会解除其他 artifacts 的阻塞状态
- 仅当
```
status
```
  已报告该 artifact 为
```
skipped
```
  ，或其自身
```
instruction
```
  明确说明它是条件性 artifact 时，才可跳过：运行
```
openspec instructions <artifact-id> --change "<name>" --json
```
  ，仅当
```
instruction
```
  字段标记其为可选时才跳过（例如“create only if...”）。Spec-driven 的
```
design.md
```
  符合此条件；
```
specs
```
  只有在上述
```
status
```
  为
```
skipped
```
  时才可跳过，绝不能凭自己的判断跳过。告知用户，并且不要重新考虑该决定
- 依赖项是促进项，而不是门禁项：如果某个所需 artifact 仍显示为
```
blocked
```
  ，原因仅仅是跳过了一个条件性依赖项，仍应写入该 artifact
- 当所需集合中的每个 artifact 都为
```
done
```
  、
```
skipped
```
  或已被有意跳过时停止
c. 如果某个 artifact 需要用户输入（上下文不明确）：
- 请求用户澄清
- 然后继续创建
显示最终状态
bash
```
openspec status --change "<name>"
```

输出

完成所有 artifacts 后，汇总：

变更名称和位置
已创建 artifacts 的列表及其简要说明，以及跳过的任何条件性 artifact 及其原因
当前就绪状态：“实施所需的所有 artifacts 均已就绪。”
提示：“artifacts 已准备就绪，可供审阅。准备好后，运行
```
/openspec-apply-change
```
或让我应用此变更。”

Artifact 创建指南

遵循
```
openspec instructions
```
中每个 artifact 类型对应的
```
instruction
```
字段——即使 artifact 名称很熟悉，它也是权威指导信息
如果
```
instruction
```
字段指定使用特定 skill 或命令创建 artifact，请调用它，而不是直接写入 artifact
Schema 定义了每个 artifact 应包含的内容——请遵循 schema
创建新 artifact 前，读取依赖 artifacts 以获取上下文
使用
```
template
```
作为输出文件的结构，并填写其中的各个部分
重要：
```
context
```
和
```
rules
```
是给你的约束，而不是文件内容
- 不要将
```
<context>
```
  、
```
<rules>
```
  、
```
<project_context>
```
  区块复制到 artifact 中
- 它们用于指导你编写内容，但绝不应出现在输出中

防护规则

触发此工作流的请求仅授权进行规划。该请求中的任何实施或 apply 指令都不会延续到下一阶段。在此工作流期间，不要实施变更、不要启动 apply 工作流，也不要编辑项目代码。展示 artifacts 后即停止，并等待新的用户请求来启动 apply 工作流
创建 apply 阶段通过依赖关系传递依赖的每个 artifact，而不只是
```
apply.requires
```
中列出的 ID
创建新 artifact 前始终读取依赖 artifacts——从磁盘重新读取，而不是依赖对话记忆，因为文件可能自上次读取后已发生变化
对于会实质性改变范围、外部可观察行为、兼容性或验收标准的歧义，应向用户询问；对于次要细节，可以作出合理假设并记录在案
如果已存在同名变更，询问用户是要继续该变更还是创建一个新变更
写入后验证每个 artifact 文件是否存在，然后再继续处理下一个 artifact