cc-devflow 4.1.0 → 4.1.1

package/.claude/commands/flow/new.md

@@ -23,19 +23,6 @@ guides:
 - {TEMPLATE:orchestration} → 加载 .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md
 - {GUIDE:troubleshoot}     → 参考 .claude/docs/guides/NEW_TROUBLESHOOTING.md
 
-使用案例:
-```markdown
-# 正文中遇到:
-→ 详见 {TEMPLATE:orchestration} Stage 4
-# 解释为:
-→ 打开并阅读 .claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md 中的 Stage 4 章节
-
-# 正文中遇到:
-→ 常见错误参见 {GUIDE:troubleshoot} Error 3
-# 解释为:
-→ 打开并阅读 .claude/docs/guides/NEW_TROUBLESHOOTING.md 中的 Error 3 章节
-```
-
 规则: 遇到 {TYPE:key} 占位符时，去头文件 YAML 中找对应类型的 key，获取文件路径并加载。
 ============================================================ -->
 
@@ -49,7 +36,7 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 **格式**:
 - REQ_ID: 需求编号 (例如: REQ-123)
 - TITLE: 需求标题
-- PLAN_URLS: 计划文档URL，多个用逗号分隔 (可选)
+- PLAN_URLS: 计划文档 URL，多个用逗号分隔 (可选)
 
 **示例**:
 ```
@@ -71,289 +58,158 @@ $ARGUMENTS = "REQ_ID|TITLE|PLAN_URLS?"
 
 ## 架构说明
 
-**设计理念**: flow-new 是**编排器**（Orchestrator），串行调用 7-8 个阶段化命令
+**设计理念**: `flow-new` 是编排器（Orchestrator），串行调用当前主干命令，避免人工串接阶段。
 
-**调用链** (v2.1.0 更新):
+**调用链** (v4.1):
 ```
 /flow-new "REQ-123|Title|URLs"
   ↓
-[1/9] /flow-init "REQ-123|Title|URLs"
-      → 包含 Brainstorming，生成 BRAINSTORM.md ⭐ v2.1.0
-  ↓
-[2/9] /flow-prd "REQ-123"
-      → 需要 BRAINSTORM.md 对齐检查 ⭐ v2.1.0
-  ↓
-[2.3/9] /flow-checklist "REQ-123" (可选, 80%门禁)
-  ↓
-[2.5/9] /flow-ui "REQ-123" (条件触发)
+[1/6] /flow-init "REQ-123|Title|URLs"
+      → 创建需求目录 + research + BRAINSTORM
   ↓
-[2.7/9] /flow-tech "REQ-123" (必需)
+[2/6] /flow-clarify "REQ-123" (可选)
+      → 仅在需求存在歧义时触发
   ↓
-[3/9] /flow-epic "REQ-123"
-      → bite-sized tasks (2-5分钟/任务) ⭐ v2.1.0
+[3/6] /flow-spec "REQ-123"
+      → PRD → Tech+UI(并行) → Epic/TASKS
   ↓
-[4/9] /flow-dev "REQ-123"
-      → TDD Checkpoint (测试必须先 FAIL) ⭐ v2.1.0
+[4/6] /flow-dev "REQ-123"
+      → TDD 执行 (测试先失败，再实现)
   ↓
-[5/9] /flow-review "REQ-123" ⭐ v2.1.0 新增
-      → Two-Stage Review (Spec → Quality)
+[5/6] /flow-quality "REQ-123" --full
+      → 规格合规 + 代码质量 + 安全验证
   ↓
-[6/9] /flow-qa "REQ-123" --full
-  ↓
-[7/9] /flow-release "REQ-123"
-      → 分支完成决策 ⭐ v2.1.0
+[6/6] /flow-release "REQ-123"
+      → 发布计划 + PR 创建 + 分支收尾
 ```
 
 ---
 
 ## 执行流程骨架
 
-### [1/9] 初始化 → /flow-init
+### [1/6] 初始化 → /flow-init
 
 ```
 调用: /flow-init "${REQ_ID}|${TITLE}|${PLAN_URLS}"
-
 检查: orchestration_status.json.status === "initialized"
-
 → 详见 {TEMPLATE:orchestration} Stage 1
 ```
 
 **输出**:
-- Git分支: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
-- 需求目录已创建
-- 研究材料已抓取
-- **BRAINSTORM.md** (需求北极星) ⭐ v2.1.0 新增
-
-> BRANCH_TITLE_EN 为 TITLE 的英文意译 (语义为准，非拼音，使用模型意译)
+- Git 分支: `feature/${REQ_ID}-${slug(BRANCH_TITLE_EN)}`
+- 需求目录与 research 上下文
+- `BRAINSTORM.md`
 
 ---
 
-### [2/9] PRD生成 → /flow-prd
+### [2/6] 需求澄清（可选）→ /flow-clarify
 
 ```
