cc-devflow 4.3.0 → 4.4.1

package/docs/guides/getting-started.zh-CN.md

@@ -1,150 +1,169 @@
-# 🚀 快速开始指南
+# cc-devflow 快速开始
 
-## 📦 安装
+[中文文档](./getting-started.zh-CN.md) | [English](./getting-started.md)
 
-### 方式 1: 使用 npx（推荐）
+---
 
-```bash
-pnpm dlx tiged Dimon94/cc-devflow/.claude .claude
-```
+## 概览
 
-### 方式 2: 手动下载
+CC-DevFlow 现在有两条入口：
 
-```bash
-curl -L https://github.com/Dimon94/cc-devflow/archive/main.zip -o cc-devflow.zip
-unzip cc-devflow.zip
-cp -r cc-devflow-main/.claude .claude
-rm -rf cc-devflow.zip cc-devflow-main
-```
+- `cc-devflow init`：把整包 `.claude` 安装到你的项目里
+- `cc-devflow adapt`：生成 Codex、Cursor、Qwen、Antigravity 等平台产物
 
-## ✅ 验证安装
+真正的工作流由 6 个可见 Skill 组成：
 
-```bash
-.claude/scripts/verify-setup.sh
-```
+```text
+cc-roadmap
 
-**预期输出**:
-```
-✅ All checks passed!
-cc-devflow is ready to use.
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 ```
 
-## 🎮 交互式演示
+公开 Skill 本身就是可见 harness。现在每个分发 `SKILL.md` 都带结构化 frontmatter 和 `Harness Contract`，每个 `PLAYBOOK.md` 都带 `Visible State Machine`，不再依赖隐藏运行时语义来理解阶段流转。
 
-运行完整演示了解工作流：
+## 前置条件
+
+- Node.js 18+
+- 已初始化的 Git 仓库
+- Claude Code 或其他受支持的 Agent 环境
+
+## 安装
+
+### 整包安装
 
 ```bash
-python3 .claude/scripts/demo.py
+npx cc-devflow init --dir /path/to/your/project
 ```
 
-## 🎯 第一个需求
+整包安装会带上 6 个可见 workflow skill，以及维护用的 `cc-spec-init` 和 `cc-simplify`。
 
-### 1. 启动需求开发
+### 单个 Skill 安装
 
 ```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 skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
 
-### 2. 查看进度
+## 生成平台产物
 
 ```bash
-/flow:status REQ-001
+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
 ```
 
-### 3. 如果中断，恢复开发
+## 验证安装
+
+检查 Skill 目录是否存在：
 
 ```bash
-/flow:dev "REQ-001" --resume
+find .claude/skills -mindepth 1 -maxdepth 1 -type d | sort
+find .claude/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 ```
 
-### 4. 验证一致性
+如果已经适配 Codex，再检查镜像出来的 skill 目录：
 
 ```bash
-/flow:verify "REQ-001" --strict
+find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 ```
 
-### 5. 创建发布
+## 第一次跑工作流
 
-```bash
-/flow:release "REQ-001"
+按这个顺序使用 Skill：
+
+```text
+1. cc-roadmap
+2. 在 cc-plan 和 cc-investigate 里二选一
+3. cc-do
+4. cc-check
+5. cc-act
+6. repeat
 ```
 
-## 📋 核心脚本
+常见产物：
 
-```bash
-# 快速环境检查
-bash .claude/scripts/check-prerequisites.sh
+- `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-check` 产出 `report-card.json`
+- `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
 
-# 查看任务状态
-bash .claude/scripts/check-task-status.sh --verbose
+durable truth 分两层：
 
-# 标记任务完成
-bash .claude/scripts/mark-task-complete.sh T001
+- `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
+- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；旧小写目录只作为历史兼容读取。
+- `devflow/changes/<change>/`：变更真相，保留 `change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、可选 `team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一的最终 handoff 文件。
+- worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 
-# 生成状态报告
-bash .claude/scripts/generate-status-report.sh --format markdown
+公开契约字段的典型形状：
 
