name	openspec-propose
description	为 QuantAgent 创建新的 OpenSpec change，并一次性生成可评审、可校验、可实施的 proposal、design、specs 和 tasks。用户要求提 proposal、创建 change、生成 OpenSpec、规划行为/架构/契约变更时使用。
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.3.1"}

为新的 change 生成 OpenSpec artifacts。默认输出中文正文，同时保留 OpenSpec CLI 必需的英文结构关键字。

需要生成的 artifacts：

proposal.md：为什么现在做、改什么、范围和非目标。
design.md：如何落地、边界、数据流、失败路径和验证。
specs/**/spec.md：可校验的行为需求和场景。
tasks.md：按依赖拆分的实施任务。

准备实现时再使用 openspec-apply-change。

输入: 用户请求应包含 kebab-case change name，或清楚描述要构建/修复的内容。

QuantAgent 质量门槛: 生成 artifacts 前必须读取直接相关的项目真源：

AGENTS.md 和受影响路径最近层级的 AGENTS.md。
用户或任务引用的 docs/design/*.md、docs/prd/*.md、既有 openspec/changes/*、issue 评论和 PR 讨论。
.agents/skills/references/engineering-quality-gate.md.
.agents/skills/references/openspec-chinese-artifact-gate.md.
涉及 apps/web/** 时读取 .agents/skills/references/web-architecture-gate.md。
Web 变更涉及 feature 结构、复杂 route、shared 能力或文件拆分时读取 .agents/skills/references/web-file-responsibility-and-feature-structure.md。
涉及 apps/api/** 时读取 .agents/skills/references/api-architecture-gate.md。
涉及 packages/core/**、packages/plugin-sdk/** 或 plugins/** 时读取 .agents/skills/references/core-and-plugin-architecture-gate.md。

生成的 artifacts 必须具体到能指导实现，不要产出泛泛的 proposal/design/tasks。凡是影响架构、行为、契约、前端 UI、后端 service、持久化、权限或审计的 change，都必须记录目录/文件规划、分层架构、职责、核心模型、API/DTO/schema/event/config/database 字段草案、复用点、数据流、失败路径和验证入口。

Web 变更必须显式应用 web-architecture-gate.md：route 边界、app runtime 所有权、apiClient -> BaseApi -> FeatureApi、TanStack Query hooks、业务 hooks、view components、README / usage notes、中文注释和目录分组。复杂 Web feature 还必须应用 web-file-responsibility-and-feature-structure.md，让 design.md 和 tasks.md 写出具体目标文件及职责。不要把这些判断留给实现阶段临场决定。

中文 OpenSpec 门槛: 写 artifacts 前必须读取 .agents/skills/references/openspec-chinese-artifact-gate.md。Artifact 正文默认中文，但 OpenSpec 语法标记保留英文：ADDED/MODIFIED/REMOVED/RENAMED Requirements、Requirement、Scenario、SHALL、MUST、WHEN、THEN、AND、FROM:、TO:。生成或大幅更新 change 后运行 openspec validate <name> --type change --strict --json，失败则回改 artifacts 直到通过或说明真实阻塞。

步骤

如果输入不清楚，先问要做什么

询问：

“你想创建哪个 change？请描述要构建或修复的内容。”

从描述中推导 kebab-case name，例如“增加用户认证” -> add-user-auth。

重要：没有理解目标前不要继续。
读取 QuantAgent 真源上下文

只读取与本轮直接相关的质量门槛和项目真源。至少包括：
- Root AGENTS.md
- The nearest AGENTS.md for affected app/package/plugin paths
- .agents/skills/references/engineering-quality-gate.md
- .agents/skills/references/openspec-chinese-artifact-gate.md
- .agents/skills/references/web-architecture-gate.md when affected paths or requested scope involve apps/web/**
- .agents/skills/references/web-file-responsibility-and-feature-structure.md when a Web change needs feature structure or file splitting decisions
- .agents/skills/references/api-architecture-gate.md when affected paths involve apps/api/**
- .agents/skills/references/core-and-plugin-architecture-gate.md when affected paths involve packages/core/**, packages/plugin-sdk/**, or plugins/**
- Related design/PRD/OpenSpec/issue/PR context named by the user or required by the affected boundary
如果上下文冲突，把冲突和取舍写入 artifacts，不要静默选择。
创建 change 目录
```
openspec new change "<name>"
```
该命令会在 openspec/changes/<name>/ 创建带 .openspec.yaml 的 scaffold。
获取 artifact 生成顺序
```
openspec status --change "<name>" --json
```
解析 JSON，获取：
- applyRequires：实现前必须完成的 artifact id 列表，例如 ["tasks"]。
- artifacts：所有 artifacts 的状态和依赖。
按顺序创建 artifacts，直到达到 apply-ready

按依赖顺序遍历 artifacts（先处理没有未完成依赖的 artifact）：

a. 对每个 ready artifact（依赖已满足）：
- 获取 instructions：
```
openspec instructions <artifact-id> --change "<name>" --json
```
- instructions JSON 包含：
  - context：项目背景，只作为约束，不复制到输出。
  - rules：artifact 专属规则，只作为约束，不复制到输出。
  - template：输出文件结构。
  - instruction：该 artifact 类型的 schema 指引。
  - outputPath：artifact 写入路径。
  - dependencies：需要读取的已完成依赖 artifacts。
- 读取已完成的依赖文件作为上下文。
- 用 template 作为结构创建 artifact 文件。
- 应用 .agents/skills/references/openspec-chinese-artifact-gate.md：
  - 正文默认中文。
  - OpenSpec 结构关键字保留英文。
  - specs/**/spec.md 使用合法 delta sections 和 4 个 # 的 #### Scenario:。
  - ADDED 和 MODIFIED requirement 正文包含 SHALL 或 MUST。
  - scenario 行保留 WHEN / THEN / AND 标签。
