cc-devflow 4.4.1 → 4.5.1

package/README.zh-CN.md

@@ -1,86 +1,111 @@
-# 🚀 cc-devflow
+# cc-devflow
 
-> 面向 Agent 编程的 cc-roadmap + PDCA / IDCA 技能体系
+> 面向 Agent 编程的路线图、计划、调查、执行、验证、交付工作流。
 
-CC-DevFlow 是一个给 Agent 编程时代准备的极简开发工作流。它只给你一个前置规划 Skill, `cc-roadmap`，然后让每个 requirement 进入两条闭环之一：新需求走 `cc-plan -> cc-do -> cc-check -> cc-act`，bug / regression 走 `cc-investigate -> cc-do -> cc-check -> cc-act`。
+[![GitHub stars](https://img.shields.io/github/stars/Dimon94/cc-devflow?style=social)](https://github.com/Dimon94/cc-devflow/stargazers)
+[![npm version](https://img.shields.io/npm/v/cc-devflow.svg)](https://www.npmjs.com/package/cc-devflow)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](./package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-[中文文档](./README.zh-CN.md) | [English](./README.md)
+[中文文档](./README.zh-CN.md) | [English](./README.md) | [快速开始](./docs/guides/getting-started.zh-CN.md) | [贡献指南](./CONTRIBUTING.zh-CN.md) | [安全策略](./SECURITY.zh-CN.md)
 
----
+CC-DevFlow 是一个给 Agent 编程时代准备的小而明确的工作流系统。它先用一个 roadmap 入口确定方向，再让每个变更进入「新需求闭环」或「Bug 调查闭环」，最后必须经过验证和交付收口。
 
-## 🎯 一句话介绍
+```text
+cc-roadmap
 
-CC-DevFlow 现在暴露 6 个可见 Skill：
+PDCA: cc-plan        -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+```
 
-- `cc-roadmap`: 产出项目的中长期路线图
-- `cc-plan`: 澄清 roadmap item，设计方案，拆成任务
-- `cc-investigate`: 冻结症状、复现、根因和修复任务，再把 bug 交给执行环
-- `cc-do`: 实现、恢复、按调查 handoff 修复 bug、处理 review feedback
-- `cc-check`: 用证据做验证
-- `cc-act`: ship、同步文档、把结果回写到下一轮
+## 为什么用 cc-devflow
 
-## ✨ 核心特性
+- **公开入口很小**：6 个可见 workflow skill，加一个负责安装和平台适配的 CLI。
+- **先证据后完成**：实现之后必须经过验证证据，才能进入 ship 或 handoff。
+- **Skill-first 分发**：公开契约写在 `.claude/skills/<skill>/SKILL.md` 和 `PLAYBOOK.md`，不依赖隐藏运行时语义。
+- **多平台产物**：一次安装，再生成 Codex、Cursor、Qwen、Antigravity 等 Agent 环境需要的输出。
+- **持久项目记忆**：roadmap、spec、planning、review、handoff 留在 `devflow/`；临时 worker scratch 不混入 durable truth。
 
-- **可见面极小**：1 个 `cc-roadmap` Skill + 2 条共享 `cc-do -> cc-check -> cc-act` 尾段的闭环
-- **多平台 CLI 已恢复**：`cc-devflow` 已重新回到可分发 CLI 入口，用于 `.claude` 安装与 Codex、Cursor、Qwen、Antigravity 多平台适配
-- **skills.sh 兼容布局**：`.claude/skills/<skill>/SKILL.md` 继续保持可被 skills.sh 单 Skill 分发的结构
-- **资源内化到 Skill**：每个 Skill 自带模板、参考资料和脚本
-- **白盒优先**：默认不做上下文注入，需要什么文件就显式读取什么文件
-- **任务模板保留**：继续以 `planning/tasks.md` 和 `task-manifest.json` 作为执行骨架
-- **Skill Pack 优先**：仓库以整包形式分发 `.claude` Skill、playbook 和资源文件
-- **先证据后完成**：验证、文档同步、PR brief、release note 都在闭环末端
-- **cc-roadmap 先行**：先定中长期方向，再让 requirement 按 PDCA 或 IDCA 执行
+## 快速开始
 
-## 🧠 心智模型
+前置条件：
 
-```text
-cc-roadmap
+- Node.js 18+
+- npm 或兼容的包运行器
+- 一个 Git 仓库
+- Claude Code 或其他受支持的 Agent 环境
 
-PDCA: cc-plan -> cc-do -> cc-check -> cc-act
-IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+安装整包 Skill：
+
+```bash
+npx cc-devflow@latest init --dir /path/to/your/project
+```
+
+生成平台产物：
+
+```bash
+npx cc-devflow@latest adapt --cwd /path/to/your/project --platform codex
+npx cc-devflow@latest adapt --cwd /path/to/your/project --platform cursor
+npx cc-devflow@latest adapt --cwd /path/to/your/project --platform qwen
+npx cc-devflow@latest adapt --cwd /path/to/your/project --platform antigravity
 ```
 
-先用 `cc-roadmap` 决定接下来 1-3 个阶段做什么。
+刷新所有受支持的平台产物：
 
-当问题是 feature / scope / task freezing，就走 `cc-plan`。
+```bash
+npx cc-devflow@latest adapt --cwd /path/to/your/project --all
+```
 
-当问题是 bug 根因 / regression / 复现链，就走 `cc-investigate`。
+安装完成后，直接让 Agent 使用这些 workflow skill。产品方向先走 `cc-roadmap`，新需求走 `cc-plan`，Bug 和 regression 走 `cc-investigate`，然后继续进入 `cc-do`、`cc-check`、`cc-act`。
 
-两条闭环最后都会并回同一条 `cc-do -> cc-check -> cc-act` 主干。
+## Workflow Skill
 
-这条可见状态机直接写在公开 Skill 里。整个包现在明确是 skill-first：路由、reroute、恢复和证据规则由 `SKILL.md` 与 `PLAYBOOK.md` 显式声明，`lib/skill-runtime/` 只保留给这些 Skill 复用的薄共享支撑代码。
+| Skill | 什么时候用 | 主要产物 |
+| --- | --- | --- |
+| `cc-roadmap` | 需要产品方向、阶段范围或 backlog 顺序 | `devflow/ROADMAP.md`、`devflow/BACKLOG.md` |
+| `cc-plan` | 新功能或变更需要澄清范围、设计方案、冻结任务 | `planning/design.md`、`planning/tasks.md`、`task-manifest.json` |
+| `cc-investigate` | Bug 需要症状、复现、根因和修复边界 | `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` |
+| `cc-do` | 已计划或已调查的任务需要实现 | 代码、测试、checkpoint、scratch runtime |
+| `cc-check` | 工作需要新鲜验证证据 | `report-card.json` |
+| `cc-act` | 已验证工作需要 PR、本地 handoff、release note 或 closeout | 唯一最终 handoff 文件 |
 
-## 🚀 安装
+整包还包含两个维护类 Skill：
 
-内置 CLI 已回到经典的 `init + adapt` 模式。
+- `cc-spec-init`：初始化和维护 `devflow/specs/` 下的 durable capability spec
+- `cc-simplify`：审查已改代码的复用、质量、效率和需求漂移
 
-对外打包后的默认入口应保持简洁：
+## 计划质量门禁
 
-```bash
-npx cc-devflow init --dir /path/to/your/project
-```
+`cc-roadmap` 现在会先记录 planning posture 和 evidence maturity，再推荐路线。idea、已有用户、付费客户、infra、recovery 场景不会被套进同一组问题。面向开发者或操作者的 roadmap item 还会把目标用户、time to first value、magic moment 和 adoption bottleneck 交给 `cc-plan`。
+
+`cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、覆盖质量，并在修改既有行为时强制规划 regression test。
+
+## 安装方式
 
-安装后，恢复后的 CLI 同时支持整包安装和多平台适配：
+### 整包安装
+
+需要完整 `.claude` skill pack 时使用：
 
 ```bash
-npx cc-devflow init --dir /path/to/your/project
-npx cc-devflow init --dir /path/to/your/project --force
-npx cc-devflow adapt --cwd /path/to/your/project --platform codex
-npx cc-devflow adapt --cwd /path/to/your/project --platform cursor
-npx cc-devflow adapt --cwd /path/to/your/project --platform qwen
-npx cc-devflow adapt --cwd /path/to/your/project --platform antigravity
+npx cc-devflow@latest init --dir /path/to/your/project
+npx cc-devflow@latest init --dir /path/to/your/project --force
 ```
 
-整包安装会带上 6 个可见 workflow skill，再额外带上维护类 skill `cc-spec-init` 和 `cc-simplify`。
-`init --force` 现在只会强制升级 cc-devflow 管理的分发 skill，不会删除项目里其他现有的 `.claude` 文件。
+`--force` 只升级 cc-devflow 管理的分发 Skill，不会删除项目里其他已有的 `.claude` 文件。
 
-如果你不是通过已安装包，而是在源码仓库里调试 CLI，本地运行请用 `node bin/cc-devflow-cli.js ...` 或 `npm exec -- cc-devflow ...`。
+### 源码仓库调试
 
-## 🧩 skills.sh 分发
+如果你在本仓库里开发：
 
-[skills.sh](https://skills.sh/) 只作为新的 `.claude` Skill 分发渠道使用。
+```bash
+node bin/cc-devflow-cli.js --help
+node bin/cc-devflow-cli.js init --dir /tmp/example-project
+node bin/cc-devflow-cli.js adapt --cwd /tmp/example-project --platform codex
+```
+
+### 通过 skills.sh 安装单个 Skill
 
-因为 skills.sh 是按单个 Skill 安装，所以按需拉取对应 Skill：
+[skills.sh](https://skills.sh/) 只作为单 Skill 分发渠道：
 
 ```bash
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
@@ -89,45 +114,64 @@ npx skills add https://github.com/Dimon94/cc-devflow --skill cc-investigate
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-do
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-check
 npx skills add https://github.com/Dimon94/cc-devflow --skill cc-act
-npx skills add https://github.com/Dimon94/cc-devflow --skill cc-spec-init
-npx skills add https://github.com/Dimon94/cc-devflow --skill cc-simplify
 ```
 
-当你想拿整包 `.claude` 时，用 `cc-devflow init`。
+需要整包用 `cc-devflow init`，需要平台产物用 `cc-devflow adapt`，只想拿单个 Skill 才用 `skills add`。
+
+## 配置
 
-当你想生成多平台产物时，用 `cc-devflow adapt`。
+CC-DevFlow 会在写入 durable workflow 文档前读取分层 YAML 配置：
 
-skills.sh 仍然用于按单个 Skill 安装或刷新。
+```text
+~/.cc-devflow/config.yml
+<repo>/.cc-devflow/config.yml
+<repo>/.cc-devflow/config.local.yml
+```
 
-## 🔁 升级
+优先级固定为：默认值 < 用户 < 项目 < 本地 < 环境变量 < CLI 参数。`output.document_language` 是机器约束，目前支持 `en` 和 `zh-CN`。非标偏好放在 `agent_preferences` 下，只影响表达风格，不覆盖 workflow 契约。
+
+```yaml
+version: 1
+output:
+  document_language: zh-CN
+agent_preferences:
+  general:
+    - 先给结论。
+  documentation:
+    - 标题短一些，避免营销腔。
+```
 
-通过最新版 CLI 刷新整包并重新执行适配：
+常用命令：
 
 ```bash
-npx cc-devflow@latest init --dir /path/to/your/project
-npx cc-devflow@latest adapt --cwd /path/to/your/project --all
-npx skills check
-npx skills update
+npx cc-devflow config init --cwd /path/to/your/project --project
+npx cc-devflow config set output.document_language zh-CN --cwd /path/to/your/project --project
+npx cc-devflow config resolve --cwd /path/to/your/project --format policy
+npx cc-devflow config doctor --cwd /path/to/your/project
 ```
 
-如果你只想立刻刷新某一个 Skill，直接重跑它对应的 `npx skills add ... --skill ...` 命令即可。
+完整样例见 [`config/user-config.template.yml`](./config/user-config.template.yml)。
 
-## 🧱 skills.sh 项目格式
+## 仓库格式
 
-CC-DevFlow 让 `.claude` Skill 目录保持与 skills.sh 单 Skill 分发兼容：
+对外分发的 Skill 位于 `.claude/skills/`：
 
-- 一个 Skill 一个目录
-- 每个分发 Skill 都有自己的 `SKILL.md`
-- `SKILL.md` 顶部使用 YAML frontmatter
-- 公开 Skill 的 frontmatter 显式声明 `triggers`、`reads`、结构化 `writes`、`effects`、`entry_gate`、`exit_criteria`、`reroutes`、`recovery_modes`、`tool_budget`
-- Skill 的本地资源与说明文件放在同级目录，比如 `PLAYBOOK.md`、`assets/`、`scripts/`、`references/`
+```text
+.claude/skills/<skill>/
+├── SKILL.md
+├── PLAYBOOK.md
+├── assets/
+├── references/
+└── scripts/
+```
 
-同时，公开 Skill 还带两层文本契约：
+每个已发布 Skill 都把运行契约放在自己目录里：
 
-- `SKILL.md` 里有 `Harness Contract`
-- `PLAYBOOK.md` 里有 `Visible State Machine`
+- `SKILL.md` 包含 YAML frontmatter 和 `Harness Contract`
+- `PLAYBOOK.md` 包含 `Visible State Machine`
+- 本地资源跟随拥有它的 Skill 一起放置
 
-这个仓库当前对外分发的 Skill 目录如下：
+当前分发目录：
 
 - `.claude/skills/cc-roadmap/`
 - `.claude/skills/cc-plan/`
@@ -138,58 +182,53 @@ CC-DevFlow 让 `.claude` Skill 目录保持与 skills.sh 单 Skill 分发兼容
 - `.claude/skills/cc-spec-init/`
 - `.claude/skills/cc-simplify/`
 
-## 🛠️ 使用
+## Durable 与 Ephemeral
 
-Skill 顺序仍然是：
+- `devflow/specs/` 保存 durable capability truth：`INDEX.md` 和 `capabilities/*.md`。
+- 新 change 目录使用 `REQ-<number>-<description>` 表示需求，使用 `FIX-<number>-<description>` 表示 Bug 修复。
+- `devflow/changes/<change>/` 保存 durable change truth：`change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、`team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一最终 handoff 文件。
+- `devflow/workspaces/<change>/` 保存 ephemeral runtime scratch，例如 worker assignment、journal、prompt 和 session log。
+- 能从 durable truth 再生成的文件，不应该持久化到 `devflow/changes/`。
 
-```text
-1. cc-roadmap
-2. 在 cc-plan 和 cc-investigate 里二选一
-3. cc-do
-4. cc-check
-5. cc-act
-6. repeat
-```
-
-你不需要记命令名。
+想先看完整产物链，可以从 [`docs/examples/START-HERE.md`](./docs/examples/START-HERE.md) 开始。样例和 Skill 的版本绑定真相源在 [`docs/examples/example-bindings.json`](./docs/examples/example-bindings.json)。
 
-`cc-devflow` CLI 仍然是整包安装与适配路径。
+## 开发
 
-skills.sh 则是已分发 `.claude/skills/*` 的单 Skill 安装路径。
+```bash
+git clone https://github.com/Dimon94/cc-devflow.git
+cd cc-devflow
+npm install
+npm test
+npm run verify
+```
 
-## 📦 产物
+发布校验：
 
-- `cc-roadmap` 产出 `devflow/ROADMAP.md` 和 `devflow/BACKLOG.md`；如果使用内置同步脚本，还会维护 `devflow/roadmap-tracking.json` 作为 roadmap/backlog 的共享真相源
-- `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
-- `cc-plan` 产出 `planning/design.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
-- `cc-investigate` 产出 `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
-- `cc-do` 产出代码、测试、任务级 `checkpoint.json`，以及 workspace scratch 运行态
-- `cc-check` 产出 `report-card.json`
-- `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
+```bash
+npm run verify:publish
+```
 
-## Durable 与 Ephemeral
+主要贡献说明见 [`CONTRIBUTING.zh-CN.md`](./CONTRIBUTING.zh-CN.md)，里面包含公开入口规则、本地 CLI 冒烟验证、文档规则和 PR 期望。
 
-- `devflow/specs/` 保存 durable 的 capability 真相：`INDEX.md` 与 `capabilities/*.md`。
-- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；旧小写目录只作为历史兼容读取。
-- `devflow/changes/<change>/` 只保存 durable 的变更真相：`change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、`team-state.json`、任务级 `checkpoint.json`、`report-card.json`，以及唯一的最终 handoff 文件。
-- `devflow/workspaces/<change>/` 只保存 ephemeral runtime scratch，比如 worker assignment、journal、prompt 和 session log。
-- 凡是可以从 durable truth 即时再生的内容，都不应该持久化到 `devflow/changes/`。
+## 社区与贡献
 
-可以先看 [docs/examples/START-HERE.md](./docs/examples/START-HERE.md) 这个单页入口，它已经把样例选择、按产物反查和样例跳转合在一起了。样例和 skill 的版本绑定真相源在 [docs/examples/example-bindings.json](./docs/examples/example-bindings.json)。
+- 如果这个工作流对你有用，可以给项目一个 Star：[GitHub stars](https://github.com/Dimon94/cc-devflow/stargazers)
+- 可复现 Bug、陈旧文档、缺失平台适配，都可以开 issue。
+- PR 保持聚焦：一个 Skill、一个 CLI 行为、一个编译 / 适配修复，或一次文档清理。
+- 如果修改已发布 Skill，同一个 PR 里同步它的 `version`、本地 `CHANGELOG.md`、样例和受影响的公开文档。
+- 参与讨论前请阅读 [行为准则](./CODE_OF_CONDUCT.zh-CN.md)。
+- 漏洞报告请走 [安全策略](./SECURITY.zh-CN.md)，不要发到公开 issue。
 
-## 原则
+## Star History
 
-- 先 cc-roadmap，再执行
-- 新需求先计划，再写代码
-- bug 先调查，再修复
-- 先根因，再修 bug
-- 先证据，再宣布完成
-- ship 之后把结果回写到下一轮计划
+<a href="https://www.star-history.com/#Dimon94/cc-devflow&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Dimon94/cc-devflow&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Dimon94/cc-devflow&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Dimon94/cc-devflow&type=Date" />
+  </picture>
+</a>
 
-## 验证
+## License
 
-```bash
-find .claude/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
-find .claude/skills -mindepth 2 -maxdepth 3 -type f | sort
-npm run verify
-```
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+[中文版](./SECURITY.zh-CN.md) | [English](./SECURITY.md)
+
+## Supported Versions
+
+Security fixes target the latest published npm release and the current `main` branch. Older versions may receive fixes only when the issue is severe and the patch can be applied without expanding the public surface.
+
+| Version | Supported |
+| --- | --- |
+| latest npm release | Yes |
+| `main` branch | Yes |
+| older releases | Best effort |
+
+## What To Report
+
+Please report issues that could affect users installing or running cc-devflow, including:
+
+- arbitrary file write or path traversal through `cc-devflow init` or `cc-devflow adapt`
+- command injection or unsafe subprocess execution
+- unsafe handling of project configuration files
+- packaging mistakes that ship secrets, local cache, or unintended generated files
+- adapter output that silently rewrites unrelated project-owned files
+
+Regular bugs, stale docs, missing examples, and feature requests should use normal GitHub issues instead.
+
+## How To Report
+
+Use GitHub private vulnerability reporting if it is enabled for this repository. If it is not available, contact the maintainer through the least public channel listed on the GitHub profile or organization page.
+
+Include:
+
+- affected version or commit
+- operating system and Node.js version
+- exact command or workflow that triggers the issue
+- minimal reproduction project or file tree
+- observed impact
+- whether the issue has been disclosed elsewhere
+
+Do not publish exploit details in a public issue before maintainers have had a chance to triage.
+
+## Response Expectations
+
+Maintainers aim to:
+
+- acknowledge valid private reports within 7 days
+- confirm severity and affected surface before publishing details
+- fix high-impact issues on `main` first
+- publish a patched npm release when package users are affected
+- credit reporters when requested and appropriate
+
+These timelines are goals, not a paid support SLA.
+
+## Scope Notes
+
+cc-devflow installs and adapts agent workflow files inside user repositories. That means security review should focus on file boundaries, package contents, generated adapter outputs, and command execution. Agent behavior generated by downstream tools is out of scope unless cc-devflow itself creates the unsafe instruction or file mutation path.

package/SECURITY.zh-CN.md

@@ -0,0 +1,56 @@
+# 安全策略
+
+[中文版](./SECURITY.zh-CN.md) | [English](./SECURITY.md)
+
+## 支持版本
+
+安全修复优先覆盖最新 npm 发布版本和当前 `main` 分支。旧版本只在问题严重且补丁不扩大公开入口时尽力处理。
+
+| 版本 | 是否支持 |
+| --- | --- |
+| 最新 npm 发布版本 | 是 |
+| `main` 分支 | 是 |
+| 旧版本 | 尽力处理 |
+
+## 报告范围
+
+请报告会影响用户安装或运行 cc-devflow 的安全问题，例如：
+
+- `cc-devflow init` 或 `cc-devflow adapt` 存在任意文件写入或路径穿越
+- 命令注入或不安全的子进程执行
+- 项目配置文件处理不安全
+- 打包错误导致 secret、本地缓存或非预期生成文件被发布
+- adapter 输出静默改写了项目自有的无关文件
+
+普通 Bug、陈旧文档、缺失样例和功能请求，请走正常 GitHub issue。
+
+## 报告方式
+
+如果仓库启用了 GitHub private vulnerability reporting，请优先使用它。如果不可用，请通过 GitHub profile 或组织页面上列出的最不公开渠道联系维护者。
+
+报告请包含：
+
+- 受影响版本或 commit
+- 操作系统和 Node.js 版本
+- 触发问题的精确命令或工作流
+- 最小复现项目或文件树
+- 已观察到的影响
+- 问题是否已在其他地方披露
+
+在维护者完成初步分级前，不要在公开 issue 中发布漏洞利用细节。
+
+## 响应预期
+
+维护者目标是：
+
+- 在 7 天内确认有效的私密报告
+- 先确认严重程度和受影响范围，再公开细节
+- 高影响问题先修复到 `main`
+- 当包用户受影响时发布修复后的 npm 版本
+- 在报告者希望且条件合适时给予致谢
+
+这些时间是维护目标，不是付费支持 SLA。
+
+## 范围说明
+
+cc-devflow 会在用户仓库中安装和适配 Agent 工作流文件。因此安全审查重点应放在文件边界、包内容、生成的 adapter 输出和命令执行。下游工具生成的 Agent 行为不在范围内，除非不安全指令或文件修改路径由 cc-devflow 自身创建。