cowork-flow 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -4,6 +4,47 @@
 
 ### Added
 
+## [1.9.1] - 2026-10-14
+
+### Fixed
+
+- **CI 与发布校验在 Node 20 全红（1.9.0 发布阻断）**：`compliance-e2e` 用例嵌套的 `node --test` 断言写死了 Node 22+ 默认 reporter 的 `✔`/`﹣` 标记，CI 的 Node 20 默认输出 TAP（`ok N -`），断言恒失败——v1.9.0 的 test / windows-core / verify 各环节全红、publish 跳过、npm 未上架。嵌套 spawn 现在显式钉 `--test-reporter=spec`，Node 20 / 24 双绿。
+- **Windows 上 Kimi Code hook 重复安装会双注册**：TOML basic string 把安装路径的反斜杠转义成 `\\`，归属比较此前只做单斜杠替换，`\\` 折叠成 `//` 后与单斜杠形式不相等，自身的 `[[hooks]]` 行恒不被识别——第二次安装追加第二行钩子（双次注入）。分隔符归一化改为折叠连续 `[\\/]+`，并新增"无标记旧行被接管而非复制"的回归测试。
+
+## [1.9.0] - 2026-10-14
+
+### Added
+
+- **多执行者协作事实（1.9.0 主线）**：把 executor / evidence / adopt 语义补成团队协调原语，让 `.cowork-flow/tasks/` 在多 agent 场景下当共享看板。① **看板归属可见**：`task next --list --json` 与 MCP `task_list`（同一实现）每条记录新增 `executor` / `ownerSessionActive`（提示位：是否有会话绑定该任务，不裁决孤儿）/ `evidenceCoverage` / `blocked` / `blockedBy`——第二个执行者不跑 `run state` 就能看出谁在占用、有没有卡住、证据到哪了。② **依赖边**：`task next --run --title ... --depends-on <task>`（可重复，完整目录名）在创建时写入 `task.json` 的 `dependsOn`，声明期 fail-closed（目标不存在 / 自依赖 / 环分别报 `TASK-CREATE-DEPENDENCY-001/002/003`，失败不落盘；归档任务按已完成依赖解析）；start 门禁 `LIFECYCLE-DEPENDENCY-001`——依赖未全部 completed 时阻断进入 in_progress，导航 payload 与 `--run` 报同一 blocker 文本，已启动任务不受回溯影响，adopt/review/complete 不受约束。③ **交接凭证**：adopt 成功后打印 Handover 段（原执行者 → 新执行者、原基线 → 新基线、剩余未勾选 AC、证据覆盖 n/m）。契约见 `.cowork-flow/spec/contracts/task-board.md`。
+- **严格任务门禁与验收闭环（10 月门禁轮）**：新建任务默认 `strict`——创建期必须声明 dev_type（`backend|frontend|fullstack|test|spec`，报 `TASK-CREATE-DEVTYPE-001`）；完成期重新校验 decision-anchor 与证据：仍有未勾选 AC 报 `LIFECYCLE-AC-001`、已声明 AC 缺 `evidence.jsonl` 记录报 `002`（唯一可被 `--allow-missing-evidence` 豁免的码）、strict 任务读不到 AC 行报 `003`、证据模块不可导入报 `004`。轻量路径 `meta.taskType=tiny`：strict+tiny 免复核凭证与 AC 证据，但只能创建期声明、`task next --list` 与 doctor 可见、不得用于触碰 runtime/门禁/spec 的任务。
+- **独立复核凭证与变更指纹**：`subagent check-review` 把 cowork-check 的结论写入 `review.jsonl`，完成门禁消费——无凭证报 `LIFECYCLE-REVIEW-001`、最新一条非 pass 报 `002`、指纹过期报 `003`、来源回查失败报 `004`；接收侧守卫 `REVIEW-RECEIPT-001..007`（上下文形态 / agent 类型 / 任务绑定 / 真实 runtime 绑定回查），`by` 字段不算独立性证据。16 hex 变更指纹的分量 = 变更内容摘要 + anchor 目标与 AC 正文 + plan 摘要 + dev_type + 被引用规范正文 + implement.jsonl 摘要——改代码 / 规范 / AC 即凭证失效，需重跑复核。
+- **spec-check 可遵循闭环（spec-check 后续）**：每次运行携带 `summary.classification` 分类事实（`parse-error` / `executor-failure` / `zero-declaration` / `violation` / `unchecked` / `pass` / `empty`，`--json` 可查）；整只执行器损坏单独阻断（executor-failure，`--allow-unchecked` 不豁免）；豁免明细（flag / by）在完成与归档同源打印；零声明处给出下游 AI 的指路，契约 quick-start 示例可从交付文件整段抽用。
+
+### Changed
+
+- **技能面收敛（16→14）**：删除 `decision-audit`（与 `adversarial-review` 是同一段 CLAIM/DOUBT 复核循环的两份文本）与 `game-design`（连同 `spec/game/` 5 个文件）；`cowork-flow-maintenance` 路由收紧为 `template/**` + `presets/**`；固定代理提示统一指向 `adversarial-review`。
+- **复核报告三元组**：`subagent check-review --finding` 的每条 finding 必须携带 clause / command / negativeProof（无命令可判的显式给 null），把取证方式写进复核契约。
+- **发布门禁覆盖自实例与实例路径**：`release:check` 增加 self-instance-drift（自实例镜像须与 `template/` 一致，`source:refresh` 消除漂移）与 doctor error 级阻断；PR CI 与发布共用同一门禁。
+- **文档事实源收敛与契约英文化**：README / AGENTS / docs / spec 四层去重消死、统一称谓、控制面唯一化；契约正文英文化并补英文版 README；新增 `spec/contracts/error-codes.md` 汇总全部 `LIFECYCLE-*` 码（code 是稳定契约、消息文本不承诺稳定）。
+- **子代理派发默认化（技能层）**：`cowork-flow` 技能新增 Delegation 段——计划并行切片逐片派发 `cowork-implement`（切片简报走运行时上下文 assignment，协议引用 `subagent-dispatch.md`）、完成前的 `cowork-check` 派发显式写入流程（不再靠撞门禁）、调研型任务可 `cowork-research` 扇出（2–3 个），协议传输细节仍由 `subagent init` 输出与 `subagent-dispatch.md` 承载、路由技能不复刻；`task-planning` 的 Parallel Work 补两条：并行项注明 dispatch（`main` | `cowork-implement`）、同一工作树内不可并行两个任务（范围门禁读取工作树全量变更，跨任务并行走独立 worktree/clone + 看板依赖边）；`agent-dispatch` 绑定步骤改为从运行时上下文读取 assignment（`goal` / `expected_output`）；`orchestration-patterns` 模式 1 使用场景改为可操作触发、模式 2 验证清单补收束与单树约束。零 runtime 代码变更。
+- **安装器共享助手收敛（内部）**：9 份 `install-*.js` 的机械重复收进 `src/lib/`，可观测行为（stdout 文案、守卫顺序、退出码）逐字冻结，既有测试零修改通过。① `writeJsonAtomic` 单源化到 `install-support.js`（写前 mkdir 父目录 + 临时文件换名），zcode/qoder/dsh-preset 的本地副本删除。② 新增 `payload-install.js`（含 `pruneEmptyDir`）：claude-code/kimi-code/opencode 三份同构安装器走共享"头部 → 归属守卫 → dry-run → 物化 → 报告"骨架，三家逐字重复的句子只保留一份（守卫拒绝、强制覆盖提示、未安装提示、完成行），各自收敛为 90 行薄壳（原 129/142/169 行；kimi-code 安装器随后因插件直装扩展至 152 行）；marketplace/registry/bundle 等宿主语义留在原模块。③ kimi-hook 与 dsh-hook 的托管块手术（定位/替换/移除）共享 `upsertManagedBlock` / `removeManagedBlock`，各自的块渲染与行尾锚定保留，重复安装幂等与卸载字节复原语义不变。④ 复核收尾删除死配置点与孤儿 import（`13f3b7c`）。
+- **OpenCode 插件收敛为 zcode 同形态传输 shim**：插件内 1125 行 JS 手写渲染/绑定（registry 加载、指纹计算、stage-contract、decision-anchor、运行时绑定 JSON-pair 写入）全部删除，`experimental.chat.system.transform` 改为 spawn 项目内 `inject.py --host opencode` 并原样注入其 stdout；`plugin-core.js` 只剩宿主能力胶水（传输、`shell.env` 上下文键导出、edit 期 spec-check 代理、载荷技能目录注册）。配套变化：① `inject.py --host opencode` 成为合法选项，新增 `opencode_policy`（digest 措辞保留 "every plugin transform"；无 SessionStart 事件，digest 形状由会话状态文件探测推导；stdout 即注入故 `emit_text`）。② 行为变化：主会话现在同样收到 `<workflow-state>` 注入（此前仅 delegated 子代理会话有），digest 全量/指纹判定由「进程内 per-session 集合」改为跨进程可靠的「会话激活文件探测」，workflow-state 头按统一规则携带 `session` 属性。③ `DEFAULT_CONTRACT_REGISTRY` 兜底单源化：JS 副本随渲染删除，只剩 Python 一份，`tests/test_contract_registry.py` 把它与 `contract-registry.json` 逐条锁定防漂移。④ 机器级安装载荷新增 `cowork-flow/runtime/scripts` 缓存副本（安装时从 template 刷新，zcode 同形态），项目外渲染 not-initialized 上下文；项目内始终以项目自身运行时副本为准。契约同步见 `.cowork-flow/spec/contracts/context-injection.md`。升级动作：`cwf host add opencode --force` 刷新机器级载荷后重启 OpenCode。
+- **Kimi Code 插件直装**：`cwf host add kimi-code` 一步完成插件安装，不再需要 TUI 手工执行 `/plugins install`。命令物化两份载荷（`plugins/sources/` 稳定重装源 + `plugins/managed/` 宿主加载副本）并直接写入宿主注册表 `$KIMI_CODE_HOME/plugins/installed.json`——落盘格式与 Kimi Code 自身安装逻辑逐字段一致（读自宿主源码 `agent-core-v2` 的 plugin store/manifest/manager）：记录含 `id/root/source:"local-path"/enabled/installedAt/updatedAt/originalSource`，按 id 合并、保留其他插件记录与未知顶层字段、首装时间与启用状态在重装时保留、注册表不可解析时 fail-closed 且原文件不动；`--uninstall` 反向移除记录并删除两份目录（外来目录仍受守卫保护，`--force` 才覆盖）。doctor 的半装/陈旧指引与 `docs/hosts.md` 同步为 `cwf host add kimi-code [--force]`。升级动作：`cwf host add kimi-code --force` 后重启 Kimi Code。后续文档收口：`host` 组件自述与 `docs/hosts.md` 不再把 hook 描述成「插件缺位时的 fallback」——hook 即注入唯一路径（`2fa9606`、`3ba305a`）。
+
+### Fixed
+
+- **测试自身两处不可信缺陷（P0）**：hook 用例被 shell 会话变量干扰造成的环境假红（改为整体清空宿主环境键的隔离夹具）；删除一条在 gitignore 目录写文件的空转断言（无论规则是否生效都不可能失败），替换为可被定点破坏变红的用例。
+- **`review-check` 非单调位置崩溃**：多行非 ASCII 字符串的字面量剥离保留了错误的字节偏移，导致工具整条崩溃（`73627d7`）。
+
+## [1.8.1] - 2026-10-08
+
+### Added
+
+- **任务收养 `task next --run --adopt`（1.9.0 多执行者协作前置）**：为孤儿/滞留任务提供受支持的接管路径，替代手改 task.json meta。收养是独立动作（不与 review/complete/archive 链式同发）：把 `in_progress`/`review` 状态、由另一执行者占有的任务重绑到收养者（`executor`），把评审基线**重置**到收养时 HEAD（原值记入 `meta.previousBaseline`），保留状态并写审计字段 `meta.previousExecutor` / `meta.previousBaseline` / `meta.adoptedAt`，结果 code `LIFECYCLE-EXECUTOR-ADOPTED`。误用 fail-closed（`LIFECYCLE-ADOPT-001`）：planning/completed、无 executor、自我收养、process-fallback 身份、delegated 上下文、携带 create/plan 或批启动旗标全部拒绝且不改状态。start 路径"基线永不覆盖"不变量原样保留（既有测试零改动），收养是唯一经审计的显式重置路径；成功后 CLI 把会话绑定到该任务。契约见 `.cowork-flow/spec/contracts/task-adopt.md`。
+
+### Fixed
+
+- **`--allow-missing-evidence` 恢复独立解析**（1.8.0 遗留缺陷）：该旗标此前被误注册为 `--allow-unchecked` 的解析别名（同一 `add_argument`、dest 相同），造成两个后果——AC 证据豁免（`LIFECYCLE-AC-002` 的可豁免路径）从 CLI 不可达（`cmd_complete` 读取的属性 argparse 从不创建，恒为 False）；且传入 `--allow-missing-evidence` 会静默获得 spec-check 未检查豁免（语义错误、方向危险：本意只豁免 AC 证据，却放开了缺失/超时的 spec-check 命令）。现在两个旗标各自独立解析，parser 级与命令贯通级回归测试锁定（既有测试手工构造 Namespace 绕过 parser，正是此缺陷漏网原因）。
 
 ## [1.8.0] - 2026-10-08
 