- 应用 .agents/skills/references/engineering-quality-gate.md：
  - proposal.md must cover why now, current gap, non-goals, and risk boundary.
  - design.md must be an implementation blueprint covering directory/file planning, layered architecture, module responsibilities, core models, DTO/schema/API/event/config/database field drafts, data flow, failure paths, reuse decisions, and validation strategy.
  - specs/**/spec.md must describe verifiable requirements and scenarios, not implementation chores.
  - tasks.md must show dependencies, parallel boundaries, write scopes, review gates, and validation actions.
- Web 变更应用 .agents/skills/references/web-architecture-gate.md，让 design.md 和 tasks.md 写清 route、runtime/API、query/mutation、business hook、component、README、comment 和 validation 边界。
- 复杂 Web feature 应用 .agents/skills/references/web-file-responsibility-and-feature-structure.md，让 artifacts 写清具体 route、api、contracts、query keys、queries、mutations、hooks、components、types、utils 和 README 文件。
- API 变更应用 .agents/skills/references/api-architecture-gate.md，让 design.md 和 tasks.md 写清 router、service、repository、DTO/envelope、DB operations、caching、concurrency、error handling 和 audit 边界。
- Core/Plugin 变更应用 .agents/skills/references/core-and-plugin-architecture-gate.md，让 design.md 和 tasks.md 写清 package 依赖方向、plugin layers、DTO contracts、Registry 边界、ORM/Repository 和 performance 边界。
- 把 context 和 rules 作为约束使用，但不要复制进 artifact 文件。
- Show brief Chinese progress: 已创建 <artifact-id>
b. 持续创建，直到所有 applyRequires artifacts 完成
- 每创建一个 artifact 后重新运行 openspec status --change "<name>" --json。
- 检查 applyRequires 中每个 artifact id 在 artifacts 数组里都是 status: "done"。
- 所有 applyRequires 完成后停止。
c. 如果 artifact 需要用户输入（关键上下文不清楚）：
- 先向用户确认
- 然后继续创建。
校验并展示最终状态
```
openspec validate <name> --type change --strict --json
openspec status --change "<name>"
```
如果校验失败，先修 artifacts 并重复校验，直到通过或确认存在真实阻塞。

输出

完成后用中文总结：

change name 和位置
已创建 artifacts 及用途
strict validate 结果
是否已准备进入实现

Artifact 创建规则

遵守 openspec instructions 返回的 instruction 字段。
schema 决定 artifact 应包含什么，不能自创结构。
创建新 artifact 前先读取依赖 artifacts。
用 template 作为输出结构，并填充各 section。
保留模板中的英文 OpenSpec 语法，但把 placeholder 正文改写为中文。
重要：context 和 rules 是写作约束，不是文件内容。
不要把 <context>、<rules>、<project_context> 块复制进 artifact。
这些内容只指导写作，不应出现在输出文件里。

护栏

创建 schema apply.requires 定义的全部实现前置 artifacts。
创建新 artifact 前必须读取依赖 artifacts。
关键上下文不清楚时向用户确认；非关键细节优先做合理判断保持推进。
同名 change 已存在时，先确认是继续该 change 还是换名新建。
写入后确认 artifact 文件实际存在，再处理下一个。
报告完成前运行 openspec validate <name> --type change --strict --json。