@xulthekl/team-flow 0.22.4

package/docs/examples/refactor-auth-boundary/specs/auth-boundary/spec.md

@@ -0,0 +1,45 @@
+# auth-request-gating Specification
+
+## MODIFIED Requirements
+
+### Requirement: Protected requests use one authentication boundary
+
+The system SHALL evaluate protected requests through one shared authentication boundary instead of scattered controller-level auth logic.
+
+#### Scenario: Valid protected request
+
+- **WHEN** a protected request includes valid authentication credentials
+- **THEN** the shared authentication boundary produces an authenticated request context
+- **AND** downstream handlers use that context instead of re-parsing credentials independently
+
+#### Scenario: Missing credentials
+
+- **WHEN** a protected request arrives without required credentials
+- **THEN** the shared authentication boundary rejects the request consistently
+- **AND** the request does not continue into protected business logic
+
+### Requirement: Auth failures map consistently
+
+The system SHALL map authentication and authorization failures through standardized request-level outcomes.
+
+#### Scenario: Invalid token
+
+- **WHEN** token validation fails
+- **THEN** the request receives the standardized unauthorized outcome
+- **AND** downstream handlers are not invoked
+
+#### Scenario: Authenticated but forbidden
+
+- **WHEN** the requester is authenticated but lacks required access
+- **THEN** the request receives the standardized forbidden outcome
+- **AND** the outcome is produced without ad hoc controller-specific branching
+
+### Requirement: Existing approved login behavior remains unchanged
+
+The refactor SHALL preserve already approved login and session semantics while changing the internal auth boundary shape.
+
+#### Scenario: Existing login flow
+
+- **WHEN** a user signs in through the existing approved login path
+- **THEN** the resulting session or token behavior remains externally unchanged
+- **AND** the new boundary consumes the established auth artifacts without requiring a new client contract

package/docs/examples/refactor-auth-boundary/tasks.md

@@ -0,0 +1,25 @@
+# Implementation Tasks
+
+## 1. Baseline Verification
+
+- [ ] 1.1 Identify the current protected request paths and auth entry points
+- [ ] 1.2 Add failing tests for missing credentials, invalid tokens, and forbidden outcomes
+- [ ] 1.3 Add a regression check for existing login and session behavior
+
+## 2. Boundary Introduction
+
+- [ ] 2.1 Introduce an `AuthBoundary` interface or equivalent module
+- [ ] 2.2 Move shared token parsing and validation behind the boundary
+- [ ] 2.3 Define a standardized auth decision or authenticated request context
+
+## 3. Incremental Migration
+
+- [ ] 3.1 Migrate one protected route group to the new boundary
+- [ ] 3.2 Remove duplicate request-level auth branching from migrated handlers
+- [ ] 3.3 Migrate remaining protected entry points
+
+## 4. Verification And Review
+
+- [ ] 4.1 Verify tests pass after each migration batch
+- [ ] 4.2 Review unauthorized and forbidden mappings for consistency
+- [ ] 4.3 Review implementation against the execution contract

package/docs/plans/2026-07-07-fix-batch-design.md

