cc-devflow 4.3.0 → 4.4.1

package/bin/adapt.js

@@ -3,7 +3,7 @@
  * CLI Entry Point - bin/adapt.js (v2.0)
  *
  * Usage:
- *   npm run adapt                        # Compile all (commands + skills + rules)
+ *   npm run adapt                        # Compile all platform outputs (skills + optional commands + 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
@@ -80,7 +80,7 @@ function showHelp() {
   console.log(`
 Usage: npm run adapt [options]
 
-Adapter Compiler - Compile CC-DevFlow to multi-platform formats
+Adapter Compiler - Compile CC-DevFlow skills, optional commands, and rules
 
 Options:
   --platform <name>   Compile for specific platform (${PLATFORMS.join(', ')})
@@ -215,10 +215,6 @@ async function main() {
       console.log(`  Files skipped: ${result.filesSkipped}`);
       console.log(`  Resources copied: ${result.resourcesCopied}`);
       console.log(`  Resources skipped: ${result.resourcesSkipped}`);
-      console.log(`  Skills emitted: ${result.skillsEmitted}`);
-      console.log(`  Agents emitted: ${result.agentsEmitted}`);
-      console.log(`  Module rules emitted: ${result.moduleRulesEmitted}`);
-      console.log(`  Hooks emitted: ${result.hooksEmitted}`);
       console.log(`  Skills registered: ${result.skillsRegistered}`);
       console.log(`  Rules generated: ${result.rulesGenerated}`);
       process.exit(0);

package/bin/cc-devflow-cli.js

@@ -1,29 +1,39 @@
 #!/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');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, '.claude');
+const TEMPLATE_SKILLS_DIR = path.join(TEMPLATE_DIR, 'skills');
+const DISTRIBUTION_CONFIG = require(path.join(PACKAGE_ROOT, 'config', 'distributable-skills.json'));
 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'
-};
+const TEMPLATE_IGNORES = new Set(['.DS_Store', 'tsc-cache']);
+const DISTRIBUTED_SKILLS = Array.from(
+  new Set(DISTRIBUTION_CONFIG.distributedSkills || DISTRIBUTION_CONFIG.publicSkills || [])
+);
+const DISTRIBUTED_SKILL_SET = new Set(DISTRIBUTED_SKILLS);
+
+function shouldIncludeTemplatePath(src) {
+  const relativePath = path.relative(TEMPLATE_DIR, src);
+
+  if (!relativePath || relativePath === '') {
+    return true;
+  }
+
+  const segments = relativePath.split(path.sep);
+  const skillIndex = segments.indexOf('skills');
+
+  if (skillIndex !== -1 && segments.length > skillIndex + 1) {
+    const skillName = segments[skillIndex + 1];
+    if (!DISTRIBUTED_SKILL_SET.has(skillName)) {
+      return false;
+    }
+  }
+
+  return !segments.some((segment) => TEMPLATE_IGNORES.has(segment));
+}
 
 function showHelp() {
   console.log(`
@@ -32,11 +42,10 @@ 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)
-  --force              Overwrite existing .claude
+  --force              Force-upgrade managed skills without deleting other .claude files
 
 Adapt options:
   --cwd <path>         Target project path (default: cwd)
@@ -52,7 +61,6 @@ 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
 `);
 }
 
@@ -106,146 +114,61 @@ function parseCliArgs(args) {
   return { options, rest };
 }
 
-function copyIncremental(src, dest) {
+function copyManagedDirectory(src, dest, options = {}) {
+  const { force = false } = options;
+
+  if (!shouldIncludeTemplatePath(src)) {
+    return;
+  }
+
   const stats = fs.statSync(src);
   if (stats.isDirectory()) {
-    if (!fs.existsSync(dest)) {
-      fs.mkdirSync(dest);
-    }
+    fs.mkdirSync(dest, { recursive: true });
     const entries = fs.readdirSync(src);
     for (const entry of entries) {
-      copyIncremental(path.join(src, entry), path.join(dest, entry));
-    }
-  } else {
-    if (!fs.existsSync(dest)) {
-      // Case 1: File missing - Copy it
-      fs.copyFileSync(src, dest);
-      console.log(`[NEW] ${path.relative(process.cwd(), dest)}`);
-    } else {
-      // Case 2: File exists - Compare content
-      try {
-        const srcContent = fs.readFileSync(src);
-        const destContent = fs.readFileSync(dest);
-
-        if (!srcContent.equals(destContent)) {
-          // Content differs - Overwrite original
-          fs.unlinkSync(dest);
-          fs.copyFileSync(src, dest);
-          console.log(`[UPDATE] ${path.relative(process.cwd(), dest)}`);
-        }
-        // else: Content identical - Silent skip
-      } catch (err) {
-        console.warn(`[WARN] Could not compare ${path.relative(process.cwd(), dest)}: ${err.message}`);
-      }
+      copyManagedDirectory(path.join(src, entry), path.join(dest, entry), options);
     }
+    return;
   }
-}
-
-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.`);
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    console.log(`[NEW] ${path.relative(process.cwd(), dest)}`);
     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;