-# 验证 Constitution 合规
-bash .claude/scripts/manage-constitution.sh verify
+- `triggers`、`reads`、结构化 `writes`、`effects`
+- `entry_gate`、`exit_criteria`
+- `reroutes`、`recovery_modes`、`tool_budget`
+
+如果你想先看几套完整产物链，再自己开始跑 Skill，可以先读 [../examples/START-HERE.md](../examples/START-HERE.md)。如果你在升级 skill 同时维护样例，可以跑 [../examples/scripts/check-example-bindings.sh](../examples/scripts/check-example-bindings.sh)。
+
+## 升级
+
+通过最新版打包 CLI 刷新整包：
+
+```bash
+npx cc-devflow@latest init --dir /path/to/your/project
 ```
 
-## 🧪 运行测试
+刷新平台产物：
 
 ```bash
-# 运行所有脚本测试
-bash .claude/tests/run-all-tests.sh --scripts
+npx cc-devflow adapt --cwd /path/to/your/project --all
+```
 
-# 运行 Constitution 测试
-bash .claude/tests/constitution/run_all_constitution_tests.sh
+刷新单个已安装 Skill：
 
-# 运行特定测试
-bash .claude/tests/scripts/test_check_prerequisites.sh
+```bash
+npx skills update
 ```
 
-## ⚙️ 基础配置
+## 常见问题
 
-最小配置 (`.claude/settings.json`):
+### `.claude` 已经存在
 
-```json
-{
-  "permissions": {
-    "allowGitOperations": true,
-    "allowNetworkRequests": true,
-    "allowSubprocesses": true
-  }
-}
+```bash
+npx cc-devflow init --dir /path/to/your/project --force
 ```
 
-## 🚨 常见问题
+`--force` 现在只会强制升级 cc-devflow 正式分发的 skill，不会删除现有的 `.claude/commands`、自定义 skill 或其他项目文件。
+
+### 没有生成 Codex 输出
+
+运行：
+
+```bash
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
 
-### Q: 安装后命令无法识别？
+如果你的项目没有可选的 `.claude/commands/` 输入目录，这也是正常的；编译器仍然会生成 skills registry，并为 Codex 镜像正式分发 skill 集合。
 
-**A**: 确保在项目根目录执行命令，且 `.claude/` 目录存在。
+Codex 现在会把正式分发的 skill 从 `.claude/skills/<skill>/` 镜像到 `.codex/skills/<skill>/`。这套集合包含 6 个公开 workflow skill 和维护类 skill `cc-spec-init`、`cc-simplify`，并且镜像是纯增量的：项目里已有的自定义 Codex skill 不会被删除。
 
-### Q: Git 仓库未初始化？
+### 保持 skill 和样例同步
 
-**A**: 先初始化 Git 仓库：
 ```bash
-git init
-git add .
-git commit -m "Initial commit"
+npm run verify
 ```
 
-### Q: 权限不足？
+如果你在准备可发布的整包，再跑：
 
-**A**: 给脚本添加执行权限：
 ```bash
-chmod +x .claude/scripts/*.sh
-chmod +x .claude/hooks/*.sh
+npm run verify:publish
 ```
 
-## 📚 下一步
+## 下一步
 
-- [完整命令参考](../commands/README.md)
+- [CLI 与 Skill](../commands/README.zh-CN.md)
 - [工作流详解](./workflow-guide.md)
 - [最佳实践](./best-practices.md)
-- [故障排查](./troubleshooting.md)
+- [样例入口页](../examples/START-HERE.md)
+- [简版样例列表](../examples/README.md)
+- [项目 README](../../README.zh-CN.md)

package/docs/skill-runtime-migration.md

