@gordon.gan/specflow 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 bstzyf
+Copyright (c) 2026 Gordon-Gan-Jiang
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 # 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)
+[![npm version](https://img.shields.io/npm/v/@gordon.gan/specflow.svg)](https://www.npmjs.com/package/@gordon.gan/specflow)
+[![npm downloads](https://img.shields.io/npm/dm/@gordon.gan/specflow.svg)](https://www.npmjs.com/package/@gordon.gan/specflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 **一句话：plan 想清楚，refine 打磨透，build 做到位，done 归档好。**
@@ -30,10 +30,10 @@ SpecFlow 把两个开源框架合并成一个工具：
 
 ## 安装
 
-### 方式 1：从 npm 全局安装（推荐，发布后可用）
+### 方式 1：从 npm 全局安装（推荐）
 
 ```bash
-npm install -g specflow
+npm install -g @gordon.gan/specflow
 ```
 
 ### 方式 2：从 GitHub 直接安装（发布前/最新代码）
@@ -59,25 +59,25 @@ npm link
 在有源码的机器上打包：
 ```bash
 npm run build
-npm pack          # 生成 specflow-0.2.2.tgz
+npm pack          # 生成 gordon.gan-specflow-1.0.2.tgz
 ```
 在目标机器上安装：
 ```bash
-npm install -g ./specflow-0.2.2.tgz
+npm install -g ./gordon.gan-specflow-1.0.2.tgz
 ```
 
 ### 验证安装
 
 ```bash
-specflow --version   # 应输出 0.2.2
+specflow --version   # 应输出 1.0.2
 specflow --help
 ```
 
 ### 卸载
 
 ```bash
-npm uninstall -g specflow
-# 如果用的是 npm link：
+npm uninstall -g @gordon.gan/specflow
+# 如果用的是 npm link（本地源码安装）：
 npm unlink -g specflow
 ```
 
@@ -125,9 +125,9 @@ specflow init
 **每阶段深度思考 → 多轮迭代精化**：每个阶段一次性产出实质内容（非占位骨架），再通过内部多轮迭代把 artifact 精化到稳态，最后进入执行。
 
 ```
-/specflow:scan    [规划中 · v0.3] 扫描已有代码生成 specs 基线；当前请直接用 /specflow:plan 描述已有行为
+/specflow:explore [可选] 需求模糊时：读代码、比方案、定边界 → 产出 explore.md
        ↓
-/specflow:plan    一次产出 4 个 artifact：proposal + delta specs + design + tasks（first-iteration 深度思考，非纯骨架）
+/specflow:propose    一次产出 4 个 artifact：proposal + delta specs + design + tasks（first-iteration 深度思考，非纯骨架）
        ↓
 /specflow:refine  内部多轮精化循环（≥2 rounds，AI 收敛判定，不设上限）
                    每轮攻击性审查 + 4 个挑战行为：
@@ -135,7 +135,7 @@ specflow init
                      · 探边界     · 质疑 scope
                    可更新任意 artifact（proposal / specs / design / tasks）
        ↓
-/specflow:build   Phase A：基于 refine 稳定后的 artifact，用 writing-plans 严格精化（rewrite）tasks.md
+/specflow:apply   Phase A：基于 refine 稳定后的 artifact，用 writing-plans 严格精化（rewrite）tasks.md
                    Phase B：逐任务 TDD 执行（subagent 模式）
                    design 有漏即停，回 refine 补齐
        ↓
@@ -145,7 +145,7 @@ specflow init
        ↓
 /specflow:verify  双重校验（delta specs 验收 + 主 specs 回归）
        ↓
-/specflow:done    归档变更 → specs 合并 → git 分支清理
+/specflow:archive    归档变更 → specs 合并 → git 分支清理
                    默认要求 phase=built，可用 --force 跳过
 ```
 
@@ -170,7 +170,7 @@ specflow init
 
 ```bash
 # 1. 安装（任选一种）
-npm install -g specflow
+npm install -g @gordon.gan/specflow
 
 # 2. 进入你的项目
 cd my-project
@@ -178,12 +178,19 @@ cd my-project
 # 3. 初始化
 specflow init
 
-# 4. 打开 Claude Code，在会话里输入：
-/specflow:plan "给用户管理模块加个批量导入功能"
+# 4. 打开 Claude Code，在会话里输入（二选一）：
+
+# 需求已清晰 — 直接 plan：
+/specflow:propose "给用户管理模块加个批量导入功能"
+
+# 需求模糊 — 先 explore 再 propose：
+/specflow:explore "批量导入时不确定该用 CSV 还是 Excel，也不清楚现有用户表结构"
+# 确认 explore.md 后：
+/specflow:propose
 ```
 
 Claude Code 接下来会：
-1. 读 `.claude/skills/specflow-plan/SKILL.md` 编排器
+1. 读 `.claude/skills/specflow-propose/SKILL.md` 编排器
 2. 问你几个澄清问题（一次一个）
 3. 生成 `specflow/changes/bulk-import/proposal.md`
 4. 展示 proposal 等你**确认**
@@ -192,16 +199,27 @@ Claude Code 接下来会：
 
 ### 更完整的示例（4 个场景）
 
-#### 场景 1：新项目从零开始
+#### 场景 1：新项目从零开始（需求已清晰）
 
 ```
-/specflow:plan "添加用户注册和登录功能"
+/specflow:propose "添加用户注册和登录功能"
 /specflow:refine           # 讨论技术方案，输出 design.md
-/specflow:build            # TDD 实现，每任务用户确认
+/specflow:apply            # TDD 实现，每任务用户确认
 /specflow:review           # 代码审查
 /specflow:test             # 跑测试
 /specflow:verify           # 对照 specs 验收
-/specflow:done             # 归档 + merge
+/specflow:archive             # 归档 + merge
+```
+
+#### 场景 1b：需求模糊，先探索再规划
+
+```
+/specflow:explore "登录有时返回 500，不确定是 token 校验还是 session 存储的问题"
+# AI 读代码、比方案、产出 explore.md；你确认方向后：
+/specflow:propose             # 读取 explore.md，合成 proposal + specs + design + tasks
+/specflow:refine
+/specflow:apply
+/specflow:archive
 ```
 
 #### 场景 2：接手已有项目（v0.2.x 工作流）
@@ -211,13 +229,13 @@ 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/
+# 棕地项目：需求模糊时先 /specflow:explore；或需求清晰时直接 /specflow:propose，
+# 在 proposal Q&A 里描述已有行为 + 新增变更，让 propose 为将要改动的 capability 生成 delta spec 基线。
+/specflow:explore "描述模糊问题或不确定的改法"   # 可选
+/specflow:propose "描述已有行为 + 你这次要改的新功能"
+/specflow:refine             # 对 propose 产出做 ≥2 轮攻击性审查
+/specflow:apply              # Phase A 重写 tasks.md → Phase B TDD
+/specflow:archive               # 归档，delta spec 合入主 specs/
 ```
 
 #### 场景 3：紧急修 Bug
@@ -256,14 +274,14 @@ specflow init
 
 | 命令 | 说明 |
 |---|---|
-| `/specflow:scan` | **[规划中 · v0.3]** 扫描已有代码库生成 specs 基线；v0.2.x 未实现，触发时 skill 会提示替代方案 |
-| `/specflow:plan` | 需求规划：生成 proposal + delta specs |
+| `/specflow:explore` | **需求模糊时** 先探索：读代码、比方案、定边界，产出 `explore.md`，再 handoff 到 propose |
+| `/specflow:propose` | 需求规划：生成 proposal + delta specs |
 | `/specflow:refine` | 技术方案探讨（brainstorming + design.md） |
-| `/specflow:build` | 两阶段构建：生成计划 → subagent TDD 执行 |
+| `/specflow:apply` | 两阶段构建：生成计划 → subagent TDD 执行 |
 | `/specflow:review` | 代码审查（含 specs 回归检查） |
 | `/specflow:test` | 全量测试 + 验证（单元/集成/E2E/回归） |
 | `/specflow:verify` | 双重校验：delta specs 验收 + 主 specs 回归 |
-| `/specflow:done` | 归档变更 + specs 合并 + git 分支清理 |
+| `/specflow:archive` | 归档变更 + specs 合并 + git 分支清理 |
 | `/specflow:fix` | 修 Bug 快速通道（调试 → TDD → 归档） |
 | `/specflow:snap` | 事后补档（从 git diff 反推变更记录） |
 
@@ -403,7 +421,7 @@ your-project/
 
 ### `specflow: command not found`
 
-- 确认 `npm install -g` 成功
+- 确认 `npm install -g @gordon.gan/specflow` 成功
 - 检查 `npm config get prefix` 下的 `bin` 目录是否在 PATH 里
 
 ### `No specflow project found at or above <dir>`
@@ -422,13 +440,9 @@ SpecFlow 需要 Node ≥ 20.19.0。用 `nvm` 切版本：
 ```bash
 nvm install 20
 nvm use 20
-npm install -g specflow
+npm install -g @gordon.gan/specflow
 ```
 
-### code-review-graph 安装失败
-
-`/specflow:scan` 规划在 v0.3 实现时会用到 code-review-graph（当前在 optionalDependencies 里占位）。这个依赖是从 GitHub 安装的，如果网络问题导致失败，**不影响任何 v0.2.x 功能**——scan 本身在 v0.2.x 不可用，其余所有命令与此依赖无关。
-
 ---
 
 ## 来源与许可

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

@@ -28,6 +28,6 @@ export declare function setPhase(name: string, phase: string, projectRoot: strin
  *
  * Usage:
  *   specflow change phase <name>            # print current phase
- *   specflow change phase <name> --set plan # update phase
+ *   specflow change phase <name> --set propose # update phase
  */
 export declare function registerChangePhaseCommand(changeCmd: Command): void;

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

@@ -46,7 +46,7 @@ export async function setPhase(name, phase, projectRoot) {
  *
  * Usage:
  *   specflow change phase <name>            # print current phase
- *   specflow change phase <name> --set plan # update phase
+ *   specflow change phase <name> --set propose # update phase
  */
 export function registerChangePhaseCommand(changeCmd) {
     changeCmd

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

@@ -7,7 +7,7 @@ import { join } from 'node:path';
 import * as fs from 'node:fs';
 import yaml from 'js-yaml';
 import { resolveSchema } from '../../core/artifact-graph/resolver.js';
-import { getCompletedArtifacts } from '../../core/artifact-graph/state.js';
+import { getCompletedArtifacts, getInProgressArtifacts } from '../../core/artifact-graph/state.js';
 import { formatStatus } from '../../core/artifact-graph/outputs.js';
 import { requireProjectRoot } from '../../utils/project-root.js';
 import { readChangeMetadata } from '../../utils/change-metadata.js';
@@ -49,7 +49,8 @@ export async function getChangeStatus(changeName, projectRoot) {
     // Resolve schema from project-local schemas/ directory, falling back to package schemas
     const schema = resolveSchema(schemaName, projectRoot);
     const completed = getCompletedArtifacts(changeDir, schema);
-    const statusOutput = formatStatus(schema.artifacts, completed);
+    const inProgress = getInProgressArtifacts(changeDir, schema);
+    const statusOutput = formatStatus(schema.artifacts, completed, inProgress);
     const completedSet = new Set(completed);
     const allDone = schema.artifacts.every((a) => completedSet.has(a.id));
     return {
@@ -66,10 +67,18 @@ export async function getChangeStatus(changeName, projectRoot) {
  */
 export function formatChangeStatus(status) {
     const lines = status.artifacts.map((entry) => {
-        const checkbox = entry.status === 'done' ? '[x]' : '[ ]';
-        const suffix = entry.missingDeps && entry.missingDeps.length > 0
-            ? ` (blocked by: ${entry.missingDeps.join(', ')})`
-            : '';
+        const checkbox = entry.status === 'done'
+            ? '[x]'
+            : entry.status === 'in_progress'
+                ? '[~]'
+                : '[ ]';
+        let suffix = '';
+        if (entry.status === 'in_progress') {
+            suffix = ' (draft — confirm before propose)';
+        }
+        else if (entry.missingDeps && entry.missingDeps.length > 0) {
+            suffix = ` (blocked by: ${entry.missingDeps.join(', ')})`;
+        }
         return `${checkbox} ${entry.id}${suffix}`;
     });
     return lines.join('\n');

package/dist/core/archive.js

@@ -80,14 +80,14 @@ export async function archiveChange(changeName, projectRoot, options = {}) {
         return {
             success: false,
             errors: [
-                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'built'. Complete '/specflow:build' first, or pass '--force' to archive anyway.`,
+                `Cannot archive: change '${changeName}' is in phase '${phaseLabel}', expected 'built'. Complete '/specflow:apply' first, or pass '--force' to archive anyway.`,
             ],
         };
     }
     if (options.force && currentPhase !== 'built') {
         const phaseLabel = currentPhase ?? 'unknown';
         console.warn(`Warning: archiving "${changeName}" in phase ${phaseLabel} with --force. ` +
-            `Consider running /specflow:build first.`);
+            `Consider running /specflow:apply first.`);
     }
     // 1. Find delta spec files
     const deltaFiles = await listMarkdownFiles(deltaSpecsDir);