-  }
+    const srcContent = fs.readFileSync(src);
+    const destContent = fs.readFileSync(dest);
 
-  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
-    console.warn('[WARN] Skipping harness script bootstrap: package.json root must be an object.');
-    return;
-  }
+    if (!force && srcContent.equals(destContent)) {
+      return;
+    }
 
-  if (!packageJson.scripts || typeof packageJson.scripts !== 'object' || Array.isArray(packageJson.scripts)) {
-    packageJson.scripts = {};
+    fs.copyFileSync(src, dest);
+    console.log(`[UPDATE] ${path.relative(process.cwd(), dest)}`);
+  } catch (err) {
+    console.warn(`[WARN] Could not compare ${path.relative(process.cwd(), dest)}: ${err.message}`);
   }
+}
 
-  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;
-    }
+function syncDistributedSkills(targetRoot, options = {}) {
+  const { force = false } = options;
+  const targetClaudeDir = path.join(targetRoot, '.claude');
+  const targetSkillsDir = path.join(targetClaudeDir, 'skills');
 
-    if (typeof existing !== 'string') {
-      continue;
-    }
+  fs.mkdirSync(targetSkillsDir, { recursive: true });
 
-    // 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;
-    }
+  for (const skillName of DISTRIBUTED_SKILLS) {
+    const sourceSkillDir = path.join(TEMPLATE_SKILLS_DIR, skillName);
+    const targetSkillDir = path.join(targetSkillsDir, skillName);
 
-    // 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;
+    if (!fs.existsSync(sourceSkillDir)) {
+      throw new Error(`Managed skill template not found: ${sourceSkillDir}`);
     }
 
-    // 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(', ')})`);
+    copyManagedDirectory(sourceSkillDir, targetSkillDir, { force });
   }
 }
 
@@ -265,29 +188,25 @@ function runInit(args) {
     return 1;
   }
 
-  // Case 1: Directory does not exist - Clean Install
+  // Case 1: Directory does not exist - Create managed skill roots only
   if (!fs.existsSync(targetDir)) {
-    fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
-    ensureHarnessScripts(targetRoot);
-    console.log(`Initialized .claude in ${targetRoot}`);
+    syncDistributedSkills(targetRoot);
+    console.log(`Initialized managed .claude skills in ${targetRoot}`);
     return 0;
   }
 
-  // Case 2: Directory exists + Force - Hard Reset
+  // Case 2: Directory exists + Force - Force-upgrade managed skills only
   if (options.force) {
-    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}`);
+    console.log('Force flag detected. Reinstalling managed skills without deleting unrelated .claude files...');
+    syncDistributedSkills(targetRoot, { force: true });
+    console.log(`Reinstalled managed .claude skills in ${targetRoot}`);
     return 0;
   }
 
   // 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.');
+  syncDistributedSkills(targetRoot);
+  console.log('Incremental update complete. Existing .claude files were preserved.');
   return 0;
 }
 
@@ -308,8 +227,6 @@ function runAdapt(args) {
     return 1;
   }
 
-  ensureHarnessScripts(targetRoot);
-
   const result = spawnSync(process.execPath, [ADAPT_BIN, ...rest], {
     stdio: 'inherit',
     cwd: targetRoot
@@ -323,24 +240,6 @@ 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'
@@ -371,10 +270,6 @@ function main() {
     return runAdapt(rest);
   }
 
-  if (command === 'harness') {
-    return runHarness(rest);
-  }
-
   return runAdapter(command, rest);
 }
 

package/config/distributable-skills.json

@@ -0,0 +1,24 @@
+{
+  "publicSkills": [
+    "cc-roadmap",
+    "cc-plan",
+    "cc-investigate",
+    "cc-do",
+    "cc-check",
+    "cc-act"
+  ],
+  "distributedSkills": [
+    "cc-roadmap",
+    "cc-plan",
+    "cc-investigate",
+    "cc-do",
+    "cc-check",
+    "cc-act",
+    "cc-spec-init",
+    "cc-simplify"
+  ],
+  "internalSkills": [
+    "docs-sync",
+    "npm-release"
+  ]
+}

package/docs/CLAUDE.md

@@ -7,20 +7,24 @@
 ```text
 docs/
 ├── CLAUDE.md
-├── SPEC_KIT_REFERENCE_ANALYSIS.md
-├── SPEC_KIT_ITERATION_BORROWING.md
 ├── commands/