@@ -0,0 +1,46 @@
+# Skill Runtime Migration
+
+## Result
+
+`lib/harness/` has been removed from the repository.
+
+The workflow now follows one clear ownership model:
+
+- public workflow semantics live in `SKILL.md`, `PLAYBOOK.md`, templates, and skill-local scripts
+- reusable internal helpers live in `lib/skill-runtime/`
+- the public entry surface remains `cc-devflow init`, `cc-devflow adapt`, and the five shipped skills
+
+## What Moved
+
+The old internal runtime modules were moved from `lib/harness/` to `lib/skill-runtime/`.
+
+That includes:
+
+- artifact and IO helpers
+- schema and planner helpers
+- lifecycle and query helpers
+- runtime operations used by internal tests
+
+## What Changed
+
+- `cc-check` gate execution and `report-card.json` assembly now run through skill-local scripts
+- task/context recovery guidance lives with `cc-do`
+- `cc-act` owns PR and release-side closure scripts
+- the old `autopilot-stages.js` compatibility layer was removed
+- tests and contributor docs now point at `lib/skill-runtime/` and `lib/skill-runtime/__tests__/`
+
+## Current Boundary
+
+`lib/skill-runtime/` is not the product story.
+
+It exists only as shared support code for skill-local scripts and internal verification. When adding new behavior:
+
+1. put workflow rules in the relevant public skill first
+2. prefer skill-local scripts over new shared runtime logic
+3. only add shared code when duplication would be fragile or noisy
+
+## Follow-ups
+
+- keep trimming duplicated narration from `intent.js`, `query.js`, and `autopilot` helpers
+- continue replacing compatibility-only tests with skill-script-oriented coverage where practical
+- avoid introducing any new `harness:*` language, paths, or mental model in docs or code

package/docs/v4.3.0-migration-guide.md

@@ -2,275 +2,110 @@
 
 ## Overview
 
-CC-DevFlow v4.3.0 introduces automatic TDD order validation and OpenSpec interoperability to solve requirement drift problems. This guide helps you migrate from v4.2.x to v4.3.0.
+This guide is for teams moving from the old slash-command and harness-heavy mental model to the current skills-first distribution model.
 
----
+The key change is simple:
+
+- visible workflow surface: skills
+- distribution surface: `cc-devflow init` and `cc-devflow adapt`
+- shared skill runtime: internal implementation detail
 
-## What's New in v4.3.0
+---
 
-### 1. Automatic TDD Order Validation
+## What Changed
 
-**Feature**: The harness planner now automatically validates TDD order when parsing TASKS.md.
+### 1. Workflow Entry Changed
 
-**Impact**:
-- [IMPL] tasks MUST depend on corresponding [TEST] tasks
-- [TEST] tasks CANNOT depend on [IMPL] tasks
-- Violations throw detailed error messages at `harness:plan` time
+Old mental model:
 
-**Example Error**:
+```text
+/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release
 ```
-TDD Order Validation Failed (Constitution Article VI):
 
-1. Task T002 (用户登录实现) missing corresponding TEST task.
-   Constitution Article VI requires: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+Current mental model:
 
-2. Task T004 (用户注册实现) must depend on T003 (用户注册测试).
-   TDD violation: Implementation must come AFTER test.
-```
+```text
+cc-roadmap
 
-**Migration Steps**:
-1. Review your existing TASKS.md files
-2. Ensure all [IMPL] tasks have corresponding [TEST] tasks
-3. Add `dependsOn` to [IMPL] tasks pointing to [TEST] tasks
-4. Use `[P]` marker for parallel tasks that don't follow TEST→IMPL pattern
-
-**Example Fix**:
-```markdown
-<!-- Before (INVALID) -->
-- [ ] T001 [IMPL] 用户登录实现
-- [ ] T002 [TEST] 用户登录测试
-
-<!-- After (VALID) -->
-- [ ] T001 [TEST] 用户登录测试
-- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+cc-plan -> cc-do -> cc-check -> cc-act
 ```
 
-### 2. OpenSpec Interoperability
-
-**Feature**: Bidirectional conversion between OpenSpec and CC-DevFlow formats.
+The workflow is now represented by explicit skills rather than a slash-command namespace.
 
-**New Commands**:
-- `/flow:import-openspec` - Import OpenSpec spec.md to CC-DevFlow
-- `/flow:export-openspec` - Export CC-DevFlow spec.md to OpenSpec
+### 2. Distribution Entry Changed
 
-**Use Cases**:
+Whole-pack install and platform adaptation now belong to the packaged CLI:
 
-#### Import from OpenSpec
 ```bash
-/flow:import-openspec "/path/to/openspec/specs/auth/spec.md" \
-  --req-id "REQ-123" \
-  --title "用户认证系统"
+npx cc-devflow init --dir /path/to/project
+npx cc-devflow adapt --cwd /path/to/project --platform codex
 ```
 