@@ -296,7 +337,10 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.8.0...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.9.1...HEAD
+[1.9.1]: https://github.com/fishlikewater/cowork-flow/compare/v1.9.0...v1.9.1
+[1.9.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.8.1...v1.9.0
+[1.8.1]: https://github.com/fishlikewater/cowork-flow/compare/v1.8.0...v1.8.1
 [1.8.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.3...v1.8.0
 [1.7.3]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.2...v1.7.3
 [1.7.2]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.1...v1.7.2

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # 参与开发
 
-感谢你参与 cowork-flow。本文只保留开始工作、判断改动范围和提交 PR 需要知道的内容。仓库结构见 [架构与扩展](docs/architecture.md)，发布流程见 [开发与发布](docs/release.md)。
+感谢你参与 cowork-flow。本文只保留开始工作、判断改动范围和提交 PR 需要知道的内容。仓库结构见 [架构与扩展](docs/architecture.md)，发布流程见 [发布与维护](docs/release.md)。
 
 ## 环境要求
 
@@ -62,30 +62,7 @@ npm run source:refresh
 | `test/host-assets.test.js`、`test/host-command.test.js`、`test/<host>-plugin.test.js`、`tests/test_host_*.py` | 行为与回归门禁 |
 | `docs/hosts.md` | 安装前提、升级、卸载和排障 |
 
-宿主特化不能进入通用层。需要遵守以下边界：
-
-- `template/.cowork-flow/scripts/{services,runtime,infra}` 和 `src/lib/` 的通用模块不写宿主分支。
-- 宿主差异放在 Host Asset Manifest、`scripts/adapters/`、`template/.<host>/` 或明确的宿主命令模块中。
-- 插件只提供宿主确实支持的字段，不复制未知或无效键。
-- 项目技能只由 `template/skills/` 分发；机器级载荷不复制同名项目技能。
-- 修改命令名时，同步更新注册表、README、doctor 提示、Skill 正文和测试。
-
-## 测试
-
-| 命令 | 覆盖范围 |
-|---|---|
-| `npm run test:fast` | 核心 Node 套件，等价于 `npm test` |
-| `npm run test:integration` | `project init` / `sync` 关键集成路径 |
-| `npm run test:node:full` | 全部 Node 测试 |
-| `npm run test:template` | 核心模板集成测试 |
-| `npm run test:template:full` | 完整模板 Python 测试 |
-| `npm run test:windows:core` | Windows 路径、换行、宿主和打包检查 |
-| `python -m pytest -q` | 仓库级 Python 测试 |
-| `npm run release:check` | 完整 Node、模板和打包门禁 |
-
-`test:fast` 只运行 `package.json` 中列出的核心套件。新增测试文件时，根据影响面决定是否加入该列表。
-
-平台前提不满足时，测试可能明确跳过。PR 描述必须列出跳过项和未验证项，不能把跳过写成通过。
+上表说明改哪里。宿主特化不能进入通用层——具体边界见 [架构与扩展](docs/architecture.md) 的“扩展规则”。
 
 ## 提交信息
 
@@ -105,23 +82,20 @@ refactor(zcode): 将插件载荷迁到 presets/zcode
 
 常用 `type`：`feat`、`fix`、`refactor`、`docs`、`test`、`chore`、`perf`。描述写清楚做了什么，不写“优化体验”一类无法核对的信息。
 
-## PR 前置检查
+## 测试与 PR 前置检查
 
-至少运行：
+最低检查：
 
 ```bash
 npm run test:fast
 git diff --check
 ```
 
-按改动范围补充：
+按改动范围该补哪些命令、各自覆盖什么，见 [发布与维护](docs/release.md) 的“发布前检查”——那是命令与适用场景的唯一清单，本文不重复。
 
-```bash
-npm run release:check                         # template/、presets/、src/commands/
-python -m pytest -q                           # template/.cowork-flow/、tests/
-npm run test:integration                     # init / sync
-./.cowork-flow/run spec-check                # 规范声明覆盖的改动
-```
+`test:fast` 只运行 `package.json` 中列出的核心套件。新增测试文件时，根据影响面决定是否加入该列表。
+
+平台前提不满足时，测试可能明确跳过。CI 在 Ubuntu 和 Windows 上运行各自的门禁，本地缺少平台前提可以跳过，但必须如实记录，不能把跳过写成通过。
 
 PR 描述需要写明：
 
@@ -130,8 +104,6 @@ PR 描述需要写明：
 - 哪些平台用例跳过或仍未验证。
 - 是否改变安装位置、命令、配置格式或升级步骤。
 
-CI 在 Ubuntu 和 Windows 上运行各自的门禁。本地缺少平台前提可以跳过，但必须如实记录。
-
 ## 许可
 
 提交代码即表示同意以 [MIT](LICENSE) 授权。

package/README.en.md

@@ -0,0 +1,180 @@
+# cowork-flow
+
+[中文](README.md) | English
+
+An in-repository collaboration workflow for AI coding assistants.
+
+Agree on the goal, the plan, and the scope of changes before work starts, and check
+against the project's own rules before calling it done. Task state lives in the
+repository, so you can pick the work back up in a new session instead of reconstructing
+progress from chat history.
+
+Supports Codex, Claude Code, OpenCode, ZCode, Qoder, Kimi Code, and DeepSeek Harness.
+
+## What it solves
+
+- Keeps requirements, decisions, plans, and the allowed change scope inside the project.
+- Makes the assistant read the current task before working, instead of continuing from memory.
+- Separates implementation from checking, so a problem sends the work back to implementation.
+- Protects custom configuration, specs, tasks, and plans in an existing project.
+
+cowork-flow is not tied to a tech stack and does not rewrite an existing project with a
+scaffold. It only adds a collaboration convention and the files that go with it.
+
+## Where it fits
+
+- You often have an AI handle features or fixes that need several rounds of confirmation.
+- You want every task to have an explicit scope, completion conditions, and a check record.
+- Work continues across multiple sessions or multiple developers.
+- You already use an AI coding host, but task state mostly lives in chat history.
+
+If you only ask questions or change a line or two, or you already have a solid task
+system, read up first and decide whether to adopt it.
+
+## Getting started
+
+Node.js 20 or later is required.
+
+### 1. Install the CLI
+
+```bash
+npm install -g cowork-flow
+cwf --version
+```
+
+`cwf` and `cowork-flow` are the same command. To skip the global install, replace `cwf`
+below with `npx cowork-flow` — except for `cwf self update`.
+
+### 2. Initialize a project
+
+Preview the files that will be written:
+
+```bash
+cwf project init . --platform codex --developer alice --dry-run
+```
+
+Drop `--dry-run` once the list looks right:
+
+```bash
+cwf project init . --platform codex --developer alice
+```
+
+Replace `codex` with the host you use:
+
+`codex`, `claude-code`, `opencode`, `zcode`, `qoder`, `kimi-code`, `dsh`.
+
+For a new project, replace `.` with `./my-project` and enter that directory. Use
+`--platform all` only when the project really will be worked on from several hosts.
+
+Initialization adds `AGENTS.md`, `.cowork-flow/`, and the matching host files. It does
+not touch application code. `--developer` is optional; on an existing project, always
+run `--dry-run` first.
+
+### 3. Finish host setup
+
+Codex, Claude Code, and OpenCode work in an initialized project as-is. ZCode, Qoder,
+DeepSeek Harness, and Kimi Code also need a machine-level component:
+
+```bash
+cwf host add <host>
+```
+
+See [host integration](docs/hosts.md) for each host's exact command, restart
+requirements, and special cases.
+
+### 4. Start inside the host
+
+Go back to your AI coding host, open the project root, and start a new session. Describe
+what you want, for example:
+
+```text
+Use cowork-flow to implement "filter the order list by status". Spell out the
+requirements, the plan, and the change scope first, and wait for confirmation before
+editing code.
+```
+
+To inspect progress by hand, run this in the project root:
+
+```bash
+./.cowork-flow/run task next
+```
+
+## Day to day
+
+- **Start a new request**: just describe what you want. The assistant confirms the goal, the plan, and the files it may change.
+- **Resume a task**: start a new session and say "continue the current task". State and context come from the project, not from the previous chat.
+- **Pause a task**: end the session. Task state stays in the project for next time.
+- **Update the project**: after upgrading the CLI, preview the sync and then apply it.
+
+```bash
+cwf self update
+cwf project sync . --dry-run
+cwf project sync .
+```
+
+`project sync` only updates files cowork-flow manages. Existing configuration, `spec/`,
+tasks, and plans are kept by default; **retired-asset cleanup** deletes obsolete
+cowork-flow files listed in the release manifest and touches nothing else. For upgrading
+machine-level host components, see [host integration](docs/hosts.md).
+
+## Troubleshooting
+
+| Symptom | First move |
+|---|---|
+| You do not know what to do next | Run `./.cowork-flow/run task next` |
+| You worry init or sync will change the wrong files | Add `--dry-run` to the command |
+| You want to confirm which hosts the project selected | Run `cwf host list .` |
+| Skills, plugins, hooks, or project files look wrong | Run `./.cowork-flow/run doctor --all` |
+| You are unsure how to write a command or flag | Run `cwf --help` or `cwf <group> <command> --help` |
+
+For host-specific problems, start with [host integration](docs/hosts.md). To understand
+how the project is organized, see [architecture and extension](docs/architecture.md).
+
+<details>
+<summary>Command reference</summary>
+
+| Command | Purpose |
+|---|---|
+| `cwf project init [target] --platform <host> [--developer <name>] [--dry-run] [--force]` | Initialize a project |
+| `cwf project sync [target] [--dry-run] [--force]` | Update the cowork-flow-managed files in a project |
+| `cwf host add <host> [--component <name>] [--dry-run] [--force] [--prune-old] [--uninstall]` | Install a machine-level host component |
+| `cwf host remove <host> [--component <name>] [--dry-run] [--force]` | Remove a machine-level host component |
+| `cwf host list [target] [--json]` | List supported hosts and what the project selected |
+| `cwf self update [--dry-run]` | Update the globally installed CLI |
+| `cwf dev refresh [target] [--dry-run]` | Refresh the self-instance while maintaining the cowork-flow repo |
+| `cwf mcp serve [args...]` | Serve task facts to an MCP client |
+
+Old command names still work; use the new names in new scripts.
+
+| Old name | New name |
+|---|---|
+| `init` | `cwf project init` |
+| `sync` | `cwf project sync` |
+| `mcp-state` | `cwf mcp serve` |
+| `update` | `cwf self update` |
+| `source-refresh` | `cwf dev refresh` |
+| `install-zcode-plugin` | `cwf host add zcode` |
+| `install-qoder-plugin` | `cwf host add qoder` |
+| `install-codex-plugin` | `cwf host add codex` |
+| `install-dsh-preset` | `cwf host add dsh --component preset` |
+| `install-dsh-hook` | `cwf host add dsh --component hook` |
+| `install-kimi-hook` | `cwf host add kimi-code --component hook` |
+
+</details>
+
+## Documentation
+
+The detailed documentation is written in Chinese.
+
+| Document | Contents |
+|---|---|
+| [Documentation index](docs/index.md) | Entry point for every document |
+| [Architecture and extension](docs/architecture.md) | How the project files are organized, how spec checks work |
+| [Host integration](docs/hosts.md) | Install, restart, troubleshoot, and uninstall for each host |
+| [Release and maintenance](docs/release.md) | Tests, CI, and maintainer commands |
+| [Contributing](CONTRIBUTING.md) | Local setup, commit conventions, and PR checks |
+| [Changelog](CHANGELOG.md) | What changed in each version |
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,5 +1,7 @@
 # cowork-flow
 
+[English](README.en.md) | 中文
+
 给 AI 编码助手加一套项目内的协作流程。
 
 开工前先确认目标、计划和改动范围，完成前按项目自己的规则检查。任务状态保存在仓库里，换个会话也能接着做，不用靠聊天记录回忆进度。
@@ -61,19 +63,13 @@ cwf project init . --platform codex --developer alice
 
 ### 3. 完成宿主设置
 
-Codex、Claude Code 和 OpenCode 在当前项目中已经能使用 `project init` 交付的内容。需要全局引导入口时，再执行表中的可选命令。
+Codex、Claude Code 和 OpenCode 在初始化的项目里就能用；ZCode、Qoder、DeepSeek Harness 和 Kimi Code 还需要安装机器级组件：
 
-| 宿主 | 建议命令 | 说明 |
-|---|---|---|
-| Codex | `cwf host add codex` | 可选，用于全局引导入口 |
-| Claude Code | `cwf host add claude-code` | 可选，用于全局引导入口 |
-| OpenCode | `cwf host add opencode` | 可选，用于全局引导入口 |
-| ZCode | `cwf host add zcode` | 初始化后执行，并新开会话 |
-| Qoder | `cwf host add qoder` | 初始化后执行；信任工作区并重启 Qoder |
-| DeepSeek Harness | `cwf host add dsh` | 初始化后执行；新会话中选择 Cowork Flow 预设 |
-| Kimi Code | `cwf host add kimi-code --component hook` | 初始化后执行；完成后重载配置或新开会话 |
+```bash
+cwf host add <host>
+```
 
-不同宿主的安装位置、重启要求和特殊情况见 [宿主接入](docs/hosts.md)。
+每个宿主的准确命令、重启要求和特殊情况见 [宿主接入](docs/hosts.md)。
 
 ### 4. 在宿主里开始
 
@@ -114,7 +110,7 @@ cwf project sync .
 | 技能、插件、hook 或项目文件状态异常 | 运行 `./.cowork-flow/run doctor --all` |
 | 不确定命令或参数怎么写 | 运行 `cwf --help` 或 `cwf <group> <command> --help` |
 
-宿主相关问题优先查 [宿主接入](docs/hosts.md)。需要了解工作原理时再看 [工作原理与扩展点](docs/architecture.md)。
+宿主相关问题优先查 [宿主接入](docs/hosts.md)。需要了解工作原理时再看 [架构与扩展](docs/architecture.md)。
 
 <details>
 <summary>命令速查</summary>
@@ -123,7 +119,7 @@ cwf project sync .
 |---|---|
 | `cwf project init [target] --platform <host> [--developer <name>] [--dry-run] [--force]` | 初始化项目 |
 | `cwf project sync [target] [--dry-run] [--force]` | 更新项目内由 cowork-flow 管理的文件 |
-| `cwf host add <host> [--component <name>] [--dry-run] [--force]` | 安装机器级宿主组件 |
+| `cwf host add <host> [--component <name>] [--dry-run] [--force] [--prune-old] [--uninstall]` | 安装机器级宿主组件 |
 | `cwf host remove <host> [--component <name>] [--dry-run] [--force]` | 卸载机器级宿主组件 |
 | `cwf host list [target] [--json]` | 查看支持的宿主和项目选择情况 |
 | `cwf self update [--dry-run]` | 更新全局安装的 CLI |
@@ -153,10 +149,10 @@ cwf project sync .
 | 文档 | 内容 |
 |---|---|
 | [文档索引](docs/index.md) | 全部文档入口 |
-| [工作原理与扩展点](docs/architecture.md) | 项目文件如何组织、规范检查如何工作 |
+| [架构与扩展](docs/architecture.md) | 项目文件如何组织、规范检查如何工作 |
 | [宿主接入](docs/hosts.md) | 各宿主的安装、重启、排障和卸载方式 |
-| [开发与发布](docs/release.md) | 测试、CI 和维护者命令 |
-| [贡献指南](CONTRIBUTING.md) | 本地开发、提交和 PR 检查 |
+| [发布与维护](docs/release.md) | 测试、CI 和维护者命令 |
+| [参与开发](CONTRIBUTING.md) | 本地开发、提交和 PR 检查 |
 | [更新日志](CHANGELOG.md) | 版本变化 |
 
 ## 许可

package/docs/architecture.md

@@ -109,6 +109,8 @@ checks:
 ## 扩展规则
 
 - 宿主特化只能放在 `spec/runtime/host-assets.json`、`scripts/adapters/`、`template/.<host>/` 或明确的宿主命令模块中。
+- 插件只提供宿主确实支持的字段，不复制未知或无效键。
+- 项目技能只由 `template/skills/` 分发；机器级载荷不复制同名项目技能。
 - `scripts/services|runtime|infra` 和 `src/lib/` 的通用计划、拷贝模块不能出现宿主分支。
 - 新宿主先更新 Host Asset Manifest 与 schema，再补安装器、doctor 和测试；不要在多个文件各写一份宿主清单。
 - 项目差异写入 `AGENTS.md`、`config.yaml`、`spec/` 或项目自有 Skill，不恢复第二套流程文档。
@@ -117,6 +119,6 @@ checks:
 
 ## 测试与字节码
 
-Node 测试位于 `test/`，Python 仓库测试位于 `tests/`。`node --test` 会加载 `test/` 下全部 `.js`，辅助模块也必须无副作用；Python 侧按 pytest 或 unittest 的默认发现规则收集。
-
 测试与技能脚本不得在 `template/`、`presets/` 下留下 `__pycache__` 或 `*.pyc`。Node 测试通过 `test/helpers/bytecode-isolation.js` 重定向缓存；技能脚本通过 `runtime_pythonpath_env(cache_bytecode=False)` 关闭字节码写入。`tests/test_no_legacy_template_paths.py` 负责守住这一边界。
+
+`node --test` 会加载 `test/` 下全部 `.js`，辅助模块也必须无副作用；Python 侧按 pytest 或 unittest 的默认发现规则收集。