@gordon.gan/specflow 1.0.0

package/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 bstzyf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package incorporates content derived from the following MIT-licensed projects:
+
+- OpenSpec (https://github.com/Fission-AI/OpenSpec) — Copyright (c) Fission-AI
+- Superpowers (https://github.com/obra/superpowers) — Copyright (c) Jesse Vincent
+
+Portions of this codebase were adapted and rewritten from those projects.
+See `<!-- SOURCE: ... -->` comments in prompt files for specific attribution.

package/README.md

@@ -0,0 +1,442 @@
+# SpecFlow
+
+[![npm version](https://img.shields.io/npm/v/specflow.svg)](https://www.npmjs.com/package/specflow)
+[![npm downloads](https://img.shields.io/npm/dm/specflow.svg)](https://www.npmjs.com/package/specflow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**一句话：plan 想清楚，refine 打磨透，build 做到位，done 归档好。**
+
+> Cursor 用户可直接参考：`CURSOR_PACKAGING_AND_USAGE_GUIDE.md`  
+> Codex 用户可直接参考：`CODEX_PACKAGING_AND_USAGE_GUIDE.md`
+
+SpecFlow 把两个开源框架合并成一个工具：
+- **OpenSpec** — 结构化需求规划（proposal → specs → design → tasks）
+- **Superpowers** — 工程执行纪律（TDD、系统化调试、代码审查、subagent 编排）
+
+一个 CLI + 一套跨 IDE 工作流技能（Claude Code / Cursor / Codex），覆盖从「扫描代码库」到「归档上线」的完整开发生命周期。
+
+---
+
+## 前置依赖
+
+- **Node.js ≥ 20.19.0**（`node --version` 检查）
+- **Git**（用于 build 的 worktree 和 done 的分支管理）
+- **AI 编码环境（任选其一或组合）**
+  - **Claude Code** — `/specflow:*` 斜杠命令
+  - **Cursor** — `specflow:*` 命令（见 Cursor 指南）
+  - **OpenAI Codex** — `$specflow-*` 技能（见 Codex 指南）
+
+---
+
+## 安装
+
+### 方式 1：从 npm 全局安装（推荐，发布后可用）
+
+```bash
+npm install -g specflow
+```
+
+### 方式 2：从 GitHub 直接安装（发布前/最新代码）
+
+```bash
+npm install -g github:Gordon-Gan-Jiang/specflow
+```
+
+### 方式 3：本地源码安装（开发者 / 贡献者）
+
+```bash
+git clone https://github.com/Gordon-Gan-Jiang/specflow.git
+cd specflow
+npm install
+npm run build
+npm link
+```
+
+使用 `npm link` 后，在源码里改代码 → 重新 `npm run build` → 全局的 `specflow` 命令立即生效（符号链接）。
+
+### 方式 4：通过本地 tarball 分发
+
+在有源码的机器上打包：
+```bash
+npm run build
+npm pack          # 生成 specflow-0.2.2.tgz
+```
+在目标机器上安装：
+```bash
+npm install -g ./specflow-0.2.2.tgz
+```
+
+### 验证安装
+
+```bash
+specflow --version   # 应输出 0.2.2
+specflow --help
+```
+
+### 卸载
+
+```bash
+npm uninstall -g specflow
+# 如果用的是 npm link：
+npm unlink -g specflow
+```
+
+---
+
+## 在项目中使用
+
+### 初始化（每个项目一次）
+
+```bash
+cd your-project
+specflow init              # 默认：Claude + Cursor（--ide both）
+specflow init --ide codex  # 仅 Codex
+specflow init --ide all    # Claude + Cursor + Codex
+```
+
+这一步会：
+- 创建 `specflow/` 目录（存放 specs 和 changes）
+- 写入 `specflow/config.yaml`（项目上下文）
+- 按 `--ide` 生成对应托管资产：
+  - **Claude**：`.claude/skills/`、`.claude/commands/specflow/`、`.claude/specflow/`
+  - **Cursor**：`.cursor/skills/`、`.cursor/commands/specflow/`、`.cursor/rules/`、`.cursor/specflow/`
+  - **Codex**：`.agents/skills/`、`.agents/specflow/`、`AGENTS.md` 上下文块
+- **自动追加** `.gitignore`，忽略可再生的 prompts/schemas/templates（幂等，不覆盖已有内容）
+
+init 后：
+- Claude Code：斜杠命令 `/specflow:*` 立即可用
+- Cursor：命令 `specflow:*` 立即可用
+- Codex：技能 `$specflow-*` 立即可用
+
+### 重新初始化
+
+```bash
+# 删掉后重新跑 init
+rm -rf specflow/config.yaml .claude/specflow/
+specflow init
+```
+
+（init 检测到已初始化会拒绝运行，避免误覆盖）
+
+---
+
+## 核心流程
+
+**每阶段深度思考 → 多轮迭代精化**：每个阶段一次性产出实质内容（非占位骨架），再通过内部多轮迭代把 artifact 精化到稳态，最后进入执行。
+
+```
+/specflow:scan    [规划中 · v0.3] 扫描已有代码生成 specs 基线；当前请直接用 /specflow:plan 描述已有行为
+       ↓
+/specflow:plan    一次产出 4 个 artifact：proposal + delta specs + design + tasks（first-iteration 深度思考，非纯骨架）
+       ↓
+/specflow:refine  内部多轮精化循环（≥2 rounds，AI 收敛判定，不设上限）
+                   每轮攻击性审查 + 4 个挑战行为：
+                     · 挑战假设   · 提新 options
+                     · 探边界     · 质疑 scope
+                   可更新任意 artifact（proposal / specs / design / tasks）
+       ↓
+/specflow:build   Phase A：基于 refine 稳定后的 artifact，用 writing-plans 严格精化（rewrite）tasks.md
+                   Phase B：逐任务 TDD 执行（subagent 模式）
+                   design 有漏即停，回 refine 补齐
+       ↓
+/specflow:review  代码审查（对照 specs 检查回归）
+       ↓
+/specflow:test    全量测试（单元 + 集成 + E2E + 回归）
+       ↓
+/specflow:verify  双重校验（delta specs 验收 + 主 specs 回归）
+       ↓
+/specflow:done    归档变更 → specs 合并 → git 分支清理
+                   默认要求 phase=built，可用 --force 跳过
+```
+
+另外两个快捷命令：
+```
+/specflow:fix     修 Bug 一条龙（调试 → TDD 修复 → 自动归档）
+/specflow:snap    事后补档（从 git diff 反推变更记录）
+```
+
+### 新机制（v0.2.0）
+
+- **plan 一次产出 4 artifact**：proposal、delta specs、design、tasks 同步生成，每个都是实质的"第一轮深度思考"（first-iteration），不再是占位骨架
+- **refine 内部多轮循环**：至少 2 轮，AI 语义判断收敛，不设上限；每轮显式执行 4 个挑战行为（挑战假设 / 提新 options / 探边界 / 质疑 scope）；可更新任意 artifact
+- **build Phase A 改为 rewrite**：不再是"生成" tasks.md，而是基于 refine 稳定后的 artifact 用 Superpowers writing-plans 严格规则"精化"重写；发现 design 缺漏即停并回 refine
+- **`.specflow.yaml` 新增 `phase` 字段**：追踪变更生命周期（`plan` / `refined` / `built` / `archived`）；`specflow change archive` 默认要求 `phase=built`，可用 `--force` 跳过守门
+
+---
+
+## 快速上手示例
+
+### 5 分钟跑通全流程
+
+```bash
+# 1. 安装（任选一种）
+npm install -g specflow
+
+# 2. 进入你的项目
+cd my-project
+
+# 3. 初始化
+specflow init
+
+# 4. 打开 Claude Code，在会话里输入：
+/specflow:plan "给用户管理模块加个批量导入功能"
+```
+
+Claude Code 接下来会：
+1. 读 `.claude/skills/specflow-plan/SKILL.md` 编排器
+2. 问你几个澄清问题（一次一个）
+3. 生成 `specflow/changes/bulk-import/proposal.md`
+4. 展示 proposal 等你**确认**
+5. 确认后生成 delta specs `specs/*/spec.md`
+6. 提示你下一步是 `/specflow:refine`
+
+### 更完整的示例（4 个场景）
+
+#### 场景 1：新项目从零开始
+
+```
+/specflow:plan "添加用户注册和登录功能"
+/specflow:refine           # 讨论技术方案，输出 design.md
+/specflow:build            # TDD 实现，每任务用户确认
+/specflow:review           # 代码审查
+/specflow:test             # 跑测试
+/specflow:verify           # 对照 specs 验收
+/specflow:done             # 归档 + merge
+```
+
+#### 场景 2：接手已有项目（v0.2.x 工作流）
+
+```bash
+cd legacy-project
+specflow init
+
+# 在 Claude Code 里：
+# 注意：/specflow:scan 当前规划在 v0.3，未实现。
+# v0.2.x 的推荐做法是直接进 plan，在 proposal Q&A 里描述已有行为 +
+# 新增变更，让 plan 为将要改动的 capability 生成 delta spec 基线。
+/specflow:plan "描述已有行为 + 你这次要改的新功能"
+/specflow:refine             # 对 plan 产出做 ≥2 轮攻击性审查
+/specflow:build              # Phase A 重写 tasks.md → Phase B TDD
+/specflow:done               # 归档，delta spec 合入主 specs/
+```
+
+#### 场景 3：紧急修 Bug
+
+```
+/specflow:fix "登录接口在 token 过期时返回 500 而不是 401"
+```
+
+一条命令包含：
+1. 自动创建轻量变更
+2. 定位相关 specs（对照规格理解预期行为）
+3. 系统化调试（4 步法：调查 → 模式 → 假设 → 验证）
+4. TDD 修复（先写复现测试让它红，再修代码让它绿）
+5. 自动代码审查
+6. 跑测试
+7. 归档
+
+紧急模式跳过审查：
+```
+/specflow:fix --urgent "生产环境崩溃"
+```
+
+#### 场景 4：同事改了代码没走流程，事后补档
+
+```
+/specflow:snap "重构了认证模块"
+```
+
+分析 git diff + git log，反推完整变更记录，推断受影响的 specs，用户确认后自动归档。
+
+---
+
+## 命令速查
+
+### Claude Code 技能命令（在 Claude Code 会话里用）
+
+| 命令 | 说明 |
+|---|---|
+| `/specflow:scan` | **[规划中 · v0.3]** 扫描已有代码库生成 specs 基线；v0.2.x 未实现，触发时 skill 会提示替代方案 |
+| `/specflow:plan` | 需求规划：生成 proposal + delta specs |
+| `/specflow:refine` | 技术方案探讨（brainstorming + design.md） |
+| `/specflow:build` | 两阶段构建：生成计划 → subagent TDD 执行 |
+| `/specflow:review` | 代码审查（含 specs 回归检查） |
+| `/specflow:test` | 全量测试 + 验证（单元/集成/E2E/回归） |
+| `/specflow:verify` | 双重校验：delta specs 验收 + 主 specs 回归 |
+| `/specflow:done` | 归档变更 + specs 合并 + git 分支清理 |
+| `/specflow:fix` | 修 Bug 快速通道（调试 → TDD → 归档） |
+| `/specflow:snap` | 事后补档（从 git diff 反推变更记录） |
+
+### CLI 命令（在终端里用）
+
+| 命令 | 说明 |
+|---|---|
+| `specflow init` | 初始化项目（生成目录、技能、prompts） |
+| `specflow change new <名称>` | 创建新的变更 |
+| `specflow change status <名称>` | 查看变更的 artifact 完成状态 |
+| `specflow change archive <名称>` | 归档变更（delta merge + 移入 archive） |
+| `specflow validate <文件>` | 校验 spec 文件格式 |
+| `specflow instructions <artifact> <change>` | 查看某个 artifact 的创建指令 |
+
+CLI 命令会从当前目录**向上查找**项目根（找 `specflow/config.yaml`），类似 `git` 的行为。在项目任意子目录下运行都能工作。
+
+---
+
+## 架构
+
+SpecFlow 分三层，各司其职：
+
+```
+┌─────────────────────────────────────────────────┐
+│  CLI 层（确定性逻辑）                              │
+│  TypeScript 实现。负责文件操作、specs 校验、        │
+│  artifact 状态追踪、delta merge、归档。            │
+│  不涉及任何 AI 逻辑。                             │
+├─────────────────────────────────────────────────┤
+│  SKILL.md 层（编排层）                             │
+│  每个命令一个 SKILL.md（50-100 行）。              │
+│  定义工作流阶段、hard gate 门禁、用户确认点。       │
+│  通过 Read 指令按需加载 prompt 文件。              │
+├─────────────────────────────────────────────────┤
+│  Prompts 层（执行指令）                            │
+│  详细的指令文件，告诉 Claude Code 在每个阶段        │
+│  具体怎么做：写 proposal、做 brainstorming、       │
+│  执行 TDD、做 code review 等。                    │
+│  按需加载，不会一次全部塞进 context。               │
+└─────────────────────────────────────────────────┘
+```
+
+**为什么这样设计？**
+
+- **渐进加载**：一个 SKILL.md 如果把所有 prompt 内嵌进去会超过 1000 行，Claude Code 容易"迷路"。拆成小文件按阶段加载，每个阶段的指令清晰聚焦。
+- **Hard Gate 双重保障**：关键门禁（如"设计未确认不许写代码"）在 SKILL.md 编排层和 prompt 文件两处都声明，防止执行漂移。
+- **CLI 处理确定性操作**：delta specs 合并、格式校验等需要精确文本操作的工作由 TypeScript 代码执行，不靠 AI 猜。
+
+---
+
+## 关键概念
+
+### Specs（规格文件）
+
+存放在 `specflow/specs/` 目录，是项目的 **Source of Truth（唯一事实来源）**。
+
+每个 spec 文件描述一个功能模块的行为规格：
+
+```markdown
+### Requirement: 用户登录
+系统应当支持通过邮箱和密码进行用户认证。
+
+#### Scenario: 登录成功
+- **WHEN** 用户提交有效凭据
+- **THEN** 系统返回认证 token
+
+#### Scenario: 登录失败
+- **WHEN** 用户提交错误密码
+- **THEN** 系统返回 401 错误
+```
+
+### Changes（变更记录）
+
+存放在 `specflow/changes/` 目录。每次新功能或修复都是一个 change。
+
+一个 change 包含：
+- `proposal.md` — 为什么做、做什么
+- `specs/` — delta specs（ADDED/MODIFIED/REMOVED/RENAMED 的需求变更）
+- `design.md` — 技术方案
+- `tasks.md` — 实施任务清单（带 checkbox）
+
+归档时，delta specs 会自动合并到主 specs，change 移入 `specflow/changes/archive/`。
+
+### Delta Specs（增量规格）
+
+描述对现有 specs 的变更，支持四种操作：
+
+```markdown
+## ADDED Requirements
+（新增的需求）
+
+## MODIFIED Requirements
+（修改的需求 — 必须包含完整更新内容）
+
+## REMOVED Requirements
+（删除的需求 — 必须说明原因和迁移方案）
+
+## RENAMED Requirements
+（重命名 — FROM: 旧名 / TO: 新名）
+```
+
+---
+
+## 项目产生的目录结构
+
+`specflow init` 后，你的项目会新增：
+
+```
+your-project/
+├── specflow/              # 需求管理（应该跟踪到 git）
+│   ├── config.yaml         # 项目上下文配置
+│   ├── specs/              # 主 specs（Source of Truth）
+│   ├── changes/            # 活跃的变更
+│   │   └── <name>/         # 每个变更的 artifact
+│   │       ├── proposal.md
+│   │       ├── specs/
+│   │       ├── design.md
+│   │       └── tasks.md
+│   └── changes/archive/    # 归档的变更
+│
+└── .claude/
+    ├── skills/specflow-*/ # 10 个技能（应该跟踪）
+    ├── commands/specflow/ # 10 个命令别名（应该跟踪）
+    └── specflow/          # 资源文件（.gitignore 自动忽略）
+        ├── prompts/
+        ├── schemas/
+        └── templates/
+```
+
+建议的 git 策略：
+- **跟踪**：`specflow/`、`.claude/skills/`、`.claude/commands/specflow/`（团队共享的规格和技能）
+- **忽略**：`.claude/specflow/{prompts,schemas,templates}/`（`specflow init` 自动忽略，因为这些可由升级 specflow 重新生成）
+
+---
+
+## 故障排查
+
+### `specflow: command not found`
+
+- 确认 `npm install -g` 成功
+- 检查 `npm config get prefix` 下的 `bin` 目录是否在 PATH 里
+
+### `No specflow project found at or above <dir>`
+
+CLI 找不到项目根。确保：
+- 你在一个跑过 `specflow init` 的项目目录里（或其子目录）
+- `specflow/config.yaml` 存在
+
+### `错误: Change "xxx" already exists`
+
+变更名冲突。要么用不同名字，要么先归档已有的。
+
+### Node 版本不兼容
+
+SpecFlow 需要 Node ≥ 20.19.0。用 `nvm` 切版本：
+```bash
+nvm install 20
+nvm use 20
+npm install -g specflow
+```
+
+### code-review-graph 安装失败
+
+`/specflow:scan` 规划在 v0.3 实现时会用到 code-review-graph（当前在 optionalDependencies 里占位）。这个依赖是从 GitHub 安装的，如果网络问题导致失败，**不影响任何 v0.2.x 功能**——scan 本身在 v0.2.x 不可用，其余所有命令与此依赖无关。
+
+---
+
+## 来源与许可
+
+SpecFlow 基于两个开源项目构建（均为 MIT 许可）：
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — artifact graph、delta merge、validation 等核心运行时
+- [Superpowers](https://github.com/obra/superpowers) — brainstorming、TDD、debugging、code review 等 prompt
+
+所有来源内容已按 SpecFlow 风格改写，通过 `<!-- SOURCE: ... -->` 注释标注出处。
+
+**许可证：MIT**

package/bin/specflow.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli/index.js';

package/dist/cli/commands/change-archive.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI command: specflow change archive <name>
+ *
+ * Archives a completed change by validating, applying deltas, and moving to archive.
+ */
+import type { Command } from 'commander';
+import type { ArchiveOptions, ArchiveResult } from '../../core/archive.js';
+/**
+ * Archives a change, throwing on failure.
+ *
+ * This is a thin wrapper around the core archiveChange function that:
+ * 1. Validates the change directory exists
+ * 2. Delegates to archiveChange (with optional --force)
+ * 3. Throws with error details if validation or archiving fails
+ *
+ * @param changeName - The name of the change to archive
+ * @param projectRoot - Absolute path to the project root
+ * @param options - Optional archive options (e.g. force to bypass phase gate)
+ * @returns The archive result on success
+ * @throws When the change does not exist, validation fails, or archiving fails
+ */
+export declare function archiveChangeCommand(changeName: string, projectRoot: string, options?: ArchiveOptions): Promise<ArchiveResult>;
+/**
+ * Registers the `change archive` subcommand with Commander.
+ */
+export declare function registerChangeArchiveCommand(changeCmd: Command): void;

package/dist/cli/commands/change-archive.js

@@ -0,0 +1,50 @@
+/**
+ * CLI command: specflow change archive <name>
+ *
+ * Archives a completed change by validating, applying deltas, and moving to archive.
+ */
+import { join } from 'node:path';
+import * as fs from 'node:fs';
+import { archiveChange } from '../../core/archive.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+/**
+ * Archives a change, throwing on failure.
+ *
+ * This is a thin wrapper around the core archiveChange function that:
+ * 1. Validates the change directory exists
+ * 2. Delegates to archiveChange (with optional --force)
+ * 3. Throws with error details if validation or archiving fails
+ *
+ * @param changeName - The name of the change to archive
+ * @param projectRoot - Absolute path to the project root
+ * @param options - Optional archive options (e.g. force to bypass phase gate)
+ * @returns The archive result on success
+ * @throws When the change does not exist, validation fails, or archiving fails
+ */
+export async function archiveChangeCommand(changeName, projectRoot, options = {}) {
+    const changeDir = join(projectRoot, 'specflow', 'changes', changeName);
+    if (!fs.existsSync(changeDir)) {
+        throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+    }
+    const result = await archiveChange(changeName, projectRoot, options);
+    if (!result.success) {
+        throw new Error(`Archive failed for "${changeName}":\n${result.errors.join('\n')}`);
+    }
+    return result;
+}
+/**
+ * Registers the `change archive` subcommand with Commander.
+ */
+export function registerChangeArchiveCommand(changeCmd) {
+    changeCmd
+        .command('archive <name>')
+        .description('Archive a completed change')
+        .option('--force', 'Archive even if the change is not in phase=built')
+        .action(async (name, opts) => {
+        const projectRoot = requireProjectRoot();
+        const result = await archiveChangeCommand(name, projectRoot, {
+            force: opts.force ?? false,
+        });
+        console.info(`Archived change "${name}" to ${result.archivePath}`);
+    });
+}

package/dist/cli/commands/change-new.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI command: specflow change new <name>
+ *
+ * Creates a new change directory with .specflow.yaml metadata.
+ */
+import type { Command } from 'commander';
+/**
+ * Creates a new change directory with initial metadata.
+ *
+ * @param name - The change name (kebab-case)
+ * @param projectRoot - Absolute path to the project root
+ * @throws When the name is invalid or the change already exists
+ */
+export declare function createChange(name: string, projectRoot: string): Promise<void>;
+/**
+ * Registers the `change new` subcommand with Commander.
+ */
+export declare function registerChangeNewCommand(changeCmd: Command): void;

package/dist/cli/commands/change-new.js

@@ -0,0 +1,53 @@
+/**
+ * CLI command: specflow change new <name>
+ *
+ * Creates a new change directory with .specflow.yaml metadata.
+ */
+import { join } from 'node:path';
+import { validateChangeName, writeChangeMetadata } from '../../utils/change-utils.js';
+import { directoryExists } from '../../utils/file-system.js';
+import { requireProjectRoot } from '../../utils/project-root.js';
+const CHANGES_REL_PATH = 'specflow/changes';
+/**
+ * Returns today's date as YYYY-MM-DD string.
+ */
+function todayDate() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Creates a new change directory with initial metadata.
+ *
+ * @param name - The change name (kebab-case)
+ * @param projectRoot - Absolute path to the project root
+ * @throws When the name is invalid or the change already exists
+ */
+export async function createChange(name, projectRoot) {
+    validateChangeName(name);
+    const changeDir = join(projectRoot, CHANGES_REL_PATH, name);
+    if (await directoryExists(changeDir)) {
+        throw new Error(`Change "${name}" already exists at ${changeDir}`);
+    }
+    const metadata = {
+        schema: 'specflow',
+        created: todayDate(),
+        phase: 'plan',
+    };
+    await writeChangeMetadata(name, metadata, projectRoot);
+}
+/**
+ * Registers the `change new` subcommand with Commander.
+ */
+export function registerChangeNewCommand(changeCmd) {
+    changeCmd
+        .command('new <name>')
+        .description('Create a new change directory')
+        .action(async (name) => {
+        const projectRoot = requireProjectRoot();
+        await createChange(name, projectRoot);
+        console.info(`Created change: ${name}`);
+    });
+}

package/dist/cli/commands/change-phase.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI command: specflow change phase <name> [--set <value>]
+ *
+ * Read or update the lifecycle phase of a change.
+ */
+import type { Command } from 'commander';
+import type { ChangePhase } from '../../utils/change-utils.js';
+/**
+ * Reads the current phase of a change.
+ *
+ * @param name - Name of the change
+ * @param projectRoot - Absolute path to the project root
+ * @returns The current phase, or undefined for legacy files without a phase field
+ * @throws When the change does not exist
+ */
+export declare function getPhase(name: string, projectRoot: string): Promise<ChangePhase | undefined>;
+/**
+ * Sets the phase of a change, validating the phase value first.
+ *
+ * @param name - Name of the change
+ * @param phase - The new phase value (validated against CHANGE_PHASES)
+ * @param projectRoot - Absolute path to the project root
+ * @throws When the phase is invalid or the change does not exist
+ */
+export declare function setPhase(name: string, phase: string, projectRoot: string): Promise<void>;
+/**
+ * Registers the `change phase` subcommand with Commander.
+ *
+ * Usage:
+ *   specflow change phase <name>            # print current phase
+ *   specflow change phase <name> --set plan # update phase
+ */
+export declare function registerChangePhaseCommand(changeCmd: Command): void;