cc-devflow 4.3.0 → 4.5.0

package/README.zh-CN.md

@@ -1,8 +1,8 @@
 # 🚀 cc-devflow
 
-> Claude Code Harness 主链需求开发流系统
+> 面向 Agent 编程的 cc-roadmap + PDCA / IDCA 技能体系
 
-基于 Claude Code 官方子代理、钩子和设置机制构建的完整开发工作流系统。通过可恢复的命令链将需求从规划推进到代码交付。
+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`。
 
 [中文文档](./README.zh-CN.md) | [English](./README.md)
 
@@ -10,823 +10,229 @@
 
 ## 🎯 一句话介绍
 
-基于 harness 的 5 阶段主链：`/flow:init` → `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`。
+CC-DevFlow 现在暴露 6 个可见 Skill：
 
----
+- `cc-roadmap`: 产出项目的中长期路线图
+- `cc-plan`: 澄清 roadmap item，设计方案，拆成任务
+- `cc-investigate`: 冻结症状、复现、根因和修复任务，再把 bug 交给执行环
+- `cc-do`: 实现、恢复、按调查 handoff 修复 bug、处理 review feedback
+- `cc-check`: 用证据做验证
+- `cc-act`: ship、同步文档、把结果回写到下一轮
 
 ## ✨ 核心特性
 
-- 🎯 **Harness 主链** - 默认路径固定为 `/flow:init` → `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`
-- 🔄 **NPM 命令链** - 流程命令统一映射到 `harness:*` 运行时操作，支持断点与恢复
-- 📋 **文档驱动** - 自动化 PRD → UI原型 → EPIC → TASKS → 实现链条
-- 📝 **模板驱动** - 自执行模板（PRD_TEMPLATE, EPIC_TEMPLATE, TASKS_TEMPLATE）
-- 🔄 **智能恢复** - `harness:resume` 基于 checkpoint 恢复中断任务
-- 🛡️ **质量闸** - 自动化 TypeScript 检查、测试、代码检查和安全扫描
-- 🤖 **子代理编排** - 12 个专业研究型代理负责不同开发阶段
-- 🎨 **UI原型生成** - 条件触发的HTML原型，融合艺术设计灵感
-- 🔗 **GitHub 集成** - 自动化 PR 创建、分支管理和规范化提交
-- 📊 **进度跟踪** - 实时状态监控和智能重启点
-- 🔍 **一致性验证** - 企业级一致性检查，智能冲突检测
-- 🧪 **TDD 强制执行** - 严格的测试驱动开发，harness planner 自动 TDD 顺序验证
-- 📜 **Constitution** - 10条宪法条款管控质量、安全和架构
-- 🔄 **OpenSpec 互操作** - OpenSpec 与 CC-DevFlow 格式双向转换，自动生成 TDD 任务
-- 🔄 **自主开发** - Ralph × Manus 集成实现有记忆的持续迭代
-- 🔌 **多平台支持** - 通过 `npm run adapt` 编译工作流到 Codex、Cursor、Qwen、Antigravity
-- 🔄 **多模块编译器** - 完整模块编译：skills、commands、agents、rules、hooks
-- 🌿 **Git Worktree 集成** - 支持 3-5 个并行 Claude 会话的隔离 worktree 开发
-- 🤝 **Claude Team 集成** - 多 Agent 并行协作，自动任务调度和冲突检测
-
----
-
-## 💡 核心概念
-
-### Hooks 系统
-
-实时质量守护，PreToolUse 阻止不合规操作，PostToolUse 自动记录变更。
-
-<details>
-<summary>📖 Hooks 详解（点击展开）</summary>
-
-**Hook 类型**:
-
-| Hook | 触发时机 | 功能 |
-|------|---------|------|
-| **UserPromptSubmit** | 用户输入提交时 | 智能推荐相关 Skills |
-| **PreToolUse** | 工具使用前 | 阻止不合规操作（TDD 违规等） |
-| **PostToolUse** | 工具使用后 | 自动记录文件变更 |
-| **Stop** | 会话停止时 | 提供错误处理提示 |
-
-**Guardrail 工作流程**:
-```
-用户编辑文件 → PreToolUse Hook 触发
-  ↓ 路径归一化
-  ↓ 规则匹配
-  ↓ 内容检查
-  ↓ 违规？阻止操作 : 允许操作
-```
-
-**跳过 Guardrail**:
-```bash
-# 方式 1: 文件标记
-echo "@skip-tdd-check" >> devflow/requirements/REQ-123/TASKS.md
-
-# 方式 2: 环境变量
-export SKIP_TDD_ENFORCER=1
-```
-
-📚 [完整 Hooks 文档](docs/guides/hooks-system.zh-CN.md)
-</details>
-
-### Skills 系统 (v4.0 Skills-First 架构)
+- **可见面极小**：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 执行
 
-智能知识库激活，分组 Skills 与自动上下文注入。
+## 🧠 心智模型
 
-<details>
-<summary>📖 Skills 详解（点击展开）</summary>
-
-**Skills-First 架构** (v4.0):
+```text
+cc-roadmap
 
-```
-.claude/skills/
-├── workflow.yaml           # Skill 依赖图 (借鉴 OpenSpec)
-├── workflow/               # 9 个工作流 Skills (flow-init, flow-spec, flow-dev 等)
-├── domain/                 # 7 个领域 Skills (tdd, debugging, brainstorming)
-├── guardrail/              # 3 个守护 Skills (constitution-guardian, tdd-enforcer)
-└── utility/                # 8 个工具 Skills (npm-release, skill-creator)
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 ```
 
