cc-devflow 4.3.0 → 4.5.0

package/docs/guides/getting-started.md

@@ -4,202 +4,167 @@
 
 ---
 
-## 📋 Overview
+## Overview
 
-This guide will help you get started with cc-devflow, from installation to your first requirement development.
+CC-DevFlow has two entry paths:
 
-## 🚀 Prerequisites
+- `cc-devflow init`: install the whole `.claude` pack into your project
+- `cc-devflow adapt`: generate platform outputs such as Codex rules
 
-- [Claude Code](https://claude.ai/code) installed and configured
-- Git repository initialized
-- Node.js project (optional, for additional quality checks)
+The workflow itself is driven by six visible skills:
 
-## 📦 Installation
+```text
+cc-roadmap
 
-### Quick Install
-
-```bash
-# Clone .claude configuration to your project
-pnpm dlx tiged Dimon94/cc-devflow/.claude .claude
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 ```
 
-### Manual Install
-
-```bash
-# Download and extract
-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
-```
+The public skills are the visible harness. Each distributed `SKILL.md` now carries structured frontmatter plus a `Harness Contract`, and each `PLAYBOOK.md` carries the stage transition rules in a `Visible State Machine` section.
 
-## ✅ Verify Installation
-
-Run the verification script:
-
-```bash
-.claude/scripts/verify-setup.sh
-```
+## Prerequisites
 
-This script will check:
-- All required files and directories exist
-- Scripts have execute permissions
-- Git repository is properly configured
+- Node.js 18+
+- A Git repository
+- Claude Code or another supported agent environment
 
-## 🎯 Your First Requirement
+## Install
 
-### Step 1: Run the Mainline Flow
+### Whole Pack Install
 
 ```bash
-/flow:init "REQ-001|User Authentication|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 init --dir /path/to/your/project
 ```
 
-This will:
-1. Initialize requirement context package
-2. Generate executable task-manifest
-3. Dispatch task execution with checkpoints
-4. Run quick/strict quality gates
-5. Generate release note and cleanup runtime logs
+The whole-pack install includes the six visible workflow skills plus `cc-spec-init` and `cc-simplify` as maintenance helpers.
 
-### Step 2: Check Progress
+### Single Skill Install
 
 ```bash
-/flow:status REQ-001
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
 
-### Step 3: Resume If Interrupted
+## Adapt For A Platform
 
 ```bash
-/flow:dev "REQ-001" --resume
+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
 ```
 
-## 🛠️ Core Scripts
+## Verify Installation
 
-### Environment Check
-```bash
-bash .claude/scripts/check-prerequisites.sh
-```
+Check that the expected skill folders exist:
 
-### View Task Status
 ```bash
-bash .claude/scripts/check-task-status.sh --verbose
+find .claude/skills -mindepth 1 -maxdepth 1 -type d | sort
+find .claude/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 ```
 
-### Mark Task Complete
-```bash
-bash .claude/scripts/mark-task-complete.sh T001
-```
+If you adapted for Codex, verify the mirrored skill folders:
 
-### Generate Status Report
 ```bash
-bash .claude/scripts/generate-status-report.sh --format markdown
+find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 ```
 
-## 🧪 Running Tests
+## First Workflow
 
-### Script Tests
-```bash
-# Run all tests
-bash .claude/tests/run-all-tests.sh --scripts
+Use the skills in this order:
 
-# Run specific test
-bash .claude/tests/scripts/test_check_prerequisites.sh
+```text
+1. cc-roadmap
+2. choose cc-plan or cc-investigate
+3. cc-do
+4. cc-check
+5. cc-act
+6. repeat
 ```
 
-### Constitution Tests
-```bash
-bash .claude/tests/constitution/run_all_constitution_tests.sh
-```
+Typical outputs:
 
-## 📊 Interactive Demo
+- `cc-roadmap` writes `devflow/ROADMAP.md` and `devflow/BACKLOG.md`; helper sync can also maintain `devflow/roadmap-tracking.json` as the shared roadmap/backlog truth source
+- `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
+- `cc-plan` writes `planning/design.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
+- `cc-investigate` writes `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
+- `cc-check` writes `report-card.json`
+- `cc-act` writes exactly one final handoff file: `handoff/pr-brief.md`, `handoff/resume-index.md`, or `handoff/release-note.md`
 
-Run the interactive demo to see the complete workflow:
+Capability truth lives in `devflow/specs/`.
+Change truth lives in `devflow/changes/<change>/`.
 
-```bash
-python3 .claude/scripts/demo.py
-```
+- Keep `INDEX.md` plus capability markdown under `devflow/specs/`.
+- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes; old lowercase directories are compatibility reads only.
+- Keep `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`.
+- Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 
-## 🔧 Configuration
+Typical public contract fields:
 
-### Minimum Configuration
+- `triggers`, `reads`, structured `writes`, `effects`
+- `entry_gate`, `exit_criteria`
+- `reroutes`, `recovery_modes`, `tool_budget`
 
-Edit `.claude/settings.json`:
+If you want to see complete artifact chains before using the skills, start with [../examples/START-HERE.md](../examples/START-HERE.md). If you are updating examples alongside skills, run [../examples/scripts/check-example-bindings.sh](../examples/scripts/check-example-bindings.sh).
 
-```json
-{
-  "permissions": {
-    "allowGitOperations": true,
-    "allowNetworkRequests": true,
-    "allowSubprocesses": true
-  }
-}
-```
+## Upgrade
 
-### Environment Variables
+Refresh the whole pack with the latest packaged CLI:
 
 ```bash
-# Quality gates
-export MIN_TEST_COVERAGE=80
-export STRICT_TYPE_CHECKING=true
-
-# Flow behavior
-export FLOW_AUTO_APPROVE=false
+npx cc-devflow@latest init --dir /path/to/your/project
 ```
 
-## 📚 Next Steps
-
-- [Command Reference](../commands/README.md) - Learn all available commands
-- [Workflow Guide](./workflow-guide.md) - Understand the development workflow
-- [Best Practices](./best-practices.md) - Follow recommended practices
+Refresh generated platform outputs:
 
-## 🚨 Troubleshooting
+```bash
+npx cc-devflow adapt --cwd /path/to/your/project --all
+```
 
-### Issue: Scripts not executable
+Refresh one installed skill:
 
 ```bash
-chmod +x .claude/scripts/*.sh
-chmod +x .claude/hooks/*.sh
+npx skills update
 ```
 
-### Issue: Git not initialized
+## Troubleshooting
+
+### `.claude` already exists
 
 ```bash
-git init
-git add .
-git commit -m "Initial commit"
+npx cc-devflow init --dir /path/to/your/project --force
 ```
 
-### Issue: Tests failing
+`--force` force-upgrades only the distributed cc-devflow skills. It does not delete existing `.claude/commands`, custom skills, or other project-owned files.
 
-```bash
-# Check prerequisites
-bash .claude/scripts/check-prerequisites.sh
+### No Codex output generated
 
-# Run tests with verbose output
-VERBOSE=true bash .claude/tests/run-all-tests.sh --scripts
-```
+Run:
 
-## 💡 Tips
+```bash
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
 
-1. **Always check progress** with `/flow:status` before continuing work
-2. **Use `/flow:verify`** to check quality gates and consistency
-3. **Enable debug mode** if you encounter issues: `export FLOW_DEBUG=1`
-4. **Read the Constitution** to understand quality standards
+If your project has no optional `.claude/commands/` input, this is expected: the compiler will still generate the skills registry and mirror the distributed skill set for Codex.
 
-## 🆘 Getting Help
+Codex mirrors the distributed skills from `.claude/skills/<skill>/` into `.codex/skills/<skill>/`. That set includes the six public workflow skills plus `cc-spec-init` and `cc-simplify`, and the mirror is additive-only: existing project-owned Codex skills are preserved instead of being deleted.
 
-- [GitHub Issues](https://github.com/Dimon94/cc-devflow/issues)
-- [Documentation](../../docs/)
-- [Contributing Guide](../../CONTRIBUTING.md)
+### Keep skills and examples in sync
 
----
+```bash
+npm run verify
+```
 
-**Ready to start? Run your first command:**
+If you are preparing a publishable pack, run:
 
 ```bash
-/flow:init "REQ-001|My First Feature"
+npm run verify:publish
 ```
+
+## Next Steps
+
+- [CLI And Skills](../commands/README.md)
+- [Workflow Guide](./workflow-guide.md)
+- [Best Practices](./best-practices.md)
+- [Example Entry Page](../examples/START-HERE.md)
+- [Compact Example List](../examples/README.md)
+- [Project README](../../README.md)

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