---
name: planning-propose
description: 创建变更提案。生成 proposal + specs + design + tasks 全套工件。融合 OpenSpec propose + brainstorming 前置验证。
---

# 变更提案 (Propose)

创建完整的变更提案，包含所有规划工件。

**规划边界**: 此工作流只创建规划工件。即使用户要求构建，也不要在此阶段开始实现。等工件完成后，等待新的用户请求来启动 apply 工作流。

## 前置条件

- 已完成 `explore` 技能（或已有明确的需求描述）

## 输入

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

## 流程

### 1. 理解请求并澄清歧义
如果未提供明确输入，询问用户：
> "你想要做什么变更？描述你想要构建或修复的内容。"

从描述中派生 kebab-case 名称（如 "add user authentication" → `add-user-auth`）。

**重要**: 不要在理解用户想要什么之前继续。
如果请求包含会实质性影响范围的歧义，先询问用户。

### 2. 确定工作流 Schema

使用配置的默认 Schema（spec-driven），除非用户明确要求不同的工作流。

### 3. 创建变更目录

```bash
specpow propose <name>
```

或手动创建：
```
openspec/changes/<name>/
├── proposal.md
├── specs/
│   └── <capability>/spec.md
├── design.md (可选，小变更可跳过)
└── tasks.md
```

### 4. 获取工件构建顺序

```bash
specpow status --change <name> --json
```

解析 JSON 获取：
- `applyRequires`: 实施前需要的工件 ID 数组
- `artifacts`: 所有工件列表，含状态和依赖关系

### 5. 按依赖顺序创建每个工件
使用 todo 列表跟踪进度。
按依赖顺序循环（无待处理依赖的工件优先）。

#### a. 对于每个 `ready` 状态的工件：
1. 获取指令：
   ```bash
   specpow instructions <artifact-id> --change <name> --json
   ```

2. 指令 JSON 包含：
   - `context`: 项目背景（约束，不要复制到输出中）
   - `rules`: 工件特定规则（约束，不要复制到输出中）
   - `template`: 输出文件的结构
   - `instruction`: Schema 特定指导
   - `resolvedOutputPath`: 输出路径

3. 读取已完成的依赖文件获取上下文（总是从磁盘重新读取）

4. 使用 `template` 作为结构创建工件文件

5. 应用 `context` 和 `rules` 作为约束 — 但不要复制到文件中

#### b. 继续直到所有必需工件都存在：
- 创建每个工件后，重新运行 `specpow status`
- 必需集合 = `applyRequires` 加上所有传递依赖
- 跳过仅在 `status` 报告为 `skipped` 时的工件

### 6. 显示最终状态
```bash
specpow status --change <name>
```

## 工件创建指南

### proposal.md
- 回答：为什么做？解决什么？成功标准？
- 包含影响范围和非目标

### specs/<capability>/spec.md
- 使用 Delta 格式：ADDED/MODIFIED/REMOVED/RENAMED
- 规范是行为契约，不是实现计划
- 每个需求必须可验证（Given/When/Then）

### design.md
- 架构决策（ADR 格式）
- 模块划分和接口定义
- 数据模型
- 小变更可跳过

### tasks.md
- 每个任务 2-5 分钟
- 包含精确文件路径
- 包含完整代码或明确修改指令
- 包含验证步骤
- 任务之间尽量独立
- 使用 YAML Frontmatter 格式（推荐）：

```yaml
---
tasks:
  - number: 1
    title: <任务标题>
    files:
      - path/to/file.ts
    description: |
      <精确的实现指令>
    verification: <验证步骤>
    dependsOn: []
    estimatedEffort: S  # S | M | L
---
```

## 输出

完成后总结：
- 变更名称和位置
- 创建的工件列表
- "实施所需的所有工件已就绪。"
- 提示："工件已准备好审核。准备好后，运行 `/apply-change` 或让我应用此变更。"

## 护栏

- 此工作流只授权规划。不要实现变更
- 创建工件前总是读取依赖工件
- 询问会实质性改变范围的歧义
- 验证每个工件文件存在后再继续

## 合理化防御表

| 借口 | 现实 |
|------|------|
| "我可以直接开始编码" | 没有规划就编码 = 返工 |
| "规范太正式了" | 规范是对齐工具，不是官僚主义 |
| "任务列表没必要" | SDD 引擎需要精确的任务定义 |
| "设计文档太重量级" | 小变更可以跳过，大变更不行 |