-**What happens**:
-1. Parses OpenSpec format (Purpose + Requirements + BDD scenarios)
-2. Generates CC-DevFlow spec.md with YAML frontmatter
-3. Auto-generates TDD tasks (TEST + IMPL pairs with correct dependencies)
-4. Adds Design section with [NEEDS CLARIFICATION] markers
-5. Generates Verification checklist
+### 3. `skills.sh` Scope Narrowed
+
+`skills.sh` remains supported, but only for single-skill distribution:
 
-#### Export to OpenSpec
 ```bash
-/flow:export-openspec "REQ-123" \
-  --output "/path/to/openspec/specs/auth/spec.md"
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
 
-**What happens**:
-1. Parses CC-DevFlow spec.md
-2. Strips YAML frontmatter and metadata
-3. Removes Design, Tasks, Verification sections
-4. Removes [NEEDS CLARIFICATION] markers
-5. Outputs pure Requirements in OpenSpec format
-
-**Round-Trip Guarantee**: Requirements are preserved through import→export→import cycles.
-
----
-
-## Breaking Changes
-
-### 1. TASKS.md Validation
-
-**Before v4.3.0**: TDD order was recommended but not enforced.
+Do not use `skills.sh` as the whole-pack lifecycle anymore.
 
-**After v4.3.0**: TDD order is enforced at `harness:plan` time.
+### 4. `.claude/commands/` Is Optional
 
-**Migration**: Update existing TASKS.md files to follow TDD order.
+The compiler still accepts legacy prompt inputs if a project has `.claude/commands/`, but the repository no longer requires that directory to exist.
 
-### 2. Task Type Detection
+Skills-first repositories are valid.
 
-**Before v4.3.0**: Task types were not tracked.
+### 5. Harness CLI Is Gone
 
-**After v4.3.0**: Tasks are classified as TEST/IMPL/OTHER based on markers.
+`harness:*` is no longer the public CLI surface.
 
-**Migration**: Ensure your TASKS.md uses `[TEST]` and `[IMPL]` markers consistently.
+Shared support code may still exist under `lib/skill-runtime/`, but it should be treated as internal runtime support for the public skills.
 
 ---
 
-## Feature Name Matching Algorithm
+## Old To New Mapping
 
-The TDD validator uses intelligent fuzzy matching to pair TEST and IMPL tasks:
-
-**Normalization Rules**:
-- Removes suffixes: "测试", "实现", "功能", "开发", "编写"
-- Trims whitespace
-- Compares core feature names
-
-**Examples**:
-```
-"用户登录功能测试" ↔ "用户登录功能实现" ✅ Match
-"用户登录测试"     ↔ "用户登录实现"     ✅ Match
-"用户登录"         ↔ "用户登录功能"     ✅ Match
-"用户登录"         ↔ "用户注册"         ❌ No match
-```
+| Old Concept | New Concept |
+|-------------|-------------|
+| `/flow:*` | visible skills |
+| `harness:*` CLI | internal skill runtime only |
+| clone `.claude` manually | `cc-devflow init` |
+| per-platform handwritten setup | `cc-devflow adapt` |
+| skills pack via old CLI lifecycle | whole pack via `cc-devflow`, single skill via `skills.sh` |
 
 ---
 
-## Parallel Tasks
+## Migration Checklist
 
-For tasks that don't follow TEST→IMPL pattern, use the `[P]` marker:
-
-```markdown
-- [ ] T001 [TEST] 用户登录测试
-- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
-- [ ] T003 [OTHER] 数据库迁移 [P]
-- [ ] T004 [OTHER] 配置文件更新 [P]
-```
-
-The `[P]` marker tells the validator to skip dependency checks for that task.
+1. Replace old workflow references in docs with the five visible skills.
+2. Replace old pack-install steps with `cc-devflow init`.
+3. Replace old platform setup steps with `cc-devflow adapt`.
+4. Keep `skills.sh` only for single-skill install or refresh.
+5. Treat `.claude/commands/` as optional compatibility input, not required structure.
+6. Stop documenting `harness:*` as if users should run it directly.
 
 ---
 
-## OpenSpec Format Reference
-
-### OpenSpec Format (Input)
-```markdown
-# Authentication Module
-
-## Purpose
-Provides secure authentication and session management.
-
-## Requirements
-
-### Requirement: User Login
-The system SHALL allow users to log in with email and password.
-
-#### Scenario: Valid credentials
-- GIVEN a registered user
-- WHEN the user submits valid email and password
-- THEN a JWT token is issued
-- AND the user is redirected to dashboard
-```
-
-### CC-DevFlow Format (Output)
-```markdown
----
-req_id: "REQ-123"
-title: "用户认证系统"
-created_at: "2026-03-13T10:00:00Z"
-version: "1.0.0"
-status: "draft"
-source: "openspec"
----
-
-# Authentication Module
-
-## Purpose
-Provides secure authentication and session management.
-
-## Requirements
-
-### Requirement: User Login
-The system SHALL allow users to log in with email and password.
-
-#### Scenario: Valid credentials
-- GIVEN a registered user
-- WHEN the user submits valid email and password
-- THEN a JWT token is issued
-- AND the user is redirected to dashboard
-
-## Design
-[NEEDS CLARIFICATION: 技术实现方案]
-
-## Tasks
-- [ ] T001 [TEST] User Login - 测试
-- [ ] T002 [IMPL] User Login - 实现 (dependsOn:T001)
-
 ## Verification