-调用: /flow-prd "${REQ_ID}"
-
-检查:
-  - BRAINSTORM.md 存在 ⭐ v2.1.0 新增
-  - PRD.md 存在且完整
-  - BRAINSTORM 对齐检查通过 ⭐ v2.1.0 新增
-
-→ 详见 {TEMPLATE:orchestration} Stage 2
+触发条件: 需求存在歧义、边界不清、验收标准冲突
+调用: /flow-clarify "${REQ_ID}"
+→ 详见 .claude/commands/flow/clarify.md
 ```
 
 **输出**:
-- PRD.md (用户故事 + GWT验收标准)
-- Constitution检查通过
+- `clarifications/*.md` (如触发)
 
 ---
 
-### [2.3/9] 需求质量检查 → /flow-checklist (可选)
+### [3/6] 统一规格阶段 → /flow-spec
 
 ```
-触发条件: quality-rules.yml 中 checklist_gate_enabled: true
-
-调用: /flow-checklist "${REQ_ID}"
-
-闸门: 完成度 ≥ 80%
-
-→ 详见 {TEMPLATE:orchestration} Stage 2.3
-```
-
----
-
-### [2.5/9] UI原型生成 → /flow-ui (条件触发)
-
-```
-触发条件 (任一满足):
-  - PRD包含UI关键词 ("页面"/"表单"/"按钮" etc.)
-  - 项目包含 package.json 或 src/components/
-  - 用户显式请求
-
-调用: /flow-ui "${REQ_ID}"
-
-→ 详见 {TEMPLATE:orchestration} Stage 2.5 (包含 UI Detection Logic)
-```
-
-**输出** (如有UI需求):
-- UI_PROTOTYPE.html (响应式单文件原型)
-- research/ui_design_strategy.md
-
-**跳过** (无UI需求):
-- orchestration_status.json.ui_skipped = true
-
----
-
-### [2.7/9] 技术方案设计 → /flow-tech (必需)
-
-```
-调用: /flow-tech "${REQ_ID}"
-
-检查: TECH_DESIGN.md 完整 (所有 Section 1-7)
-
-→ 详见 {TEMPLATE:orchestration} Stage 2.7
+调用: /flow-spec "${REQ_ID}" [--skip-tech] [--skip-ui]
+默认: PRD + Tech + UI + Epic/TASKS
+→ 详见 .claude/commands/flow/spec.md
 ```
 
 **输出**:
-- TECH_DESIGN.md (完整技术方案)
-- data-model.md (数据模型)
-- contracts/openapi.yaml (API契约)
-- quickstart.md (快速开始)
+- `PRD.md`
+- `TECH_DESIGN.md` / `UI_PROTOTYPE.html` (按模式)
+- `EPIC.md` + `TASKS.md`
 
 ---
 
-### [3/9] Epic规划 → /flow-epic
-
-```
-调用: /flow-epic "${REQ_ID}"
-
-检查:
-  - EPIC.md + TASKS.md 存在
-  - TASKS 覆盖 TECH_DESIGN.md 所有技术层
-  - 任务粒度: 2-5分钟/任务 (bite-sized) ⭐ v2.1.0
-
-→ 详见 {TEMPLATE:orchestration} Stage 3
-```
-
-**输出**:
-- EPIC.md (Epic描述)
-- TASKS.md (单文件管理所有任务，bite-sized)
-
----
-
-### [4/9] 开发执行 → /flow-dev
+### [4/6] 开发执行 → /flow-dev
 
 ```
 调用: /flow-dev "${REQ_ID}"
-
-执行模式: TDD (Tests First)
-  Phase 1: 分析现有代码
-  Phase 2: 编写测试 (Tests First)
-  ⚠️ TDD CHECKPOINT (测试必须先 FAIL) ⭐ v2.1.0
-  Phase 3: 实现代码
-  Phase 4: 测试验证 (测试必须通过)
-  Phase 5: Git提交并标记完成
-
-→ 详见 {TEMPLATE:orchestration} Stage 4
-```
-
-**输出**:
-- 实现代码
-- 测试代码
-- TASKS.md 更新 (checkbox 标记)
-- Git commits (每个任务一个)
-
----
-
-### [5/9] 代码审查 → /flow-review ⭐ v2.1.0 新增
-
-```
-调用: /flow-review "${REQ_ID}"
-
-Two-Stage Review:
-  Stage 1: Spec Compliance (规格合规)
-    → 不信任实现者报告，读代码验证
-    → 检查 scope creep
-    → BRAINSTORM 对齐检查
-  Stage 2: Code Quality (代码质量)
-    → 仅在 Stage 1 通过后执行
-    → 测试质量、Constitution 合规
-
-→ 详见 flow-review.md
+执行模式: TDD
+  1) 先写测试并确认失败
+  2) 再实现功能
+  3) 最终测试通过
+→ 详见 .claude/commands/flow/dev.md
 ```
 
 **输出**:
-- SPEC_REVIEW.md (Stage 1)
-- CODE_QUALITY_REVIEW.md (Stage 2)
+- 实现代码 + 测试代码
+- `TASKS.md` 勾选状态更新
 
 ---
 
-### [6/9] 质量保证 → /flow-qa
+### [5/6] 质量验证 → /flow-quality
 
 ```
-调用: /flow-qa "${REQ_ID}" --full
-
-Exit Gate检查:
-  - ✅ 所有测试通过
-  - ✅ 代码覆盖率 ≥ 80%
-  - ✅ 无高危安全问题
-  - ✅ TypeScript类型检查通过
-
-→ 详见 {TEMPLATE:orchestration} Stage 5
+调用: /flow-quality "${REQ_ID}" --full
+检查: 规格一致性、代码质量、安全与测试门禁
+→ 详见 .claude/commands/flow/quality.md
 ```
 
 **输出**:
-- TEST_PLAN.md
-- TEST_REPORT.md
-- SECURITY_PLAN.md
-- SECURITY_REPORT.md
+- `SPEC_REVIEW.md`
+- `CODE_QUALITY_REVIEW.md`
+- `SECURITY_REPORT.md`
 
 ---
 
-### [7/9] 发布管理 → /flow-release
+### [6/6] 发布管理 → /flow-release
 
 ```
 调用: /flow-release "${REQ_ID}"
-
-执行:
-  - 分支完成决策 (FF merge / PR / Squash / Cleanup) ⭐ v2.1.0
-  - 生成发布计划
-  - 更新 CLAUDE.md (如有重要架构变更)
-  - 最终构建
-  - 创建 GitHub Pull Request
-
-→ 详见 {TEMPLATE:orchestration} Stage 6
+执行: 生成 RELEASE_PLAN、创建 PR、执行收尾策略
+→ 详见 .claude/commands/flow/release.md
 ```
 
 **输出**:
-- RELEASE_PLAN.md
-- CLAUDE.md (更新技术架构，如有)
-- GitHub Pull Request
+- `RELEASE_PLAN.md`
+- Pull Request / 合并策略决策
 
 ---
 
 ## 进度展示
 
-**实时进度** (详见 `{TEMPLATE:orchestration}` Progress Display Format):
+**实时进度**:
 
 ```
-🎯 CC-DevFlow 完整需求开发流程 (v2.1.0)
+🎯 CC-DevFlow 完整需求开发流程 (v4.1)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 需求: REQ-123 | 支持用户下单
 
-[1/9] ✅ 初始化完成 (含 Brainstorming)
-[2/9] ✅ PRD生成完成 (BRAINSTORM 对齐)
-[2.5/9] ✅ UI原型生成完成 ⚡️
-[2.7/9] ✅ 技术方案设计完成 🔧
-[3/9] ✅ Epic规划完成 (bite-sized tasks)
-[4/9] 🔄 开发执行中... (8/18 已完成)
-[5/9] ⏳ 等待代码审查... ⭐ 新增
-[6/9] ⏳ 等待质量保证...
-[7/9] ⏳ 等待发布管理...
+[1/6] ✅ 初始化完成
+[2/6] ✅ 澄清完成 (可选)
+[3/6] ✅ 统一规格完成
+[4/6] 🔄 开发执行中... (8/18 已完成)
+[5/6] ⏳ 等待质量验证...
+[6/6] ⏳ 等待发布管理...
 ```
 
 ---
 
 ## 输出产物
 
-**完整目录结构** (详见 `{TEMPLATE:orchestration}` Output Structure):
-
 ```
 devflow/requirements/${REQ_ID}/
-├── BRAINSTORM.md ⭐ v2.1.0 新增
-├── research/ (初始化时生成)
+├── BRAINSTORM.md
+├── research/
 ├── PRD.md
-├── UI_PROTOTYPE.html (条件)
-├── TECH_DESIGN.md
-├── data-model.md
-├── contracts/openapi.yaml
-├── quickstart.md
+├── TECH_DESIGN.md                  # 若未跳过 tech
+├── UI_PROTOTYPE.html               # 若未跳过 ui 且识别到 UI 需求
 ├── EPIC.md
-├── TASKS.md (bite-sized, checkbox 标记)
-├── SPEC_REVIEW.md ⭐ v2.1.0 新增
-├── CODE_QUALITY_REVIEW.md ⭐ v2.1.0 新增
-├── TEST_PLAN.md + TEST_REPORT.md
-├── SECURITY_PLAN.md + SECURITY_REPORT.md
+├── TASKS.md
+├── SPEC_REVIEW.md                  # flow-quality --full
+├── CODE_QUALITY_REVIEW.md          # flow-quality --full
+├── SECURITY_REPORT.md              # flow-quality --full
 └── RELEASE_PLAN.md
 ```
 
@@ -368,74 +224,55 @@ devflow/requirements/${REQ_ID}/
 # 从中断点恢复
 /flow-restart "REQ-123"
 
-# 或手动执行特定阶段
-/flow-tech "REQ-123"
-/flow-epic "REQ-123"
+# 手动执行后续阶段
+/flow-spec "REQ-123"
 /flow-dev "REQ-123" --resume
+/flow-quality "REQ-123" --full
 ```
 
 ---
 
-## 错误处理
-
-**常见错误**:
-→ 详见 `{GUIDE:troubleshoot}`
-
-**主要错误场景**:
-1. Stage command not found → 检查命令文件
-2. Status file corrupted → 重建或修复
-3. 中途中断无法恢复 → 使用 /flow-restart
-4. UI detection false positive → 在PRD明确标注
-5. Epic 未覆盖所有技术层 → 重新生成或手动补充
-6. QA gate failure → 补充测试/修复安全问题
-7. Build failure → 修复类型错误
-8. PR creation failed → 认证 gh CLI 或手动创建
-
-**恢复步骤**:
-→ 详见 `{GUIDE:troubleshoot}` Recovery Procedures
-
----
-
 ## 使用建议
 
 ### ✅ 适合使用 flow-new
 
-- 简单明确的需求
-- 演示和学习工作流程
-- 快速原型开发
-- 熟悉的需求类型
+- 明确需求，需要一口气走完整条流水线
+- 团队希望减少阶段切换的上下文开销
+- 希望快速拿到可评审发布结果
 
 ### ❌ 建议使用阶段化命令
 
-- 复杂需求，需要每个阶段审查
-- 需要在PRD阶段与需求方确认
-- 需要在Epic阶段调整任务分解
-- 开发过程中可能需要暂停调整
+- 需求高度不确定，需频繁往返讨论
+- 规格阶段需要多人异步审阅
+- 开发阶段需要多次暂停/切换优先级
 
 ---
 
 ## Next Step
 
-```
-# 查看PR状态
+```bash
+# 查看 PR 状态
 cat devflow/requirements/${REQ_ID}/RELEASE_PLAN.md | grep "PR URL"
 
-# 审查PR
+# 审查 PR
 gh pr view <PR_NUMBER>
 
-# 合并PR
+# 合并 PR
 gh pr merge <PR_NUMBER>
 ```
 
 ---
 
 **Related Documentation**:
-- [NEW_ORCHESTRATION_TEMPLATE.md](../.claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md) - 详细编排流程
-- [NEW_TROUBLESHOOTING.md](../.claude/docs/guides/NEW_TROUBLESHOOTING.md) - 故障排查指南
-- [flow-init.md](./flow-init.md) - 初始化阶段 (含 Brainstorming)
-- [flow-review.md](./flow-review.md) - 代码审查阶段 ⭐ v2.1.0 新增
-- [flow-dev.md](./flow-dev.md) - 开发阶段 (TDD Checkpoint)
-- [flow-fix.md](./flow-fix.md) - Bug 修复流程 ⭐ v2.1.0 增强
+- [NEW_ORCHESTRATION_TEMPLATE.md](../../docs/templates/NEW_ORCHESTRATION_TEMPLATE.md) - 详细编排流程
+- [NEW_TROUBLESHOOTING.md](../../docs/guides/NEW_TROUBLESHOOTING.md) - 故障排查指南
+- [flow-init.md](./init.md) - 初始化阶段
+- [flow-clarify.md](./clarify.md) - 需求澄清阶段
+- [flow-spec.md](./spec.md) - 统一规格阶段
+- [flow-dev.md](./dev.md) - 开发阶段 (TDD)
+- [flow-quality.md](./quality.md) - 统一质量验证阶段
+- [flow-release.md](./release.md) - 发布阶段
+- [flow-fix.md](./fix.md) - Bug 修复流程
 
 ---
 

package/.claude/docs/templates/NEW_ORCHESTRATION_TEMPLATE.md

@@ -1,77 +1,50 @@
 # Flow-New Orchestration Template
 
-> Execution flow for `/flow-new` one-shot requirement development
+> Execution flow for `/flow-new` one-shot requirement development (v4.1)
 
 ---
 
 ## Stage Execution Skeleton
 
-### [1/8] /flow-init
+### [1/6] /flow-init
 - 创建需求目录 + Git 分支
-- MCP 研究材料收集 (mandatory)
-- Exit Gate: 5-level quality check (research.md 完整性)
-
-### [2/8] /flow-prd
-- 生成 PRD.md (用户故事 + GWT 验收标准)
-- Constitution 符合性检查
-
-### [2.3/8] /flow-checklist (可选, 80% 门禁)
-- 触发条件: `quality-rules.yml` 中 `checklist_gate_enabled: true`
-- 生成 checklists/*.md (5 维度质量验证)
-- 闸门: 完成度 ≥ 80%
-
-### [2.5/8] /flow-ui (条件触发)
-**UI Detection Logic** (JavaScript):
-```javascript
-function detectUIRequirement(prdContent, projectRoot) {
-  const uiKeywords = ['用户界面', '前端', 'Web页面', 'UI', '界面设计', '交互',
-                      '页面', '表单', '按钮', '导航', '布局', '组件'];
-  const hasUIKeywords = uiKeywords.some(kw => prdContent.includes(kw));
-  const hasFrontendStack = fs.existsSync(`${projectRoot}/package.json`);
-  const isBackendOnly = prdContent.includes('纯后端');
-  return (hasUIKeywords || hasFrontendStack) && !isBackendOnly;
-}
-```
-- 输出: UI_PROTOTYPE.html + research/ui_design_strategy.md
-- 跳过: orchestration_status.json.ui_skipped = true
+- 研究材料收集 + `BRAINSTORM.md` 初始化
+- Exit Gate: `orchestration_status.status == initialized`
 
-### [2.7/8] /flow-tech (必需)
-- 生成 TECH_DESIGN.md (7 sections: 架构/技术栈/数据模型/API/安全/性能/部署)
-- 输出: data-model.md + contracts/openapi.yaml + quickstart.md
-- Exit Gate: 所有 Section 1-7 完整
+### [2/6] /flow-clarify (可选)
+- 触发条件: 需求歧义、边界冲突、验收标准不明确
+- 输出: `clarifications/*.md`
+- 若跳过: 标记 `clarify_skipped: true`
 
-### [3/8] /flow-epic
-- Entry Gate: Checklist 完成度 ≥ 80% (如果启用)
-- 生成 EPIC.md + TASKS.md
-- 验证: TASKS 覆盖 TECH_DESIGN.md 所有技术层
+### [3/6] /flow-spec
+- 统一规格阶段: PRD → Tech+UI(并行) → Epic/TASKS
+- 支持模式: `--skip-tech` / `--skip-ui`
+- Exit Gate: 规格产物完整，`status = spec_complete`
 
-### [4/8] /flow-dev
+### [4/6] /flow-dev
 **TDD 执行模式**:
 ```
 Phase 1: 分析现有代码
 Phase 2: 编写测试 (Tests First)
   ↓
-TEST VERIFICATION CHECKPOINT → 测试必须先失败
+TDD CHECKPOINT → 测试必须先失败
   ↓
 Phase 3: 实现代码
 Phase 4: 测试验证 → 测试必须通过
-Phase 5: Git 提交并标记完成
 ```
-- 输出: 实现代码 + 测试代码 + TASKS.md 更新 (checkbox 标记)
-
-### [5/8] /flow-qa --full
-**Exit Gate 检查**:
-- ✅ 所有测试通过
-- ✅ 代码覆盖率 ≥ 80%
-- ✅ 无高危安全问题
-- ✅ TypeScript 类型检查通过
-- 输出: TEST_REPORT.md + SECURITY_REPORT.md
-
-### [6/8] /flow-release
-- 生成 RELEASE_PLAN.md
-- 更新 CLAUDE.md (如有架构变更)
-- 最终构建
-- 创建 GitHub Pull Request
+- 输出: 实现代码 + 测试代码 + `TASKS.md` 勾选更新
+
+### [5/6] /flow-quality --full
+**统一质量验证**:
+- 规格合规审查
+- 代码质量审查
+- 安全扫描与测试门禁
+- 输出: `SPEC_REVIEW.md`, `CODE_QUALITY_REVIEW.md`, `SECURITY_REPORT.md`
+
+### [6/6] /flow-release
+- 生成 `RELEASE_PLAN.md`
+- 执行发布分支策略（PR/merge/squash 等）
+- 必要时更新 `CLAUDE.md`
 
 ---
 
@@ -83,65 +56,52 @@ Phase 5: Git 提交并标记完成
 
 需求: REQ-123 | 支持用户下单
 
-[1/8] ✅ 初始化完成
-[2/8] ✅ PRD生成完成
-[2.5/8] ✅ UI原型生成完成 ⚡️
-[2.7/8] ✅ 技术方案设计完成 🔧
-[3/8] ✅ Epic规划完成
-[4/8] 🔄 开发执行中... (8/18 已完成)
-[5/8] ⏳ 等待质量保证...
-[6/8] ⏳ 等待发布管理...
+[1/6] ✅ 初始化完成
+[2/6] ✅ 澄清完成 (可选)
+[3/6] ✅ 统一规格完成
+[4/6] 🔄 开发执行中... (8/18 已完成)
+[5/6] ⏳ 等待质量验证...
+[6/6] ⏳ 等待发布管理...
 ```
 
-**状态图标**:
-- ✅ 已完成
-- 🔄 执行中
-- ⏳ 等待执行
-- ⚡️ 条件触发已执行
-- 🔧 必需步骤已完成
-
 ---
 
 ## Output Structure
 
 ```
 devflow/requirements/${REQ_ID}/
-├── research/                     # [1/8]
-├── PRD.md                        # [2/8]
-├── checklists/*.md               # [2.3/8] (可选)
-├── UI_PROTOTYPE.html             # [2.5/8] (条件)
-├── TECH_DESIGN.md                # [2.7/8]
-├── data-model.md
-├── contracts/openapi.yaml
-├── quickstart.md
-├── EPIC.md                       # [3/8]
-├── TASKS.md                      # [4/8] (checkbox 标记任务完成状态)
-├── TEST_REPORT.md                # [5/8]
-├── SECURITY_REPORT.md
-└── RELEASE_PLAN.md               # [6/8]
+├── BRAINSTORM.md
+├── research/
+├── clarifications/                # 可选
+├── PRD.md
+├── TECH_DESIGN.md                 # 若未跳过 tech
+├── UI_PROTOTYPE.html              # 若未跳过 ui 且识别到 UI 需求
+├── EPIC.md
+├── TASKS.md
+├── SPEC_REVIEW.md                 # flow-quality --full
+├── CODE_QUALITY_REVIEW.md         # flow-quality --full
+├── SECURITY_REPORT.md             # flow-quality --full
+└── RELEASE_PLAN.md
 ```
 
 ---
 
 ## Status Tracking
 
-**orchestration_status.json 关键字段**:
+**orchestration_status.json 推荐字段**:
 ```json
 {
   "status": "dev_complete",
   "phase": "execution",
-  "phase0_complete": true,
-  "prd_complete": true,
-  "checklist_complete": true,    // 如果启用
-  "ui_skipped": false,            // 或 ui_complete: true
-  "tech_design_complete": true,
-  "epic_complete": true,
+  "initialized": true,
+  "clarify_complete": true,
+  "spec_complete": true,
   "dev_complete": true,
-  "qa_complete": false,
+  "quality_complete": false,
   "release_complete": false
 }
 ```
 
 ---
 
-**Last Updated**: 2025-12-19
+**Last Updated**: 2026-02-07

package/.claude/skills/workflow/flow-init/scripts/check-prerequisites.sh

@@ -85,7 +85,15 @@ done
 
 # Source common functions
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
+COMMON_SH="$SCRIPT_DIR/common.sh"
+if [[ ! -f "$COMMON_SH" ]]; then
+    COMMON_SH="$SCRIPT_DIR/../../../../scripts/common.sh"
+fi
+if [[ ! -f "$COMMON_SH" ]]; then
+    echo "ERROR: common.sh not found (checked local + .claude/scripts)" >&2
+    exit 1
+fi
+source "$COMMON_SH"
 
 # Get requirement paths
 eval $(get_requirement_paths)
@@ -229,4 +237,4 @@ else
         check_file "$ANALYSIS_FILE" "ANALYSIS.md"
         check_file "$PLAN_FILE" "PLAN.md"
     fi
-fi
+fi

package/.claude/skills/workflow/flow-init/scripts/create-requirement.sh

@@ -173,7 +173,15 @@ done
 
 # Source common functions
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
+COMMON_SH="$SCRIPT_DIR/common.sh"
+if [[ ! -f "$COMMON_SH" ]]; then
+    COMMON_SH="$SCRIPT_DIR/../../../../scripts/common.sh"
+fi
+if [[ ! -f "$COMMON_SH" ]]; then
+    echo "ERROR: common.sh not found (checked local + .claude/scripts)" >&2
+    exit 1
+fi
+source "$COMMON_SH"
 REPO_ROOT=$(get_repo_root)
 
 # Interactive mode

package/.claude/skills/workflow/flow-init/scripts/validate-research.sh

@@ -28,7 +28,15 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
 # shellcheck source=.claude/scripts/common.sh
-source "$SCRIPT_DIR/common.sh"
+COMMON_SH="$SCRIPT_DIR/common.sh"
+if [[ ! -f "$COMMON_SH" ]]; then
+  COMMON_SH="$SCRIPT_DIR/../../../../scripts/common.sh"
+fi
+if [[ ! -f "$COMMON_SH" ]]; then
+  echo "ERROR: common.sh not found (checked local + .claude/scripts)" >&2
+  exit 1
+fi
+source "$COMMON_SH"
 
 STRICT_MODE=false
 

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [4.1.1] - 2026-02-07
+
+### 🔧 Flow-Init Script Reliability + Flow Docs Alignment
+
+v4.1.1 focuses on execution reliability for embedded flow-init scripts and removes stale command guidance from flow documentation.
+
+#### Fixed
+
+- **Flow-Init embedded scripts** now resolve shared `common.sh` safely
+  - Added fallback loading path from `skills/workflow/flow-init/scripts/*` to `.claude/scripts/common.sh`
+  - Prevents runtime failure when running bundled scripts directly from skill directories
+  - Affects:
+    - `check-prerequisites.sh`
+    - `create-requirement.sh`
+    - `validate-research.sh`
+
+#### Changed
+
+- **Flow command docs aligned with actual v4.1 workflow**
+  - Updated `/flow-new` orchestration to `flow-init → flow-clarify(optional) → flow-spec → flow-dev → flow-quality → flow-release`
+  - Removed outdated references to deprecated `/flow-review` and `/flow-qa` in active workflow guidance
+  - Synced bilingual README command links to namespace paths under `.claude/commands/flow/`
+
+#### Maintenance
+
+- **Lockfile metadata synchronized**
+  - Normalized `package-lock.json` package version markers to match `package.json`
+
+#### Benefits
+
+- ✅ `flow-init` script execution no longer fails due to missing local `common.sh`
+- ✅ Command docs now map to real command files and current workflow semantics
+- ✅ Release metadata consistency improved for publish pipeline
+
+
 ## [4.1.0] - 2026-02-07
 
 ### 🤖 Claude Team Integration: Multi-Agent Parallel Collaboration

package/README.md

@@ -262,14 +262,13 @@ bash .claude/tests/constitution/run_all_constitution_tests.sh
 |---------|---------|---------------|---------------|
 | `/flow-new` | 🎯 Start New Requirement | `/flow-new "REQ-123\|Feature"` | [→](docs/commands/flow-new.md) |
 | `/flow-init` | 📦 Initialize Requirement | `/flow-init "REQ-123\|Feature"` | [→](docs/commands/flow-init.md) |
-| `/flow-clarify` | 🔎 Clarify Ambiguities | `/flow-clarify "REQ-123"` | [→](.claude/commands/flow-clarify.md) |
-| `/flow-spec` | 📋 Unified Specification (v4.1) | `/flow-spec "REQ-123"` | [→](.claude/commands/flow-spec.md) |
-| `/flow-checklist` | ✅ Requirement Quality Check | `/flow-checklist --type ux` | [→](.claude/commands/flow-checklist.md) |
-| `/flow-review` | �� Two-Stage Code Review | `/flow-review "REQ-123"` | [→](.claude/commands/flow-review.md) |
-| `/flow-fix` | 🐛 Systematic Bug Fix | `/flow-fix "BUG-123\|Description"` | [→](.claude/commands/flow-fix.md) |
-| `/flow-verify` | 🔍 Verify Consistency | `/flow-verify "REQ-123"` | [→](docs/commands/flow-verify.md) |
-| `/flow-qa` | 🧪 Quality Assurance | `/flow-qa "REQ-123"` | [→](docs/commands/flow-qa.md) |
-| `/flow-release` | 🚢 Create Release | `/flow-release "REQ-123"` | [→](docs/commands/flow-release.md) |
+| `/flow-clarify` | 🔎 Clarify Ambiguities | `/flow-clarify "REQ-123"` | [→](.claude/commands/flow/clarify.md) |
+| `/flow-spec` | 📋 Unified Specification (v4.1) | `/flow-spec "REQ-123"` | [→](.claude/commands/flow/spec.md) |
+| `/flow-checklist` | ✅ Requirement Quality Check | `/flow-checklist --type ux` | [→](.claude/commands/flow/checklist.md) |
+| `/flow-quality` | ✅ Combined Quality Verification | `/flow-quality "REQ-123" --full` | [→](.claude/commands/flow/quality.md) |
+| `/flow-fix` | 🐛 Systematic Bug Fix | `/flow-fix "BUG-123\|Description"` | [→](.claude/commands/flow/fix.md) |
+| `/flow-verify` | 🔍 Verify Consistency | `/flow-verify "REQ-123"` | [→](.claude/commands/flow/verify.md) |
+| `/flow-release` | 🚢 Create Release | `/flow-release "REQ-123"` | [→](.claude/commands/flow/release.md) |
 
 📚 [Complete Command Reference](docs/commands/README.md)
 
@@ -288,7 +287,7 @@ Your Scenario:
 ├─ Continue interrupted development? → /flow-restart "REQ-123"
 ├─ Check development progress? → /flow-status REQ-123
 ├─ Found document inconsistencies? → /flow-verify "REQ-123"
-├─ Development complete, need testing? → /flow-qa "REQ-123"
+├─ Development complete, need verification? → /flow-quality "REQ-123" --full
 ├─ Fix production bug? → /flow-fix "BUG-001|Description"
 └─ Ready to release? → /flow-release "REQ-123"
 ```
@@ -322,11 +321,9 @@ graph TB
 
     FlowSpec --> FlowDev["/flow-dev<br/>TASKS.md execution<br/>TDD Checkpoint"]
 
-    FlowDev --> FlowReview["/flow-review<br/>Two-Stage Review<br/>Spec → Quality"]
+    FlowDev --> FlowQuality["/flow-quality<br/>Quick/Full Verification<br/>Spec + Quality + Security"]
 
-    FlowReview --> FlowQA["/flow-qa<br/>QA reports & Security"]
-
-    FlowQA --> FlowRelease["/flow-release<br/>PR creation<br/>Branch decision"]
+    FlowQuality --> FlowRelease["/flow-release<br/>PR creation<br/>Branch decision"]
 
     FlowRelease --> FlowVerify["/flow-verify<br/>Consistency check"]
 
@@ -340,8 +337,7 @@ graph TB
     style FlowClarify fill:#fff9c4
     style FlowSpec fill:#e8f5e9
     style FlowDev fill:#f3e5f5
-    style FlowReview fill:#e1bee7
-    style FlowQA fill:#fce4ec
+    style FlowQuality fill:#e1bee7
     style FlowRelease fill:#e0f2f1
     style FlowVerify fill:#e3f2fd
 ```
@@ -351,7 +347,7 @@ graph TB
 - **Requirement-Level Commands** (light orange): Execute once per requirement (REQ-XXX)
 - **Unified /flow-spec** (v4.1): Replaces flow-prd/flow-tech/flow-ui/flow-epic with parallel execution
 - **Brainstorming** (v2.3.0): `/flow-init` now generates `BRAINSTORM.md` as requirement "North Star"
-- **Two-Stage Review** (v2.3.0): `/flow-review` validates Spec Compliance before Code Quality
+- **Unified Quality Verification** (v3.0.0): `/flow-quality --full` combines spec compliance, code quality, and security
 - **Optional Steps** (yellow): `/flow-clarify` is optional; skip if requirements are clear
 - **TDD Checkpoint** (v2.3.0): `/flow-dev` includes mandatory TDD checkpoint (tests must FAIL first)
 - **Quality Gates**: Each stage has entry/exit gates ensuring document quality and Constitution compliance
@@ -713,7 +709,7 @@ v2.3.0 upgrades the Constitution from a "document" to an "executable discipline
 - Cross-reference to `rationalization-library.md`
 
 **📁 New Files**:
-- `.claude/commands/cancel-ralph.md` - Cancel Ralph loop command
+- `.claude/commands/util/cancel-ralph.md` - Cancel Ralph loop command
 - `.claude/skills/flow-attention-refresh/SKILL.md` - 4 attention refresh protocols
 - `.claude/hooks/ralph-stop-hook.sh` - Stop Hook for self-referential loops
 - `.claude/hooks/hooks.json` - Hook registration configuration
@@ -722,7 +718,7 @@ v2.3.0 upgrades the Constitution from a "document" to an "executable discipline
 - `.claude/docs/templates/ATTEMPT_TEMPLATE.md` - Research attempt log format
 - `.claude/agents/spec-reviewer.md` - Stage 1 spec compliance reviewer
 - `.claude/agents/code-quality-reviewer.md` - Stage 2 code quality reviewer
-- `.claude/commands/flow-review.md` - Two-stage review command
+- `.claude/commands/flow-review.md` - Two-stage review command (legacy, replaced by `.claude/commands/flow/quality.md`)
 - `.claude/rules/rationalization-library.md` - Centralized rationalization defense
 - `.claude/scripts/verify-gate.sh` - Exit gate verification script
 - `.claude/skills/flow-brainstorming/` - Brainstorming skill

package/README.zh-CN.md

@@ -256,12 +256,13 @@ bash .claude/tests/constitution/run_all_constitution_tests.sh
 |------|------|----------|----------|
 | `/flow-new` | 🎯 启动新需求 | `/flow-new "REQ-123\|功能"` | [→](docs/commands/flow-new.zh-CN.md) |
 | `/flow-init` | 📦 初始化需求 | `/flow-init "REQ-123\|功能"` | [→](docs/commands/flow-init.zh-CN.md) |
-| `/flow-clarify` | 🔎 澄清歧义 | `/flow-clarify "REQ-123"` | [→](.claude/commands/flow-clarify.md) |
-| `/flow-spec` | 📋 统一规格阶段 (v4.1) | `/flow-spec "REQ-123"` | [→](.claude/commands/flow-spec.md) |
-| `/flow-checklist` | ✅ 需求质量检查 | `/flow-checklist --type ux` | [→](.claude/commands/flow-checklist.md) |
-| `/flow-verify` | 🔍 验证一致性 | `/flow-verify "REQ-123"` | [→](docs/commands/flow-verify.zh-CN.md) |
-| `/flow-qa` | 🧪 质量保证 | `/flow-qa "REQ-123"` | [→](docs/commands/flow-qa.zh-CN.md) |
-| `/flow-release` | 🚢 创建发布 | `/flow-release "REQ-123"` | [→](docs/commands/flow-release.zh-CN.md) |
+| `/flow-clarify` | 🔎 澄清歧义 | `/flow-clarify "REQ-123"` | [→](.claude/commands/flow/clarify.md) |
+| `/flow-spec` | 📋 统一规格阶段 (v4.1) | `/flow-spec "REQ-123"` | [→](.claude/commands/flow/spec.md) |
+| `/flow-checklist` | ✅ 需求质量检查 | `/flow-checklist --type ux` | [→](.claude/commands/flow/checklist.md) |
+| `/flow-quality` | ✅ 统一质量验证 | `/flow-quality "REQ-123" --full` | [→](.claude/commands/flow/quality.md) |
+| `/flow-fix` | 🐛 系统化缺陷修复 | `/flow-fix "BUG-123\|描述"` | [→](.claude/commands/flow/fix.md) |
+| `/flow-verify` | 🔍 验证一致性 | `/flow-verify "REQ-123"` | [→](.claude/commands/flow/verify.md) |
+| `/flow-release` | 🚢 创建发布 | `/flow-release "REQ-123"` | [→](.claude/commands/flow/release.md) |
 
 📚 [完整命令参考](docs/commands/README.zh-CN.md)
 
@@ -281,7 +282,7 @@ bash .claude/tests/constitution/run_all_constitution_tests.sh
 ├─ 开发中断需要继续？ → /flow-restart "REQ-123"
 ├─ 检查开发进度？ → /flow-status REQ-123
 ├─ 发现文档不一致？ → /flow-verify "REQ-123"
-├─ 开发完成需要测试？ → /flow-qa "REQ-123"
+├─ 开发完成需要验证？ → /flow-quality "REQ-123" --full
 ├─ 修复生产 Bug？ → /flow-fix "BUG-001|描述"
 └─ 准备发布？ → /flow-release "REQ-123"
 ```
@@ -315,9 +316,9 @@ graph TB
 
     FlowSpec --> FlowDev["/flow-dev<br/>TASKS.md 执行<br/>TDD 强制"]
 
-    FlowDev --> FlowQA["/flow-qa<br/>QA 报告 & 安全审查"]
+    FlowDev --> FlowQuality["/flow-quality<br/>快速/完整验证<br/>规格 + 质量 + 安全"]
 
-    FlowQA --> FlowRelease["/flow-release<br/>PR 创建 & 部署"]
+    FlowQuality --> FlowRelease["/flow-release<br/>PR 创建 & 部署"]
 
     FlowRelease --> FlowVerify["/flow-verify<br/>一致性检查"]
 
@@ -331,7 +332,7 @@ graph TB
     style FlowClarify fill:#fff9c4
     style FlowSpec fill:#e8f5e9
     style FlowDev fill:#f3e5f5
-    style FlowQA fill:#fce4ec
+    style FlowQuality fill:#fce4ec
     style FlowRelease fill:#e0f2f1
     style FlowVerify fill:#e3f2fd
 ```
@@ -340,6 +341,7 @@ graph TB
 - **项目级命令**（浅蓝色）：项目初始化时执行一次，建立全局标准（SSOT）
 - **需求级命令**（浅橙色）：每个需求（REQ-XXX）执行一次
 - **统一 /flow-spec** (v4.1)：替代 flow-prd/flow-tech/flow-ui/flow-epic，支持并行执行
+- **统一质量验证** (v3.0.0)：`/flow-quality --full` 合并规格合规、代码质量与安全检查
 - **可选步骤**（黄色）：`/flow-clarify` 为可选步骤，需求清晰时可跳过
 - **质量闸门**：每个阶段都有入口/出口闸门，确保文档质量和 Constitution 合规性
 - **TDD 强制执行**：`/flow-dev` 严格强制执行测试驱动开发顺序
@@ -701,7 +703,7 @@ v2.3.0 将 Constitution 从"文档"升级为"可执行纪律系统"，借鉴 sup
 - 交叉引用到 `rationalization-library.md`
 
 **📁 新增文件**:
-- `.claude/commands/cancel-ralph.md` - 取消 Ralph 循环命令
+- `.claude/commands/util/cancel-ralph.md` - 取消 Ralph 循环命令
 - `.claude/skills/flow-attention-refresh/SKILL.md` - 4 个注意力刷新协议
 - `.claude/hooks/ralph-stop-hook.sh` - 自引用循环 Stop Hook
 - `.claude/hooks/hooks.json` - Hook 注册配置
@@ -710,7 +712,7 @@ v2.3.0 将 Constitution 从"文档"升级为"可执行纪律系统"，借鉴 sup
 - `.claude/docs/templates/ATTEMPT_TEMPLATE.md` - 研究尝试日志格式
 - `.claude/agents/spec-reviewer.md` - 阶段 1 规格合规性审查员
 - `.claude/agents/code-quality-reviewer.md` - 阶段 2 代码质量审查员
-- `.claude/commands/flow-review.md` - 两阶段审查命令
+- `.claude/commands/flow-review.md` - 两阶段审查命令（legacy，已由 `.claude/commands/flow/quality.md` 取代）
 - `.claude/rules/rationalization-library.md` - 集中式合理化防御
 - `.claude/scripts/verify-gate.sh` - 出口闸门验证脚本
 - `.claude/skills/flow-brainstorming/` - 头脑风暴技能

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.1.0",
+    "version": "4.1.1",
     "description": "DevFlow CLI tool",
     "main": "bin/cc-devflow.js",
     "bin": {