# Rune

基于 SDD（Spec-Driven Development）的命令行工具，通过向 AI 开发工具注入 command 和 skill，驱动结构化编码流程。

## 安装

```bash
bunx rune init opencode
```

## 使用

### 初始化

```bash
bunx rune init opencode          # OpenCode 编辑器
bunx rune init claude-code       # Claude Code 编辑器
```

会在项目中创建：
- `.rune/` 目录（配置、变更文档、归档）
- 编辑器对应的 command 和 skill 文件（如 `.opencode/commands/`、`.opencode/skills/`）

### 更新编辑器配置

当 Rune 版本升级后，需要更新已注入的命令和 skill 文件：

```bash
bunx rune update opencode        # 更新 OpenCode 的命令和 skill
bunx rune update claude-code     # 更新 Claude Code 的命令
```

更新策略：对比文件内容，不一致则用内置版本覆盖；不存在则新建。

### SDD 流程

SDD 工作流包含固定的四个阶段，不可自定义增删：

1. **讨论阶段** — `/rune-discuss`：与 AI 自由讨论需求和方案。讨论结果保留在 AI 会话上下文中传递到后续阶段，不持久化到文件。结束前会引导是否进入规划阶段。
2. **规划阶段** — `/rune-plan <变更名> <文档名>`：按配置的文档模板生成规划文档。变更名仅支持中文、英文和短横线（`-`）。默认包含 `design`（设计文档）和 `task`（任务清单，依赖 design）两个文档。文档间支持 `depend` 字段声明前置依赖，依赖未满足时有友好提示。plan 命令自身不写入文件，只输出提示词供 AI 消费。
3. **构建阶段** — `/rune-build <变更名>`：按 task.md 中的任务顺序逐个实现。每个任务完成后更新对应的 checkbox 为 `[x]`。可多次执行直到所有任务完成。
4. **归档阶段** — `/rune-archive <变更名>`：将变更目录移至 `archive/`。归档前自动检查 task.md 的完成状态，如有未完成任务会注入警告提示词，引导 AI 询问用户是否确认归档。

### 状态查看

```bash
rune status              # 查看所有变更（含各阶段文档完成状态、下一步建议）
rune status <变更名>     # 查看指定变更的详细状态
```

规划阶段应引导 AI 先通过 `rune status` 获取当前有哪些文档需要编写。

### 命令参考

```bash
rune help                # 显示全局帮助
rune help <command>      # 显示指定命令的详细帮助
rune version             # 显示版本号
```

| 命令 | 说明 |
|------|------|
| `rune init <tool>` | 初始化项目，注入编辑器配置 |
| `rune update <tool>` | 更新编辑器的命令和 skill 文件 |
| `rune discuss` | 输出讨论阶段提示词 |
| `rune plan <变更名> <文档名>` | 输出规划阶段提示词 |
| `rune build <变更名>` | 输出构建阶段提示词 |
| `rune archive <变更名>` | 输出归档阶段提示词，同时移动变更目录到 archive/ |
| `rune status [变更名]` | 显示变更状态和下一步建议 |

### 自定义配置

编辑 `.rune/config.yaml` 自定义各阶段的提示词和文档模板。配置合并采用阶段级别全量覆盖策略：自定义某个阶段时需完整重写该阶段的配置，未配置的阶段使用内置默认配置。

规划阶段的文档支持 `depend` 字段声明前置依赖，如 `task` 依赖 `design`：

```yaml
stages:
  plan:
    documents:
      - name: design
        prompt: 生成设计文档，包含背景、目标、方案、接口和注意事项
      - name: task
        prompt: 生成任务清单，将设计拆分为可独立执行的小任务
        depend: [design]
```

计划阶段文档模板支持 `{{change-name}}` 变量，运行时会替换为实际变更名。

## 设计决策

- **四阶段固定**：discuss → plan → build → archive 不可自定义增删
- **配置覆盖策略**：阶段级别全量覆盖，不支持字段级合并
- **讨论结果不持久化**：完全依赖 AI 会话上下文传递
- **plan 不写文件**：plan 命令只输出提示词，由 AI 负责写入文档
- **变更名限制**：仅支持中文、英文、短横线（`-`）
- **同一变更名同天多次归档**：依靠日期+变更名去重，不做冲突处理
- **无跨变更依赖**：变更之间完全独立
- **无并发锁**：同一变更可被多个 AI agent 同时操作
- **无变更废弃命令**：用户手动删除 `.rune/changes/<变更名>/` 目录即可

## 开发

```bash
bun test          # 运行测试
bun src/cli.ts    # 运行 CLI
```