-- [ ] User Login
-  - [ ] Valid credentials
-```
-
----
-
-## Testing
 
-All v4.3.0 features are covered by automated tests:
+After migration, these commands should succeed:
 
 ```bash
-# Run all tests
-npm test
-
-# Run TDD validation tests only
-npm test -- planner.tdd.test.js
-
-# Run OpenSpec interop tests only
-npm test -- openspec.test.js
+npx cc-devflow --help
+npx cc-devflow init --dir /tmp/cc-devflow-demo
+npx cc-devflow adapt --cwd /tmp/cc-devflow-demo --platform codex
 ```
 
-**Test Coverage**:
-- TDD validation: 10 tests (all passing)
-- OpenSpec interop: 5 tests (all passing)
-- Total: 233 tests (all passing)
-
----
-
-## Troubleshooting
-
-### Error: "Task T002 missing corresponding TEST task"
-
-**Cause**: An [IMPL] task has no matching [TEST] task.
-
-**Solution**: Add a [TEST] task with similar feature name before the [IMPL] task.
-
-### Error: "Task T002 must depend on T001"
-
-**Cause**: An [IMPL] task doesn't depend on its corresponding [TEST] task.
-
-**Solution**: Add `(dependsOn:T001)` to the [IMPL] task.
-
-### Error: "Task T001 depends on IMPL tasks"
-
-**Cause**: A [TEST] task depends on an [IMPL] task (reverse TDD order).
+And the installed project should contain:
 
-**Solution**: Remove the dependency or reorder tasks.
-
-### Feature Name Mismatch
-
-**Cause**: TEST and IMPL tasks have very different feature names.
-
-**Solution**: Rename tasks to have similar core feature names, or use `[P]` marker if they're truly independent.
-
----
-
-## Rollback
-
-If you need to rollback to v4.2.0:
-
-```bash
-npm install cc-devflow@4.2.0
+```text
+.claude/skills/cc-roadmap/SKILL.md
+.claude/skills/cc-plan/SKILL.md
+.claude/skills/cc-investigate/SKILL.md
+.claude/skills/cc-do/SKILL.md
+.claude/skills/cc-check/SKILL.md
+.claude/skills/cc-act/SKILL.md
+.claude/skills/cc-simplify/SKILL.md
 ```
-
-Note: v4.2.0 does not have TDD validation or OpenSpec interop features.
-
----
-
-## Support
-
-- GitHub Issues: https://github.com/anthropics/cc-devflow/issues
-- Documentation: https://github.com/anthropics/cc-devflow/tree/main/docs
-- Constitution: `.claude/rules/project-constitution.md`
-
----
-
-**Last Updated**: 2026-03-13
-**Version**: 4.3.0