cm-workflow

Codex-native、spec-driven 的双运行时工作流分发包：需求文档 → 开发规格 → 实现 → 独立审查 → QA → 文档同步，并支持存量功能只读测试与可选外部专家研究。Codex Skills 与 runtime/ 是权威流程， Claude Code 跨平台直接使用 /cm-* Skills；compat/claude-commands/ 保存 macOS/Linux 的历史 /cm:* 别名包装。

技术栈

• 语言: Markdown（prompt 资产主体）+ Bash（安装与可视化脚本）+ PowerShell（Windows 安装器与自检入口）+ Python（标准库校验/夹具）+ JavaScript（Node.js 18+；Playwright 可选）
• 框架: Pi/BYZ 原生 package + Codex plugin + Agent Skills；Claude Code commands/agents 兼容层
• 包管理: 根 package.json 保存 Pi/BYZ manifest 和 npm 安装命令入口，无 npm 依赖或 lifecycle scripts；Codex npm 入口复用 install-codex.sh，Claude Code 用 install.sh / install.ps1
• 版本控制: remote
• 交付形态: Pi/BYZ package + Codex/Claude Code 本地开发者工具（无构建产物）
• 业务地图: 跳过（开发者工具分发仓库，不是 src/ 风格业务应用）；本地扫描产物不提交，公开架构见 docs/architecture.md

常用命令

