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

提出新变更——创建变更并一步生成所有工件。

规划边界：本工作流仅创建规划工件。触发本工作流的用户请求仅授权开展规划工作，即便请求中要求构建或修复某项内容也不例外。请勿编辑项目代码。规划工件完成后即停止操作，不要在同一次响应中启动实施，即便初始请求有此要求。在展示工件后等待用户的新请求，再启动应用工作流。

我将创建一个包含您的schema所定义的所有工件的变更。对于默认的规格驱动schema，工件包括：

proposal.md（内容与背景）
```
specs/<capability-path>/spec.md
```
（系统必须实现的功能——为增量内容，而非主规格说明）
design.md（实现方式）
tasks.md（实施步骤）

<capability-path>

是相对于

specs/

的规格目录（例如

user-auth

或

identity/user-auth

）。对于现有能力，保留其完整路径；对于新能力，遵循项目已有的组织规范。

当用户准备好实施时，必须显式启动应用工作流。

存储库选择：如果用户指定了store（store是注册在本机上的独立OpenSpec仓库），或者工作内容位于某个store中，请运行

openspec store list --json

获取已注册的store ID，然后在所有读写规格和变更的命令（

new change

、

status

、

instructions

、

list

、

show

、

validate

、

archive

、

doctor

、

context

、

schemas

、

view

）中传入

--store <id>

参数。一旦选定store，在工作流剩余步骤中

--store <id>

将保持生效。下文所有未限定范围的命令示例均为简写：运行前请追加该参数。例如，应运行

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

，而非下文所示的未限定范围的形式。其他命令不接受该参数。命令输出的提示信息已携带该参数时，后续操作请保留该参数。若未指定store，命令将作用于最近的本地

openspec/

根目录。

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

步骤

理解需求并澄清重大歧义

如果未提供明确输入，请向用户提问（开放式问题，不提供预设选项）：

“您想要处理什么变更？请描述您想要构建或修复的内容。”
根据用户的描述，生成一个kebab-case格式的名称（例如，“添加用户认证” →
```
add-user-auth
```
）。
重要提示：在未理解用户待构建内容之前，请勿继续操作。

如果请求中存在会对范围、外部可观测行为、兼容性或验收标准产生重大影响的歧义，请在创建变更前向用户澄清。对于次要细节，可做出合理假设并记录在规划工件中。
确定工作流schema

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

仅当用户出现以下情况时才使用其他schema：
- 明确通过名称指定了某个schema → 使用
```
--schema <schema-name>
```
- 要求“展示工作流”或询问“存在哪些工作流” → 从当前工作目录运行
```
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
```
解析出的规划主目录中创建一个脚手架化的变更。
获取工件构建顺序
bash
```
openspec status --change "<name>" --json
```
解析JSON以获取：
- ```
applyRequires
```
  ：实施前所需的工件ID数组（例如
```
["tasks"]
```
  ）
- ```
artifacts
```
  ：所有工件的列表，每个工件包含其
```
status
```
  和
```
requires
```
  边（即它直接依赖的工件ID）
- ```
planningHome
```
  、
```
changeRoot
```
  、
```
artifactPaths
```
  和
```
actionContext
```
  ：路径与范围上下文。请使用这些值，而非假设仓库本地路径。
创建所需集合中的所有工件

使用待办列表跟踪工件创建进度。

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

输出

完成所有工件后，请总结以下内容：

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

工件创建指南

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

防护规则

调用本工作流的请求仅授权开展规划工作。该请求中的任何实施或应用指令均不生效。在本工作流期间，请勿实施变更、启动应用工作流或编辑项目代码。展示工件后即停止，等待用户的新请求以启动应用工作流
创建应用阶段传递依赖的所有工件，而不仅仅是
```
apply.requires
```
中列出的ID
创建新工件前务必读取依赖工件——从磁盘重新读取，而非依赖对话记忆（文件可能自你上次查看后已发生更改）
对于会对范围、外部可观测行为、兼容性或验收标准产生重大影响的歧义，应向用户询问；对于次要细节，做出合理假设并记录下来
如果同名变更已存在，询问用户是要继续该变更还是创建新变更
写入每个工件文件后，验证其存在再继续下一步