@@ -0,0 +1,68 @@
+# 修复批次设计文档（fix/issue-verification-batch）
+
+> 日期：2026-07-07 | 基线：v0.8.14 | 范围：真实缺陷 + 轻量增强（用户选定）
+> 来源：对 19 条 GitHub issues 的独立代码核查（见 `team-flow-issues-analysis.md`）
+
+## 范围与分类
+
+| 项 | 类型 | 修复归属 |
+|----|------|----------|
+| BUG-A 收口 `closing` 卡死 | 真实 BUG（P0） | team-flow 自身 |
+| BUG-B `readState` 静默默认致状态漂移 | 真实 BUG（P0） | team-flow 自身 |
+| #26 / #27.2 `tf` 未进 PATH | 真实 BUG / 增强（P1） | team-flow 自身 |
+| #28 门禁可跳步（spec-merger 被跳过） | 真实 BUG（P1） | team-flow 自身 |
+| #15 git 分支隔离仅建议、无强制 | 真实 BUG（P2） | team-flow 自身 |
+| #29 ZCODE 平台支持 | 轻量增强 | team-flow 自身 |
+
+## BUG-A：收口跳转 `executing → closing` 被永久卡死
+
+**根因**：`release-archivist` 从不写 `test_result: pass`，而 `tests-passing` 守卫强制要求它；`tf state transition` 又强制执行守卫并 `exit(1)`，导致收口永远失败。
+
+**修复**：
+1. `scripts/guard/checks/tests-passing.mjs`：在 `state.test_result === 'pass'` 之外，额外接受 `state.dp_6_result` 以 `"pass"` 开头（release-archivist 验证结果即等价信号）。代码级兜底，不依赖 AI 记忆。
+2. `skills/release-archivist/SKILL.md`：在 DP-6 通过后、执行 `state transition closing` 之前，补一步 `tf state set <change-dir> test_result pass`（随 #26 一并改为 node 调用），保持状态文件语义一致。
+3. 回归测试：`tests/lib/guard-tests-passing.test.mjs` —— 无 test_result 且无 dp_6 pass 时 `executing→closing` 守卫失败；dp_6_result 以 pass 开头时通过。
+
+## BUG-B：`readState` 对缺失文件静默返回默认 → 幽灵状态文件/漂移
+
+**根因**：`state-loader.mjs:45-47` 文件不存在时返回默认 `state: exploring`；`cmd-state.mjs` 的 `get/set/transition` 据此静默操作，尤其 `set` 会在错误目录新建 `.team-flow.yaml`。
+
+**修复**：
+1. `scripts/lib/cmd-state.mjs`：对所有非 `init` 子命令，先校验 `.team-flow.yaml` 是否存在；不存在则明确报错 `No state file at <path>. Run 'tf state init <change-dir>' first.` 并 `exit(1)`。这同时杜绝 `set` 创建幽灵文件。
+2. 回归测试：`tests/lib/cmd-state-missing.test.mjs` —— 对不存在目录执行 transition/get/set 均非零退出且提示 "No state file"。
+
+## #26 / #27.2：skill 依赖裸 `tf`（PATH 依赖）
+
+**根因**：skills 大量调用裸 `tf ...`，但安装脚本从不把 `tf` 链入 PATH；cursor/marketplace 用户无 `tf` 二进制 → 步骤失败。
+
+**修复（彻底去 PATH 依赖）**：把 `skills/**/SKILL.md` 中所有 `tf <sub>` 调用统一改写为 `node "${CLAUDE_PLUGIN_ROOT}/scripts/team-flow.mjs" <sub>`（`CLAUDE_PLUGIN_ROOT` 安装时已替换为绝对路径，必然可用）。该机械改写由脚本完成并逐文件 review diff。这同时满足 #27.2「没有 tf 命令也能用」的诉求。
+
+## #28：门禁可跳步（delta specs 存在时 spec-merger 被跳过）
+
+**修复（硬门）**：
+1. 新增 `scripts/guard/checks/specs-merged.mjs`：若 `spec_merged === true` → 通过；否则若 `specs/` 含 `## ADDED/MODIFIED/REMOVED/RENAMED` delta 需求且 `spec_merged !== true` → 失败（提示先跑 spec-merger）。
+2. `scripts/guard/guard.mjs`：`executing:closing` 增加维度 `specs-merged`，并在 CHECK_RUNNERS 注册。
+3. `state-loader.mjs`：增加字段 `spec_merged`（默认 false），同步到 writeState 与 SETTABLE_FIELDS。
+4. `skills/spec-merger/SKILL.md`：合并完成后写 `tf state set <change-dir> spec_merged true`（node 调用）。
+5. 回归测试：`tests/lib/guard-specs-merged.test.mjs`。
+
+## #15：git 分支隔离仅建议、无强制（曾改坏 master）
+
+**修复（可强制）**：
+1. 新增 `scripts/ensure-branch.mjs`：检查当前分支；若在 `main`/`master`，优先 `git worktree add`，失败则 `git switch -c`；均失败且未获用户显式批准则非零退出并提示。
+2. `scripts/team-flow.mjs`：注册 `isolate` 命令 → `cmd-isolate.mjs`（封装 ensure-branch.mjs）。
+3. `skills/build-executor/SKILL.md`：将"Branch/worktree preflight"由建议文本改为**必须运行** `node "${CLAUDE_PLUGIN_ROOT}/scripts/ensure-branch.mjs" <change-dir>`（或 `tf isolate`），其失败即阻断编辑。
+
+## #29：ZCODE 平台支持
+
+**修复（机械镜像 cursor 安装）**：
+1. 新增 `scripts/install-zcode.mjs`，镜像 `install-cursor.mjs`（复制 skills、替换 `CLAUDE_PLUGIN_ROOT`、生成 rules）。
+2. `scripts/team-flow.mjs` 注册 `install-zcode`。
+3. `INSTALL.md` 平台表增加 ZCODE 行。
+> 假设：ZCODE 以 skills 目录方式发现技能（与 Cursor 本地 skills 同形）。具体 manifest 格式待用户确认后补；当前实现保证 `tf install-zcode` 可用。
+
+## 验证
+
+- 每个修复配独立回归测试（`node --test`）。
+- 全量运行 `npm test`，确保无回归。
+- 手动 `tf doctor` 检查安装健康度。

package/docs/plans/2026-07-20-001-refactor-skill-collaboration-protocol-plan.md