• 必验与完成边界：明确必验标记的新运行冻结批准规格的 acceptanceContract；普通旧规格不强制新验证入口，原宿主/完成门禁共用校验；completion 只读区分任务、功能、项目与收尾，产品验收和部署缺证据为 UNKNOWN。旧运行不迁移，见 docs/cm-acceptance-completion.md。
• 批准前验收预览：node scripts/cm-acceptance-preview.mjs --specs {SPECS_DIR} [--feature {FEATURE_DIR} --task {TASK_ID}] [--json]；PRD 摘要也展示同源预览。阻断细项沿原 reason 保存，由 guidance.blockage 解释；只读预览/指引不授予审批或恢复权限。
• 已完成运行受控集成：node scripts/cm-ai-integration-preview.mjs --run-definition {原run.json} --plan {plan.json} 只读预检；独立审查后由原 owner 用固定目标显式接纳，保留历史和次数。详见 docs/reviewed-integration.md。
• 方案推敲：$cm-challenge / /cm-challenge，显式三轮或必要追问；复用 runtime/steelman-review.md，只输出讨论建议，不启动宿主、不替代正式审查。
• 兼容手工任务：N3 编辑前运行 node scripts/cm-task-gate.mjs capture-baseline --project-root {CODE_PROJECT} --reviews-dir {SPECS_DIR}/.reviews --feature {FEATURE_SLUG} --task {T-xxx}；仅命令行 N4/N5 与完成入口开启清单核对，库调用默认行为不变，JS 使用自己的审查包基线。仅单代码根，历史缺基线用现有 --allow-legacy-unbound 披露清单未核验；详见 runtime/task-gates.md。
• CM control v2：新 cm-ai run 用 --control-config POLICY.json 明确运行能力，禁止 --allow-*；旧 run 沿 legacy，不迁移记录。配置、operator/model 与 V3 grant 不证明真人身份，真实对话及外部动作授权保持；详见 控制策略与恢复合同。
• v2 受控补正仅适用于无 JS ownership 的兼容 taskgate 任务；cm-ai 单/批 r2 blocked 仍无 runner-owned correction 完成入口，不删 journal 或绕过 owner 门禁。
• 安全扫描：$cm-security / /cm-security，分支差异加已跟踪未提交修改；--all 扫全部已跟踪文件。工具缺失保留缺口，不自动修复或安装；定点验证 node --test scripts/cm-security.test.mjs。
• 分支影响分析：直接 $cm-test / /cm-test；默认比较当前提交与主分支，输出业务影响和回归重点，再检查单测覆盖率；“补齐单测”连续补测、重跑、审查。显式目标保留原模式。
• cm-fix Claude 隔离验证：新运行可选 reviewVerification，node scripts/cm-fix-review-preflight.mjs --config {运行定义.json} --model {Claude模型} 生成诊断；限定 macOS 自包含命令，不迁移旧运行。详见 skills/cm-fix/references/isolated-review.md。
• cm-fix 原运行更正：命令配置发现使用 scripts/cm-fix-command-correction.mjs 只读预览，随后独立授权 prepare_command_correction；已编写测试的限定回调类型更正使用 scripts/cm-fix-test-type-correction.mjs 和 prepare_test_type_correction。两者只追加原 owner 历史，原配置、审查次数与失败证据不改；详见 skills/cm-fix/references/command-correction.md、test-type-correction.md。
• JS 修复入口: node scripts/cm-fix-host.mjs --help；同仓specs可显式配置protectSpecs:true，原权限/审查不变，宿主只回文本提案，由固定沙箱写入；QA子配置复用，详见docs/js-workflow-control.md
• cm-ai 进度：当前任务真实阶段更新 .cm-status.json；单／批驱动检查边界及阻塞说明写 stderr。可选 guidance 只解释原恢复前提，不授予重试权限；保护模式不转发原始命令输出，并行状态卡旧完成不能抢占，详见 docs/js-workflow-control.md。
• CM 收尾：有文档能力的新 run 默认在原 documentation_inspect 做只读资料核对；原 workflow-config 可用 knowledgeCloseout:false 关闭，旧 run 沿快照，报告不代替 Review/QA。见 skills/cm-ai/references/knowledge-closeout.md。
• 双运行时容灾: 断点交接 node scripts/cm-failover.mjs status|handoff|probe --specs {SPECS_DIR}（只读，不标记完成）；启动前选路 cm-ai-host.mjs serve ... --failover（显式 opt-in，只定起跑运行时，切换必播报）。运行时声明 runtimes.available 与四个预设见 templates/cm-workflow.yml、runtime/workflow-config.md（声明不等于派发）。主从与边界见 docs/runtime-failover.md；定点测试 node --test scripts/cm-failover.test.mjs scripts/cm-runtime-failover.test.mjs。
• 运行时声明：$cm-runtime 先查看并默认保留，主动修改才进入预设向导；高级模型入口只读说明。show|preview <preset>|set <preset>|set --user <preset>|unset --user；向导确认 [y/N]，set --expect-preview <sha256> 拒绝过期预览。项目 > ~/.cm-workflow/runtimes.yml > 未声明；只影响新 run。安装器可跳过配置且默认保留，--yes / -Yes 或非 TTY 跳过。
• 提醒渠道：$cm-notify / /cm:notify 查看、bark|pushplus 切换（目标密钥可解析才生效，否则不改文件）、test、off；托管发送器复制到 <CM_WORKFLOW_HOME>/notify/cm-notify-send.mjs，自定义命令需 --replace-custom。密钥只由用户填文件，不读出、不显示。定点测试 node --test scripts/cm-notify-command.test.mjs scripts/cm-notify.test.mjs。
• 外部模型：node scripts/cm-model-setup.mjs configure --provider codex|claude，一组模型／可选强度；--external-models 显式启用，宿主不切模型，恢复只读原快照，未知调用不重派。范围及回滚见 docs/external-models.md。
• 安装依赖: 无 npm 安装步骤（package.json 无依赖；可视化工具按需使用外部 Playwright）
• 开发运行: 不适用（直接维护 Markdown 与脚本）
• 构建: 不适用（无构建产物）
• 测试: bash scripts/test-shell-compat.sh && node --test scripts/cm-ai-admission.test.mjs scripts/cm-workflow-config.test.mjs scripts/cm-log-event.test.mjs scripts/cm-task-gate.test.mjs scripts/validate-test-cases.test.mjs && python3 scripts/test-task-gate.py
• JS 分组测试：node scripts/cm-test-suite.mjs check 核对唯一清单；run ordinary、run native --concurrency 1、run history --concurrency 4 分别跑普通、原生沙箱和历史组，自动隔离 CM 配置与日志目录；安装兼容夹具只写各自临时目录，不改变用户安装。要求与 CI 分片命令见 CONTRIBUTING.md。
• Lint/安全: python3 scripts/validate-public-repo.py && python3 scripts/scan-public-safety.py
• Bash 语法: find . -type f -name '*.sh' -print0 | xargs -0 -n1 /bin/bash -n
• Pi/BYZ package: pi install git:github.com/kingxiaozhe/cm-workflow
• Codex 安装: ./install-codex.sh（装完新开会话跑 $cm-check）
• Claude 安装: ./install.sh（核心运行时整体更新、失败回滚，但安装中运行的会话可能读到新旧混合文件，见 docs/installation.md 限制表；可选更新器 best-effort，装完跑 /cm-check）；它与 install-codex.sh 按安装清单发现手改即停下（退出码 3），--yes 不绕过，确认丢弃加 --overwrite-local-edits；同一目标并发安装时后来者以退出码 4 停下，锁残留需人工确认后清理
• Windows 安装: powershell -ExecutionPolicy Bypass -File install.ps1（同样整体更新、失败回滚）
• 一致性自检: ./scripts/cm-check-runtime.sh；完整当前会话机械/语义接线：node scripts/cm-check-host.mjs --help
• 完整 cm-check 默认先调用 scripts/cm-check-update.mjs 查询并升级已管理安装，再检查返回目录；低层检查仍只读。定点测试：node --test scripts/cm-check-update.test.mjs scripts/cm-check-host.test.mjs。
• 全局日志夹具: ./scripts/cm-check-runtime.sh --log-fixtures
• 交付声明：node scripts/cm-delivery-evidence.mjs --help；preview/status/history 只读，record 由负责人在交互终端确认，非自动产品验收或部署。
• 本地运行分析：node scripts/cm-run-analysis.mjs --specs {SPECS_DIR} [--run-id {RUN_ID}] [--json]；缺失用量/时间不估算。
• API 用量报告: python3 scripts/cm-usage-report.py --last 10
• OpenAI 兼容调用夹具: python3 scripts/test-cm-openai-compatible-call.py
• 审批 manifest: python3 scripts/cm-spec-manifest.py {specs}
• PRD 单轮恢复夹具: python3 scripts/test-cm-prd-review-gate.py
• PRD JS 变更/会话恢复: node scripts/cm-prd-host.mjs --help；定点夹具 node --test scripts/cm-prd-completion.test.mjs
• 公开包检查: python3 scripts/validate-public-repo.py
• 安全扫描: python3 scripts/scan-public-safety.py
• JS runtime 兼容夹具: node --test experiments/js-orchestration/*.test.mjs（完整宿主验证要求支持原生沙箱的平台与 Node.js 24.14+；历史夹具通过不等于真实模型验收）
• JS 单任务入口: node scripts/cm-ai-host.mjs --help；默认当前会话，Codex 同仓 specs 可显式选 --protected-config；v2 用策略启用开发与常规审查，legacy 保留原按轮选项；原 workflow 配置接受保护 QA 与审前文档，安装与真实模型验收另验
• JS 多任务入口: node scripts/cm-ai-batch-host.mjs --help；复用原 batch/单任务宿主，Codex/Claude 可选 --protected-conversation-config 同仓文本提案/沙箱；v2 常规 Review 自动至两轮，legacy 保留按 feature/task/轮次授权
• 当前会话执行证据：四驾驶员可显式配置 liveEvidence，合同与不可用恢复见 docs/live-evidence-drivers.md；静态文件不能代替实际执行。
• 第二轮 blocked 后的人工补正：明确人审范围后使用一次性的 cm-task-gate.mjs prepare-human-correction / publish-human-correction-review；保留旧证据，补正独立 Review，详见 docs/human-correction.md。
• cm-fix 原根因拒绝恢复：standalone rediagnose 需 --allow-rediagnosis；原 run 一次新诊断/fresh r2，历史不覆盖，第二次拒绝停机；详见 skills/cm-fix/references/js-host.md。
• JS 重构: node scripts/cm-refactor-host.mjs --help；协议见 skills/cm-refactor/references/js-host.md，轻量/批量、判官准备、恢复、Learning/规则/备忘共用原门禁；真实双端使用与Git交付另验
• Claude JS 接线: 单/批任务 --runtime claude 已接原开发/Review/QA链，已安装CLI通过本机回环配置诊断；真实模型Review及Skill实装仍缺，不等于双端验收
• 只读任务提案: scripts/cm-task-gate.mjs 的 prepare-mark-done / verify-mark-done-plan；参数与私有输出契约见 runtime/task-gates.md，不是完成授权
• 插件验证: python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
• 发版面冒烟: ./scripts/cm-release-smoke.sh（本地 BYZ + Codex；Codex 装入一次性 HOME）
• 查看版本: cat VERSION
• 可视化预览: templates/pixel/cm-pixel.sh --demo、templates/dashboard/serve.sh {specs路径}

不使用第三方单元测试框架；Shell、Python 与 Node.js 行为由可执行夹具覆盖，prompt 流程另需相关路径 dogfood。安装命令会写用户级目录，只在明确安装或隔离冒烟时执行。

目录结构

compat/claude-commands/ # macOS/Linux 历史 /cm:* 三行别名包装
skills/                # Codex 权威流程与工种能力
├── cm-{challenge,idea,init,prd,ai,test,fix,refactor,check,runtime}/
├── cm-*-engineer/     # frontend/ui/miniprogram/backend/database/contract/qa/devops
├── cm-product-manager/、cm-finance-expert/、cm-doc-syncer/
└── codebase-context/、external-expert/、darwin-skill/ # 独立工具；点子访谈引擎位于 cm-idea/references/
agents/                # 并行子 agent → ~/.claude/agents/ —— agent 管纪律
runtime/               # 双运行时共享合同；runtime/js/cm-ai 的 host/runner 是新 cm-ai 任务的默认执行与持久状态层
templates/             # workflow config / rules 骨架 / hooks / statusline / dashboard / pixel
docs/                  # 使用手册、安装架构、交付材料与示例 specs
assets/                # README 与使用手册的本地视觉资产
scripts/               # 双运行时机械检查、公开包校验与辅助脚本
experiments/js-orchestration/ # JS 兼容转发、历史实验与本地夹具；不保存第二份 cm-ai 实现
.codex-plugin/         # Codex 插件清单
VERSION                # 语义版本源，与 plugin manifest 基础版本一致
CHANGELOG.md           # 用户可感知的版本变化；未发布改动单独记录

核心架构原则

• agent 管纪律，skill 管技术：并行干活的做 agent（前端/UI/小程序/后端/数据库/合约），串行把关的做 skill（产品/金融/QA/运维/doc-syncer）。新增角色前先归到这两类之一。
• 引用即契约：本仓库历史缺陷全属「引用断链」——改名残留、匹配表缺项、死角色、失效命令引用。任何跨文件引用都由 /cm-check 机器化校验。
• 一份流程真相：Codex Skill 是权威实现，Claude 旧别名只转发，不复制业务规则。
• 业务地图回写：需求与修复共用 skills/codebase-context/references/writeback.md，只增量更新、审前定稿；缺失建局部地图，项目指定文档优先，固定写入范围不自动扩大。
• 任务级 Learning loop：开发/排错先重读根 AGENTS.md；每 task 收尾按 runtime/project-learning.md 提炼写回、随任务审查并回读，无新增明确记录。JS 源码接通不等于真实下一 task 复用已验收。
• 源码分发不等于激活：正式 JS 源码、本地测试或独立审查不等于 host 已接入、真实 provider 执行、任务完成、跨平台验证或发布；真实项目写入仍需明确授权。
• 容灾只在边界切换：角色主从（developer 主 codex / reviewer 主 claude）只决定起跑运行时；任务中途失效靠落盘断点在另一端续跑，状态机不做 in-flight 切换。探测到 CLI 可解析不等于配额可用。
• 模板层是团队定制入口：公司规范沉淀进 templates/rules/，所有项目 /cm-init 出的 rules 自动带公司基因。
• 流程间隔离（维护者确立,2026-07-18）：修改任一 cm-* 流程不得顺带修改其他流程；流程 A 需要流程 B 的内容时读取 B 的落盘物，不复制或改写 B 的规则。发版版本只同步 VERSION 与 plugin manifest。

规则

@rules/coding-style.md @rules/testing.md @rules/security.md @rules/git-workflow.md