cc-devflow 4.1.5 → 4.2.0

package/bin/cc-devflow-cli.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+/**
+ * [INPUT]: 依赖 .claude 模板、adapt 编译入口与 harness 运行时入口。
+ * [OUTPUT]: 提供 init/adapt/harness 命令，并在目标仓库自动补齐 harness npm scripts。
+ * [POS]: cc-devflow 的统一 CLI 门面，串联安装、编译与运行时发布链路。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
@@ -7,6 +13,17 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, '.claude');
 const ADAPT_BIN = path.join(PACKAGE_ROOT, 'bin', 'adapt.js');
 const ADAPTER_BIN = path.join(PACKAGE_ROOT, 'bin', 'cc-devflow.js');
+const HARNESS_BIN = path.join(PACKAGE_ROOT, 'bin', 'harness.js');
+const HARNESS_SCRIPT_COMMANDS = {
+  'harness:init': 'init',
+  'harness:pack': 'pack',
+  'harness:plan': 'plan',
+  'harness:dispatch': 'dispatch',
+  'harness:verify': 'verify',
+  'harness:release': 'release',
+  'harness:resume': 'resume',
+  'harness:janitor': 'janitor'
+};
 
 function showHelp() {
   console.log(`
@@ -15,6 +32,7 @@ Usage: cc-devflow <command> [options]
 Commands:
   init                Install .claude template into a project
   adapt               Compile .claude into multi-platform outputs
+  harness             Run harness runtime commands (init/verify/release/janitor...)
 
 Init options:
   --dir <path>         Target project path (default: cwd)
@@ -34,6 +52,7 @@ Examples:
   cc-devflow init --dir /path/to/project
   cc-devflow adapt --platform cursor
   cc-devflow adapt --cwd /path/to/project --platform codex
+  cc-devflow harness release --change-id REQ-123
 `);
 }
 
@@ -122,6 +141,114 @@ function copyIncremental(src, dest) {
   }
 }
 
+function detectJsonIndent(content) {
+  const match = content.match(/\n([ \t]+)"[^"\n]+":/);
+  if (!match) {
+    return 2;
+  }
+
+  const indent = match[1];
+  return indent.includes('\t') ? '\t' : indent.length;
+}
+
+function hasLocalHarnessBinary(targetRoot) {
+  return fs.existsSync(path.join(targetRoot, 'bin', 'harness.js'));
+}
+
+function getHarnessScriptCommand(targetRoot, subcommand) {
+  if (hasLocalHarnessBinary(targetRoot)) {
+    return `node bin/harness.js ${subcommand}`;
+  }
+  return `cc-devflow harness ${subcommand}`;
+}
+
+function ensureHarnessScripts(targetRoot) {
+  const pkgPath = path.join(targetRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    console.warn(`[WARN] Missing package.json in ${targetRoot}; skipping harness script bootstrap.`);
+    return;
+  }
+
+  let raw;
+  let packageJson;
+  try {
+    raw = fs.readFileSync(pkgPath, 'utf8');
+    packageJson = JSON.parse(raw);
+  } catch (error) {
+    console.warn(`[WARN] Skipping harness script bootstrap: cannot parse package.json (${error.message})`);
+    return;
+  }
+
+  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    console.warn('[WARN] Skipping harness script bootstrap: package.json root must be an object.');
+    return;
+  }
+
+  if (!packageJson.scripts || typeof packageJson.scripts !== 'object' || Array.isArray(packageJson.scripts)) {
+    packageJson.scripts = {};
+  }
+
+  const hasLocalBinary = hasLocalHarnessBinary(targetRoot);
+  const added = [];
+  const repaired = [];
+  let changed = false;
+
+  for (const [scriptName, subcommand] of Object.entries(HARNESS_SCRIPT_COMMANDS)) {
+    const desired = getHarnessScriptCommand(targetRoot, subcommand);
+    const existing = packageJson.scripts[scriptName];
+
+    if (typeof existing === 'undefined') {
+      packageJson.scripts[scriptName] = desired;
+      added.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    if (typeof existing !== 'string') {
+      continue;
+    }
+
+    // Auto-repair legacy value when local harness binary does not exist.
+    if (!hasLocalBinary && existing.trim() === `node bin/harness.js ${subcommand}`) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    // Auto-repair previous injected npx-based value to deterministic runtime path.
+    if (!hasLocalBinary && existing.trim() === `npx --yes cc-devflow harness ${subcommand}`) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+      continue;
+    }
+
+    // Auto-repair previous absolute-path fallback value (not portable across machines).
+    const escapedHarnessBin = HARNESS_BIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const absoluteLegacy = new RegExp(`^node\\s+["']?${escapedHarnessBin}["']?\\s+${subcommand}(\\s*\\|\\|\\s*cc-devflow\\s+harness\\s+${subcommand})?$`);
+    if (!hasLocalBinary && absoluteLegacy.test(existing.trim())) {
+      packageJson.scripts[scriptName] = desired;
+      repaired.push(scriptName);
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return;
+  }
+
+  const indent = detectJsonIndent(raw);
+  fs.writeFileSync(pkgPath, `${JSON.stringify(packageJson, null, indent)}\n`);
+
+  if (added.length > 0) {
+    console.log(`[UPDATE] package.json (added ${added.join(', ')})`);
+  }
+  if (repaired.length > 0) {
+    console.log(`[UPDATE] package.json (repaired ${repaired.join(', ')})`);
+  }
+}
+
 function runInit(args) {
   const { options } = parseCliArgs(args);
 
@@ -141,6 +268,7 @@ function runInit(args) {
   // Case 1: Directory does not exist - Clean Install
   if (!fs.existsSync(targetDir)) {
     fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+    ensureHarnessScripts(targetRoot);
     console.log(`Initialized .claude in ${targetRoot}`);
     return 0;
   }
@@ -150,6 +278,7 @@ function runInit(args) {
     console.log('Force flag detected. Resetting .claude directory...');
     fs.rmSync(targetDir, { recursive: true, force: true });
     fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+    ensureHarnessScripts(targetRoot);
     console.log(`Re-initialized .claude in ${targetRoot}`);
     return 0;
   }
@@ -157,6 +286,7 @@ function runInit(args) {
   // Case 3: Directory exists - Incremental Update
   console.log(`Target ${targetDir} already exists. Performing incremental update...`);
   copyIncremental(TEMPLATE_DIR, targetDir);
+  ensureHarnessScripts(targetRoot);
   console.log('Incremental update complete. Existing files were preserved.');
   return 0;
 }
@@ -178,6 +308,8 @@ function runAdapt(args) {
     return 1;
   }
 
+  ensureHarnessScripts(targetRoot);
+
   const result = spawnSync(process.execPath, [ADAPT_BIN, ...rest], {
     stdio: 'inherit',
     cwd: targetRoot
@@ -191,6 +323,24 @@ function runAdapt(args) {
   return typeof result.status === 'number' ? result.status : 1;
 }
 
+function runHarness(args) {
+  const { options, rest } = parseCliArgs(args);
+
+  const targetRoot = path.resolve(options.cwd || process.cwd());
+  const cliArgs = options.help || rest.length === 0 ? ['--help'] : rest;
+  const result = spawnSync(process.execPath, [HARNESS_BIN, ...cliArgs], {
+    stdio: 'inherit',
+    cwd: targetRoot
+  });
+
+  if (result.error) {
+    console.error(`Failed to run harness: ${result.error.message}`);
+    return 1;
+  }
+
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
 function runAdapter(command, args) {
   const result = spawnSync(process.execPath, [ADAPTER_BIN, command, ...args], {
     stdio: 'inherit'
@@ -221,6 +371,10 @@ function main() {
     return runAdapt(rest);
   }
 
+  if (command === 'harness') {
+    return runHarness(rest);
+  }
+
   return runAdapter(command, rest);
 }
 

package/bin/harness.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * [INPUT]: 依赖 lib/harness/cli 的 runCli 函数与 shell argv。
+ * [OUTPUT]: 将 harness 子命令分发到内核，并用 exit code 返回执行结果。
+ * [POS]: Harness 命令行入口，被 npm scripts(harness:*) 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { runCli } = require('../lib/harness/cli');
+
+async function main() {
+  try {
+    const code = await runCli(process.argv.slice(2));
+    process.exit(code);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/docs/commands/README.md

@@ -4,54 +4,50 @@
 
 ---
 
-## 🎯 Requirement Management Commands
+## 🎯 Requirement Commands
 
 | Command | Purpose | Quick Example | Detailed Docs |
 |---------|---------|---------------|---------------|
-| `/flow-new` | 🚀 Start New Requirement Development | `/flow-new "REQ-123\|Feature"` | [→](./flow-new.md) |
-| `/flow-init` | 📦 Initialize Requirement Structure | `/flow-init "REQ-123\|Feature"` | [→](./flow-init.md) |
-| `/flow-status` | 📊 Query Development Progress | `/flow-status REQ-123` | [→](./flow-status.md) |
-| `/flow-restart` | 🔄 Resume Interrupted Development | `/flow-restart "REQ-123"` | [→](./flow-restart.md) |
-| `/flow-update` | ✅ Update Task Progress | `/flow-update "REQ-123" "T001"` | [→](./flow-update.md) |
-
-## 🏗️ Architecture Design Commands
-
-| Command | Purpose | Quick Example | Detailed Docs |
-|---------|---------|---------------|---------------|
-| `/core-roadmap` | 🗺️ Generate Product Roadmap | `/core-roadmap` | [→](./core-roadmap.md) |
-| `/core-architecture` | 🏛️ Generate System Architecture | `/core-architecture` | [→](./core-architecture.md) |
-| `/core-guidelines` | 📘 Generate Project Guidelines | `/core-guidelines` | [→](./core-guidelines.md) |
-
-## 🧪 Quality Assurance Commands
+| `/flow:init` | 📦 Initialize requirement context | `/flow:init "REQ-123\|Feature"` | [→](../../.claude/commands/flow/init.md) |
+| `/flow:spec` | 📋 Generate task-manifest | `/flow:spec "REQ-123"` | [→](../../.claude/commands/flow/spec.md) |
+| `/flow:dev` | 🛠️ Dispatch or resume task execution | `/flow:dev "REQ-123" --resume` | [→](../../.claude/commands/flow/dev.md) |
+| `/flow:verify` | ✅ Quick/strict quality gates | `/flow:verify "REQ-123" --strict` | [→](../../.claude/commands/flow/verify.md) |
+| `/flow:release` | 🚢 Release + runtime cleanup | `/flow:release "REQ-123"` | [→](../../.claude/commands/flow/release.md) |
+| `/flow:status` | 📊 Query progress snapshot | `/flow:status REQ-123` | [→](../../.claude/commands/flow/status.md) |
+| `/flow:restart` | 🔄 Recover interrupted workflow | `/flow:restart "REQ-123" --from=dev` | [→](../../.claude/commands/flow/restart.md) |
+| `/flow:update` | ✅ Update task progress | `/flow:update "REQ-123" "T001"` | [→](../../.claude/commands/flow/update.md) |
+| `/flow:fix` | 🐛 Bug fix workflow | `/flow:fix "BUG-001\|Description"` | [→](../../.claude/commands/flow/fix.md) |
+
+## ⚠️ Deprecated Commands
+
+| Deprecated | Migration |
+|------------|-----------|
+| `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
+| `/flow:clarify` | Use `/flow:spec` |
+| `/flow:checklist` | Use `/flow:verify --strict` |
+| `/flow:quality` | Use `/flow:verify` |
+
+## 🏗️ Core Commands
 
 | Command | Purpose | Quick Example | Detailed Docs |
 |---------|---------|---------------|---------------|
-| `/flow-checklist` | ✅ Requirement Quality Check | `/flow-checklist --type ux` | [→](../../.claude/commands/flow-checklist.md) |
-| `/flow-verify` | 🔍 Verify Document Consistency | `/flow-verify "REQ-123"` | [→](./flow-verify.md) |
-| `/flow-qa` | 🧪 Execute Quality Assurance | `/flow-qa "REQ-123"` | [→](./flow-qa.md) |
-| `/flow-constitution` | 📜 Constitution Compliance | `/flow-constitution --verify` | [→](./flow-constitution.md) |
-
-## 🛠️ Tool Commands
-
-| Command | Purpose | Quick Example | Detailed Docs |
-|---------|---------|---------------|---------------|
-| `/flow-fix` | 🐛 Bug Fix Flow | `/flow-fix "BUG-001\|Description"` | [→](./flow-fix.md) |
-| `/flow-release` | 🚢 Create Release | `/flow-release "REQ-123"` | [→](./flow-release.md) |
+| `/core:roadmap` | 🗺️ Generate product roadmap | `/core:roadmap` | [→](./core-roadmap.md) |
+| `/core:architecture` | 🏛️ Generate system architecture | `/core:architecture` | [→](./core-architecture.md) |
+| `/core:guidelines` | 📘 Generate project guidelines | `/core:guidelines` | [→](./core-guidelines.md) |
+| `/core:style` | 🎨 Generate style system guide | `/core:style` | [→](./core-style.md) |
 
 ## 🎯 Quick Selection Guide
 
-```
+```text
 Your Scenario:
-├─ Start brand new feature? → /flow-new "REQ-123|Feature"
-├─ Plan product direction? → /core-roadmap
-├─ Design system architecture? → /core-architecture
-├─ Validate requirement quality? → /flow-checklist --type ux,api,security
-├─ Continue interrupted development? → /flow-restart "REQ-123"
-├─ Check development progress? → /flow-status REQ-123
-├─ Found document conflicts? → /flow-verify "REQ-123"
-├─ Development complete, test? → /flow-qa "REQ-123"
-├─ Fix production bug? → /flow-fix "BUG-001|Description"
-└─ Ready to release? → /flow-release "REQ-123"
+├─ Start requirement delivery? → /flow:init "REQ-123|Feature|URLs"
+├─ Need executable plan? → /flow:spec "REQ-123"
+├─ Need implementation/resume? → /flow:dev "REQ-123" [--resume]
+├─ Need release gates? → /flow:verify "REQ-123" --strict
+├─ Ready to ship? → /flow:release "REQ-123"
+├─ Check progress? → /flow:status REQ-123
+├─ Fix production bug? → /flow:fix "BUG-001|Description"
+└─ Project-level planning? → /core:roadmap /core:architecture /core:guidelines
 ```
 
 ## 📚 Related Documentation

package/docs/commands/README.zh-CN.md

@@ -1,51 +1,49 @@
 # 📋 命令参考文档
 
-## 🎯 需求管理命令
+## 🎯 需求命令
 
 | 命令 | 用途 | 快速示例 |
 |------|------|----------|
-| `/flow-new` | 🚀 启动新需求开发 | `/flow-new "REQ-123|功能"` → [详细文档](./flow-new.md) |
-| `/flow-init` | 📦 初始化需求结构 | `/flow-init "REQ-123|功能"` → [详细文档](./flow-init.md) |
-| `/flow-status` | 📊 查询开发进度 | `/flow-status REQ-123` → [详细文档](./flow-status.md) |
-| `/flow-restart` | 🔄 恢复中断的开发 | `/flow-restart "REQ-123"` → [详细文档](./flow-restart.md) |
-| `/flow-update` | ✅ 更新任务进度 | `/flow-update "REQ-123" "T001"` → [详细文档](./flow-update.md) |
-
-## 🏗️ 架构设计命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/core-roadmap` | 🗺️ 生成产品路线图 | `/core-roadmap` → [详细文档](./core-roadmap.md) |
-| `/core-architecture` | 🏛️ 生成系统架构 | `/core-architecture` → [详细文档](./core-architecture.md) |
-| `/core-guidelines` | 📘 生成项目规范 | `/core-guidelines` → [详细文档](./core-guidelines.md) |
-
-## 🧪 质量保证命令
+| `/flow:init` | 📦 初始化需求上下文 | `/flow:init "REQ-123|功能"` → [详细文档](../../.claude/commands/flow/init.md) |
+| `/flow:spec` | 📋 生成可执行任务清单 | `/flow:spec "REQ-123"` → [详细文档](../../.claude/commands/flow/spec.md) |
+| `/flow:dev` | 🛠️ 分发/恢复任务执行 | `/flow:dev "REQ-123" --resume` → [详细文档](../../.claude/commands/flow/dev.md) |
+| `/flow:verify` | ✅ 执行快速/严格质量闸 | `/flow:verify "REQ-123" --strict` → [详细文档](../../.claude/commands/flow/verify.md) |
+| `/flow:release` | 🚢 发布并清理运行时 | `/flow:release "REQ-123"` → [详细文档](../../.claude/commands/flow/release.md) |
+| `/flow:status` | 📊 查询开发进度 | `/flow:status REQ-123` → [详细文档](../../.claude/commands/flow/status.md) |
+| `/flow:restart` | 🔄 恢复中断工作流 | `/flow:restart "REQ-123" --from=dev` → [详细文档](../../.claude/commands/flow/restart.md) |
+| `/flow:update` | ✅ 更新任务进度 | `/flow:update "REQ-123" "T001"` → [详细文档](../../.claude/commands/flow/update.md) |
+| `/flow:fix` | 🐛 Bug 修复流程 | `/flow:fix "BUG-001\|描述"` → [详细文档](../../.claude/commands/flow/fix.md) |
+
+## ⚠️ 已废弃命令
+
+| 废弃命令 | 迁移路径 |
+|----------|----------|
+| `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
+| `/flow:clarify` | 使用 `/flow:spec` |
+| `/flow:checklist` | 使用 `/flow:verify --strict` |
+| `/flow:quality` | 使用 `/flow:verify` |
+
+## 🏗️ 核心命令
 
 | 命令 | 用途 | 快速示例 |
 |------|------|----------|
-| `/flow-verify` | 🔍 验证文档一致性 | `/flow-verify "REQ-123"` → [详细文档](./flow-verify.md) |
-| `/flow-qa` | 🧪 执行质量保证 | `/flow-qa "REQ-123"` → [详细文档](./flow-qa.md) |
-| `/flow-constitution` | 📜 Constitution 合规 | `/flow-constitution --verify` → [详细文档](./flow-constitution.md) |
-
-## 🛠️ 工具命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/flow-fix` | 🐛 Bug 修复流程 | `/flow-fix "BUG-001\|描述"` → [详细文档](./flow-fix.md) |
-| `/flow-release` | 🚢 创建发布 | `/flow-release "REQ-123"` → [详细文档](./flow-release.md) |
+| `/core:roadmap` | 🗺️ 生成产品路线图 | `/core:roadmap` → [详细文档](./core-roadmap.md) |
+| `/core:architecture` | 🏛️ 生成系统架构 | `/core:architecture` → [详细文档](./core-architecture.md) |
+| `/core:guidelines` | 📘 生成项目规范 | `/core:guidelines` → [详细文档](./core-guidelines.md) |
+| `/core:style` | 🎨 生成设计风格指南 | `/core:style` → [详细文档](./core-style.md) |
 
 ## 🎯 快速选择指南
 
-```
+```text
 你的场景：
-├─ 启动全新功能？ → /flow-new "REQ-123|功能"
-├─ 规划产品方向？ → /core-roadmap
-├─ 设计系统架构？ → /core-architecture
-├─ 开发中断继续？ → /flow-restart "REQ-123"
-├─ 检查开发进度？ → /flow-status REQ-123
-├─ 发现文档冲突？ → /flow-verify "REQ-123"
-├─ 开发完成测试？ → /flow-qa "REQ-123"
-├─ 修复生产 Bug？ → /flow-fix "BUG-001|描述"
-└─ 准备发布上线？ → /flow-release "REQ-123"
+├─ 启动需求交付？ → /flow:init "REQ-123|功能|URLs"
+├─ 生成可执行计划？ → /flow:spec "REQ-123"
+├─ 执行或恢复开发？ → /flow:dev "REQ-123" [--resume]
+├─ 进行发布门禁？ → /flow:verify "REQ-123" --strict
+├─ 准备发布上线？ → /flow:release "REQ-123"
+├─ 检查进度？ → /flow:status REQ-123
+├─ 修复生产 Bug？ → /flow:fix "BUG-001|描述"
+└─ 做项目级规划？ → /core:roadmap /core:architecture /core:guidelines
 ```
 
 ## 📚 相关文档

package/docs/commands/core-roadmap.md

@@ -22,7 +22,7 @@ Generate comprehensive product roadmap and requirement priority planning through
 - Present product plan to team
 
 ### ❌ Not Recommended Scenarios
-- Single requirement development → Use `/flow-new`
+- Single requirement development → Use `/flow:init` (then `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`)
 
 ## 🔄 Execution Flow (6-Stage Interactive Dialogue)
 
@@ -96,7 +96,7 @@ User: Target users are Tech Leads and senior engineers in development teams.
 ## 🔗 Related Commands
 
 - [`/core-architecture`](./core-architecture.md) - Generate architecture based on roadmap
-- [`/flow-init`](./flow-init.md) - Initialize requirement based on roadmap
+- [`/flow:init`](./flow-init.md) - Initialize requirement based on roadmap
 - `.claude/scripts/sync-roadmap-progress.sh` - Sync progress to roadmap
 
 ## 📚 Deep Reading

package/docs/commands/core-roadmap.zh-CN.md

@@ -18,7 +18,7 @@
 - 向团队展示产品规划
 
 ### ❌ 不推荐场景
-- 单个需求开发 → 使用 `/flow-new`
+- 单个需求开发 → 使用 `/flow:init`（随后 `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`）
 
 ## 🔄 执行流程（6阶段交互式对话）
 
@@ -92,7 +92,7 @@ User: 目标用户是开发团队的 Tech Lead 和高级工程师。
 ## 🔗 相关命令
 
 - [`/core-architecture`](./core-architecture.md) - 基于路线图生成架构
-- [`/flow-init`](./flow-init.md) - 基于路线图初始化需求
+- [`/flow:init`](./flow-init.md) - 基于路线图初始化需求
 - `.claude/scripts/sync-roadmap-progress.sh` - 同步进度到路线图
 
 ## 📚 深度阅读