package/dist/core/artifact-graph/explore-status.d.ts

@@ -0,0 +1,5 @@
+export type ExploreArtifactStatus = 'missing' | 'draft' | 'confirmed';
+/**
+ * Reads explore.md Status field. Only `confirmed` counts as exploration complete.
+ */
+export declare function readExploreArtifactStatus(changeDir: string): ExploreArtifactStatus;

package/dist/core/artifact-graph/explore-status.js

@@ -0,0 +1,21 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Reads explore.md Status field. Only `confirmed` counts as exploration complete.
+ */
+export function readExploreArtifactStatus(changeDir) {
+    const explorePath = path.join(changeDir, 'explore.md');
+    let content;
+    try {
+        content = fs.readFileSync(explorePath, 'utf-8');
+    }
+    catch {
+        return 'missing';
+    }
+    const match = content.match(/\*\*Status\*\*:\s*(confirmed|draft)\b/i);
+    if (!match) {
+        // File exists but Status is missing or malformed — treat as in-progress draft.
+        return 'draft';
+    }
+    return match[1].toLowerCase();
+}

package/dist/core/artifact-graph/index.d.ts

@@ -3,7 +3,9 @@ export type { Artifact, ApplyPhase, SchemaYaml, CompletedSet, BlockedArtifacts,
 export { loadSchema, parseSchema, SchemaValidationError, } from './schema.js';
 export { resolveSchema, getSchemaDir, getPackageSchemasDir, getProjectSchemasDir, listSchemas, SchemaLoadError, } from './resolver.js';
 export { ArtifactGraph } from './graph.js';
-export { getCompletedArtifacts } from './state.js';
+export { getCompletedArtifacts, getInProgressArtifacts } from './state.js';
+export { readExploreArtifactStatus } from './explore-status.js';
+export type { ExploreArtifactStatus } from './explore-status.js';
 export { loadInstructions } from './instruction-loader.js';
 export type { ArtifactInstructions, DependencyInfo, ProjectConfig, } from './instruction-loader.js';
 export { formatStatus, formatStatusHuman } from './outputs.js';

package/dist/core/artifact-graph/index.js

@@ -2,6 +2,7 @@ export { ArtifactSchema, ApplyPhaseSchema, SchemaYamlSchema, } from './types.js'
 export { loadSchema, parseSchema, SchemaValidationError, } from './schema.js';
 export { resolveSchema, getSchemaDir, getPackageSchemasDir, getProjectSchemasDir, listSchemas, SchemaLoadError, } from './resolver.js';
 export { ArtifactGraph } from './graph.js';
-export { getCompletedArtifacts } from './state.js';
+export { getCompletedArtifacts, getInProgressArtifacts } from './state.js';
+export { readExploreArtifactStatus } from './explore-status.js';
 export { loadInstructions } from './instruction-loader.js';
 export { formatStatus, formatStatusHuman } from './outputs.js';

package/dist/core/artifact-graph/outputs.d.ts

@@ -4,7 +4,7 @@ import type { Artifact } from './types.js';
  */
 export interface ArtifactStatusEntry {
     readonly id: string;
-    readonly status: 'done' | 'ready' | 'blocked';
+    readonly status: 'done' | 'ready' | 'blocked' | 'in_progress';
     readonly missingDeps?: readonly string[];
 }
 /**
@@ -20,7 +20,7 @@ export interface StatusOutput {
  * @param completed - Array of completed artifact IDs
  * @returns Structured status with each artifact's state
  */
-export declare function formatStatus(artifacts: readonly Artifact[], completed: readonly string[]): StatusOutput;
+export declare function formatStatus(artifacts: readonly Artifact[], completed: readonly string[], inProgress?: readonly string[]): StatusOutput;
 /**
  * Formats artifact statuses as human-readable checkbox text.
  *
@@ -32,4 +32,4 @@ export declare function formatStatus(artifacts: readonly Artifact[], completed:
  * @param completed - Array of completed artifact IDs
  * @returns Checkbox-style text string
  */
-export declare function formatStatusHuman(artifacts: readonly Artifact[], completed: readonly string[]): string;
+export declare function formatStatusHuman(artifacts: readonly Artifact[], completed: readonly string[], inProgress?: readonly string[]): string;

package/dist/core/artifact-graph/outputs.js

@@ -5,12 +5,16 @@
  * @param completed - Array of completed artifact IDs
  * @returns Structured status with each artifact's state
  */
-export function formatStatus(artifacts, completed) {
+export function formatStatus(artifacts, completed, inProgress = []) {
     const completedSet = new Set(completed);
+    const inProgressSet = new Set(inProgress);
     const statuses = artifacts.map(artifact => {
         if (completedSet.has(artifact.id)) {
             return { id: artifact.id, status: 'done' };
         }
+        if (inProgressSet.has(artifact.id)) {
+            return { id: artifact.id, status: 'in_progress' };
+        }
         const missingDeps = artifact.requires.filter(req => !completedSet.has(req));
         if (missingDeps.length === 0) {
             return { id: artifact.id, status: 'ready' };
@@ -34,14 +38,28 @@ export function formatStatus(artifacts, completed) {
  * @param completed - Array of completed artifact IDs
  * @returns Checkbox-style text string
  */
-export function formatStatusHuman(artifacts, completed) {
+export function formatStatusHuman(artifacts, completed, inProgress = []) {
     const completedSet = new Set(completed);
+    const inProgressSet = new Set(inProgress);
     const lines = artifacts.map(artifact => {
-        const checkbox = completedSet.has(artifact.id) ? '[x]' : '[ ]';
+        let checkbox;
+        if (completedSet.has(artifact.id)) {
+            checkbox = '[x]';
+        }
+        else if (inProgressSet.has(artifact.id)) {
+            checkbox = '[~]';
+        }
+        else {
+            checkbox = '[ ]';
+        }
         const missingDeps = artifact.requires.filter(req => !completedSet.has(req));
-        const suffix = missingDeps.length > 0
-            ? ` (blocked by: ${missingDeps.join(', ')})`
-            : '';
+        let suffix = '';
+        if (inProgressSet.has(artifact.id)) {
+            suffix = ' (draft — confirm before propose)';
+        }
+        else if (missingDeps.length > 0) {
+            suffix = ` (blocked by: ${missingDeps.join(', ')})`;
+        }
         return `${checkbox} ${artifact.id}${suffix}`;
     });
     return lines.join('\n');

package/dist/core/artifact-graph/state.d.ts

@@ -7,3 +7,7 @@ import type { SchemaYaml } from './types.js';
  * @returns Array of completed artifact IDs
  */
 export declare function getCompletedArtifacts(changeDir: string, schema: SchemaYaml): string[];
+/**
+ * Artifacts that exist but are not yet complete (e.g. explore.md with Status: draft).
+ */
+export declare function getInProgressArtifacts(changeDir: string, schema: SchemaYaml): string[];

package/dist/core/artifact-graph/state.js

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { readExploreArtifactStatus } from './explore-status.js';
 /**
  * Checks if an artifact's generated file(s) exist in the change directory.
  * Supports simple file paths and basic glob patterns with "**".
@@ -85,9 +86,30 @@ export function getCompletedArtifacts(changeDir, schema) {
     }
     const completed = [];
     for (const artifact of schema.artifacts) {
+        if (artifact.id === 'explore') {
+            if (readExploreArtifactStatus(changeDir) === 'confirmed') {
+                completed.push('explore');
+            }
+            continue;
+        }
         if (artifactFileExists(changeDir, artifact.generates)) {
             completed.push(artifact.id);
         }
     }
     return completed;
 }
+/**
+ * Artifacts that exist but are not yet complete (e.g. explore.md with Status: draft).
+ */
+export function getInProgressArtifacts(changeDir, schema) {
+    if (!fs.existsSync(changeDir)) {
+        return [];
+    }
+    const inProgress = [];
+    for (const artifact of schema.artifacts) {
+        if (artifact.id === 'explore' && readExploreArtifactStatus(changeDir) === 'draft') {
+            inProgress.push('explore');
+        }
+    }
+    return inProgress;
+}

package/dist/core/templates/index.js

@@ -10,6 +10,7 @@ const TEMPLATE_IDS = [
     'spec',
     'design',
     'tasks',
+    'explore',
 ];
 /**
  * Error thrown when a template cannot be found or loaded.

package/dist/core/templates/types.d.ts

@@ -1,4 +1,4 @@
 /**
  * Valid template identifiers corresponding to markdown files in the templates/ directory.
  */
-export type TemplateId = 'proposal' | 'spec' | 'design' | 'tasks';
+export type TemplateId = 'proposal' | 'spec' | 'design' | 'tasks' | 'explore';

package/dist/integrations/codex/adapter.js

@@ -36,7 +36,7 @@ function renderCodexAgentsBlock() {
         '- Respect specflow phase gates: plan -> refined -> built -> archived',
         '- Never bypass CLI validation and archive checks',
         '- Use artifacts under specflow/changes/<change>/ before coding',
-        '- Workflow skills: $specflow-plan, $specflow-refine, $specflow-build, $specflow-review, $specflow-test, $specflow-verify, $specflow-done, $specflow-fix, $specflow-snap',
+        '- Workflow skills: $specflow-explore, $specflow-propose, $specflow-refine, $specflow-apply, $specflow-review, $specflow-test, $specflow-verify, $specflow-archive, $specflow-fix, $specflow-snap',
         '- Runtime prompts live under .agents/specflow/prompts/',
         '',
     ].join('\n');

package/dist/integrations/cursor/adapter.js

@@ -26,7 +26,7 @@ function renderCursorRule() {
     return [
         '# SpecFlow Cursor Context',
         '',
-        '- Respect specflow phase gates: plan -> refined -> built -> archived',
+        '- Respect specflow phase gates: propose -> refined -> built -> archived',
         '- Never bypass CLI validation and archive checks',
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '',

package/dist/integrations/shared/capability-evidence.js

@@ -1,20 +1,24 @@
 import { COMMAND_IDS } from './command-catalog.js';
 const MARKER_RULES = [
-    { id: 'sub.scan.planned_v03_notice', skill: 'scan', includes: ['[PLANNED v0.3]', 'NOT YET FUNCTIONAL'] },
-    { id: 'sub.plan.first_iteration', skill: 'plan', includes: ['first-iteration deep-analysis pass'] },
+    { id: 'sub.explore.conversation_first', skill: 'explore', includes: ['think-before-propose', 'Do NOT write proposal'] },
+    { id: 'sub.explore.handoff_propose', skill: 'explore', includes: ['explore.md', 'handoff'] },
+    { id: 'sub.explore.mid_change_reexplore', skill: 'explore', includes: ['Re-explore Mid-Change', 'stuck during'] },
+    { id: 'sub.propose.explore_handoff', skill: 'propose', includes: ['explore.md', 'Explore Handoff'] },
+    { id: 'sub.propose.first_iteration', skill: 'propose', includes: ['first-iteration deep-analysis pass'] },
     { id: 'sub.refine.multi_round', skill: 'refine', includes: ['auto-multi-round loop', '## LOOP (Stages 2-4)'] },
     { id: 'sub.refine.challenge_scope', skill: 'refine', includes: ['Challenge Behaviors #3 and #4', 'question scope'] },
-    { id: 'sub.build.phase_a', skill: 'build', includes: ['## Phase A: Task Rewrite'] },
-    { id: 'sub.build.phase_b', skill: 'build', includes: ['## Phase B: Subagent TDD Execution'] },
-    { id: 'sub.build.gap_detection', skill: 'build', includes: ['Gap Detection'] },
+    { id: 'sub.apply.phase_a', skill: 'apply', includes: ['## Phase A: Task Rewrite'] },
+    { id: 'sub.apply.phase_b', skill: 'apply', includes: ['## Phase B: Subagent TDD Execution'] },
+    { id: 'sub.apply.gap_detection', skill: 'apply', includes: ['Gap Detection'] },
     { id: 'sub.review.spec_regression', skill: 'review', includes: ['regression'] },
     { id: 'sub.test.full_scope', skill: 'test', includes: ['unit, integration, e2e', 'verification report'] },
     { id: 'sub.verify.dual_validation', skill: 'verify', includes: ['Dual validation', 'delta specs'] },
-    { id: 'sub.done.archive_merge', skill: 'done', includes: ['specflow change archive', 'delta specs into main specs'] },
+    { id: 'sub.archive.archive_merge', skill: 'archive', includes: ['specflow change archive', 'delta specs into main specs'] },
     { id: 'sub.fix.urgent_mode', skill: 'fix', includes: ['--urgent', 'skip'] },
     { id: 'sub.snap.posthoc', skill: 'snap', includes: ['post-hoc', 'archive'] },
-    { id: 'failure.scan.not_implemented_guard', skill: 'scan', includes: ['do NOT attempt to run `specflow scan`'] },
-    { id: 'failure.build.phase_gate', skill: 'build', includes: ['HARD GATE (prerequisite)', 'phase is not `refined`, REFUSE'] },
+    { id: 'failure.explore.proposal_exists_redirect', skill: 'explore', includes: ['explore is too late', 'refine'] },
+    { id: 'failure.propose.explore_draft_gate', skill: 'propose', includes: ['Status: draft', 'REFUSE to proceed'] },
+    { id: 'failure.apply.phase_gate', skill: 'apply', includes: ['HARD GATE (prerequisite)', 'phase is not `refined`, REFUSE'] },
     { id: 'failure.verify.explicit_skip_marker', skill: 'verify', includes: ['Pass 2: skipped (no baseline'] },
 ];
 export function deriveCapabilityIds(supportedCommandIds, skillContentsByCommand) {

package/dist/integrations/shared/command-catalog.js

@@ -1,12 +1,12 @@
 export const COMMAND_CATALOG = [
-    { id: 'scan', description: 'Brownfield project scanner via code-review-graph' },
-    { id: 'plan', description: 'Create proposal and spec artifacts for a change' },
+    { id: 'explore', description: 'Think-before-propose exploration when requirements are fuzzy' },
+    { id: 'propose', description: 'Create proposal and spec artifacts for a change' },
     { id: 'refine', description: 'Refine and iterate on spec artifacts' },
-    { id: 'build', description: 'Implement tasks from a change spec' },
+    { id: 'apply', description: 'Implement tasks from a change spec' },
     { id: 'review', description: 'Review code changes against spec' },
     { id: 'test', description: 'Run tests and verify coverage' },
     { id: 'verify', description: 'Verify implementation matches spec' },
-    { id: 'done', description: 'Finalize and archive a completed change' },
+    { id: 'archive', description: 'Finalize and archive a completed change' },
     { id: 'fix', description: 'Debug and fix failing tests or builds' },
     { id: 'snap', description: 'Snapshot current project state' },
 ];

package/dist/integrations/shared/parity-manifest.js

@@ -6,21 +6,25 @@ export const CAPABILITY_MANIFEST = [
         level: 'command',
         required: true,
     })),
-    { id: 'sub.scan.planned_v03_notice', commandId: 'scan', level: 'sub-capability', required: true },
-    { id: 'sub.plan.first_iteration', commandId: 'plan', level: 'sub-capability', required: true },
+    { id: 'sub.explore.conversation_first', commandId: 'explore', level: 'sub-capability', required: true },
+    { id: 'sub.explore.handoff_propose', commandId: 'explore', level: 'sub-capability', required: true },
+    { id: 'sub.explore.mid_change_reexplore', commandId: 'explore', level: 'sub-capability', required: true },
+    { id: 'sub.propose.explore_handoff', commandId: 'propose', level: 'sub-capability', required: true },
+    { id: 'sub.propose.first_iteration', commandId: 'propose', level: 'sub-capability', required: true },
     { id: 'sub.refine.multi_round', commandId: 'refine', level: 'sub-capability', required: true },
     { id: 'sub.refine.challenge_scope', commandId: 'refine', level: 'sub-capability', required: true },
-    { id: 'sub.build.phase_a', commandId: 'build', level: 'sub-capability', required: true },
-    { id: 'sub.build.phase_b', commandId: 'build', level: 'sub-capability', required: true },
-    { id: 'sub.build.gap_detection', commandId: 'build', level: 'sub-capability', required: true },
+    { id: 'sub.apply.phase_a', commandId: 'apply', level: 'sub-capability', required: true },
+    { id: 'sub.apply.phase_b', commandId: 'apply', level: 'sub-capability', required: true },
+    { id: 'sub.apply.gap_detection', commandId: 'apply', level: 'sub-capability', required: true },
     { id: 'sub.review.spec_regression', commandId: 'review', level: 'sub-capability', required: true },
     { id: 'sub.test.full_scope', commandId: 'test', level: 'sub-capability', required: true },
     { id: 'sub.verify.dual_validation', commandId: 'verify', level: 'sub-capability', required: true },
-    { id: 'sub.done.archive_merge', commandId: 'done', level: 'sub-capability', required: true },
+    { id: 'sub.archive.archive_merge', commandId: 'archive', level: 'sub-capability', required: true },
     { id: 'sub.fix.urgent_mode', commandId: 'fix', level: 'sub-capability', required: true },
     { id: 'sub.snap.posthoc', commandId: 'snap', level: 'sub-capability', required: true },
-    { id: 'failure.scan.not_implemented_guard', commandId: 'scan', level: 'failure-path', required: true },
-    { id: 'failure.build.phase_gate', commandId: 'build', level: 'failure-path', required: true },
+    { id: 'failure.explore.proposal_exists_redirect', commandId: 'explore', level: 'failure-path', required: true },
+    { id: 'failure.propose.explore_draft_gate', commandId: 'propose', level: 'failure-path', required: true },
+    { id: 'failure.apply.phase_gate', commandId: 'apply', level: 'failure-path', required: true },
     { id: 'failure.verify.explicit_skip_marker', commandId: 'verify', level: 'failure-path', required: true },
 ];
 export const IDE_ASSET_MANIFEST = [

package/dist/utils/change-metadata.d.ts

@@ -3,7 +3,7 @@
  *
  * - `plan`: Initial phase, created by `specflow change new`.
  * - `refined`: After `/specflow:refine` iterative deep review completes.
- * - `built`: After `/specflow:build` Phase B execution finishes.
+ * - `built`: After `/specflow:apply` Phase B execution finishes.
  * - `archived`: Post-archive state; assigned automatically on successful archive.
  */
 export declare const CHANGE_PHASES: readonly ["plan", "refined", "built", "archived"];

package/dist/utils/change-metadata.js

@@ -8,7 +8,7 @@ const METADATA_FILENAME = '.specflow.yaml';
  *
  * - `plan`: Initial phase, created by `specflow change new`.
  * - `refined`: After `/specflow:refine` iterative deep review completes.
- * - `built`: After `/specflow:build` Phase B execution finishes.
+ * - `built`: After `/specflow:apply` Phase B execution finishes.
  * - `archived`: Post-archive state; assigned automatically on successful archive.
  */
 export const CHANGE_PHASES = ['plan', 'refined', 'built', 'archived'];