-**按分类的关键 Skills**:
+先用 `cc-roadmap` 决定接下来 1-3 个阶段做什么。
 
-| 分类 | Skills | 用途 |
-|------|--------|------|
-| **Workflow** | flow-init, flow-spec, flow-dev, flow-verify, flow-release | 核心开发工作流 |
-| **Domain** | tdd, debugging, brainstorming, verification | 领域专业知识 |
-| **Guardrail** | constitution-guardian, tdd-enforcer | 实时合规检查 |
-| **Utility** | npm-release, skill-creator, writing-skills | 开发工具 |
+当问题是 feature / scope / task freezing，就走 `cc-plan`。
 
-**上下文注入** (借鉴 Trellis):
-- 每个 Skill 有 `context.jsonl` 定义所需上下文文件
-- `inject-skill-context.ts` 钩子在 Skill 执行前自动加载上下文
-- 变量替换: `{REQ}` → 实际需求 ID
+当问题是 bug 根因 / regression / 复现链，就走 `cc-investigate`。
 
-📚 [完整 Skills 文档](docs/guides/skills-system.zh-CN.md)
-</details>
+两条闭环最后都会并回同一条 `cc-do -> cc-check -> cc-act` 主干。
 
-### Agent Orchestration
-
-研究型代理（11个，只读分析）+ 主代理（执行）的双层执行模型。
-
-<details>
-<summary>📖 代理编排详解（点击展开）</summary>
-
-**执行模型**:
-- **研究型代理**: 只读分析，生成 Markdown 计划和报告
-- **主代理 (Claude)**: 执行所有代码操作，拥有完整上下文
-- **工作流程**: 代理研究 → 输出计划 → 主代理执行 → 迭代
-
-**工具分配**:
-- 研究型代理: Read, Grep, Glob（分析）
-- 主代理: Edit, Write, Bash, Git（执行）
-
-📚 [执行模型详解](docs/architecture/execution-model.zh-CN.md)
-</details>
-
----
+这条可见状态机直接写在公开 Skill 里。整个包现在明确是 skill-first：路由、reroute、恢复和证据规则由 `SKILL.md` 与 `PLAYBOOK.md` 显式声明，`lib/skill-runtime/` 只保留给这些 Skill 复用的薄共享支撑代码。
 
-## 🚀 快速开始
+## 🚀 安装
 
-### 安装
+内置 CLI 已回到经典的 `init + adapt` 模式。
 
-#### 方式 1: 从 npm 安装（推荐）
+对外打包后的默认入口应保持简洁：
 
 ```bash
-# 全局安装
-npm install -g cc-devflow
-# 或
-pnpm add -g cc-devflow
-
-# 在项目中初始化
-cc-devflow init
-
-# 编译到特定平台（可选）
-cc-devflow adapt --platform cursor
-cc-devflow adapt --platform codex
-cc-devflow adapt --platform antigravity
-cc-devflow adapt --platform qwen
+npx cc-devflow init --dir /path/to/your/project
 ```
 
-#### 方式 2: 手动安装
+安装后，恢复后的 CLI 同时支持整包安装和多平台适配：
 
 ```bash
-pnpm dlx tiged Dimon94/cc-devflow/.claude .claude
+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
 ```
 
-#### 更新指南 (Update)
+整包安装会带上 6 个可见 workflow skill，再额外带上维护类 skill `cc-spec-init` 和 `cc-simplify`。
+`init --force` 现在只会强制升级 cc-devflow 管理的分发 skill，不会删除项目里其他现有的 `.claude` 文件。
 
-更新到最新版本并同步本地项目：
+如果你不是通过已安装包，而是在源码仓库里调试 CLI，本地运行请用 `node bin/cc-devflow-cli.js ...` 或 `npm exec -- cc-devflow ...`。
 
-```bash
-# 全局更新
-npm install -g cc-devflow@latest
-
-# 更新本地项目文件（将覆盖冲突文件）
-cc-devflow init
-```
-
-### CLI 使用
-
-```bash
-# 在当前目录初始化
-cc-devflow init
-
-# 在指定目录初始化
-cc-devflow init --dir /path/to/project
+## ⚙️ 个人 YAML 配置
 
-# 编译到特定平台
-cc-devflow adapt --platform codex
-cc-devflow adapt --cwd /path/to/project --platform cursor
+CC-DevFlow 会在写入 durable workflow 文档前按运行时读取个人 / 项目 YAML 配置。配置文件支持三层：
 
-# 直接运行 harness runtime（供 npm scripts 委派）
-cc-devflow harness release --change-id REQ-123
+```text
+~/.cc-devflow/config.yml
+<repo>/.cc-devflow/config.yml
+<repo>/.cc-devflow/config.local.yml
 ```
 
-`cc-devflow init` 与 `cc-devflow adapt` 现在会自动补齐 `package.json` 中缺失的 `harness:*` scripts，且统一写入可移植的 `cc-devflow harness <subcommand>`（不使用机器绝对路径），避免 `/flow:*` 因脚本缺失退化到手工 fallback。
+优先级固定为：默认值 < 用户 < 项目 < 本地 < 环境变量 < CLI 参数。`output.document_language` 是机器约束，目前只支持 `en` 和 `zh-CN`。非标偏好统一放在 `agent_preferences` 下，它只作为表达和格式建议，不覆盖 workflow 合同。
 
-### 验证安装
+最小示例：
 
-```bash
-.claude/scripts/verify-setup.sh
+```yaml
+version: 1
+output:
+  document_language: zh-CN
+agent_preferences:
+  general:
+    - 先给结论。
+  documentation:
+    - 标题短一些，避免营销腔。
 ```
 
