cc-devflow 1.0.1

package/bin/adapt.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * CLI Entry Point - bin/adapt.js (v2.0)
+ *
+ * Usage:
+ *   npm run adapt                        # Compile all (commands + skills + rules)
+ *   npm run adapt -- --platform codex    # Compile for Codex only
+ *   npm run adapt -- --all               # Compile for all platforms (explicit)
+ *   npm run adapt -- --check             # Check for drift
+ *   npm run adapt -- --skills            # Generate skills-registry.json only
+ *   npm run adapt -- --rules             # Generate rules entry files only
+ *   npm run adapt -- --verbose           # Show detailed output
+ *   npm run adapt -- --help              # Show help
+ *
+ * Exit Codes:
+ *   0: Success
+ *   1: Compilation error
+ *   2: Drift detected (with --check)
+ *   3: Invalid arguments
+ */
+const { compile, PLATFORMS } = require('../lib/compiler/index.js');
+const { generateSkillsRegistryV2, writeSkillsRegistry } = require('../lib/compiler/skills-registry.js');
+const { emitAllRules } = require('../lib/compiler/rules-emitters/index.js');
+
+// ============================================================
+// parseArgs - 解析命令行参数
+// ============================================================
+function parseArgs(argv) {
+  const args = {
+    platform: null,
+    all: false,
+    check: false,
+    verbose: false,
+    help: false,
+    skills: false,
+    rules: false
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--platform':
+        args.platform = argv[++i];
+        break;
+      case '--all':
+        args.all = true;
+        break;
+      case '--check':
+        args.check = true;
+        break;
+      case '--verbose':
+        args.verbose = true;
+        break;
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+      case '--skills':
+        args.skills = true;
+        break;
+      case '--rules':
+        args.rules = true;
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Unknown option: ${arg}`);
+          process.exit(3);
+        }
+    }
+  }
+
+  return args;
+}
+
+// ============================================================
+// showHelp - 显示帮助信息
+// ============================================================
+function showHelp() {
+  console.log(`
+Usage: npm run adapt [options]
+
+Adapter Compiler - Compile CC-DevFlow to multi-platform formats
+
+Options:
+  --platform <name>   Compile for specific platform (${PLATFORMS.join(', ')})
+  --all               Compile for all platforms (default if no --platform)
+  --check             Check for drift without compiling
+  --skills            Generate skills-registry.json only
+  --rules             Generate rules entry files only
+  --verbose           Show detailed compilation output
+  --help, -h          Show this help message
+
+Examples:
+  npm run adapt                        # Full compilation
+  npm run adapt -- --platform codex    # Compile for Codex only
+  npm run adapt -- --skills            # Generate skills registry
+  npm run adapt -- --rules             # Generate rules entry files
+  npm run adapt -- --check             # Check for drift
+  npm run adapt -- --verbose           # Show detailed output
+
+Exit Codes:
+  0 - Success
+  1 - Compilation error
+  2 - Drift detected (with --check)
+  3 - Invalid arguments
+`);
+}
+
+// ============================================================
+// main - 主函数
+// ============================================================
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // 显示帮助
+  if (args.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  // 确定目标平台
+  let platforms;
+  if (args.platform) {
+    if (!PLATFORMS.includes(args.platform)) {
+      console.error(`Unknown platform: ${args.platform}`);
+      console.error(`Available platforms: ${PLATFORMS.join(', ')}`);
+      process.exit(3);
+    }
+    platforms = [args.platform];
+  } else {
+    platforms = PLATFORMS;
+  }
+
+  // 处理 --skills 单独模式
+  if (args.skills && !args.rules) {
+    try {
+      const skillsDir = '.claude/skills';
+      const registry = await generateSkillsRegistryV2(skillsDir);
+      const outputPath = await writeSkillsRegistry(registry);
+
+      console.log(`Skills registry generated: ${outputPath}`);
+      console.log(`  Skills found: ${registry.skills.length}`);
+      process.exit(0);
+    } catch (error) {
+      console.error(`Error generating skills registry: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  // 处理 --rules 单独模式
+  if (args.rules && !args.skills) {
+    try {
+      const skillsDir = '.claude/skills';
+      const registry = await generateSkillsRegistryV2(skillsDir);
+
+      const rulesResults = await emitAllRules(registry, [], { platforms });
+      let rulesGenerated = 0;
+
+      for (const ruleResult of rulesResults) {
+        if (ruleResult.error) {
+          console.error(`  Error (${ruleResult.platform}): ${ruleResult.error}`);
+        } else {
+          rulesGenerated++;
+          if (args.verbose) {
+            console.log(`  Generated: ${ruleResult.path}`);
+          }
+        }
+      }
+
+      console.log(`Rules entry files generated: ${rulesGenerated}`);
+      process.exit(0);
+    } catch (error) {
+      console.error(`Error generating rules: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  try {
+    // 确定编译选项
+    const compileOptions = {
+      platforms,
+      verbose: args.verbose,
+      check: args.check,
+      rules: true,
+      skills: true
+    };
+
+    // 如果只指定 --skills 或 --rules，调整选项
+    if (args.skills || args.rules) {
+      compileOptions.skills = args.skills;
+      compileOptions.rules = args.rules;
+    }
+
+    const result = await compile(compileOptions);
+
+    // 处理 check 模式
+    if (args.check) {
+      if (result.drift && result.drift.length > 0) {
+        console.log('Drift detected:');
+        for (const item of result.drift) {
+          console.log(`  - ${item.source}: ${item.issue}`);
+        }
+        process.exit(2);
+      }
+      console.log('No drift detected.');
+      process.exit(0);
+    }
+
+    // 输出编译结果
+    if (result.success) {
+      console.log(`Compilation complete.`);
+      console.log(`  Platforms: ${result.platforms.join(', ')}`);
+      console.log(`  Files compiled: ${result.filesCompiled}`);
+      console.log(`  Files skipped: ${result.filesSkipped}`);
+      console.log(`  Resources copied: ${result.resourcesCopied}`);
+      console.log(`  Resources skipped: ${result.resourcesSkipped}`);
+      console.log(`  Skills registered: ${result.skillsRegistered}`);
+      console.log(`  Rules generated: ${result.rulesGenerated}`);
+      process.exit(0);
+    } else {
+      console.error('Compilation failed:');
+      for (const error of result.errors) {
+        console.error(`  - ${error}`);
+      }
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// 导出 parseArgs 供测试使用
+module.exports = { parseArgs };
+
+// 如果是直接运行则执行 main
+if (require.main === module) {
+  main();
+}

package/bin/cc-devflow-cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+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');
+
+function showHelp() {
+  console.log(`
+Usage: cc-devflow <command> [options]
+
+Commands:
+  init                Install .claude template into a project
+  adapt               Compile .claude into multi-platform outputs
+
+Init options:
+  --dir <path>         Target project path (default: cwd)
+  --force              Overwrite existing .claude
+
+Adapt options:
+  --cwd <path>         Target project path (default: cwd)
+  --platform <name>    Compile for specific platform
+  --all                Compile all platforms (default)
+  --check              Check for drift without compiling
+  --skills             Generate skills registry only
+  --rules              Generate rules entry files only
+  --verbose            Show detailed output
+
+Examples:
+  cc-devflow init
+  cc-devflow init --dir /path/to/project
+  cc-devflow adapt --platform cursor
+  cc-devflow adapt --cwd /path/to/project --platform codex
+`);
+}
+
+function parseCliArgs(args) {
+  const options = {
+    dir: null,
+    cwd: null,
+    force: false,
+    help: false
+  };
+  const rest = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--dir') {
+      options.dir = args[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--dir=')) {
+      options.dir = arg.slice('--dir='.length);
+      continue;
+    }
+
+    if (arg === '--cwd') {
+      options.cwd = args[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--cwd=')) {
+      options.cwd = arg.slice('--cwd='.length);
+      continue;
+    }
+
+    rest.push(arg);
+  }
+
+  return { options, rest };
+}
+
+function runInit(args) {
+  const { options } = parseCliArgs(args);
+
+  if (options.help) {
+    showHelp();
+    return 0;
+  }
+
+  const targetRoot = path.resolve(options.dir || options.cwd || process.cwd());
+  const targetDir = path.join(targetRoot, '.claude');
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    console.error(`Template not found: ${TEMPLATE_DIR}`);
+    return 1;
+  }
+
+  if (fs.existsSync(targetDir)) {
+    if (!options.force) {
+      console.error(`Target already exists: ${targetDir}`);
+      console.error('Use --force to overwrite.');
+      return 1;
+    }
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+
+  fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
+  console.log(`Initialized .claude in ${targetRoot}`);
+  return 0;
+}
+
+function runAdapt(args) {
+  const { options, rest } = parseCliArgs(args);
+
+  if (options.help) {
+    showHelp();
+    return 0;
+  }
+
+  const targetRoot = path.resolve(options.cwd || process.cwd());
+  const claudeDir = path.join(targetRoot, '.claude');
+
+  if (!fs.existsSync(claudeDir)) {
+    console.error(`Missing .claude directory in ${targetRoot}`);
+    console.error('Run: cc-devflow init');
+    return 1;
+  }
+
+  const result = spawnSync(process.execPath, [ADAPT_BIN, ...rest], {
+    stdio: 'inherit',
+    cwd: targetRoot
+  });
+
+  if (result.error) {
+    console.error(`Failed to run adapt: ${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'
+  });
+
+  if (result.error) {
+    console.error(`Failed to run adapter: ${result.error.message}`);
+    return 1;
+  }
+
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const [command, ...rest] = argv;
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    showHelp();
+    return 0;
+  }
+
+  if (command === 'init') {
+    return runInit(rest);
+  }
+
+  if (command === 'adapt') {
+    return runAdapt(rest);
+  }
+
+  return runAdapter(command, rest);
+}
+
+if (require.main === module) {
+  process.exit(main());
+}

package/bin/cc-devflow.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const AdapterRegistry = require('../lib/adapters/registry');
+const ClaudeAdapter = require('../lib/adapters/claude-adapter');
+const CodexAdapter = require('../lib/adapters/codex-adapter');
+const { validateConfig, getDefaultConfig } = require('../lib/adapters/config-validator');
+const logger = require('../lib/adapters/logger');
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+async function main() {
+    try {
+        // 1. Initialize Registry
+        const registry = AdapterRegistry.getInstance();
+
+        // 2. Register known adapters
+        registry.register(new ClaudeAdapter());
+        registry.register(new CodexAdapter());
+
+        // 3. Load and Validate Config
+        let config = getDefaultConfig();
+        const configPath = path.resolve(__dirname, '../config/adapters.yml');
+
+        if (fs.existsSync(configPath)) {
+            try {
+                const fileContents = fs.readFileSync(configPath, 'utf8');
+                const rawConfig = yaml.load(fileContents);
+                const result = validateConfig(rawConfig);
+
+                if (result.success) {
+                    config = result.data;
+                    logger.debug('Config loaded', { path: configPath });
+                } else {
+                    logger.error('Config validation failed', { error: result.error });
+                    process.exit(1);
+                }
+            } catch (e) {
+                logger.warn('Failed to load config, using defaults', { error: e.message });
+            }
+        }
+
+        registry.setConfig(config.adapters);
+
+        // 4. Parse Command
+        // Usage: cc-devflow <command> [args...]
+        const [, , command, ...args] = process.argv;
+
+        if (!command) {
+            logger.info('Usage: cc-devflow <command> [args...]');
+            process.exit(0);
+        }
+
+        // 5. Detect & Execute
+        // Note: executeCommand will auto-detect if no adapter specified
+        logger.info('Processing command', { command });
+
+        try {
+            const result = await registry.executeCommand(command, args);
+            // If result has output/code, handle it. 
+            // Claude adapter pipes to stdio, so result might be just an exit code.
+            if (result && result.msg) {
+                logger.info('Command completed', { msg: result.msg, code: result.code });
+            }
+            process.exit(result.code || 0);
+
+        } catch (err) {
+            logger.error('Execution failed', { error: err.message });
+            process.exit(1);
+        }
+
+    } catch (error) {
+        logger.error('Fatal error', { error: error.message, stack: error.stack });
+        process.exit(1);
+    }
+}
+
+main();

package/config/adapters.yml

@@ -0,0 +1,5 @@
+adapters:
+  preferred: null
+  policies:
+    allow_shell: false
+    allow_network: false

package/config/schema/adapters.schema.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+        "adapters": {
+            "type": "object",
+            "properties": {
+                "preferred": {
+                    "type": [
+                        "string",
+                        "null"
+                    ],
+                    "description": "The preferred adapter key (e.g. 'codex', 'claude'). If null, auto-detection logic applies."
+                },
+                "policies": {
+                    "type": "object",
+                    "properties": {
+                        "allow_shell": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Whether to allow the adapter to execute arbitrary shell commands."
+                        },
+                        "allow_network": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Whether to allow the adapter to make arbitrary network requests."
+                        }
+                    },
+                    "required": [
+                        "allow_shell"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "required": [
+                "policies"
+            ],
+            "additionalProperties": false
+        }
+    },
+    "required": [
+        "adapters"
+    ]
+}

package/docs/CLAUDE.md

@@ -0,0 +1,26 @@
+# docs/
+
+本目录存放 **cc-devflow 的用户可读文档**（命令说明、上手指南、对外分析报告）。
+
+## 目录结构
+
+```text
+docs/
+├── CLAUDE.md
+├── SPEC_KIT_REFERENCE_ANALYSIS.md
+├── SPEC_KIT_ITERATION_BORROWING.md
+├── commands/
+└── guides/
+```
+
+## 文件职责（一句话说清）
+
+- `docs/SPEC_KIT_REFERENCE_ANALYSIS.md`: cc-devflow 与 spec-kit 的总体架构/理念/机制对照（静态对比基线）。
+- `docs/SPEC_KIT_ITERATION_BORROWING.md`: 基于 spec-kit 近期迭代（Changelog）的“增量差异”与可借鉴项（动态演进对比）。
+
+## 编写约定
+
+- 面向使用者：优先写“怎么用/怎么做”，其次再写“为什么”。
+- 可检索：标题清晰、关键词统一（`/flow-*`、`/core-*`、`/speckit.*`）。
+- 可落地：结论必须能映射到具体命令、脚本或模板文件路径。
+

package/docs/commands/README.md

@@ -0,0 +1,61 @@
+# 📋 Command Reference
+
+[中文文档](./README.zh-CN.md) | [English](./README.md)
+
+---
+
+## 🎯 Requirement Management 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
+
+| 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) |
+
+## 🎯 Quick Selection Guide
+
+```
+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"
+```
+
+## 📚 Related Documentation
+
+- [Getting Started Guide](../guides/getting-started.md)
+- [Workflow Guide](../guides/workflow-guide.md)
+- [Best Practices](../guides/best-practices.md)

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

@@ -0,0 +1,55 @@
+# 📋 命令参考文档
+
+## 🎯 需求管理命令
+
+| 命令 | 用途 | 快速示例 |
+|------|------|----------|
+| `/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-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) |
+
+## 🎯 快速选择指南
+
+```
+你的场景：
+├─ 启动全新功能？ → /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"
+```
+
+## 📚 相关文档
+
+- [快速开始](../guides/getting-started.md)
+- [工作流指南](../guides/workflow-guide.md)
+- [最佳实践](../guides/best-practices.md)