-└── guides/
+├── examples/
+├── guides/
+├── skill-runtime-migration.md
+└── v4.3.0-migration-guide.md
 ```
 
 ## 文件职责（一句话说清）
 
-- `docs/SPEC_KIT_REFERENCE_ANALYSIS.md`: cc-devflow 与 spec-kit 的总体架构/理念/机制对照（静态对比基线）。
-- `docs/SPEC_KIT_ITERATION_BORROWING.md`: 基于 spec-kit 近期迭代（Changelog）的“增量差异”与可借鉴项（动态演进对比）。
+- `docs/commands/`: CLI、分发与平台适配相关文档。
+- `docs/examples/`: 端到端样例与样例绑定真相源。
+- `docs/guides/`: 上手与迁移类说明。
+- `docs/skill-runtime-migration.md`: 旧 runtime 叙事迁移说明。
+- `docs/v4.3.0-migration-guide.md`: 对外版本迁移说明。
 
 ## 编写约定
 
 - 面向使用者：优先写“怎么用/怎么做”，其次再写“为什么”。
 - 可检索：标题清晰、关键词统一（`/flow-*`、`/core-*`、`/speckit.*`）。
 - 可落地：结论必须能映射到具体命令、脚本或模板文件路径。
-
+- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；描述部分使用 kebab-case。

package/docs/commands/README.md

@@ -1,57 +1,30 @@
-# 📋 Command Reference
+# CLI And Skills
 
-[中文文档](./README.zh-CN.md) | [English](./README.md)
+CC-DevFlow no longer uses the old `/flow:*` command surface as the primary interface.
 
----
+Use the repository CLI for whole-pack setup and platform adaptation:
 
-## 🎯 Requirement Commands
+```bash
+npx cc-devflow init --dir /path/to/your/project
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
 
-| Command | Purpose | Quick Example | Detailed Docs |
-|---------|---------|---------------|---------------|
-| `/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) |
+Use skills directly for the workflow itself:
 
-## ⚠️ Deprecated Commands
+```text
+cc-roadmap
 
-| 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` |
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+```
 
-## 🏗️ Core Commands
+Use maintenance skills separately when needed:
 
-| 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) |
-| `/core:style` | 🎨 Generate style system guide | `/core:style` | [→](./core-style.md) |
+- `cc-spec-init`: bootstrap or repair `devflow/specs/` and `change-meta.json`
+- `cc-simplify`: cleanup pass before ship
 
-## 🎯 Quick Selection Guide
+Use [skills.sh CLI](https://skills.sh/docs/cli) when you only want one skill:
 
-```text
-Your Scenario:
-├─ 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
+```bash
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
-
-## 📚 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

@@ -1,53 +1,30 @@
-# 📋 命令参考文档
-
-## 🎯 需求命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/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` |
-
-## 🏗️ 核心命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/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) |
-
-## 🎯 快速选择指南
+# CLI 与 Skill
+
+CC-DevFlow 不再把旧的 `/flow:*` 命令面当作主要用户接口。
+
+整包安装和多平台适配，使用仓库自带 CLI：
+
+```bash
+npx cc-devflow init --dir /path/to/your/project
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
+
+真正的工作流直接使用 Skill：
 
 ```text
-你的场景：
-├─ 启动需求交付？ → /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
+cc-roadmap
+
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 ```
 
-## 📚 相关文档
+维护类动作按需单独调用：
+
+- `cc-spec-init`：初始化或修复 `devflow/specs/` 与 `change-meta.json`
+- `cc-simplify`：ship 前做清理和坏味道检查
 
-- [快速开始](../guides/getting-started.md)
-- [工作流指南](../guides/workflow-guide.md)
-- [最佳实践](../guides/best-practices.md)
+如果你只想安装单个 Skill，再使用 [skills.sh CLI](https://skills.sh/docs/cli)：
+
+```bash
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
+```

package/docs/examples/BY-ARTIFACT.md

@@ -0,0 +1,7 @@
+# By Artifact
+
+This page is now a compatibility shortcut.
+
+The canonical one-page entry is [START-HERE.md](./START-HERE.md).
+
+If you only know which file you have in hand, jump to the `By Artifact` section inside [START-HERE.md](./START-HERE.md).

package/docs/examples/README.md

@@ -0,0 +1,38 @@
+# Example Gallery
+
+This page is now a compact list view.
+
+The canonical one-page entry is [START-HERE.md](./START-HERE.md).
+
+Use this page only when you already know you want the short list.
+
+If you need to verify that examples still match the current skill contracts, use [example-bindings.json](./example-bindings.json) and [scripts/check-example-bindings.sh](./scripts/check-example-bindings.sh).
+
+## Available Examples
+
+### 1. Happy Path: tiny-design + `create-pr`
+
+- Path: [./pdca-loop/README.md](./pdca-loop/README.md)
+- Shows:
+  - `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act`
+  - `tiny-design`
+  - `pass`
+  - `create-pr`
+
+### 2. Counterexample: `full-design` + `blocked` + reroute to `cc-plan`
+
+- Path: [./full-design-blocked/README.md](./full-design-blocked/README.md)
+- Shows:
+  - a requirement that was planned too narrowly for the real integration surface
+  - tests may pass, but `cc-check` still returns `blocked`
+  - the correct next move is to reopen planning instead of faking completion
+
+### 3. Counterexample: verified work + `local-handoff`
+
+- Path: [./local-handoff/README.md](./local-handoff/README.md)
+- Shows:
+  - work that is truly verified
+  - a case where remote / PR actions are intentionally skipped
+  - `cc-act` leaving exactly one final handoff file, with `resume-index.md` only for local-handoff
+
+If you need symptom routing or artifact-based lookup, go back to [START-HERE.md](./START-HERE.md).