-### 第一个需求
+创建或修改配置：
 
 ```bash
-/flow:init "REQ-001|用户认证|https://docs.example.com/auth"
-/flow:spec "REQ-001"
-/flow:dev "REQ-001"
-/flow:verify "REQ-001" --strict
-/flow:release "REQ-001"
+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 set output.document_language zh-CN --user
 ```
 
-<details>
-<summary>🔍 完整入门教程（点击展开）</summary>
+查看和诊断解析后的策略：
 
-**交互式演示**:
 ```bash
-python3 .claude/scripts/demo.py
+npx cc-devflow config resolve --cwd /path/to/your/project --format policy
+npx cc-devflow config get output.document_language --cwd /path/to/your/project
+npx cc-devflow config doctor --cwd /path/to/your/project
 ```
 
-**核心脚本**:
-```bash
-# 环境检查
-bash .claude/scripts/check-prerequisites.sh
+完整样例见 `config/user-config.template.yml`。
 
-# 查看任务状态
-bash .claude/scripts/check-task-status.sh --verbose
+## 🧩 skills.sh 分发
 
-# 标记任务完成
-bash .claude/scripts/mark-task-complete.sh T001
+[skills.sh](https://skills.sh/) 只作为新的 `.claude` Skill 分发渠道使用。
 
-# 生成状态报告
-bash .claude/scripts/generate-status-report.sh --format markdown
-```
+因为 skills.sh 是按单个 Skill 安装，所以按需拉取对应 Skill：
 
-**运行测试**:
 ```bash
-# 运行所有测试
-bash .claude/tests/run-all-tests.sh --scripts
-
-# Constitution 测试
-bash .claude/tests/constitution/run_all_constitution_tests.sh
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-plan
+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
 ```
 
-📚 [完整入门指南](docs/guides/getting-started.zh-CN.md)
-</details>
-
----
+当你想拿整包 `.claude` 时，用 `cc-devflow init`。
 
-## 📋 命令速查表
+当你想生成多平台产物时，用 `cc-devflow adapt`。
 
-### 🏢 项目级命令（Project-Level）
+skills.sh 仍然用于按单个 Skill 安装或刷新。
 
-**用途**: 项目整体规划和架构设计，通常在项目初期执行一次
+## 🔁 升级
 
-| 命令 | 用途 | 快速示例 | 详细文档 |
-|------|------|----------|----------|
-| `/core-roadmap` | 🗺️ 生成产品路线图 | `/core-roadmap` | [→](docs/commands/core-roadmap.zh-CN.md) |
-| `/core-architecture` | 🏗️ 生成系统架构 | `/core-architecture` | [→](docs/commands/core-architecture.zh-CN.md) |
-| `/core-guidelines` | 📘 生成项目规范 | `/core-guidelines` | [→](docs/commands/core-guidelines.zh-CN.md) |
-| `/core-style` | 🎨 生成设计风格指南 | `/core-style` | [→](docs/commands/core-style.zh-CN.md) |
+通过最新版 CLI 刷新整包并重新执行适配：
 
