@xulthekl/team-flow 0.43.1 → 0.45.0

package/docs/usage-guide.md

@@ -0,0 +1,619 @@
+# team-flow 使用说明（研发团队版）
+
+> 版本锚点：v0.44.0（25 skills + 16 agents）· 更新日期：2026-08-17
+> 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
+> 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
+
+---
+
+## 目录
+
+1. [team-flow 是什么](#1-team-flow-是什么)
+2. [安装与验证](#2-安装与验证)
+3. [快速决策：我的任务走哪条路](#3-快速决策我的任务走哪条路)
+4. [核心概念速览](#4-核心概念速览)
+5. [场景实战](#5-场景实战)
+6. [日常高频操作菜谱](#6-日常高频操作菜谱)
+7. [tf CLI 命令速查](#7-tf-cli-命令速查)
+8. [产物目录全景](#8-产物目录全景)
+9. [FAQ 与排障](#9-faq-与排障)
+10. [最佳实践与红线](#10-最佳实践与红线)
+11. [附录：平台支持矩阵](#11-附录平台支持矩阵)
+
+---
+
+## 1. team-flow 是什么
+
+**一句话**：team-flow 把"AI 辅助写代码"变成一条**有状态机、有质量门禁、有标准产物、有人工决策点**的工程化工作流插件。
+
+它解决的核心问题：
+
+| 没有 team-flow | 有 team-flow |
+|----------------|--------------|
+| 需求聊两句就开始写代码，写到一半发现理解不一致 | 需求澄清 → 规格制品 → 执行契约，层层确认后才允许动代码 |
+| AI 说"完成了"但文件根本没创建 | 文件存在性双层防护 + 程序化测试证据，"完成"必须有机器可验证的凭证 |
+| 改完代码架构文档就过时了 | change 关闭时强制回写全局架构/测试台账/原型（复利闭环） |
+| 大需求拆成一团乱麻，改 A 坏 B | 产品级编排拆分 change + 依赖 DAG + 跨 change 冲突检测 |
+| 会话中断后上下文全丢 | 状态持久化在 `.team-flow.yaml`，新会话可无损恢复 |
+
+**规模感知**：24 个 skills（工作流能力）+ 15 个 agents（子代理角色）+ 1 个 `tf` CLI（状态机与门禁运行时）。你日常真正需要记住的入口只有 **3 个**（见第 3 节）。
+
+### 双层编排架构
+
+```
+产品级（workflow-orchestrator）——管"做什么、什么顺序"
+  模糊需求 → PRD+原型 → 实施计划 → 产品级架构 → change 拆分分发 → 全局监控
+                              │
+                              ▼ 每个 change 独立走一遍
+变更级（workflow-start）——管"怎么做"，8 态状态机
+  exploring → specifying → bridging → approved-for-build → executing → closing
+```
+
+---
+
+## 2. 安装与验证
+
+> 详细的多平台安装（Claude Code / Cursor / Codex / Gemini CLI / 其他 9+ 平台）见 [INSTALL.md](../INSTALL.md)。这里给出最常用的 Claude Code 路径。
+
+### 2.1 安装（Claude Code）
+
+```bash
+# 方式一：Marketplace（推荐）
+/plugin install team-flow
+
+# 方式二：npm 全局安装 tf CLI（skills 中的 tf 命令依赖它）
+npm install -g @xulthekl/team-flow
+```
+
+> SessionStart hook 会在每次会话启动时自动核对 tf CLI 版本与插件版本，不一致会自动 `npm install -g` 同步，**通常你不需要手动升级 CLI**。
+
+### 2.2 验证安装
+
+```bash
+tf --version        # 应输出 0.44.0
+tf doctor           # 体检：版本一致性、hooks、runtime skills、docs 完整性
+```
+
+在 Claude Code 会话中，新开一个会话应能看到注入的 team-flow 上下文提示。输入 `/team-flow:` 应能补全出 `workflow-start`、`workflow-orchestrator` 等 skill。
+
+### 2.3 平台能力差异（重要）
+
+**门禁强度随平台分层，请确认你所在平台的能力等级**：
+
+| 等级 | 平台 | 门禁能力 |
+|------|------|---------|
+| ★ 完整 | Claude Code | PreToolUse 硬拦截（非 build 态禁止写实施代码）+ 状态机门禁 + 规则注入 |
+| ☆ 中等 | Cursor | SessionStart 注入 + phase-guard 规则文件（软约束，无硬拦截） |
+| ○ 提示级 | Codex / Gemini CLI / OpenCode / Cline / Kiro / Windsurf 等 | phase-guard 规则文件常驻上下文 + CLI 门禁；依赖模型自觉 |
+
+**含义**：在非 Claude Code 平台上，状态机门禁（`tf state transition` 时的 guard 校验）依然硬生效，但"非 build 态写代码"没有运行时硬拦截——靠规则文件提示约束。
+
+---
+
+## 3. 快速决策：我的任务走哪条路
+
+这是全文最重要的一节。**先选对入口，再谈其他**。
+
+```
+你手头是什么任务？
+│
+├─ 既有项目第一次用 team-flow（还没有 docs/architecture/baseline.md）
+│     → 先跑一次 workflow-bootstrap（一次性接入，见 5.1）
+│
+├─ 产品级新需求 / 大迭代（"我想做一个 XX 功能"、多 change 的大需求）
+│     → /team-flow:workflow-orchestrator（产品级唯一入口，见 5.2）
+│
+├─ 已在一个 change 目录里（有 .team-flow.yaml），要继续 / 开始 / 恢复
+│     → /team-flow:workflow-start（变更级唯一入口，见 5.3）
+│
+├─ 紧急小 bug 修复（≤2 任务、≤2 文件、不动 schema/API）
+│     → hotfix 模式（workflow-start 会自动识别，见 5.4）
+│
+├─ 极小调整（≤4 任务的纯配置/文案类）
+│     → tweak 模式（workflow-start 自动识别，见 5.4）
+│
+└─ 独立的工具性操作
+      ├─ 纯架构设计（不走工作流）→ /team-flow:architecture-design
+      ├─ 原型绘制/迭代 → /team-flow:prototype
+      ├─ 设计系统创建 → /team-flow:design-system
+      ├─ 想法探索（不产 PRD）→ /team-flow:ce-ideate
+      ├─ 聚焦头脑风暴（已有明确主题，不要全流程）→ /team-flow:ce-brainstorm
+      ├─ E2E 测试生成/执行 → /team-flow:e2e
+      └─ 沉淀一条经验 → /team-flow:ce-compound
+```
+
+**三条反模式，不要做**：
+
+1. ❌ 普通编码任务（改个函数、查个问题）强行触发 workflow——session-start hook 注入的第一条规则就是"无 team-flow 制品且用户未明确要求时不调用工作流"。
+2. ❌ 在 change 内绕过 workflow-start 直接调用执行类 skill（spec-writer/build-executor 等）——这些 skill 是"仅路由"层级，只能由 workflow-start dispatch。
+3. ❌ 小需求硬走 full 全流程——hotfix/tweak 就是为它们设计的，仪式开销差一个数量级。
+
+---
+
+## 4. 核心概念速览
+
+### 4.1 变更级状态机（8 态）
+
+每个 change 目录（`changes/<name>/`）下有一个 `.team-flow.yaml` 状态文件，记录它走到了哪一步：
+
+```
+exploring ──→ specifying ──→ bridging ──→ approved-for-build ──→ executing ──→ closing
+ (探索需求)    (写规划制品)   (造执行契约)     (批准待开工)          (实施中)      (收尾归档)
+     │             │              │                  │                ↕
+     │             │              │                  │            debugging
+     │             │              │                  │             (调试旁路)
+     └─────────────┴──────────────┴──────────────────┴──→ abandoned（终态，放弃）
+```
+
+**快速路径**（workflow 模式限定，见 4.2）：
+- hotfix：`exploring → bridging`（跳过需求探索与规划制品）
+- tweak：`exploring → approved-for-build`（跳过探索/规划/契约）
+
+**规则**：
+- 所有状态转换必须走 `tf state transition`，它内部自动执行 guard 门禁校验，任一维度 FAIL 就不落盘。**不要手工编辑 `.team-flow.yaml` 的 state 字段**——这是红线，CLI 会拒绝非法写入，hook 也永远拦截对该文件的手工修改。
+- 回退是合法的：executing 可以退回 specifying/bridging（发现需求变了，回去改规划，而不是硬改代码）。
+- `closing` 即收尾完成态；`abandoned` 是终态，不能再转出。
+
+### 4.2 三种 workflow 模式
+
+workflow-start 在初始化时自动推断（`tf runtime infer`），你也可以在 DP-0 确认时调整：
+
+| 模式 | 判据（自动推断） | 特点 | 豁免项 |
+|------|----------------|------|--------|
+| **full** | 默认（不满足下面两个） | 全流程：需求探索→架构门→四件套→契约→执行计划→TDD→逐 wave 审查→完整收尾 | 无 |
+| **hotfix** | ≤2 任务、≤2 文件、不动 schema/API | 跳过需求探索和规划制品，最小契约仍需 DP-3 批准 | test-matrix-complete、执行计划回执 |
+| **tweak** | ≤4 任务的纯配置/文档类 | 直接进 approved-for-build，直接编辑 | 执行计划、逐 wave 审查回执、测试矩阵 |
+
+**注意**：hotfix/tweak 豁免测试矩阵时**必须显式 skip 并写明理由**（`tf state set test_matrix_skipped true` + `test_matrix_skip_reason`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
+
+### 4.3 决策点（DP）——什么时候需要你拍板
+
+工作流会在这些点停下来等你确认，**不会替你拍板**：
+
+| 决策点 | 时机 | 你要确认什么 |
+|--------|------|-------------|
+| DP-0 | workflow-start 初始化 | change 定义：名称/意图/约束（有 change-brief 则确认继承） |
+| DP-1 | 需求探索结束 | scope / non-goals / 成功标准 |
+| DP-A | 架构设计产出后 | 架构三件套是否接受（可选调整，调整回原子代理修改） |
+| DP-2 | 四件规划制品完成 | proposal/specs/design/tasks 评审批准 |
+| DP-3 | 执行契约生成后 | **硬门禁**：契约批准。没有你的批准记录，任何实施都不被允许 |
+| DP-4 | 执行模式选择 | `tf execution recommend` 展示证据后，你选 SDD/Inline/Batch Inline |
+| DP-5 | 调试受阻 | 3+ 次修复失败 → 升级为架构问题的判断确认 |
+| DP-6 | 收尾验证 | 验证结论 pass/conditional/fail |
+| DP-7 | 归档 | 确认归档（系统会核验 DP-0~DP-6 全部齐备） |
+
+产品级编排还有 G1-G5 五个团队同步点（`tf publish` 推送阶段产物），每次都会问你：推送 / 仅提交 / 暂不同步。
+
+### 4.4 核心产物清单
+
+**代码强制执行校验的产物**（hash 链覆盖，改了不重建会被门禁拦）：
+
+| 产物 | 路径 | 校验机制 |
+|------|------|---------|
+| 状态文件 | `changes/<name>/.team-flow.yaml` | state-loader 管理，禁止手工编辑 state |
+| 提案 | `changes/<name>/proposal.md` | artifacts_hash |
+| 规格 | `changes/<name>/specs/<capability>/spec.md` | artifacts_hash + Validator 引擎（SHALL/MUST + Scenario） |
+| 设计 | `changes/<name>/design.md` | artifacts_hash |
+| 任务 | `changes/<name>/tasks.md` | artifacts_hash |
+| 架构三件套 | `changes/<name>/architecture/{architecture,database,api}.md` | artifacts_hash（sql/ 不纳入，由版本控制保证） |
+| 执行契约 | `changes/<name>/execution-contract.md` | contract_hash（独立防自循环） |
+| 测试矩阵 | `changes/<name>/test-matrix.md` | test_matrix_hash（独立防自循环） |
+
+**设计层约定的产物**（无 hash 强制，但流程依赖）：`requirement/vN/prd.md`、`requirement/vN/plan.md`、`changes/<name>/change-brief.md`（产品级→变更级唯一交接物）、`docs/architecture/iterations/vN/architecture.md`（产品级架构快照）。
+
+**改了规划制品之后**：跑 `tf state rebuild <change-dir>` 重算 hash，否则后续 contract-fresh 门禁会报 stale。
+
+### 4.5 门禁（guard）——你会在哪被拦
+
+门禁在状态转换时自动执行（`tf state transition` 内部 spawn guard），也可单独预检：
+
+```bash
+tf runtime guard check <change-dir> <from-state> <to-state> [--workflow full|hotfix|tweak]
+```
+
+关键门禁与应对（完整清单见 [9. FAQ](#9-faq-与排障)）：
+
+| 门禁 | 拦在哪 | 常见原因与出路 |
+|------|--------|---------------|
+| contract-fresh | bridging→approved-for-build 等 | 规划制品改了没重建契约 → 回 contract-builder 重生成 |
+| dp-gate-passed | approved-for-build→executing | DP-3/DP-4 没记录 → 完成对应决策 |
+| test-matrix-ready | approved-for-build→executing | 契约缺 Test Matrix 段或 test-matrix.md 为空 → 回 bridging 生成，或显式 skip+理由 |
+| tests-passing | executing→closing | 只认 `tf test record` 的程序化证据 → 跑测试并记录 |
+| execution-reviews-passed | executing→closing | 有 wave 缺 pass 审查回执 → 补审查 |
+| compound-captured | executing→closing | 缺 learnings.md → `tf solutions capture` 或显式 skip |
+| arch-snapshot | executing→closing | 产品级架构快照缺失 → 补快照或物化 SKIPPED 标记 |
+
+**设计哲学**：门禁硬，但每条都有逃生舱——存量豁免（字段缺失即视为老 change）、显式 skip+理由、`--force`/`--acknowledge-*` 参数。豁免一律留痕，可审计。
+
+### 4.6 复利闭环——change 关闭时自动发生什么
+
+closing 阶段 release-archivist 会按**固定顺序**执行回写链：
+
+```
+tf arch-merge（架构增量 → docs/architecture/ 全局当前态）
+  → tf prototype-sync（UX 增量 → 全局 prototype/）
+  → tf test-merge（测试矩阵 → docs/test-ledger/ 全局台账）
+  → tf solutions promote（learnings.md 经验 → docs/solutions/）
+  → tf deisolate --merge（worktree 代码合并回主分支，Step 5c Code Landing）
+```
+
+这就是"改动不烂尾、知识不流失"的机制保障。经验沉淀后，下一个 change 的对应阶段会通过 `tf solutions inject` 自动注入 top-5 相关经验。
+
+---
+
+## 5. 场景实战
+
+### 5.1 场景一：既有项目首次接入（一次性）
+
+**适用**：项目已有代码，第一次用 team-flow。全新空项目跳过本节直接看 5.2。
+
+```
+在 Claude Code 中：
+> /team-flow:workflow-bootstrap
+```
+
+流程（B1→B5）：
+1. **B1 代码侦察**：确定性脚本 + 并行子代理分析代码库，产出 `docs/architecture/baseline.md`（核心基线）
+2. **B1.5 conventions 生成**：按技术栈（java/js/python）生成项目规范到 `.team-flow/conventions/`
+3. **B2 架构基线文档化**：ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md（≥5 模块或 ≥10 文件才执行；优先导入你已有的 DDL/物理模型/Swagger 成果物）
+4. **B3 领域词汇提取**：从代码命名提取术语到 `docs/architecture/CONCEPTS.md`
+5. **B4 目录初始化**：requirement/ 、prototype/ 、docs/ 、changes/
+6. **B5 路径判断**：问你接下来去哪（进 orchestrator / 头脑风暴 / 仅建基线等）
+
+**你要做的**：回答它的问题；有现成的架构文档/DDL/Swagger 就喂给它（比 AI 推断准确得多）。
+
+### 5.2 场景二：产品级新需求全流程
+
+**适用**："我想做一个 XX 功能"、一个新迭代、会拆出多个 change 的需求。
+
+```
+在 Claude Code 中：
+> /team-flow:workflow-orchestrator
+> 我想给订单系统加一个批量导出功能，支持异步任务和邮件通知
+```
+
+编排器会带你走 S1→S5（每步都会等你确认）：
+
+| 阶段 | 发生什么 | 你要做什么 |
+|------|---------|-----------|
+| S1 路径路由 | 读 registry.yaml，判断入口路径（全新/续版/重新计划…），注入基线+复利经验 | 确认路由（路由是建议，你可以改） |
+| S2 PRD+原型 | ce-brainstorm 产出 `requirement/vN/prd.md` 草稿 → PRD 完整性自动评审 → 原型循环（产出→自动评审≤3轮） | 回答澄清问题；审 PRD；审原型（美观/体验只有你能判）；确认后冻结 |
+| S3 计划 | ce-plan 产出 `requirement/vN/plan.md`：change 拆分 + 依赖 DAG + 技术方向 | 审计划；发现 PRD 问题会回退 S2 |
+| ARCH 产品级架构 | architecture-design product 模式 8 步设计，产出 `docs/architecture/iterations/vN/architecture.md` 快照，自动评审 PASS 才放行 | 审架构（skip 也要物化 SKIPPED 标记） |
+| S4 拆分分发 | change-split-auditor 审计拆分质量（PASS 硬前置）→ 创建 `changes/v{N}-C{n}-{name}/` 脚手架 + change-brief.md | 确认拆分结果 |
+| S5 监控 | 多 change 并行时跟踪进度、跨 change 冲突检测 | 按提示进入各 change 执行 |
+
+**然后**：对每个 change 进目录走 5.3（执行顺序按 DAG，如 C1 →（C2∥C3）→ C4）。
+
+### 5.3 场景三：在 change 内工作（最高频）
+
+**适用**：orchestrator 分发了 change、或你要继续/恢复一个已有 change。
+
+```
+cd changes/v1-C1-batch-export
+> /team-flow:workflow-start        # 或直接说"继续"/"开始实施"
+```
+
+workflow-start 会自动：
+1. 扫描 change 产物和状态（含恢复扫描：`tf handoff list` / `tf checkpoint list`）
+2. 带你过 DP-0（有 change-brief 则一次确认继承，不重复问）
+3. 判定 workflow 模式（full/hotfix/tweak）
+4. 按状态路由到正确的阶段子代理
+
+**full 模式全程**：
+
+```
+需求模糊？ → need-explorer 交互式澄清（DP-1）
+  → architecture-design 五项检查（涉及架构变更才做三件套，否则 skip；自动审查+DP-A）
+  → spec-writer 产出四件套（proposal/specs/design/tasks，逐个确认后 DP-2）
+  → contract-builder 产出契约+测试矩阵（DP-3 批准，硬门禁）
+  → tf execution recommend → 你选执行模式 → tf execution plan --confirm（DP-4）
+  → tf isolate（worktree 隔离，保护 main）
+  → build-executor 逐 wave TDD 实施（RED→GREEN→REFACTOR）
+  → 每个 wave 完成 → code-reviewer 审查 → findings 修复 → re-review
+  → 全部 wave pass → release-archivist 收尾验证（DP-6/DP-7）→ 回写链 → closing
+```
+
+**关键纪律**（工作流会引导，你知道原理更好配合）：
+- **契约是权威**：实施以 execution-contract.md 为准，不是聊天记录。发现契约错了→回退 bridging，不是硬改代码。
+- **TDD 铁律**：没有失败的测试就不写生产代码。
+- **受阻别硬修**：3 次修复失败会自动升级 bug-investigator 做根因调查；它只出调查报告不实施修复，修之前先确认根因。
+- **完成要证据**：release-archivist 的 Iron Law 是"验证先于完成"——测试要新鲜跑过、`tf test record` 记录、0 个测试不算 PASS。
+
+### 5.4 场景四：hotfix 与 tweak（快速路径）
+
+**hotfix**（紧急 bug，≤2 任务 ≤2 文件不动 schema/API）：
+```
+workflow-start 自动识别为 hotfix
+→ exploring 直接跳 bridging（跳过需求探索和四件套）
+→ 最小契约仍要 DP-3 批准 → 实施 → tests-passing 仍要程序化证据 → closing
+```
+
+**tweak**（纯配置/文案小调整，≤4 任务）：
+```
+workflow-start 自动识别为 tweak
+→ exploring 直接跳 approved-for-build → 直接编辑 → 收尾（豁免执行计划与逐 wave 审查）
+```
+
+两者都：**架构五项检查不豁免**（通常结果是 skip，但检查会跑）；测试矩阵豁免必须显式 skip+理由。
+
+### 5.5 场景五：会话中断了怎么办
+
+状态都在磁盘上，新会话无损恢复：
+
+```
+cd changes/<name>
+> /team-flow:workflow-start        # 它会读 .team-flow.yaml 自动判断从哪继续
+```
+
+- 长对话感觉 AI"变笨"了（上下文腐化）→ 说"交接"触发 session-handoff，压缩交接文档到 `.team-flow/handoffs/`，新会话读它继续
+- 任务级中断 → `tf checkpoint save/list/show` 管理恢复点
+- 产品级状态（orchestrator.yaml/registry.yaml）自动恢复，无需操作
+
+---
+
+## 6. 日常高频操作菜谱
+
+| 我想… | 怎么做 |
+|-------|--------|
+| 看所有 change 和状态 | `tf list` |
+| 看当前 change 状态字段 | `tf state get <change-dir> <field>`（或全量读 .team-flow.yaml） |
+| 校验 change 制品格式 | `tf validate <change-dir>` |
+| 体检环境 | `tf doctor` |
+| 改了规划制品后刷新 hash | `tf state rebuild <change-dir>` |
+| 转换状态 | `tf state transition <change-dir> <to-state>`（门禁自动执行） |
+| 预检门禁 | `tf runtime guard check <change-dir> <from> <to>` |
+| 记录测试结果（closing 必需） | `tf test record <change-dir> --from <runner输出文件>`（支持 maven-surefire/jest/pytest，可 auto 识别） |
+| 隔离工作区 | `tf isolate <change-dir>`（建 worktree；失败无 --force 会 STOP 要求人工处理） |
+| 收尾合并代码 | `tf deisolate <change-dir> --merge`（dirty 会阻断；merge commit 不 rebase） |
+| 沉淀一条经验 | `tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "..."` |
+| 生成决策点审计报告 | `tf audit <change-dir>` |
+| 阶段产物推送团队 | `tf publish --prd / --arch / --changes <dir> / --all` |
+| 记录工作流问题 | `/team-flow:workflow-feedback`（skill 触发不准、SOP 不顺、产物质量差都记这里，它是插件演进的输入） |
+| 原型版本分支 | `tf prototype branch <prd-vN>` / `tf prototype deisolate <prd-vN> --merge` |
+
+---
+
+## 7. tf CLI 命令速查
+
+### 状态与校验
+```bash
+tf list                                # 列出所有 change 及状态
+tf validate <dir>                      # Validator 引擎校验制品（SHALL/MUST、Scenario、跨段冲突等）
+tf doctor                              # 环境体检
+tf state init <dir>                    # 创建 change 状态（打戳 schema_version，计算三 hash）
+tf state check <dir>                   # artifacts_hash 一致性检查
+tf state get <dir> <field>             # 读字段
+tf state set <dir> <field> <value>     # 写白名单字段（dp_N_*、arch_design_*、skip 类等）
+tf state rebuild <dir>                 # 重算三 hash（改完规划制品必跑）
+tf state transition <dir> <to-state>   # 状态转换（自动执行 guard 门禁）
+tf audit <dir>                         # 生成 decision-point-audit.md
+```
+
+**不可手工 set 的字段**（CLI 有专用报错引导）：`state`（用 transition）、`test_result`（用 `tf test record`）、`schema_version`（仅 init 打戳的存量豁免键）。
+
+### 执行计划
+```bash
+tf execution recommend <dir>           # 证据驱动的执行模式推荐（DP-4 前置）
+tf execution plan <dir> --mode <m> --confirm --reason "..." --wave ...
+tf execution show <dir> [--json]       # 查看当前计划（current:true 才能开工）
+tf execution revise <dir> --mode sdd   # 修订计划（只能升级/重规划，不能降级）
+tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
+tf execution refresh-hash <dir>        # 不 bump revision 刷新 plan 内 hash
+```
+
+### 测试与收尾
+```bash
+tf test record <dir> --from <output> [--runner auto|maven-surefire|jest|pytest]
+tf test-merge <dir> [--dry-run]        # 测试矩阵 → docs/test-ledger/
+tf test-matrix-export <in.json> <out.md>   # glaf4 矩阵格式桥接
+tf sync <dir>                          # delta specs 合并进主 spec 基
+tf arch-merge <dir> [--dry-run]        # 架构增量 → docs/architecture/
+tf prototype-sync <dir>                # UX 增量 → 全局 prototype/
+tf publish --prd|--arch|--changes <dir>|--all [--push] [--dry-run]
+```
+
+### 隔离与恢复
+```bash
+tf isolate <change-dir> [--force]      # worktree 隔离（build 前置）
+tf deisolate <change-dir> [--merge] [--clean] [--force] [--json]
+tf checkpoint save|list|show           # 任务级恢复点
+tf handoff create|list|finish|resolve  # prototype/research/experiment 交接单
+tf prototype branch <prd-vN> | tf prototype deisolate <prd-vN> [--merge]
+```
+
+### 复利与架构
+```bash
+tf solutions capture|index-gen|inject|promote
+tf arch init [--mode reconstruction|design]   # 项目架构基线打戳（存量豁免键）
+tf arch show
+tf inject <dir> [--platforms claude,cursor,...]   # 按当前状态生成 phase-guard 注入各平台
+tf config [--resolve-model <profile>]          # mechanical/standard/strong/review 四档
+tf runtime check-update | infer <dir> | guard ... | config ... | asset read <path>
+```
+
+---
+
+## 8. 产物目录全景
+
+```
+项目根/
+├── .team-flow/                        # 产品级编排状态（只有编排状态，不放 change）
+│   ├── registry.yaml                  # 需求注册表
+│   ├── requirements/<req-id>/orchestrator.yaml   # 每需求的编排状态（change_dag/replan_log）
+│   ├── handoffs/                      # session-handoff 交接文档（gitignore）
+│   ├── feedback/                      # workflow-feedback 问题记录
+│   ├── conventions/                   # 项目规范（bootstrap 生成，按技术栈）
+│   ├── design-system/                 # 设计系统（base.md + b-end/c-end 变体 + preview.html）
+│   ├── arch-state.json                # 架构基线打戳（tf arch init，存量豁免键）
+│   └── team-flow.config.json          # 项目配置（v0.26+ 迁入 .team-flow/ 规划中）
+│
+├── requirement/vN/                    # 产品级需求制品（vN = PRD 迭代版本）
+│   ├── prd.md                         # PRD（frontmatter 冻结态是单一真相源）
+│   ├── plan.md                        # 实施计划（change 拆分+DAG+技术方向，无接口清单）
+│   ├── business-analysis.md           # 业务场景/流程分析
+│   ├── prd-completeness-review.md     # PRD 完整性自动评审报告
+│   ├── prototype-auto-review.md       # 原型自动评审报告
+│   └── change-split-audit.md          # 拆分质量审计报告
+│
+├── prototype/                         # 全局唯一原型（独立 git 仓库，按 PRD 版本分支）
+│   ├── index.html / pages/ / components/ / assets/
+│   ├── design-tokens.css / design-system.md / flow.md
+│
+├── docs/
+│   ├── architecture/                  # L1 全局架构当前态（arch-merge 回写，权威）
+│   │   ├── ARCHITECTURE.md            # marker 区 = 所有已合并 change 增量的投影
+│   │   ├── DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md
+│   │   ├── CONCEPTS.md                # 领域词汇表
+│   │   ├── baseline.md                # bootstrap 产出的项目基线画像
+│   │   ├── changelog/                 # DDL/migration 归档
+│   │   └── iterations/vN/architecture.md   # L3 迭代快照（预测态，收尾标 archived）
+│   ├── solutions/                     # 复利经验库（INDEX.md ≤150 条 + 分阶段目录）
+│   └── test-ledger/                   # 全局测试台账（test-merge 回写）
+│
+├── specs/<capability>/spec.md         # 主 spec 基（spec-merger 合并 delta 的目标）
+│
+├── changes/v{N}-C{n}-{kebab-name}/    # ★ 变更目录（状态机主场）
+│   ├── .team-flow.yaml                # 状态文件（禁手工编辑 state）
+│   ├── change-brief.md                # 产品级→变更级交接物（有则 DP-0 继承）
+│   ├── proposal.md / design.md / tasks.md      # 规划制品（hash 覆盖）
+│   ├── specs/<capability>/spec.md     # delta specs（ADDED/MODIFIED/REMOVED/RENAMED）
+│   ├── architecture/                  # 架构三件套 + sql/（arch_design_decision=required 时）
+│   ├── execution-contract.md          # 执行契约（contract_hash）
+│   ├── test-matrix.md                 # 测试矩阵（12 列，test_matrix_hash）
+│   ├── learnings.md                   # 复利经验（closing 门禁要求或显式 skip）
+│   ├── code-review.md / *-review.md   # 各审查报告
+│   └── .superpowers/                  # 运行时 overlay
+│       ├── sdd/                       # execution-plan.json / reviews/ / checkpoints / progress.md
+│       └── test-evidence/             # tf test record 的 runner 原始输出证据
+│
+├── .worktrees/                        # worktree 隔离区（tf isolate 创建，gitignore）
+│   ├── <change>/<repo>/               # 变更隔离（多仓库工作区）
+│   └── prd-vN/prototype/              # 原型版本隔离
+│
+└── STRATEGY.md                        # 产品战略锚点（可选，ce-strategy 产出）
+```
+
+---
+
+## 9. FAQ 与排障
+
+### Q1：门禁 BLOCK 了我，怎么看原因、怎么解？
+
+转换失败时 CLI 会逐条打印 `[dimension] failure` 及具体原因。也可预检：
+
+```bash
+tf runtime guard check <change-dir> <from> <to> --json
+```
+
+**高频阻断速查**：
+
+| 报错特征 | 原因 | 解法 |
+|---------|------|------|
+| `execution-contract.md is stale: artifacts hash mismatch` | 规划制品改了，契约没重建 | 回 bridging 重跑 contract-builder，或 `tf state rebuild` 后重新生成 |
+| `no programmatic test evidence recorded` | 没有 `tf test record` 记录 | 跑测试 → `tf test record <dir> --from <输出文件>` |
+| `recorded-by` 校验失败 | 手工写了 test_result | 手工通道已关闭，必须走 tf test record；或显式 skip+理由 |
+| `test matrix skip reason missing` | skip 了矩阵没写理由 | `tf state set test_matrix_skip_reason "<理由>"` |
+| `dp_3_result` / `dp_4_result` 缺失 | DP 决策未记录 | 回到对应决策点完成确认 |
+| `plan revision <N>` 不匹配 | DP-4 记录没引用当前计划版本 | 重新 `tf execution plan`（或 revise） |
+| `base == head` review 被拒 | 空 diff 审查 | 用真实的 wave 起止 commit |
+| `Unknown transition` | 非法状态转换对 | 状态机闭合，按合法路径走（如需放弃用 →abandoned） |
+| hook block："implementation editing is limited to build states" | 非 build 态在 change 目录外写实施代码 | 推进工作流到 approved-for-build/executing/debugging；change 目录内制品写永远放行 |
+
+### Q2：存量 change / 老项目会被新门禁卡死吗？
+
+不会。豁免键设计：
+- `schema_version` 缺失 = 存量 change → 测试门禁接受自述 PASS（新 change 由 `tf state init` 打戳，走严格程序化证据）
+- `.team-flow/arch-state.json` 的 `arch_baseline` 缺失 = 存量项目 → arch 门禁 WARN 不 FAIL（跑一次 `tf arch init` 打戳即可转正）
+
+### Q3：我真的要跳过某个门禁怎么办？
+
+每条门禁都有合法逃生舱，但**必须显式+留痕**：
+- 测试矩阵：`test_matrix_skipped=true` + `test_matrix_skip_reason`
+- 复利：`tf state set compound_skipped true`
+- 架构 skip：物化 `iterations/vN/SKIPPED` 标记 + 理由
+- 隔离失败：`--force`（会警告）
+- 偏离执行推荐：`--acknowledge-recommendation`
+
+不要用手工编辑 `.team-flow.yaml` 的方式绕——writeState 会拒绝非法值，hook 永远拦截该文件。
+
+### Q4：AI 报告说完成了，我怎么信它？
+
+三道凭证，缺一即质疑：
+1. **测试凭证**：`tf test record` 解析真实 runner 输出（total/passed/failed 来自 maven/jest/pytest 实际执行数，不是 AI 自述）；证据原文在 `.superpowers/test-evidence/`
+2. **审查凭证**：每个 wave 的 review receipt（`tf execution show` 可见，含 git base/head 校验）
+3. **决策点审计**：`tf audit <change-dir>` 生成 DP-0~DP-7 全程审计
+
+### Q5：需求变了怎么办？
+
+**回退，不要硬改**：executing 可以合法回退到 specifying（改规划）或 bridging（改契约）。phase-guard 会提示这个纪律。规划制品改了记得 `tf state rebuild`，契约要重新过 DP-3。
+
+### Q6：多个 change 并行会冲突吗？
+
+- 执行隔离：每个 change 独立 worktree（`tf isolate`），互不干扰
+- 语义冲突：closing 前 cross-change-consistency-checker 检测共享聚合/API 签名/架构锚点漂移；`tf sync` 前 Validator 的 detectSyncConflicts 检测同一 requirement 被多 change 修改
+- 产品级快照是聚合所有权的唯一事实源，变更级只引用不重定义
+
+### Q7：Bash 写的文件 hook 管不住？
+
+是的，这是已知边界（PreToolUse 只拦 Write/Edit/MultiEdit）。设计上刻意如此（避免误伤），门禁体系在状态转换层兜底。团队约定：**不要指导 AI 用 Bash 写实施代码绕状态门**。
+
+### Q8：怎么反馈问题？
+
+`/team-flow:workflow-feedback`——skill 触发不准、SOP 不顺、产物质量差、交互难受，都记录到 `.team-flow/feedback/`。这个插件的每个近期版本都是被这些反馈驱动演进的，你的反馈会真实进入 roadmap。
+
+---
+
+## 10. 最佳实践与红线
+
+### 最佳实践
+
+1. **选对模式比走完流程重要**：小需求用 hotfix/tweak，别硬撑 full。
+2. **把已有的成果物喂给系统**：bootstrap/ARCH 阶段，现成的 DDL、物理模型、Swagger 比 AI 推断可靠十倍。
+3. **决策点认真审**：DP-2/DP-3 是性价比最高的质量关口——这里花 10 分钟，省后面 2 小时返工。
+4. **受阻先查根因**：bug-investigator 的"3 次修复失败 = 架构问题信号"是真的，别无限打补丁。
+5. **及时沉淀经验**：解决了一个坑就 `tf solutions capture`，下个 change 会自动注入。
+6. **会话变长就交接**：感觉 AI 响应质量下降，session-handoff 比硬撑便宜。
+7. **改完规划制品就 rebuild**：`tf state rebuild` 一个命令，省一堆 stale 报错。
+
+### 红线（系统会拦，但你也该知道）
+
+1. ⛔ 手工编辑 `.team-flow.yaml` 的 state 字段（永远被拦）
+2. ⛔ 非 build 态写实施代码（Claude Code 硬拦；其他平台靠自觉+转换门禁兜底）
+3. ⛔ 绕过 DP-3 开始实施（无契约批准 = 非法开工）
+4. ⛔ 手工伪造 test_result（通道已关闭，只认 tf test record）
+5. ⛔ 主代理直接改子代理的产物（违反 Artifact Ownership，修改要经 SendMessage 回原子代理）
+6. ⛔ 用 rebase 合并收尾代码（规范是 merge commit，保真实历史可回退）
+7. ⛔ 空 diff 记 review receipt（base==head 被 CLI 拒绝）
+
+---
+
+## 11. 附录：平台支持矩阵
+
+| 平台 | 安装方式 | SessionStart 注入 | 硬拦截（PreToolUse） | 门禁生效形式 |
+|------|---------|------------------|---------------------|-------------|
+| Claude Code | Marketplace / plugin.json | ✅ | ✅ | hook + guard + 规则 |
+| Cursor | 一键脚本 | ✅ | ❌ | SessionStart + phase-guard.mdc |
+| Codex CLI/App | 插件目录 / release tag | ❌ | ❌ | phase-guard 规则 |
+| Gemini CLI | gemini-extension.json | ❌ | ❌ | GEMINI.md marker 注入 |
+| OpenCode | JS plugin | ❌ | ❌ | bootstrap 注入 |
+| Cline/Kiro/Windsurf/Qwen/Amazon-Q/Roo/Continue/Pi/Qoder | `tf install-<平台>` | ❌ | ❌ | phase-guard 规则文件 |
+
+> 所有平台的 skills/agents/CLI 能力一致，差异只在守卫强度。非 Claude Code 平台建议：关键状态转换后手动 `tf inject <change-dir>` 刷新 phase-guard 规则文件。
+
+---
+
+## 相关文档索引
+
+| 想了解 | 看哪里 |
+|--------|--------|
+| 多平台安装/升级/卸载细节 | [INSTALL.md](../INSTALL.md) |
+| 状态机转换矩阵细节 | [state-machine.md](state-machine.md) |
+| 决策点协议细节 | [decision-points.md](decision-points.md) |
+| 制品格式契约 | [artifact-contract.md](artifact-contract.md) |
+| 平台能力矩阵 | [platform-matrix.md](platform-matrix.md) |
+| 发布检查清单 | [release-checklist.md](release-checklist.md) |
+
+---
+
+*本文档基于 v0.44.0 源码全量分析产出。发现与实际行为不符，请 `/team-flow:workflow-feedback` 反馈——这正是本插件的演进方式。*

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
-  "version": "0.43.1",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 25 skills, one install.",
+  "version": "0.45.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.43.1: auto-sync CLI version with plugin version
+# v0.45.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.43.1"
+PLUGIN_VERSION="0.45.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.43.1.
+Current version: v0.45.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