cc-devflow 4.2.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

@@ -0,0 +1,111 @@
+# CC-DevFlow v4.3.0 Migration Guide
+
+## Overview
+
+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 Changed
+
+### 1. Workflow Entry Changed
+
+Old mental model:
+
+```text
+/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release
+```
+
+Current mental model:
+
+```text
+cc-roadmap
+
+cc-plan -> cc-do -> cc-check -> cc-act
+```
+
+The workflow is now represented by explicit skills rather than a slash-command namespace.
+
+### 2. Distribution Entry Changed
+
+Whole-pack install and platform adaptation now belong to the packaged CLI:
+
+```bash
+npx cc-devflow init --dir /path/to/project
+npx cc-devflow adapt --cwd /path/to/project --platform codex
+```
+
+### 3. `skills.sh` Scope Narrowed
+
+`skills.sh` remains supported, but only for single-skill distribution:
+
+```bash
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
+```
+
+Do not use `skills.sh` as the whole-pack lifecycle anymore.
+
+### 4. `.claude/commands/` Is Optional
+
+The compiler still accepts legacy prompt inputs if a project has `.claude/commands/`, but the repository no longer requires that directory to exist.
+
+Skills-first repositories are valid.
+
+### 5. Harness CLI Is Gone
+
+`harness:*` is no longer the public CLI surface.
+
+Shared support code may still exist under `lib/skill-runtime/`, but it should be treated as internal runtime support for the public skills.
+
+---
+
+## Old To New Mapping
+
+| 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` |
+
+---
+
+## Migration Checklist
+
+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.
+
+---
+
+## Verification
+
+After migration, these commands should succeed:
+
+```bash
+npx cc-devflow --help
+npx cc-devflow init --dir /tmp/cc-devflow-demo
+npx cc-devflow adapt --cwd /tmp/cc-devflow-demo --platform codex
+```
+
+And the installed project should contain:
+
+```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
+```

package/lib/compiler/CLAUDE.md

@@ -1,125 +1,96 @@
-# Command Emitter - Compiler Module Architecture
+# Skills-First Compiler Module Architecture
 
 ## Purpose
-Multi-platform compiler that transforms `.claude/` modules (commands, skills, agents, rules, hooks) into native formats for Codex, Cursor, Qwen, and Antigravity platforms.
+Multi-platform compiler that transforms `.claude/skills/` plus optional `.claude/commands/*.md` into native outputs for Codex, Cursor, Qwen, and Antigravity platforms.
 
-## Architecture (v3.0)
+## Architecture
 
 ```
 lib/compiler/
-├── parser.js           # Parse .md files, extract frontmatter + detect placeholders
+├── parser.js           # Parse optional command .md files, extract frontmatter + detect placeholders
 ├── transformer.js      # Expand {SCRIPT:*}, {AGENT_SCRIPT}, map $ARGUMENTS
 ├── manifest.js         # Incremental compilation, drift detection
-├── schemas.js          # Zod validation schemas (CommandIR, Manifest)
+├── schemas.js          # Zod validation schemas (PromptIR, Manifest)
 ├── errors.js           # Custom error types (MissingFrontmatter, UnknownAlias, etc.)
 ├── skills-registry.js  # Generate skills registry from .claude/skills/
-├── skill-discovery.js  # Recursive SKILL.md discovery (grouped + root skills)
-├── resource-copier.js  # Resource collection/copy and .claude path rewriting
-├── platforms.js        # Platform configuration registry (v2.0)
-├── context-expander.js # context.jsonl expansion (v3.0)
 ├── index.js            # Compiler entry point, orchestrates pipeline
-├── emitters/
-│   ├── base-emitter.js       # Abstract base class (v2.0: multi-module support)
-│   ├── codex-emitter.js      # .codex/prompts/*.md, .codex/skills/*, AGENTS.md
-│   ├── cursor-emitter.js     # .cursor/commands/*.md, .cursor/rules/*.mdc, subagents/
-│   ├── qwen-emitter.js       # .qwen/commands/*.toml, .qwen/agents/*, CONTEXT.md
-│   ├── antigravity-emitter.js # .agent/workflows/*.md, .agent/skills/*, rules/
-│   └── index.js              # Emitter factory
-└── rules-emitters/           # Legacy rules emitters (deprecated)
-    └── ...
+└── emitters/
+    ├── base-emitter.js       # Abstract base class
+    ├── codex-emitter.js      # .codex/prompts/*.md (YAML frontmatter)
+    ├── cursor-emitter.js     # .cursor/commands/*.md (pure Markdown)
+    ├── qwen-emitter.js       # .qwen/commands/*.toml (TOML format)
+    ├── antigravity-emitter.js # .agent/workflows/*.md (12K limit, auto-split)
+    └── index.js              # Emitter factory
 ```
 
-## Multi-Module Compilation (v3.0)
-
-### Supported Modules
-
-| Module | Source | Codex | Cursor | Qwen | Antigravity |
-|--------|--------|-------|--------|------|-------------|
-| skills | `.claude/skills/` | `.codex/skills/` | `.cursor/rules/*.mdc` | `.qwen/commands/*.toml` | `.agent/skills/` |
-| commands | `.claude/commands/` | `.codex/prompts/` | `.cursor/commands/` | `.qwen/commands/` | `.agent/workflows/` |
-| agents | `.claude/agents/` | `AGENTS.md` | `.cursor/subagents/` | `.qwen/agents/` | `AGENTS.md` |
-| rules | `.claude/rules/` | `AGENTS.md` | `.cursor/rules/*.mdc` | `CONTEXT.md` | `.agent/rules/` |
-| hooks | `.claude/hooks/` | ❌ | `hooks.json` + `hooks/` | ❌ | ❌ |
-
-### Data Flow (v3.0)
+## Data Flow
 
 ```
-.claude/
-├── skills/*/SKILL.md
-├── commands/*.md
-├── agents/*.md
-├── rules/*.md
-└── hooks/*.ts
+.claude/skills/
         │
-        ▼
-┌─────────────────────┐
-│  compileMultiModule │ Orchestrates all modules
-│     (index.js)      │
-└────────┬────────────┘
+        ├──────────────► skills-registry.json + platform rules
+        │
+        └── optional `.claude/commands/*.md`
+                         │
+                         ▼
+┌─────────────────┐
+│     Parser      │ gray-matter → PromptIR
+│  (parser.js)    │ - Extract frontmatter
+│                 │ - Detect placeholders
+│                 │ - Compute SHA-256 hash
+└────────┬────────┘
+         │ PromptIR[]
+         ▼
+┌─────────────────┐
+│   Transformer   │ Platform-specific transforms
+│(transformer.js) │ - {SCRIPT:alias} → "bash <path>"
+│                 │ - $ARGUMENTS → {{args}} / [arguments]
+│                 │ - {AGENT_SCRIPT} + __AGENT__ substitution
+└────────┬────────┘
+         │ TransformedContent
+         ▼
+┌─────────────────┐
+│    Emitters     │ Platform format + file write
+│ (emitters/*.js) │ - Codex: MD + YAML frontmatter
+│                 │ - Cursor: pure MD
+│                 │ - Qwen: TOML
+│                 │ - Antigravity: MD + YAML (12K limit)
+└────────┬────────┘
          │
-    ┌────┴────┬────────┬────────┬────────┐
-    ▼         ▼        ▼        ▼        ▼
-┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
-│Skills │ │Commands│ │Agents │ │Rules  │ │Hooks  │
-│Emitter│ │Emitter │ │Emitter│ │Emitter│ │Emitter│
-└───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
-    │         │        │        │        │
-    ▼         ▼        ▼        ▼        ▼
-Platform-specific output directories
+         ▼
+┌─────────────────┐
+│    Manifest     │ devflow/.generated/manifest.json
+│ (manifest.js)   │ - Track source/target hashes
+│                 │ - Enable incremental compilation
+│                 │ - Detect drift
+└─────────────────┘
 ```
 
 ## CLI Usage
 
 ```bash
-# Compile commands + modules
 npm run adapt                       # Compile all platforms
 npm run adapt -- --platform codex   # Compile single platform
 npm run adapt -- --check            # Drift detection only
-
-# v3.0: Multi-module compilation
-npm run adapt -- --modules skills,commands,agents,rules
-npm run adapt -- --modules skills --platform cursor
-```
-
-## Key APIs
-
-### compile(options) - Main Flow
-Compiles commands and emits platform modules (skills, agents, rules, hooks).
-
-### compileMultiModule(options) - v3.0
-Compiles all specified modules.
-
-```javascript
-const { compileMultiModule } = require('./lib/compiler');
-
-await compileMultiModule({
-  sourceBaseDir: '.claude/',
-  outputBaseDir: '.',
-  platforms: ['codex', 'cursor', 'qwen', 'antigravity'],
-  modules: ['skills', 'commands', 'agents', 'rules'],
-  verbose: true
-});
+npm run adapt -- --skills           # Generate skills-registry.json
+npm run adapt -- --verbose          # Detailed output
 ```
 
 ## Key Schemas
 
-- **CommandIR**: Intermediate representation after parsing
+- **PromptIR**: Intermediate representation after parsing
 - **ManifestEntry**: Single compilation record (source, target, hash, platform)
 - **Manifest**: Complete compilation history
-- **PlatformConfig**: Platform-specific configuration (v2.0)
 
 ## Dependencies
 
 - `gray-matter`: Frontmatter parsing
 - `@iarna/toml`: TOML serialization (Qwen)
-- `js-yaml`: YAML serialization (Codex, Antigravity, Cursor)
+- `js-yaml`: YAML serialization (Codex, Antigravity)
 - `zod`: Schema validation
 
 ---
 
 **Created**: 2025-12-18
-**Updated**: 2026-02-07
-**REQ**: REQ-005 (RM-007), Multi-Platform Adaptation
-**Version**: 3.0.0
-
-[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+**REQ**: REQ-005 (RM-007)
+**Version**: 1.0.0

package/lib/compiler/__tests__/drift.test.js

@@ -124,7 +124,7 @@ describe('Drift Detection', () => {
 
   describe('Rules Entry Drift Detection', () => {
     test('should include rules entry files in drift check', async () => {
-      // 规则入口文件应该和普通命令文件一样被检测
+      // 规则入口文件应该和其他编译产物一样被检测
       // 这需要在 Phase 4 扩展 checkDrift 函数
 
       const { checkDrift, hashContent, addRulesEntry, createManifest } = require('../manifest');

package/lib/compiler/__tests__/errors.test.js

@@ -1,7 +1,6 @@
 /**
  * T010: Error Types Tests
  * Tests for compiler error classes
- * Expected: All tests FAIL (errors not implemented)
  */
 
 // ============================================================