-### 📦 需求级命令（Requirement-Level）
-
-**用途**: 具体需求开发，每个需求（REQ-XXX）执行一次
-
-| 命令 | 用途 | 快速示例 | 详细文档 |
-|------|------|----------|----------|
-| `/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"` | [→](.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:fix` | 🐛 系统化缺陷修复 | `/flow:fix "BUG-123\|描述"` | [→](.claude/commands/flow/fix.md) |
-| `/flow:new` | ⚠️ 已废弃别名 | 改用 `/flow:init` 主链 | [→](.claude/commands/flow/new.md) |
-| `/flow:clarify` | ⚠️ 已废弃 | 合并入 `/flow:spec` | [→](.claude/commands/flow/clarify.md) |
-| `/flow:checklist` | ⚠️ 已废弃 | 改用 `/flow:verify --strict` | [→](.claude/commands/flow/checklist.md) |
-| `/flow:quality` | ⚠️ 已废弃 | 改用 `/flow:verify` | [→](.claude/commands/flow/quality.md) |
-
-📚 [完整命令参考](docs/commands/README.zh-CN.md)
-
-<details>
-<summary>🎯 我应该用哪个命令？（点击展开）</summary>
-
-```
-你的场景：
-├─ 规划产品方向？ → /core-roadmap
-├─ 设计系统架构？ → /core-architecture
-├─ 建立编码规范？ → /core-guidelines
-├─ 建立设计风格指南？ → /core-style
-├─ 启动需求交付？ → /flow:init "REQ-123|功能|URLs"
-├─ 生成任务清单？ → /flow:spec "REQ-123"
-├─ 执行任务？ → /flow:dev "REQ-123"
-├─ 严格质量闸？ → /flow:verify "REQ-123" --strict
-├─ 开发中断需要继续？ → /flow:restart "REQ-123"
-├─ 检查开发进度？ → /flow:status REQ-123
-├─ 任意阶段复检一致性？ → /flow:verify "REQ-123"
-├─ 修复生产 Bug？ → /flow:fix "BUG-001|描述"
-└─ 准备发布？ → /flow:release "REQ-123"
+```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
 ```
-</details>
 
----
+如果你只想立刻刷新某一个 Skill，直接重跑它对应的 `npx skills add ... --skill ...` 命令即可。
 
-## 🔄 工作流程图
-
-以下 Mermaid 流程图展示了完整的 cc-devflow 工作流，包括项目级和需求级两个层面的流程：
-
-```mermaid
-graph TB
-    Start([项目启动]) --> ProjectLevel{项目级初始化}
-
-    ProjectLevel --> CoreRoadmap["/core-roadmap<br/>ROADMAP.md & BACKLOG.md"]
-    ProjectLevel --> CoreArch["/core-architecture<br/>ARCHITECTURE.md"]
-    ProjectLevel --> CoreGuidelines["/core-guidelines<br/>前端/后端规范"]
-    ProjectLevel --> CoreStyle["/core-style<br/>STYLE.md"]
-
-    CoreRoadmap --> ReqLevel
-    CoreArch --> ReqLevel
-    CoreGuidelines --> ReqLevel
-    CoreStyle --> ReqLevel
-
-    ReqLevel([需求级开发流程]) --> FlowInit["/flow:init<br/>harness:init + harness:pack"]
-    FlowInit --> FlowSpec["/flow:spec<br/>harness:plan<br/>task-manifest"]
-    FlowSpec --> FlowDev["/flow:dev<br/>harness:dispatch/resume<br/>runtime-events"]
-    FlowDev --> FlowVerify["/flow:verify<br/>harness:verify<br/>report-card"]
-    FlowVerify --> FlowRelease["/flow:release<br/>harness:release/janitor<br/>release-note"]
-    FlowRelease --> End([发布完成])
-
-    FlowVerify -.->|可在任意阶段重跑| ReqLevel
-
-    style ProjectLevel fill:#e1f5ff
-    style ReqLevel fill:#fff4e1
-    style FlowInit fill:#e8f5e9
-    style FlowSpec fill:#e8f5e9
-    style FlowDev fill:#f3e5f5
-    style FlowVerify fill:#fce4ec
-    style FlowRelease fill:#e0f2f1
-    style End fill:#e3f2fd
-```
+## 🧱 skills.sh 项目格式
 
-**流程说明**:
-- **项目级命令**（浅蓝色）：项目初始化时执行一次，建立全局标准（SSOT）
-- **需求级命令**（浅橙色）：每个需求（REQ-XXX）执行一次
-- **默认主链**：`/flow:init` → `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`
-- **Harness 运行时链路**：各阶段统一委托 `npm run harness:*`，并持久化 checkpoint
-- **统一 /flow:spec**：将规格阶段收敛为单一任务清单产出
-- **报告卡质量闸**：`/flow:verify --strict` 不通过时阻断发布
-- **TDD 强制执行**：`/flow:dev` 保留 fail-first 检查
-- **废弃命令**：`/flow:new`、`/flow:clarify`、`/flow:checklist`、`/flow:quality` 仅保留迁移提示
+CC-DevFlow 让 `.claude` Skill 目录保持与 skills.sh 单 Skill 分发兼容：
 
----
+- 一个 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/`
 
-## 🏗️ 系统架构
+同时，公开 Skill 还带两层文本契约：
 
-**执行模型**: 研究型代理（11个，只读）+ 主代理（执行）
-**文档结构**: 单轨架构，一个需求目录包含所有产物
-**质量保证**: Constitution v2.0.0 + TDD 强制执行 + 实时 Guardrail
+- `SKILL.md` 里有 `Harness Contract`
+- `PLAYBOOK.md` 里有 `Visible State Machine`
 
-<details>
-<summary>📖 架构详解（点击展开）</summary>
+这个仓库当前对外分发的 Skill 目录如下：
 
-### 子代理工作流
+- `.claude/skills/cc-roadmap/`
+- `.claude/skills/cc-plan/`
+- `.claude/skills/cc-investigate/`
+- `.claude/skills/cc-do/`
+- `.claude/skills/cc-check/`
+- `.claude/skills/cc-act/`
+- `.claude/skills/cc-spec-init/`
+- `.claude/skills/cc-simplify/`
 
-```text
-clarify-analyst     → 澄清问题（11 维度歧义扫描）
-prd-writer          → PRD 生成（必须使用 PRD_TEMPLATE）
-checklist-agent     → 需求质量验证（5 维度，6 类型）⭐ 新增
-ui-designer         → UI 原型（条件触发）
-tech-architect      → 技术设计（Anti-Tech-Creep 强制执行）
-planner             → EPIC & TASKS（必须使用 EPIC_TEMPLATE, TASKS_TEMPLATE）
-dev-implementer     → 实现计划（仅研究）
-qa-tester           → 测试计划 + 测试报告
-security-reviewer   → 安全计划 + 安全报告
-release-manager     → 发布计划
-```
+## 🛠️ 使用
 
-### 单轨架构
+Skill 顺序仍然是：
 
 ```text
-devflow/
-├── ROADMAP.md               # 产品路线图
-├── ARCHITECTURE.md          # 系统架构设计
-├── BACKLOG.md               # 需求待办列表
-└── requirements/REQ-123/
-    ├── PRD.md
-    ├── EPIC.md
-    ├── TASKS.md
-    ├── EXECUTION_LOG.md
-    ├── checklists/          # 需求质量检查清单
-    │   ├── ux.md
-    │   ├── api.md
-    │   └── security.md
-    ├── TEST_PLAN.md
-    ├── TEST_REPORT.md
-    ├── SECURITY_PLAN.md
-    ├── SECURITY_REPORT.md
-    └── RELEASE_PLAN.md
+1. cc-roadmap
+2. 在 cc-plan 和 cc-investigate 里二选一
+3. cc-do
+4. cc-check
+5. cc-act
+6. repeat
 ```
 
-### 质量闸
+你不需要记命令名。
 
-- Pre-push Guard（TypeScript、测试、代码检查、安全、构建）
-- Report Card Gate（`/flow:verify --strict`，在 `/flow:release` 前执行）
-- Constitution Compliance（每个阶段强制执行）
-- TDD Checkpoint（TEST VERIFICATION CHECKPOINT）
-- Guardrail Hooks（PreToolUse 实时阻止不合规操作）
+`cc-devflow` CLI 仍然是整包安装与适配路径。
 
-📚 [完整架构文档](docs/architecture/README.zh-CN.md)
-</details>
+skills.sh 则是已分发 `.claude/skills/*` 的单 Skill 安装路径。
 
----
+## 📦 产物
 
-## ⚙️ 配置
+- `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`
 
-**最小配置** (`.claude/settings.json`):
+## Durable 与 Ephemeral
 
-```json
-{
-  "permissions": {
-    "allowGitOperations": true,
-    "allowNetworkRequests": true,
-    "allowSubprocesses": true
-  }
-}
-```
-
-<details>
-<summary>🔧 完整配置选项（点击展开）</summary>
-
-### Hooks 配置
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Edit|Write",
-      "hooks": [{"type": "command", "command": "..."}]
-    }]
-  }
-}
-```
-
-### 环境变量
-
-```bash
-# 流程行为
-export FLOW_AUTO_APPROVE=false
-export MIN_TEST_COVERAGE=80
-export STRICT_TYPE_CHECKING=true
-
-# Guardrail 跳过
-export SKIP_TDD_ENFORCER=1
-export SKIP_CONSTITUTION_CHECK=1
-```
-
-📚 [完整配置指南](docs/guides/configuration.zh-CN.md)
-</details>
-
----
-
-## 🧪 测试覆盖
-
-**脚本测试**: 8/8 通过 ✅ (100%)
-**Constitution 测试**: 38/38 通过 ✅ (100%)
-
-```bash
-# 运行所有测试
-bash .claude/tests/run-all-tests.sh --scripts
-```
-
-<details>
-<summary>📊 测试框架详解（点击展开）</summary>
-
-### 测试套件
-
-| 测试套件 | 测试用例数 | 状态 |
-|----------|-----------|------|
-| `test_check_prerequisites` | 18 | ✅ 100% |
-| `test_check_task_status` | 18 | ✅ 100% |
-| `test_common` | 15 | ✅ 100% |
-| `test_mark_task_complete` | 15 | ✅ 100% |
-| `test_setup_epic` | 13 | ✅ 100% |
-| `test_validate_constitution` | 4 | ✅ 100% |
-
-📚 [测试框架详解](docs/guides/testing-guide.zh-CN.md)
-</details>
-
----
-
-## 📝 版本历史
-
-说明：v6.0.0 之前的条目保留当时的命令写法，用于历史追踪。
-
-### v6.0.0 (2026-02-18) - 最新版本
-
-**🧩 Harness-First 主链：默认流程收敛为可审计运行时**
+- `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/`。
 
-v6.0.0 将 cc-devflow 收敛为单一默认路径，并由内部 runtime 引擎驱动：
+可以先看 [docs/examples/START-HERE.md](./docs/examples/START-HERE.md) 这个单页入口，它已经把样例选择、按产物反查和样例跳转合在一起了。样例和 skill 的版本绑定真相源在 [docs/examples/example-bindings.json](./docs/examples/example-bindings.json)。
 
-- **默认命令链**
-  - `/flow:init` → `/flow:spec` → `/flow:dev` → `/flow:verify` → `/flow:release`
-  - 每个阶段都映射到 `npm run harness:*`，保证流程可恢复、可追踪
+## 原则
 
-- **核心运行时产物**
-  - `context-package.md` + `harness-state.json`：初始化状态
-  - `task-manifest.json` + `runtime-events.jsonl`：执行轨迹
-  - `report-card.json` + `release-note.md`：质量与发布证据
+- 先 cc-roadmap，再执行
+- 新需求先计划，再写代码
+- bug 先调查，再修复
+- 先根因，再修 bug
+- 先证据，再宣布完成
+- ship 之后把结果回写到下一轮计划
 
-- **废弃命令迁移**
-  - `/flow:new` → 改为显式执行 5 阶段主链
-  - `/flow:clarify` → 合并进 `/flow:spec` 规划闭环
-  - `/flow:checklist`、`/flow:quality` → 统一迁移到 `/flow:verify`
+## 验证
 
-**📊 v6.0 改进指标**:
-| 指标 | 之前 | 之后 | 改善 |
-|------|------|------|------|
-| 默认需求命令路径 | 8+ 条混合路径 | 固定 5 阶段主链 | 显著简化 |
-| 中断恢复能力 | 命令分散实现 | 统一 `harness:resume` | 更稳定 |
-| 质量证据 | 分散产物 | 单一 report-card 闸门 | 可审计 |
-
-### v4.7.0 (2026-02-07)
-
-**🤝 Claude Team 集成：多 Agent 并行协作**
-
-v4.7.0 引入 Claude Team 集成，支持多 Agent 并行开发：
-
-- **flow-dev Team 模式** - 多 Agent 并行任务执行
-  - `--team` 标志启用 Team 模式（默认 3 个 Agent）
-  - `--agents N` 指定 Agent 数量（2-5）
-  - 自动任务依赖分析和冲突检测
-  - 文件冲突任务分配给同一 Agent 串行执行
-
-- **新增 Hooks** - Team 生命周期管理
-  - `TeammateIdle Hook` - 任务分配和调度
-  - `TaskCompleted Hook` - 完成时质量验证
-  - 超时检测和告警
-
-- **任务依赖解析器** - 智能任务分析
-  - `parse-task-dependencies.js` - 解析 TASKS.md 格式
-  - 识别 `[P]` 并行标记、`[US*]` 用户故事分组
-  - 基于 Phase 的依赖解析
-
-- **状态恢复** - 断点续传
-  - `team-state-recovery.sh` - 快照和恢复 Team 状态
-  - 支持中断会话恢复
-
-- **新增文件**
-  - `.claude/scripts/parse-task-dependencies.js` - 任务解析器
-  - `.claude/scripts/detect-file-conflicts.sh` - 冲突检测
-  - `.claude/scripts/team-dev-init.sh` - Dev Team 初始化
-  - `.claude/scripts/team-state-recovery.sh` - 状态恢复
-  - `.claude/docs/guides/TEAM_MODE_GUIDE.md` - 完整使用指南
-
-**📊 v4.7 改进指标**:
-| 指标 | 之前 | 之后 | 改善 |
-|------|------|------|------|
-| 并行 Agent 数 | 1 | 3-5 | +400% |
-| 需求完成时间 | 90 分钟 | 50 分钟 | -45% |
-| 任务调度 | 手动 | 自动 | 100% |
-| 质量验证 | 单点 | 分布式 | 100% |
-
-### v4.3.0 (2026-02-07)
-
-**🌿 Git Worktree 集成：并行开发支持**
-
-v4.3.0 引入 Git Worktree 集成，支持多个隔离的 Claude Code 会话并行开发：
-
-- **Git Worktree 模式（默认）** - 隔离的开发环境
-  - 创建 `../repo-name-REQ-xxx/` worktree 目录
-  - 每个 worktree 有独立的 Claude Code 会话
-  - 用 `cd` 切换需求，而非 `git checkout`
-  - `--branch-only` 标志支持传统分支模式
-
-- **新增 Skill: using-git-worktrees** - 完整的 worktree 管理
-  - `worktree-create.sh` - 创建新 worktree
-  - `worktree-list.sh` - 列出所有 worktree
-  - `worktree-switch.sh` - 切换 worktree
-  - `worktree-cleanup.sh` - 清理已合并的 worktree
-  - Shell 别名模板 (za/zl/zm/zw)
-
-- **修改的命令**
-  - `/flow:init` - 默认 worktree 模式，`--branch-only` 兼容旧模式
-  - `/flow:release` - 自动清理 worktree
-
-**📊 v4.3 改进指标**:
-| 指标 | 之前 | 之后 | 改善 |
-|------|------|------|------|
-| 并行需求数 | 1 | 3-5 | +400% |
-| 上下文切换时间 | 30s | 1s | -97% |
-| 会话隔离 | 无 | 完全 | 100% |
-
-### v4.1.0 (2026-02-07)
-
-**🎯 统一规格阶段：/flow:spec 命令**
-
-v4.1.0 将 flow-prd/flow-tech/flow-ui/flow-epic 合并为单一 `/flow:spec` 命令，支持并行执行：
-
-- **统一 /flow:spec 命令** - 一个命令完成整个规格阶段
-  - 完整模式：PRD → Tech + UI（并行）→ Epic/Tasks
-  - 快速模式：`--skip-tech --skip-ui` 适用于小需求
-  - 仅后端：`--skip-ui`
-  - 仅前端：`--skip-tech`
-
-- **并行 Agent 执行** - Tech + UI 代理并发运行
-  - 设计阶段时间减少约 35%
-  - 共享模板组件位于 `_shared/` 目录
-
-- **简化工作流** (v4.1)
-  ```
-  精简 (3 步):   /flow:init --quick → /flow:spec --skip-tech --skip-ui → /flow:dev → /flow:release
-  标准 (4 步):   /flow:init → /flow:spec → /flow:dev → /flow:verify → /flow:release
-  完整 (5 步):   /flow:init → /flow:spec → /flow:dev → /flow:verify --strict → /flow:release
-  ```
-
-- **废弃命令**：`/flow-prd`、`/flow-tech`、`/flow-ui`、`/flow-epic` 已废弃（请使用 `/flow:spec`）
-
-**📊 v4.1 改进指标**:
-| 指标 | 之前 (v4.0) | 之后 (v4.1) | 改善 |
-|------|-------------|-------------|------|
-| 命令调用次数 | 4 | 1 | -75% |
-| 设计阶段时间 | 8-12 分钟 | 5-8 分钟 | -35% |
-| Entry/Exit Gate 代码 | ~280 行 | ~100 行 | -64% |
-
-### v4.0.0 (2026-02-07)
-
-**🏗️ Skills-First 架构：统一 Skills 与上下文注入**
-
-v4.0.0 引入重大架构重构，将 135 个文件重组为统一的 Skills-First 架构，借鉴 Trellis 和 OpenSpec：
-
-- **Skills-First 架构** - 所有 Skills 组织为 4 个分组
-  - `workflow/`: 9 个核心工作流 Skills (flow-init, flow-spec, flow-dev 等)
-  - `domain/`: 7 个领域专业 Skills (tdd, debugging, brainstorming, verification)
-  - `guardrail/`: 3 个实时合规 Skills (constitution-guardian, tdd-enforcer)
-  - `utility/`: 8 个开发工具 Skills (npm-release, skill-creator, writing-skills)
-
-- **JSONL 上下文注入** (借鉴 Trellis)
-  - 每个 Skill 有 `context.jsonl` 定义所需上下文文件
-  - `inject-skill-context.ts` 钩子在 Skill 执行前自动加载上下文
-  - 变量替换: `{REQ}` 替换为实际需求 ID
-  - 支持可选文件 `"optional": true`
-
-- **workflow.yaml 依赖图** (借鉴 OpenSpec)
-  - 通过 `requires` 和 `generates` 定义 Skill 依赖
-  - 文件存在性状态检测
-  - 清晰可视化 Skill 执行顺序
-
-- **自包含 Skills**
-  - 每个 Skill 目录包含: SKILL.md + context.jsonl + scripts/ + references/ + assets/
-  - SKILL.md 限制 <500 行，聚焦核心指令
-  - Agent 指令移至 `references/` 子目录
-  - 模板移至 `assets/` 子目录
-
-- **多模块跨平台编译器** (v3.0)
-  - 完整模块编译：skills、commands、agents、rules、hooks
-  - 平台专用输出格式：
-    - **Codex**: `.codex/skills/`, `.codex/prompts/`, `AGENTS.md`
-    - **Cursor**: `.cursor/rules/*.mdc`, `.cursor/subagents/`, `hooks.json`
-    - **Qwen**: `.qwen/commands/*.toml`, `.qwen/agents/`, `CONTEXT.md`
-    - **Antigravity**: `.agent/skills/`, `.agent/workflows/`, `.agent/rules/`
-  - `context.jsonl` 编译时展开，支持平台专用格式
-  - 197 个测试通过（24 个新增多模块测试）
-
-**📊 v4.0 改进指标**:
-| 指标 | 之前 | 之后 | 改善 |
-|------|------|------|------|
-| 维护点 | 4 个目录 | 1 个目录 | -75% |
-| 上下文加载 | 手动全量 | 按需自动 | -70% token |
-| 依赖可见性 | 隐式 | 显式 (workflow.yaml) | +100% |
-| 平台模块支持 | 仅命令 | 全部模块 | +400% |
-
-**📁 新增文件**:
-- `.claude/skills/workflow.yaml` - Skill 依赖图
-- `.claude/hooks/inject-skill-context.ts` - 上下文注入钩子
-- `.claude/skills/workflow/*/context.jsonl` - 每个 Skill 的上下文定义
-- `devflow/spec/{frontend,backend,shared}/index.md` - 规范索引
-- `lib/compiler/context-expander.js` - Context.jsonl 展开模块
-- `lib/compiler/__tests__/multi-module-emitters.test.js` - 多模块测试
-
-### v2.3.0 (2026-01-08)
-
-**🛡️ 纪律系统：铁律 + 合理化防御 + 压力测试**
-
-v2.3.0 将 Constitution 从"文档"升级为"可执行纪律系统"，借鉴 superpowers 项目最佳实践：
-
-- **铁律 + 合理化表格** - 预先阻止 AI Agent 合理化尝试
-  - 10 条 Constitution 条款现在都有铁律（绝对禁止）
-  - 合理化表格采用 `| 借口 | 现实 |` 格式
-  - 红旗标志用于 AI 自检触发
-  - 集中式 `rationalization-library.md` 存储所有合理化
-
-- **两阶段代码审查** - `/flow-review` 命令（新增）
-  - 阶段 1：规格合规性（不信任实现者报告，直接读代码）
-  - 阶段 2：代码质量（仅在阶段 1 通过后运行）
-  - `spec-reviewer.md` 和 `code-quality-reviewer.md` 代理
-
-- **完成前验证** - 断言前先有证据
-  - `verification-before-completion` 技能
-  - `verify-gate.sh` 脚本用于所有流程出口闸门
-  - 没有新鲜验证证据不得声称完成
-
-- **系统化调试** - `/flow-fix` 增强 4 阶段调试
-  - 阶段 1：根因调查（尚未修复）
-  - 阶段 2：模式分析
-  - 阶段 3：假设和测试
-  - 阶段 4：TDD 实现
-  - `flow-debugging` 和 `flow-tdd` 技能
-
-- **头脑风暴集成** - `/flow:init` 现在包含头脑风暴
-  - `BRAINSTORM.md` 作为需求"北极星"
-  - `/flow:spec` 需要 BRAINSTORM 对齐检查
-  - `flow-brainstorming` 技能
-
-- **压力测试框架** - 技能的 TDD
-  - `tests/pressure-scenarios/` 包含 4 个场景
-  - 测试 AI 在时间/沉没成本/权威/疲劳压力下的行为
-  - `run-pressure-tests.sh` 运行器
-
-- **技能融合** - Superpowers 技能迁移到本地
-  - `flow-tdd`、`flow-debugging`、`flow-receiving-review`、`flow-finishing-branch`
-  - 所有 `superpowers:xxx` 引用替换为本地技能
-
-- **Ralph × Manus 集成** - 有记忆的自主开发（新增）
-  - 合并入 `/flow:dev` (默认自主模式)
-  - `flow-attention-refresh` 技能提供 4 个刷新协议
-  - `ERROR_LOG.md` 结构化错误追踪
-  - `research/attempts/` 失败痕迹记录
-  - Stop Hook 实现自引用循环
-  - `/flow:init` Stage 2.5 融入 Manus 研究方法
-  - 目标：无人工干预任务完成率 ≥85%
-
-**📋 Constitution v2.1.0**:
-- 所有 10 条条款现在都有铁律 + 合理化防御 + 红旗标志
-- 交叉引用到 `rationalization-library.md`
-
-**📁 新增文件**:
-- `.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 注册配置
-- `.claude/scripts/setup-ralph-loop.sh` - Ralph 状态初始化脚本
-- `.claude/docs/templates/ERROR_LOG_TEMPLATE.md` - 执行错误日志格式
-- `.claude/docs/templates/ATTEMPT_TEMPLATE.md` - 研究尝试日志格式
-- `.claude/agents/spec-reviewer.md` - 阶段 1 规格合规性审查员
-- `.claude/agents/code-quality-reviewer.md` - 阶段 2 代码质量审查员
-- `.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/` - 头脑风暴技能
-- `.claude/skills/flow-debugging/` - 系统化调试技能
-- `.claude/skills/flow-tdd/` - TDD 强制执行技能
-- `.claude/skills/flow-receiving-review/` - 审查反馈处理技能
-- `.claude/skills/flow-finishing-branch/` - 分支完成决策技能
-- `.claude/skills/verification-before-completion/` - 完成验证技能
-- `tests/` - 压力测试框架
-
-### v2.2.0 (2025-12-19)
-
-**🔌 多平台适配：Agent 适配器架构 + 命令编译器**
-
-v2.2.0 引入全面的多平台支持，让 cc-devflow 工作流能在多个 AI 编码助手上运行：
-
-- **Agent 适配器架构 (REQ-004)** - 平台差异的可插拔适配层
-  - 统一的 Agent Adapter 抽象（环境探测、命令执行、能力声明）
-  - Adapter Registry 支持自动检测和显式覆盖
-  - 内置适配器：Claude Code（默认）、Codex CLI、Cursor、Qwen、Antigravity
-  - 安全优先设计：能力白名单，高风险操作默认禁用
-  - 结构化日志便于调试和审计
-
-- **命令编译器 (REQ-005)** - 单一真相源编译
-  - `.claude/` 作为 SSOT，编译为平台原生格式
-  - `npm run adapt` CLI 多平台编译
-  - 支持平台：Codex (`.codex/`)、Cursor (`.cursor/`)、Qwen (`.qwen/`)、Antigravity (`.agent/`)
-  - 占位符展开：`{SCRIPT:*}`、`{TEMPLATE:*}`、`{GUIDE:*}`、`{AGENT_SCRIPT}`、`$ARGUMENTS`
-  - 模板/指南内联，自动嵌入引用内容
-  - 资源复制与路径重写（脚本、模板、指南 → 平台目录）
-  - 基于 Manifest 的增量编译和漂移检测
-
-- **适配器编译器 (REQ-006)** - 多平台规则入口文件生成
-  - 4 个平台专用规则 Emitters（Cursor MDC、Codex SKILL.md、Qwen TOML、Antigravity 12K 智能分块）
-  - 技能注册表编译（合并 `skill-rules.json` + `skill.md` 元数据）
-  - Manifest v2.0 扩展，支持 `skills` 和 `rulesEntry` 追踪
-  - `--rules` 和 `--skills` CLI 选项实现选择性编译
-  - **Bug 修复**：默认关闭模板内联（保持路径引用而非内联展开）
-  - 173 个测试，新模块覆盖率 87%
-
-**📦 新 CLI 工具**:
 ```bash
-npm run adapt                        # 编译到所有平台
-npm run adapt -- --platform codex    # 编译到指定平台
-npm run adapt -- --check             # 检查漂移（不编译）
-npm run adapt -- --verbose           # 显示详细输出
+find .claude/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
+find .claude/skills -mindepth 2 -maxdepth 3 -type f | sort
+npm run verify
 ```
-
-### v2.1.0 (2025-11-07)
-
-**🏢 核心突破：引入项目级命令（Project-Level Commands）**
-
-v2.1.0 的核心突破是引入了**项目级命令**，与之前的**需求级命令**形成两层体系：
-
-- **项目级命令** - 项目整体规划和架构设计（项目初期执行一次）
-  - `/core-roadmap` - 交互式产品路线图生成（6阶段对话）
-  - `/core-architecture` - 4种架构图生成（Mermaid格式）
-  - `/core-guidelines` - 项目规范生成（前端/后端分离）
-  - `/core-style` - 项目设计风格指南生成（视觉一致性SSOT）
-
-- **需求级命令增强** - Stage 1.5 路线图与架构上下文加载（flow-init）
-  - 初始化需求时自动加载项目级上下文
-  - 需求与路线图自动映射（RM-ID, Milestone, Quarter）
-  - 架构上下文自动关联（Feature Layer, Tech Stack, Module）
-
-**📚 文档改进**:
-- README 完全重构（完整目录 + 折叠 + 外部文档链接）
-- 新增 25+ 个详细文档
-
-📋 [完整变更日志](CHANGELOG.md)
-
----
-
-## 🤝 贡献 & 支持
-
-**贡献**: [贡献指南](CONTRIBUTING.md)
-**问题**: [GitHub Issues](https://github.com/Dimon94/cc-devflow/issues)
-**文档**: [完整文档](docs/)
-
----
-
-## 📄 许可证
-
-MIT License - 查看 [LICENSE](LICENSE) 文件
-
----
-
-**🌟 如果 cc-devflow 帮助简化了您的开发工作流，请为此仓库点星！**