@@ -0,0 +1,128 @@
+---
+title: Skill 协作协议层设计 - Plan
+type: refactor
+date: 2026-07-20
+topic: skill-collaboration-protocol
+artifact_contract: ce-unified-plan/v1
+artifact_readiness: requirements-only
+product_contract_source: ce-brainstorm
+execution: code
+---
+
+# Skill 协作协议层设计 - Plan
+
+## Goal Capsule
+
+**Objective：** 为 team-flow 的 17 个 skill 建立统一协作协议层，解决四套子系统（team-flow / compound-engineering / architecture-design / prototype）之间的数据流转、跨系统衔接和决策点交互体验问题。第一优先级修复 ce-brainstorm 产物与 PRD 体系的不匹配。
+
+**Product Authority：** LT
+
+**Open Blockers：** 无阻塞项。
+
+## Product Contract
+
+### Summary
+
+分三阶段实施：**P1 PRD 对齐** — 改造 ce-brainstorm 使其读取可配置的 PRD 模板、输出 PRD 格式到 `prd/vN/prd.md`、支持迭代版本自动检测+用户确认；**P2 Schema 协议层** — 每个 skill 声明 input/output schema，建立机器可解析的工件契约；**P3 Handoff + DP 优化** — 标准化 skill 间 handoff 文件，优化决策点信息展示。
+
+### Problem Frame
+
+**P1 根因（已验证）：** ce-brainstorm 是从 compound-engineering 复制过来的 skill，其产物契约（`ce-unified-plan/v1`、Goal Capsule + Product Contract 章节结构）是 compound 自己的设计。team-flow 设计要求 ce-brainstorm 产出 PRD 文档到 `prd/vN/prd.md`，支持可配置模板（`prd.template` 配置字段已设计但未落地）。实际验证发现：产出格式不对（ce-unified-plan vs PRD）、产出路径不对（`docs/plans/` vs `prd/`）、模板文件不存在、迭代版本（vN）无感知。
+
+**P2-P3 根因：** 四套体系拼合后协作依赖隐式约定，缺少机器可解析的契约定义和标准化 handoff 协议。
+
+### Key Decisions
+
+1. **改造 ce-brainstorm 输出 PRD 格式**（session-settled: user-directed — chosen over 路由层适配/新建 skill: 直接改造，保持 skill 数量不变）
+
+2. **PRD 模板外部可配置**（session-settled: user-directed — 不同项目/团队的 PRD 模板不同，通过 `prd.template` 配置字段指定模板路径，`tf runtime config --get prd.template` 读取）
+
+3. **迭代版本 vN = 产品迭代版本**（session-settled: user-directed — `prd/vN` 中的 vN 是项目不同迭代版本（如 v1=MVP, v2=扩展），不是同一 PRD 的文档版本）
+
+4. **迭代版本自动检测 + 用户确认**（session-settled: user-directed — ce-brainstorm 扫描 `prd/` 目录检测已有迭代，建议最新迭代或新迭代，用户确认）
+
+5. **Schema 声明式协议 + Handoff 模板混合策略**（session-settled: user-directed — chosen over 中间件总线模式: 非侵入式、增量可部署）
+
+6. **保留全部 8 个决策点，优化信息展示**（session-settled: user-directed — chosen over 合并同类 DP: 保留决策粒度）
+
+### Requirements
+
+**Phase 1：PRD 对齐**
+
+R1. 创建默认 PRD 模板 `templates/prd.md`（已完成），包含 11 个一级章节：版本修订记录、业务流程一览、D7.1 业务流程、D7.2 画面原型及设计、D7.3 报表清单、D7.4 业务术语字典、D7.5 系统功能清单、D7.6 系统功能处理说明书、D7.7 要件定义自查报告、D7.8 要件定义完成报告、D7.9 评审会议纪。
+
+R2. 改造 ce-brainstorm SKILL.md，使其读取 `prd.template` 配置（`tf runtime config --get prd.template`），如未配置则使用默认模板 `templates/prd.md`。
+
+R3. ce-brainstorm 产出 PRD 文档写入 `prd/vN/prd.md`（N 为迭代版本号），而非 `docs/plans/` 目录。
+
+R4. ce-brainstorm 在启动时扫描 `prd/` 目录检测已有迭代版本，自动建议最新迭代或创建新迭代，用户确认后继续。
+
+R5. ce-brainstorm 的产物元数据适配 PRD 体系：移除 `artifact_contract: ce-unified-plan/v1`，替换为 PRD 相关元数据（项目名称、迭代版本、文档状态等，对齐模板 §1.1 版本信息表）。
+
+R6. ce-brainstorm 的章节结构从 "Goal Capsule + Product Contract" 改为 PRD 模板的 11 章结构。brainstorm 对话中收集的信息填充到对应 PRD 章节。
+
+R7. 保留 ce-brainstorm 的对话式 brainstorm 能力（交互规则、Phase 1-4 流程），但产出格式和目标路径对齐 PRD 体系。
+
+**Phase 2：Schema 协议层**
+
+R8. 每个 skill 的 SKILL.md frontmatter 增加 `input_schema` 和 `output_schema` 字段，声明该 skill 消费和产出的工件列表及结构约束。
+
+R9. `input_schema` 中每个工件条目包含：`artifact`（工件文件名）、`required`（是否必须）、`schema_ref`（可选，指向 JSON Schema 定义文件）。
+
+R10. `output_schema` 格式与 `input_schema` 对称，额外增加 `consumed_by` 字段声明下游消费者 skill 列表。
+
+R11. 在 `team-flow/schemas/` 目录下维护关键衔接点的 JSON Schema 定义文件。
+
+**Phase 3：Handoff + DP 优化**
+
+R12. 每个 skill 完成时生成标准 handoff 文件（`handoff.yaml`），包含 `from_skill`、`to_skill`、`timestamp`、`artifacts`、`context_summary`、`dp_digest` 字段。
+
+R13. 四套子系统的衔接点使用专用 handoff 变体，通过 `bridge_type` 字段区分。
+
+R14. 每个 DP 的触发 skill 从上游 handoff 自动提取结构化摘要，生成精炼的 DP 展示信息。
+
+R15. 保持全部 8 个 DP（DP-0 至 DP-7）的门禁完整性。
+
+### Scope Boundaries
+
+**Deferred for later：**
+
+- Schema 校验引擎的自动化实现（运行时校验、CI 集成）
+- DP 展示的 UI/UX 细节设计（交互控件、布局、动画）
+- handoff 文件的版本演进和向后兼容策略
+- PRD 模板的多样化（不同行业/团队的模板变体）
+
+**Outside this scope：**
+
+- 不改状态机的 8 态定义和转换规则
+- 不涉及 team-flow 底座（TypeScript 解析引擎）的代码改动
+- 不改变 PRD 模板的 11 章结构（由企业模板蒸馏确定）
+
+### Dependencies / Assumptions
+
+- `tf runtime config --get prd.template` 机制可正常读取配置（HANDOFF.md §6 提到需要实测）
+- 现有 `.superpowers/sdd/checkpoints/` 和 `.superpowers/sdd/handoffs/` 目录结构可复用
+- 所有 skill 的 SKILL.md frontmatter 支持扩展字段
+- PRD 模板的 11 章结构适用于大多数项目（不适用时通过 `prd.template` 配置替换）
+
+### Outstanding Questions
+
+**Deferred to Planning：**
+
+- `prd.template` 配置字段在 `team-flow.config.json` 中的 schema 定义（需要扩展 config schema）
+- ce-brainstorm 如何处理"需求不够完整、无法填充全部 11 章"的场景（部分章节留空 vs 分阶段填充）
+- 迭代版本 vN 的编号规范（纯数字 v1/v2/v3 vs 语义化 v1.0/v1.1）
+- `handoff.yaml` 是否需要与现有 `checkpoint` JSON 格式保持结构一致性
+- 17 个 skill 的 input/output schema 逐一定义的具体字段清单
+
+### Acceptance Examples
+
+**AE1.** **When** 用户启动 ce-brainstorm 并指定"完善产品研发工作流的设计"，**then** ce-brainstorm 扫描 `prd/` 目录，检测到已有 v1，建议"在 v1 上继续"或"创建 v2"，用户确认后在对应迭代目录下工作。
+
+**AE2.** **When** ce-brainstorm 完成 brainstorm 对话，**then** 产出 `prd/v1/prd.md`（或 `prd/v2/prd.md`），结构对齐 `templates/prd.md` 的 11 章，占位符被对话中收集的信息填充。
+
+**AE3.** **When** 项目配置了自定义 PRD 模板（`team-flow.config.json` 中 `prd.template: ".team-flow/custom-prd.md"`），**then** ce-brainstorm 读取自定义模板而非默认模板。
+
+**AE4.** **When** ce-plan 接手 ce-brainstorm 的 PRD 产出，**then** ce-plan 在同一 `prd/vN/prd.md` 文件上就地 enrich，将 requirements-only 状态提升为 implementation-ready。
+
+**AE5.** **When** ce-plan 完成 PRD enrich 后需要交给 spec-writer 启动 change，**then** ce-plan 生成 handoff 文件，spec-writer 从中读取 PRD 引用，无需用户手动转述。

package/docs/platform-matrix.md

@@ -0,0 +1,45 @@
+# 平台支持矩阵
+
+team-flow 共支持 **18 个** AI 编程平台。每个平台按三层接入：
+
+- **Skills** — 9 个 skill 部署到平台技能目录（`${CLAUDE_PLUGIN_ROOT}` 重写为绝对路径）。
+- **Rules** — phase-guard 规则文件部署到平台规则目录，被平台自动加载为常驻上下文（守卫机制）。
+- **Hooks** — SessionStart 上下文注入钩子（仅在该平台原生支持且已验证时接入）。
+
+## 矩阵
+
+| # | 平台 | Skills | Rules（路径 / 格式） | Hooks |
+|---|------|:------:|----------------------|:-----:|
+| 1 | Claude Code | ✅ | `.claude/rules/` · md | ✅ SessionStart |
+| 2 | Cursor | ✅ | `.cursor/rules/` · mdc | ✅ sessionStart |
+| 3 | OpenAI Codex CLI | ✅ | marketplace · md | ✅ |
+| 4 | OpenAI Codex App | ✅ | marketplace · md | ✅ |
+| 5 | GitHub Copilot CLI | ✅ | `.github/instructions/` · copilot | ✅ |
+| 6 | Gemini CLI | ✅ | `GEMINI.md`（无 rules 目录） | ✅ |
+| 7 | OpenCode | ✅ | `.opencode/` · md | — |
+| 8 | WorkBuddy | ✅ | `marketplace plugin rules/` · md | — |
+| 9 | Trae | ✅ | — | — |
+| 10 | Cline | ✅ | `.clinerules/`（项目根）· md | — |
+| 11 | Kiro | ✅ | `.kiro/steering/` · md | — ¹ |
+| 12 | Windsurf | ✅ | `.windsurf/rules/` · md | — ¹ |
+| 13 | Qwen Code | ✅ | `.qwen/rules/` · md | — ¹ |
+| 14 | Amazon Q Developer | ✅ | `.amazonq/rules/` · md | — ¹ |
+| 15 | Roo Code | ✅ | `.roo/rules/` · md | — |
+| 16 | Continue | ✅ | `.continue/rules/` · md | — |
+| 17 | Pi | ✅ | —（无规则目录） | — |
+| 18 | Qoder | ✅ | `.qoder/rules/` · md | — |
+
+> ¹ Kiro / Windsurf / Qwen / Amazon Q 平台原生支持 hooks（comet 源码确认 hookFormat 分别为 kiro / windsurf / qwen / claude-code），但 team-flow 的 SessionStart 钩子在这些平台的可用性尚未逐一验证，故 v0.8.13 暂不写入 hook 配置，避免塞入失效配置。上下文注入由 phase-guard 规则（平台自动加载）承担。后续版本将逐平台验证后补齐。
+
+## 路径来源
+
+所有 `skillsDir` / `rulesDir` / `rulesFormat` / `hookFormat` 均与 [comet](https://github.com/rpamis/comet) 的 `src/core/platforms.ts` 交叉核实，并对照各平台官方约定。team-flow 的守卫机制是 **phase-guard 规则文件**（平台自动加载），而非 comet 的 PreToolUse 钩子——这是两层架构的根本区别。
+
+## 安装命令速查
+
+```bash
+npx team-flow@latest install-<id>
+# <id> ∈ {cline, kiro, windsurf, qwen, amazon-q, roocode, continue, pi, qoder, cursor, workbuddy}
+```
+
+Claude Code / Codex / Copilot / Gemini / OpenCode / Trae 走各自 marketplace 或本地目录，详见 [INSTALL.md](../INSTALL.md)。

package/docs/prototype-design-research.md

@@ -0,0 +1,206 @@
+# 原型设计解决方案调研与最优方案（纯 CLI 插件场景）
+
+> 调研目标（LT 第 13–14 轮指令）：
+> 1. 调研 Claude Design / Open Design / Trae 等"设计系统驱动原型"方案；
+> 2. 确认"无应用、纯 CLI 插件"是否存在高质量原型方案；
+> 3. 回答拷问：team-flow 的原型实际有人用吗？效果如何？怎么用？
+> 4. 补充约束：原型需**随需求持续迭代**（迭代方案 + 产物维护），且要**衔接实施阶段**（架构/API/开发）。
+> 本文件为 v0.3 原型章的方案基础与专家评审材料。
+
+---
+
+## 一、五个方案的事实对比
+
+| 维度 | Claude Design（Anthropic 官方） | Open Design（开源替代） | Trae Work Design 模式 | team-flow handoff --type prototype | 本地 HTML 原型内核（self-contained HTML skill） |
+|---|---|---|---|---|---|
+| 定位 | 对话生成设计/交互原型/幻灯片 | 本地优先的开源 Claude Design 替代 | IDE 内 Design 模式生成/迭代界面 | 验证"某变更设计可行性"的 overlay | 同一套设计纪律在无 GUI 下的平移 |
+| 设计系统 | 组织设计系统自动继承；`/design-sync` 从 repo/设计文件导入 | **71 个品牌级 `DESIGN.md`**（9 段 schema：color/typography/spacing/layout/components/motion/voice/brand/anti-patterns），可移植 Markdown | 内置 + 自定义设计系统，可导入主题/组件/图像/规范 | 无设计系统概念，仅草图验证 | 本地 `design-system.md`（借鉴 DESIGN.md 概念，项目 config 注入）+ 页面内 Tweaks 面板 |
+| 产物 | 交互原型、standalone HTML、PPTX、PDF，可移交 Claude Code | web-prototype/saas-landing/dashboard/mobile-app 等 19 skill；导出 HTML/PDF/PPTX/ZIP/MD | 画布预览，导出 Figma/PNG/JPG/HTML/ZIP；可"在 Code 模式开发" | `prototype/` 目录 + `HANDOFF_RESULT.md` | 本地自包含 HTML（CSS 进 `<style>`、JS 进 `<script>`）+ 内嵌 Tweaks |
+| GUI 依赖 | **强依赖** web/desktop 可视化画布（拖拽、行内评论） | 需本地 daemon + Vite React 前端 + 浏览器 sandbox iframe 预览 | **强依赖** GUI 画布/可视化编辑器 | 纯 CLI（开隔离 worktree） | **零 GUI、可离线**，CLI 写文件即可 |
+| 纯 CLI 适配 | 否（仅 MCP 桥接，底层依赖 api.anthropic.com） | 否（需 daemon+前端+浏览器） | 否 | 是，但能力弱（草图） | **是，最契合** |
+| 迭代机制 | 对话/画布编辑/行内评论迭代 | 表单锁定 + 沙箱预览 + 评论式手术编辑（路线图中） | 画布编辑 + 批量修改 + 连线跳转 | 一次性 overlay，不回写 | 重新生成 HTML / 调 Tweaks，全局一份 + git 分支隔离版本 |
+| 与开发衔接 | 导出/移交 Claude Code | artifact 落盘项目目录 | "Code 模式开发"打包 zip + 默认指令 | 不自动改 design.md/tasks.md（硬约束） | 原型（全局）进 execution-contract.md 作 UI 契约参考 |
+| 成熟度/采用 | 2026-04-17 发布，beta，仅 web/desktop | 早期实现（Apache-2.0，GitHub nexu-io/open-design） | 2025-06 上线，字节生态 | 机制存在但非主流 | 设计纪律规范（skill 级） |
+
+**关键事实核实：**
+- Claude Design 官方指南明确：入口仅 web/desktop，**无纯 CLI**；唯一非 GUI 通道是 Claude Code + Claude Design MCP server（HTTP），底层仍依赖 api.anthropic.com 的设计能力，GUI 画布交互在终端无法等效替代。
+- Open Design FAQ 明确：本地优先，最少需要本地 daemon + 一个 Agent；"不安装 CLI 或桌面端不能用"。其价值在 **DESIGN.md 可移植设计系统概念**（71 个品牌、9 段 schema、5 方向确定性调色板），而非纯 CLI 内核。
+- Trae Design 文档显示：强 GUI 画布、可视化编辑器（设计+原型页签建立跳转）、"在 Code 模式中开发"衔接思路可借鉴，但强依赖 IDE。
+- 本地 HTML 原型内核（自包含 HTML + Tweaks，公开方法论内化）：产物是本地自包含 HTML，用页面内 `<div>` Tweaks 控件替代云端工具栏，明确"avoid remote dependencies"，**可完全离线**。
+
+---
+
+## 二、针对"无应用、纯 CLI 插件"的结论
+
+| 方案 | 能否内嵌进我们的统一插件 | 判断 |
+|---|---|---|
+| Claude Design | 否 | 强 GUI + 云端依赖，只能做外部 MCP 桥接，不可离线 |
+| Open Design | 间接（借鉴概念） | 需 daemon+前端+浏览器，非纯 CLI；但 **DESIGN.md 设计系统概念值得整体借鉴** |
+| Trae Design | 否 | 强 GUI IDE 依赖 |
+| team-flow handoff | 部分（机制可用但弱） | 纯 CLI 但仅草图验证，无设计系统、无闭环、非主流 |
+| **本地 HTML 原型内核（self-contained HTML skill）** | **是（最优内核，零外部依赖）** | 不安装任何外部设计软件，纯 CLI 产出本地 HTML，契合"一次安装一个插件" |
+
+**结论：我们"无应用、纯 CLI 插件"的高质量原型方案 = 本地 HTML 原型内核（self-contained HTML skill，零外部软件依赖）+ 借鉴 Open Design 的 DESIGN.md 可移植设计系统概念（仅借鉴思想，不安装任何外部软件）。**
+
+不内嵌任何 GUI 工具的渲染层，只把它们的"设计系统驱动风格"思想落成本地 `design-system.md`，原型内核自研为一个 skill（写合规 HTML 文件）。
+
+> **零外部依赖声明**：本方案**不安装、不调用任何外部设计软件**（Claude Design / Open Design / Trae 均不安装）。"本地 HTML 原型内核"与"DESIGN.md 概念"只是借鉴其公开的"AI 生成自包含 HTML 原型"方法论与"用 Markdown 定义设计系统"的思想，全部内化为我们插件内部的**通用 skill**。
+
+### 2.1 配置驱动：插件通用 + 项目注入（回应 LT 第 15 轮修正）
+
+**原则：插件只提供通用机制与默认骨架，项目独特资产由项目级配置注入，不固化在插件内。**
+
+team-flow 已有项目级配置机制，可直接扩展：
+- `.team-flow.yaml`：per-change 状态/决策缓存（dp_0_decisions、workflow、state 等 12 字段）。
+- `team-flow.config.json`：项目级配置，**config-aware**（CHANGELOG 证实支持 `artifacts.order` / `artifacts.skip`，由 `tf runtime config --get <key>` 读取）。我们在此基础上扩展 `prd` / `prototype` 段（以及未来可扩展 `api` / `architecture` 模板段）。
+
+**插件层（一次安装，通用，不含任何公司风格）：**
+- `skills/prototype-builder/SKILL.md`：通用原型构建规则（产出自包含 HTML 原型系统、多页面、组件化、Tweaks）。
+- `skills/prd-writer/`（或复用 ce-plan）：通用 PRD 结构 schema。
+- `templates/prd.default.md`、`templates/design-system.base.md`：默认骨架（可被项目覆盖）。
+
+**项目层（每项目一份 `team-flow.config.json` + 自定义模板/设计系统文件，放在项目目录如 `.ourflow/`）：**
+```json
+{
+  "artifacts": { "order": ["proposal","specs","design","tasks"], "skip": [] },
+  "prd": { "template": ".ourflow/prd.acme.md" },
+  "prototype": {
+    "designSystem": ".ourflow/design-system.acme.md",
+    "outDir": "prototype"
+  }
+}
+```
+- `prd.template`：项目独特 PRD 结构与模板（不同公司/项目结构不同）。
+- `prototype.designSystem`：项目独特设计系统（颜色/字体/组件/品牌，9 段 schema）。
+- `prototype.outDir`：全局原型目录（**全局层，与 PRD 同级**，非 change 子目录）。
+
+**运行逻辑**：prototype-builder / prd-writer 启动时读 `tf runtime config --get prd.template` 与 `prototype.designSystem`；若配置缺失，回退到插件内置默认骨架。项目资产始终留在项目目录，**插件保持通用、可跨公司复用，设计风格零硬编码**。
+
+---
+
+## 三、team-flow 原型的真实使用情况（回答拷问）
+
+**机制确实存在（源码核实）：**
+- `tf handoff create <dir> --type prototype`（`sdd-overlay.mjs` 中 `HANDOFF_TYPES = ['prototype','research','experiment']`）。
+- 触发：workflow-start 在检测到 UX/规格不确定性时建议。
+- 行为：`tf isolate <change-dir> prototype-<handoff-id>` 开隔离 worktree，结果落 `HANDOFF_RESULT.md` + `prototype/` 目录。
+
+**但实际使用情况（公开资料核实）：**
+- GitHub Star ≈ 449（v0.9.0，npm.io 数据），社区实战案例集中在主流程：add-dark-mode、RBAC 权限、bug 修复等。
+- **无任何一篇实战文章/社区讨论演示 `handoff --type prototype` 的使用案例或效果反馈**（腾讯云完整指南 v0.9.0 实战章节未提及；juejin/头条/segmentfault 等文章全在主流程）。
+- 官方定位：它是验证"某变更设计可行性"的 **overlay**，不是 PRD 之后的循环环节。
+- **硬约束：handoff 结果不自动改 design.md/tasks.md**（overlay 规则，INSTALL.md）。
+
+**效果与怎么用：**
+- 效果：机制可用但**非主流、缺实战背书、无 PRD 闭环、无"原型随需求迭代"原生概念**。
+- 怎么用：仅在 workflow-start 检测到 UX/规格不确定性时触发，做一次性可行性草图，结果由人工判读后决定是否回流 PRD/design；不自动回写。
+
+**对 LT 第 12 轮拷问的修正结论：** 原型机制"有"，但既非主流用法、也无闭环、更无迭代模型——所以你第 12 轮说的"缺失原型设计及原型→完善 PRD 循环"完全成立，且需进一步补"迭代/维护/衔接"。
+
+> **Note（第 16 轮修正）**：team-flow 自带的 `handoff --type prototype` 是 **per-change overlay**（开隔离 worktree，落 change 内 `prototype/`），与我们定义的"**全局原型、与 PRD 同级**"定位不同。我们的原型能力**不复用**该 overlay 作为主机制，而是自建全局 `prototype/` 目录（见 §4）。team-flow 的 handoff 仅作可选的可行性草图旁路。
+
+---
+
+## 四、原型迭代方案 + 产物维护 + 与实施阶段衔接（回答补充）
+
+### 4.0 产物层级模型（全局层 vs 变更层，回应 LT 第 16 轮）
+
+必须先厘清 PRD / 原型 / 代码 / change 的层级关系，否则原型归属会错（此前误把原型放 change 维度）。
+
+**全局层（产品级，与 PRD 同级）：**
+- `prd/`：PRD，**有版本迭代** v1→v2→v3…，每个版本是完整需求基线。
+- `prototype/`：原型，**全局一份**，与 PRD 同级；随 PRD 版本演进，物理一份，git 分支隔离版本。
+- `design-system.md`：全局一份，config 注入。
+- `architecture.md`：全局架构，复利回写目标。
+- `api.md`：全局 API，复利回写目标。
+- `src/`：代码，全局一份，git 分支隔离。
+
+**变更层（team-flow change，从 PRD 拆解）：**
+- `changes/<id>/`：proposal.md / specs/ / design.md / tasks.md / execution-contract.md。
+- 每个 change 走 team-flow 8 状态机。
+- **一份 PRD（某版本）可拆出多个 change**；change 是实施工作单位，不是产品基线。
+
+**关系链：**
+```
+PRD(vN) ──拆解──┬─▶ change-1 ─▶ team-flow（exploring→…→closing）
+                ├─▶ change-2 ─▶ team-flow
+                └─▶ change-3 ─▶ team-flow
+全局 prototype/ ──（UI 契约参考）──▶ 各 change 的 build-executor
+各 change 完成 ──（增量合并）──▶ 全局 architecture.md / api.md / prototype / src
+```
+**核心纠正（此前错误）：原型不是 per-change 的 overlay，而是全局一份、与 PRD 同级；版本演进靠 git 分支，不靠 change 内 v1/v2 目录。**
+
+### 4.1 原型迭代模型（全局一份，随 PRD 版本演进）
+
+- 原型是**全局产物**（与 PRD 同级），**物理一份**，不是某个 change 的子目录。
+- **版本演进靠 git 分支**：PRD 升版（v1→v2）时，原型在对应分支上演进到该版本形态（如 `prd-v2` 分支上的 `prototype/` = v2 产品原型）；一份代码/原型，git 隔离版本。
+- **PRD 有版本，原型/代码无多份**：PRD 持续迭代产生 v1/v2/v3 需求基线；原型与代码各自只有"当前形态一份"，历史版本由 git 分支/标签保留。
+- **change 引用全局原型**：每个 change 实施时，把全局 `prototype/` 作为 UI 契约参考（进 execution-contract.md）；change 不直接拥有原型文件。
+- change 完成 → 其 UX 增量合并回全局 `prototype/` 与 `architecture.md`/`api.md`（compound 复利回写）。
+
+### 4.2 产物维护（完整原型系统，全局一份）
+
+原型目录位于**全局层**（与 PRD 同级），是完整原型系统，不是单页、不是 change 子目录：
+
+```
+prototype/                      # 全局，一份，git 分支隔离版本
+├── index.html                  # 入口 / 全局导航
+├── pages/                      # 多页面（首页 / 列表 / 详情 / 设置 …）
+├── components/                 # 可复用组件（按钮 / 表单 / 卡片 …），统一设计系统
+├── assets/                     # 共享 style.js / design-tokens.css
+├── design-system.md            # 本项目设计系统（config 注入，9 段 schema）
+└── flow.md                     # 页面跳转 / 用户流说明
+```
+- 版本管理：**git 分支 / 标签**隔离 PRD 版本（非 change 内 v1/v2 目录）。
+- 复利回写：change 完成 → 原型结论 + 设计系统迭代回写**全局** `design-system.md` / `architecture.md` / `api.md`；design-system 是项目资产（config 注入），回写发生在项目内。
+- 全局 `design-system.md` 作本项目风格唯一真相源，随 PRD 版本演进复利，防漂移。
+
+### 4.3 与实施阶段衔接（闭环，两层）
+
+```
+PRD(vN) ──拆解──┬─▶ change-1 ─┐
+                ├─▶ change-2 ─┼─▶ team-flow: spec-writer → contract-builder → build-executor
+                └─▶ change-3 ─┘         （各 change 引用全局 prototype/ 作 UI 契约）
+                                              │
+        全局 prototype/ ◀── 增量合并 ────────┘（change 完成回写 UX / 架构 / API）
+        compound 复利回写: design-system.md / architecture.md / api.md
+```
+- 原型（全局）→ 架构：原型确认的 UX 流向全局 `architecture.md` 限界上下文映射（DDD）。
+- 原型 → API：原型交互 → 端点设计 → 流入 `execution-contract.md` + build-executor。
+- 原型 → 开发：全局原型作 UI 契约参考进 `execution-contract.md`，build-executor 按契约 + TDD 实现。
+- 闭环：PRD 版本演进 → 拆 change → team-flow 实施 → 增量回写全局原型/架构/API；原型随 PRD 持续迭代不腐烂。
+
+---
+
+## 五、最优解决方案（总结提案）
+
+对"我们这种无应用、纯 CLI 插件"，最优原型方案：
+
+1. **原型内核 = 本地 HTML 原型 skill（配置驱动）**：自包含 HTML 原型系统（多页面 + 组件 + 导航）+ 内嵌 Tweaks + 项目级设计系统板；PRD 模板与设计系统由 `team-flow.config.json` 注入，插件保持通用；零外部软件依赖、可离线、纯 CLI 产出。不安装/不调用任何 GUI 设计产品（Claude Design / Open Design / Trae 均不安装）。
+2. **设计系统 = 借鉴 Open Design 的 DESIGN.md 概念**：由项目 `team-flow.config.json` 注入的 `design-system.md`（9 段 schema + 5 方向确定性调色板，项目资产），作为原型渲染 token 源与项目级复利真相源；原型 skill 读取它渲染，保证风格与品牌一致，插件不固化任何公司风格。
+3. **整合进 team-flow change-centric 模型（两层）**：原型**全局一份**、随 PRD 版本 git 分支演进、change 引用全局原型作 UI 契约；change 完成增量回写项目级 `design-system.md`/`architecture.md`/`api.md`，并最终进 `execution-contract.md` 驱动开发。
+4. **不内嵌 Claude Design / Trae / Open Design 的 GUI**，只借鉴其"设计系统驱动风格"思想，内核自研为 skill。
+
+**与 v0.2/v0.3 的关系：**
+- 此前 v0.3 仅计划"补原型↔PRD 闭环"（见 v0.2 摘要第 9 节）。
+- 本轮补充使 v0.3 原型章必须扩展为：**产物层级模型（全局 vs 变更）+ 配置驱动（插件通用+项目注入）+ 本地 HTML 原型 skill + 完整原型目录维护（全局一份、多页面/组件/导航、git 分支隔离版本）+ 回流 PRD + 衔接架构/API/开发 + 复利回写项目级设计系统**。
+- 这同时回应了 LT 第 12 轮两问（I/O 钉死 + 原型闭环）、第 13–14 轮（设计系统方案调研 + 迭代/维护/衔接）、第 15 轮（配置驱动 + 完整原型）与第 16 轮（全局层 vs 变更层）。
+
+---
+
+## 六、引用来源
+- Claude Design 官方指南（support.claude.com，2026-04-17 beta）
+- Open Design GitHub（nexu-io/open-design）+ FAQ（open-design.ai）
+- Trae Work Design 模式文档（docs.trae.cn）
+- team-flow 完整使用指南（腾讯云，v0.9.0）+ 源码 `sdd-overlay.mjs` / `workflow-start` SKILL.md / INSTALL.md
+- 本地 HTML 原型内核规范（lobehub skill，公开方法论内化）
+- team-flow npm.io 数据（449 Stars, v0.9.0, Deps 0）
+
+---
+
+## 七、待 LT 决策（已更新）
+1. 原型内核选型（本地 HTML 原型 skill，零外部依赖）——**已认可方向**。
+2. 配置驱动原则（插件通用 + 项目 `team-flow.config.json` 注入 PRD 模板/设计系统）——**已认可方向**。
+3. **产物层级模型（本轮确认 ✓）**：全局层（PRD 有版本、原型/代码/设计系统各一份、git 分支隔离）+ 变更层（一份 PRD 拆多 change，change = team-flow 单位）；原型全局、与 PRD 同级。LT 第 16 轮已确认"符合"。
+4. 是否同意将本方案并入 v0.3 原型章（含：层级模型 + 配置驱动 + 完整原型目录维护 + 迭代/衔接/复利回写）？
+5. 是否授权：起草 v0.3（含原型章）→ 安排专家评审 → 你决策 → 再建统一插件？

package/docs/release-checklist.md

@@ -0,0 +1,96 @@
+# Release Checklist
+
+Use this checklist before publishing a new version of `team-flow`.
+
+## Repository Shape
+
+- `README.md` is current
+- `docs/README_en.md` is current
+- `INSTALL.md` matches the supported installation story
+- `CHANGELOG.md` contains the new release entry
+- `LICENSE` is present
+- `tf version <semver>` covers all manifests (JSON) + documentation (Markdown/shell)
+- `node scripts/check-version-consistency.mjs` passes (also runs in CI)
+- Verify all nine runtime-dependent canonical skills use the exact release version, and local installer output rewrites them to its bundled `scripts/team-flow.mjs`.
+- Verify `.github/plugin/marketplace.json` and `.claude-plugin/marketplace.json` versions match
+
+## Workflow Integrity
+
+- skill descriptions still match their actual responsibilities
+- `workflow-start` still acts as the primary entry point
+- `contract-builder` still requires explicit approval before execution
+- planning artifacts and execution contract roles remain distinct
+- self-contained ownership is preserved
+
+## Templates And Docs
+
+- templates reflect the current workflow expectations
+- `docs/artifact-contract.md` matches the templates and skills
+- `docs/state-machine.md` matches the actual workflow routing model
+- examples still demonstrate the documented workflow
+
+## Example Quality
+
+For each example in `docs/examples/`:
+
+- `README.md` explains the scenario
+- `proposal.md` defines intent and scope
+- `specs/` define testable behavior
+- `design.md` defines technical shape and constraints
+- `tasks.md` defines execution order
+- `execution-contract.md` defines approved build rules
+
+## CLI And Config
+
+- `node scripts/team-flow.mjs doctor` — all checks pass
+- `node scripts/team-flow.mjs version <version> --dry-run` — reports all files in sync
+- `node scripts/check-version-consistency.mjs` — exits 0
+- `node scripts/team-flow.mjs --help` — all subcommands listed
+- `node scripts/team-flow.mjs install-workbuddy --dry-run` — finds all 9 skills and target paths
+- `npm run test:raw-mode` — packs the current source and runs a canonical runtime in an empty directory with no plugin-root variables or global `tf`.
+- Run a representative local-installer smoke test.
+- `team-flow.config.json` absence still works (backward compatible defaults)
+- `package.json` `bin` field points to correct entry script
+
+## AI Agent Marketplace Delivery
+
+- Review `README.md`, `INSTALL.md`, and `CHANGELOG.md` so their installation, upgrade, and release messages match.
+- Verify external marketplace delivery instead of treating a tag or npm publish as completion:
+
+  ```bash
+  node scripts/verify-marketplace-release.mjs \
+    --manifest-url https://raw.githubusercontent.com/hashgraph-online/awesome-codex-plugins/main/plugins/MageByte-Zero/team-flow/.codex-plugin/plugin.json \
+    --expected-version <semver>
+  ```
+
+- Use one 干净 Codex configuration directory for marketplace add, plugin add, and plugin list:
+
+  ```bash
+  CODEX_HOME="$(mktemp -d)"
+  export CODEX_HOME
+  codex plugin marketplace add hashgraph-online/awesome-codex-plugins
+  codex plugin add team-flow@awesome-codex-plugins
+  codex plugin list | rg team-flow
+  ```
+
+- If the remote marketplace version lags, submit and track the 同步 PR; wait for maintainers to merge and the generator to finish, then rerun the delivery verification and clean-Codex installation check.
+
+## Publishing Checks
+
+- Release preparation does not authorize `git tag`, `npm publish`, GitHub Release creation, marketplace publication, issue closure, or external issue comments. Perform those only after the maintainer explicitly authorizes publication.
+- there are no stray `TODO` or `TBD` markers
+- links and referenced paths are still valid
+- no local-only junk files are included
+- `.gitignore` still excludes editor and OS artifacts
+
+## Recommended Final Pass
+
+Do one last read of:
+
+- `README.md`
+- `docs/README_en.md`
+- `INSTALL.md`
+- `skills/workflow-start/SKILL.md`
+- `skills/contract-builder/SKILL.md`
+
+If those five files feel coherent together, the release is usually in good shape.