@xulthekl/team-flow 0.22.4 → 0.24.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.22.4 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.24.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 23 skills + 8 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.22.4",
+      "version": "0.24.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 8 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.22.4"
+    "version": "0.24.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 23 skills + 8 agents, one install.",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.22.4"
+    "version": "0.24.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.22.4",
+      "version": "0.24.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -13,8 +13,9 @@
 ### 身份与依赖关系
 
 - **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 23 个 skills + 8 个 agents + hooks + templates
-- **team-flow**（npm 底座包）：team-flow 的 CLI 工具层（`package.json` name = `team-flow`，bin = `tf`），提供状态机、校验、复利 CLI 等运行时能力
-- 关系：team-flow 插件 **包含** team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `npx --yes --package @xulthekl/team-flow@x.y.z tf ...` 调用的是已发布的 npm 底座包，版本号必须与当前 `package.json` version 一致
+- **@xulthekl/team-flow**（npm 底座包）：team-flow 的 CLI 工具层（`package.json` name = `@xulthekl/team-flow`，bin = `tf` / `team-flow`），提供状态机、校验、复利 CLI 等运行时能力
+- 关系：team-flow 插件 **包含** @xulthekl/team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `npx --yes --package @xulthekl/team-flow@x.y.z tf ...` 调用的是已发布的 npm 底座包，版本号必须与当前 `package.json` version 一致
+- 历史身份（已废弃）：`spec-superflow`（npm 包名，0.11.0 后停止发布）/ `ssf`（CLI 前缀）/ `.spec-superflow.yaml`（状态文件）—— 详见设计增强方案 v0.9 §27
 
 ## Commands
 

package/CHANGELOG.md

@@ -6,6 +6,81 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-07-28
+
+### Fixed（复利工程强制化补强，5 项）
+
+#### P0: Hook 旧名修复
+- **hooks/pre-tool-use-guard**: 修复 `.spec-superflow.yaml` → `.team-flow.yaml` 的硬编码旧名（5 处），恢复状态机编辑守卫
+- **hooks/session-start**: 修复 `spec-superflow` → `team-flow` 的硬编码旧名（3 处），恢复会话启动提示
+
+#### P1: 复利维度 guard
+- **guard/checks/compound-captured.mjs**: 新增复利捕获检查维度（learnings.md 存在性或显式 compound_skipped）
+- **guard/guard.mjs**: 将 `compound-captured` 维度挂到 `executing:closing` 转换（full 和 hotfix workflow）
+- **state-loader.mjs**: BUILTIN_DEFAULTS 新增 `compound_skipped` 字段
+- **cmd-state.mjs**: SETTABLE_FIELDS 新增 `compound_skipped` 字段，支持 `tf state set` 写入
+
+#### P1: Bootstrap DDL 提取
+- **workflow-bootstrap/scripts/recon-probe.sh**: 新增 DDL 提取能力（策略优先级：SQL 文件 > Java Entity 注解 > 占位兜底）
+  - 策略 1: 扫描 `db/migration/` 等目录的 `.sql` 文件，提取 CREATE TABLE 语句
+  - 策略 2: 扫描 `@Entity`/`@Table` 注解的 Java 类，提取表名和字段定义
+  - 策略 3: 无 DDL 源时生成占位文件，提示手动补充
+  - 新增 `--ddl-out` 参数，支持独立输出 DDL 文件
+  - JSON 输出新增 `ddl_extraction` 字段（source/table_count/tables/ddl_statements）
+
+#### P1: Bootstrap 模板引用
+- **workflow-bootstrap/SKILL.md**: B2 阶段新增 Step 0（模板初始化），从 `architecture-design/templates/` 复制 5 个模板到 `docs/architecture/`
+- **workflow-bootstrap/references/b1-reconnaissance.md**: 更新 B1.1a 章节，标注 DDL 提取已实现（v0.24.0），补充 CLI 用法和 JSON 输出字段说明
+
+#### P2: solutions 脚本测试
+- **tests/lib/solutions-capture.test.mjs**: 新增 6 个测试用例（文件创建、INDEX 追加、中文 slugify、默认 phase、无效 phase 拒绝）
+- **tests/lib/solutions-inject.test.mjs**: 新增 8 个测试用例（空索引、phase 过滤、cross-phase 包含、domain 匹配、severity 排序、top-5 截断）
+- **tests/lib/solutions-promote.test.mjs**: 新增 8 个测试用例（无 learnings、高/中/低 severity 晋升、insight 类型跳过、重复检测、多条晋升、INDEX 追加）
+- **tests/lib/solutions-index-gen.test.mjs**: 新增 7 个测试用例（全量重建、severity 排序、date 排序、7 phase 扫描、非 .md 跳过、150 条截断、空目录处理）
+- **scripts/lib/solutions-promote.mjs**: CLI 守卫增加 `NODE_ENV !== 'test'` 条件，避免 import 时触发 process.exit
+
+#### 测试修复
+- **tests/lib/guard.test.mjs**: `recordPassingClosingPrerequisites()` 新增 learnings.md 创建，满足 compound-captured 维度
+- **tests/lib/guard-specs-merged.test.mjs**: `makeChangeDir()` 新增 learnings.md 创建
+- **tests/lib/guard-tests-passing.test.mjs**: `makeChangeDir()` 新增 learnings.md 创建
+
+### Verified
+
+- check-version-consistency: ✅ PASS（全部 0.24.0，自动修复 6 处版本号）
+- npm test: ✅ 457/457 通过（428 既有 + 29 新增）
+
+### Statistics
+
+- 新增代码: ~350 行（guard 检查器 + DDL 提取 + 测试用例）
+- 修改文件: 52 个
+- 测试覆盖: solutions 四个脚本从 0% → 100%（29 个测试用例）
+- 复利强制化: executing:closing 转换新增 compound-captured 维度（learnings.md 或显式 skip）
+
+## [0.22.5] - 2026-07-28
+
+### Fixed（制品链评审与修复，设计 v0.9 §28）
+
+- **state-loader.mjs**：BUILTIN_DEFAULTS 新增 `arch_design_decision` / `arch_design_reason` / `arch_design_timestamp` / `arch_design_artifacts` 四个字段，writeState() 序列化逻辑同步更新
+- **cmd-state.mjs**：SETTABLE_FIELDS 新增上述四个 arch_design_* 字段，支持 `tf state set` 写入
+- **architecture-design/SKILL.md**：移除错误的"状态写入"章节（职责边界应为"判断+产出"，非"判断+写入"）
+- **workflow-start/SKILL.md**：新增 "State Writes" 章节，明确声明 arch_design_* 的 reasonableness check + 状态写入权责
+- **ce-brainstorm/SKILL.md**：新增 "Optional Inputs" 章节，声明消费 `docs/ideation/*.md`（source: ce-ideate），修复 ideation 制品链断裂
+- **workflow-start/SKILL.md Fast-Path Routing**：新增 DP-0 处理说明（hotfix/tweak 隐式跳过 DP-0，dp_0_confirmed 保持 null）
+
+### Added（模板补全）
+
+- **templates/change-brief.md**：新增变更简报模板，基于 s4-split-validate.md 的 brief_schema（5 个 frontmatter 字段 + 6 个 body sections）
+- **templates/architecture.md**：新增架构设计模板（4A+DDD 增量设计：As-Is 基线冻结 + To-Be 增量 + 变更分叉级联 + 跨域一致性 + 演进日志）
+- **templates/database.md**：新增数据库设计模板（CQRS 增量：写模型/读模型/Schema 变更/实体关系/数据迁移脚本 + 演进日志）
+- **templates/api.md**：新增 API 设计模板（Command/Read/Query 分流 + 端点详细设计 + 跨域一致性检查 + 演进日志）
+
+### Verified
+
+- check-version-consistency：✅ PASS（全部 0.22.5）
+- npm test：✅ 421/421 通过
+
+---
+
 ## [0.22.4] - 2026-07-27
 
 ### Changed（npm 包名 scope 化，发布至 npm）
@@ -633,3 +708,31 @@ The format loosely follows Keep a Changelog.
 - First release targets Claude Code and Trae style local skill loading
 - Runtime ownership remains inside `team-flow`
 - OpenSpec and Superpowers are reference influences, not runtime dependencies
+
+## v0.23.0 (2026-07-28) — 架构制品体系可执行化 + 上下文治理
+
+### 新增
+- **`tf arch-merge` CLI 命令**：8 步完整合并脚本，将 change 级架构增量（architecture/*.md + sql/）合并回全局 docs/architecture/（ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md）
+- **架构门控（guard.mjs）**：`exploring:specifying` 转换新增 `arch-design` 维度；`arch_design_decision=required` 时必须存在 architecture/*.md，`skipped` 时 reason 非空（advisory）
+- **architecture/*.md 纳入 artifacts_hash**：修改 hash.mjs，三件套变更触发 hash 失效
+- **5 个架构模板**：architecture.md / database.md / api.md / index.md / physical-model.md + change-brief.md
+- **架构上下文加载协议**：INDEX.md 摘要索引 + 物理模型按业务域分段 + 按需加载三层策略，单次执行预算 ~2K tokens
+
+### 修改
+- **database.md 模板**：DDL 从内嵌代码块改为引用 `sql/ddl/` 和 `sql/migration/` 目录
+- **api.md 定位调整**：聚焦 Command/Read/Query 分流归属+端点概要（架构路由表），不重复 Swagger 管理的精确 Schema；frontmatter 须声明 `api_contract_manager: swagger`
+- **Bootstrap B2 新增成果物导入环节**：优先用户提供既有 SQL/物理模型/API 文档，兜底确定性提取（Entity 类解析 / SHOW CREATE TABLE）；新产出 PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md；CONCEPTS.md 路径迁移至 docs/architecture/
+- **architecture-design SKILL.md**：产出目录新增 sql/ 子目录；api.md 架构路由表定位；新增上下文加载协议段；新增 arch-merge 引用
+
+### 下游消费同步
+- **spec-writer**：输入源增加 architecture/sql/ 路径 + api.md 路由表说明
+- **build-executor**：输入源增加 architecture/sql/ddl/*.sql + sql/migration/*.sql
+- **code-reviewer**：新增 Architecture Cross-Domain Consistency 评审维度
+- **release-archivist**：closing 步骤新增 `tf arch-merge`（先于 prototype-sync）
+
+### 设计文档
+- 新增 `docs/architecture-api-db-design-enhancement-v0.10.md`（§28-§31 完整设计决策记录）
+
+### 参考
+- v0.10 设计文档：`docs/architecture-api-db-design-enhancement-v0.10.md`
+- 设计增强方案权威版本：v0.10（承袭 v0.9 全部内容）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.22.4 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.24.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/HANDOFF.md

@@ -2,47 +2,63 @@
 
 > 本文件用于把「team-flow 统一插件」的当前状态、设计决策、安装方式、剩余待办一次性交接清楚，
 > 以便后续在 **Claude Code** 中直接打开 `team-flow/` 目录继续开发，无需回看历史对话。
-> 最后更新：2026-07-20
+> 最后更新：2026-07-28
 
 ---
 
 ## 0. 这是什么 / 目标
 
-`team-flow` 是一个**统一插件**，把四套能力合并进一个 `plugin.json`，一次安装即加载全部 17 个 skill，覆盖
-「需求探索 → PRD → 架构增量 → 本地原型 → spec 驱动实现 → 全局复利回写」的完整工作流。
+`team-flow` 是一个**统一插件**，把九套能力合并进一个 `plugin.json`，一次安装即加载全部 23 个 skill + 8 个 agent，覆盖
+「需求探索 → PRD → 架构增量 → 本地原型 → spec 驱动实现 → 复利回写 → e2e 测试 → session 交接 → 反馈闭环」的完整工作流。
 
 | 来源 | 并入范围 | skill 数 |
 |---|---|---|
 | **team-flow**（底座，v0.10.0） | 全部 9 个 spec 驱动开发 skill | 9 |
-| **compound-engineering 核心子集（C 方案）** | ce-brainstorm / ce-plan / ce-compound / ce-strategy / ce-ideate / ce-proof | 6 |
+| **compound-engineering 核心子集** | ce-brainstorm / ce-plan / ce-compound / ce-strategy / ce-ideate / ce-proof | 6 |
 | **architecture-design**（4A+DDD 增量设计） | 整个 skill | 1 |
-| **prototype**（本地 HTML 原型，新建） | 整个 skill（含脚手架） | 1 |
-| **合计** | | **17** |
+| **prototype**（本地 HTML 原型） | 整个 skill | 1 |
+| **design-system**（设计系统管理） | 整个 skill | 1 |
+| **workflow-orchestrator**（产品级编排） | 整个 skill | 1 |
+| **workflow-bootstrap**（项目接入） | 整个 skill | 1 |
+| **e2e**（端到端测试） | 整个 skill | 1 |
+| **session-handoff**（session 交接） | 整个 skill | 1 |
+| **workflow-feedback**（反馈闭环） | 整个 skill | 1 |
+| **合计** | | **23 skills + 8 agents** |
 
 - 零运行时外部依赖（team-flow 底座自包含）。
 - prototype 额外**零外部依赖、可离线**（自包含 HTML + 页面内 Tweaks 控件，无 CDN）。
 - 插件保持通用：所有风格由项目 `design-system.md` / `prd.template` 注入，不固化任何公司/产品风格。
-- 支持 9 安装面：Claude Code、Cursor、OpenAI Codex CLI/App、GitHub Copilot CLI、Gemini CLI、OpenCode、WorkBuddy、Trae、ima-copilot。
+- 支持 11 安装面：Claude Code、Cursor、OpenAI Codex CLI/App、GitHub Copilot CLI、Gemini CLI、OpenCode、WorkBuddy、Trae、ima-copilot、ZCode、RooCode、Amazon Q、Windsurf、Continue、Kiro、Pi、Qwen、Qoder。
 
 ---
 
-## 1. 当前状态
+## 1. 当前状态（v0.22.4，2026-07-28）
 
 ### ✅ 已完成
-- [x] 以 `team-flow` 工程为底座复制出 `team-flow/`（目录、`.claude-plugin/`、scripts、dist、hooks 等齐全）。
-- [x] **统一插件名 `team-flow`**：所有插件清单（顶层 `plugin.json`、`.claude-plugin/`、`marketplace.json`、`.cursor-plugin/`、`gemini-extension.json`、`.github/plugin/marketplace.json`、`.agents/plugins/marketplace.json`）的 `name` 已改为 `team-flow`，作者改为 `LT`，homepage/repository 指向 `https://github.com/LT/team-flow`。
-- [x] **compound 核心子集（C 方案 6 个）** 已复制到 `team-flow/skills/`，architecture-design 一并复制（排除 ima 嵌套冗余副本）。
-- [x] **新建 `prototype` skill**：`skills/prototype/SKILL.md` + `references/prototype-scaffold/`（6 文件：index.html / design-system.md / flow.md / assets/design-tokens.css / components/button.html / pages/index.html）。
-- [x] **统一 `AGENTS.md`**：合并 team-flow 8 态机 + compound 核心 6 skill + architecture-design（4A/DDD）+ prototype 四套机制、全局产物结构、SOP、配置注入、关键约束。
-- [x] `README.md` / `INSTALL.md` 已改写为 team-flow 顶层说明。
-- [x] **版本一致性检查通过**：`node scripts/check-version-consistency.mjs` → ✅ all files at 0.10.0。
-- [x] 两份权威设计文档已归入 `docs/`（`architecture-api-db-design-enhancement-v0.3.md`、`prototype-design-research.md`）。
+- [x] **品牌重命名 + 身份统一全部完成**（P1-6 三阶段全部收口）：
+  - 第一阶段 v0.15.0：产品级状态文件 `.team-flow/` 化
+  - 第二阶段 v0.22.3：`spec-superflow → team-flow` 全量迁移（721+ 处）
+    - 包名 `spec-superflow → team-flow`
+    - CLI `ssf → tf`
+    - 状态文件 `.spec-superflow.yaml → .team-flow.yaml`
+    - 配置文件 `spec-superflow.config.json → team-flow.config.json`
+    - 脚本 `spec-superflow.mjs → team-flow.mjs`
+  - 第三阶段 v0.22.4：npm 包 scope 化（解决 publish 权限冲突）
+    - 包名 `team-flow → @xulthekl/team-flow`
+    - author `MageByte → xulthekl`
+    - 所有 npx 引用 179 处更新为 `@xulthekl/team-flow@`
+- [x] **npm 发布**：`@xulthekl/team-flow@0.22.4` 已上线公共 registry
+- [x] **统一插件名 `team-flow`**：所有插件清单（`plugin.json`、`.claude-plugin/`、`marketplace.json` 等 9 个安装面）已统一
+- [x] **compound 核心子集（C 方案 6 个）** + architecture-design + prototype + design-system + workflow-* 等已并入
+- [x] **统一 `AGENTS.md`**：合并 9 套能力、全局产物结构、SOP、配置注入、关键约束
+- [x] **版本一致性检查通过**：`check-version-consistency.mjs` ✅ all files at 0.22.4
+- [x] **测试全过**：`npm test` ✅ 421/421
+- [x] **权威设计文档**：`docs/architecture-api-db-design-enhancement-v0.9.md`（当前 v0.9，含 §27 身份统一章节）
 
 ### ⏳ 待办（详见 §6）
-- 品牌重命名残留（package.json name、GEMINI.md/phase-guard 头部、INSTALL.md marketplace URL、`npx team-flow@0.10.0` 调用、CHANGELOG）。
-- 实测 `tf runtime config --get prototype.designSystem`（v0.3 修正 A）。
-- 跑通 `npm test` / `npm run validate`（开发期尚未执行）。
-- 验证 17 个 skill 在 Claude Code/各宿主被正确加载。
+- [ ] **实测 `tf runtime config --get prototype.designSystem`**（v0.3 修正 A，仍是设计假设）。
+- [ ] **v1.0.0 GA 发布标准**：规划正式发布里程碑。
+- [ ] **pre-commit hook 检测未发布版本**：§27.3 step 9 设计，防止本地版本领先 npm。
 
 ---
 
@@ -50,49 +66,60 @@
 
 ```
 team-flow/
-├── HANDOFF.md                 # 本文件
-├── plugin.json                # 顶层插件清单（name=team-flow, version=0.10.0）
+├── HANDOFF.md                 # 本文件（最后更新 2026-07-28）
+├── plugin.json                # 顶层插件清单（name=team-flow, version=0.22.4）
+├── package.json               # npm 包（name=@xulthekl/team-flow）
 ├── .claude-plugin/
-│   ├── plugin.json            # ★ Claude Code 实际读取的清单（name=team-flow）
+│   ├── plugin.json            # ★ Claude Code 实际读取的清单
 │   └── marketplace.json
 ├── .cursor-plugin/  .codex-plugin/  .github/plugin/  .agents/plugins/  .opencode/plugins/
 │                             # 各宿主安装面清单（均已统一为 team-flow）
-├── AGENTS.md                  # 插件级机制说明（四套合一 + SOP + 配置注入）
-├── README.md / INSTALL.md     # 顶层说明 / 9 安装面安装指南
-├── package.json               # npm 包（name 仍为 team-flow，见 §6 品牌残留）
+├── AGENTS.md                  # 插件级机制说明（九套合一 + SOP + 配置注入）
+├── README.md / INSTALL.md     # 顶层说明 / 多安装面安装指南
 ├── scripts/                   # tf 运行时 + 各宿主安装器 + 版本一致性检查
+│   ├── team-flow.mjs          # ★ CLI 入口（bin: tf / team-flow）
 │   └── check-version-consistency.mjs   # CI 守卫：所有 manifest 版本须=package.json
 ├── src/ dist/                 # team-flow TypeScript 底座（schema/parsing/validation）
-├── skills/                    # ★ 17 个 skill（开发重点目录）
-│   ├── workflow-start … bug-investigator   # team-flow 9 个
-│   ├── ce-brainstorm … ce-proof            # compound 核心 6 个（含 references/agents/*）
-│   ├── architecture-design                 # 4A+DDD 增量设计
-│   └── prototype                            # 本地 HTML 原型（新建）
-├── docs/                      # 设计文档 + 上游 team-flow 文档
-│   ├── architecture-api-db-design-enhancement-v0.3.md  # ★ 权威设计规格（含原型章）
+├── skills/                    # ★ 23 个 skill（开发重点目录）
+│   ├── workflow-start … bug-investigator    # 底座 9 个
+│   ├── ce-brainstorm … ce-proof             # compound 核心 6 个
+│   ├── architecture-design                  # 4A+DDD 增量设计
+│   ├── prototype                            # 本地 HTML 原型
+│   ├── design-system                        # 设计系统管理
+│   ├── workflow-orchestrator                # 产品级编排
+│   ├── workflow-bootstrap                   # 项目接入
+│   ├── e2e                                  # 端到端测试
+│   ├── session-handoff                      # session 交接
+│   └── workflow-feedback                    # 反馈闭环
+├── agents/                    # 8 个顶层 agent
+├── docs/                      # 设计文档 + 上游文档
+│   ├── architecture-api-db-design-enhancement-v0.9.md  # ★ 权威设计规格（当前版本）
 │   ├── prototype-design-research.md                    # 原型方案调研
 │   ├── state-machine.md / artifact-contract.md / decision-points.md …
-├── hooks/  templates/  tests/  assets/  llms.txt  GEMINI.md  .claude/  .codex/
+├── hooks/  templates/  tests/  assets/  llms.txt  GEMINI.md  .claude/
 ```
 
 **设计权威来源**（改方案前必读）：
-- `docs/architecture-api-db-design-enhancement-v0.3.md` —— v0.3 终稿，含第十五章原型设计能力（§15.0–§15.8：五方案对比 / 两层层级模型 / 迭代模型 / 完整目录 / 配置驱动 / 本地 HTML 原型 skill / 衔接 / I/O 钉死 / 设计系统复利）。用户已于第 16 轮通过并采纳 3 条专家评审修正。
-- `docs/prototype-design-research.md` —— 原型五方案事实对比与「零外部依赖」结论。
+- `docs/architecture-api-db-design-enhancement-v0.9.md` —— v0.9 当前权威版本（含 §27 身份统一章节）
+- `docs/prototype-design-research.md` —— 原型五方案事实对比与「零外部依赖」结论
 
 ---
 
 ## 3. 关键设计决策（ADR 速记）
 
 1. **插件名 = `team-flow`**（用户拍板）。
-2. **compound 范围 = 核心子集（C 方案，6 个）**，非全量 33。理由：避免 27 个嵌套 agent 全部并入导致膨胀；6 个核心已覆盖「头脑风暴→PRD→全局复利→策略→创意→验证」主链路。
-3. **compound 的 agent 随所属 skill 自动并入**：~27 个 agent 全部嵌套在各 skill 内部的 `skills/<name>/references/agents/*.md`，作为运行时子代理/研究员参考，**非独立顶层 agents**，复制 skill 目录即带入，无需单独注册。6 个核心 skill 携带 agents 数：ce-plan 15 / ce-compound 7 / ce-ideate 4 / ce-brainstorm 1 / ce-strategy 0 / ce-proof 0。
-4. **版本保持 `0.10.0`**（对齐 team-flow base），不擅自 bump。理由：① `check-version-consistency.mjs` 强制所有 manifest 版本=package.json；② 运行时 `tf` 与 `npx team-flow@0.10.0` 仍指向 team-flow base，bump 需先发布 team-flow 到 npm。见 §6。
-5. **配置扩展字段为插件层（非 team-flow 原生 schema）**：原生仅 `artifacts.order` / `artifacts.skip`；`prd.template` / `prototype.designSystem` / `prototype.entry` 是我们在 `team-flow.config.json` 上扩展的字段，由插件层自读（`tf runtime config --get <key>`）。
+2. **npm 包名 = `@xulthekl/team-flow`**（scoped，解决 publish 权限冲突；author = `xulthekl`）。
+3. **compound 范围 = 核心子集（C 方案，6 个）**，非全量 33。理由：避免 27 个嵌套 agent 全部并入导致膨胀；6 个核心已覆盖「头脑风暴→PRD→全局复利→策略→创意→验证」主链路。
+4. **compound 的 agent 随所属 skill 自动并入**：嵌套在各 skill 内部的 `references/agents/*.md`，作为运行时子代理，非独立顶层 agents。
+5. **CLI = `tf`**（bin 同时暴露 `team-flow` 别名）。npx 调用统一用 `npx --yes --package @xulthekl/team-flow@X.Y.Z tf <subcmd>`。
+6. **状态文件 = `.team-flow.yaml`**（扁平，每 change 一份）。
+7. **配置文件 = `team-flow.config.json`**（插件层扩展字段：`prd.template` / `prototype.designSystem` / `prototype.entry`）。
+8. **版本同步机制**：`npm run version <x.y.z>` 自动更新 package.json + 所有 manifest + 所有 skill npx 引用 + phase-guard.md / llms.txt / GEMINI.md 版本戳。
 
 ### v0.3 三条专家评审修正（已采纳）
-- **修正 A（§15.4）**：明确上述扩展字段非原生 schema，需实测 `tf runtime config --get prototype.designSystem` 是否真能读。
+- **修正 A（§15.4）**：明确扩展字段非原生 schema，需实测 `tf runtime config --get prototype.designSystem` 是否真能读。
 - **修正 B（§11）**：`arch-merge` → `prototype-sync` **顺序提交**（同一 change closing 内）。
-- **修正 C（§15.3）**：原型膨胀防控（components/ 复用 design-system，禁内联漂移）+ 分支约定（原型随 PRD 当前版本分支维护）。
+- **修正 C（§15.3）**：原型膨胀防控（components/ 复用 design-system，禁内联漂移）+ 分支约定。
 
 ---
 
@@ -100,18 +127,13 @@ team-flow/
 
 ### 4.1 本地安装（开发态）
 ```bash
-# 进入 team-flow 目录，用 Claude Code 加载为插件
 cd team-flow
 claude  # 启动 Claude Code
 /plugin add /absolute/path/to/team-flow   # 本地路径安装
-# 或从仓库
-git clone <your-repo> && cd team-flow && claude
-/plugin add ./team-flow
 ```
-> Claude Code 实际读取 `.claude-plugin/plugin.json`（已统一为 team-flow）。安装后自动加载 `hooks/hooks.json`，新会话注入上下文。
 
 ### 4.2 项目级配置注入
-项目根 `team-flow.config.json`（注意：文件名仍沿用 team-flow，因为 `tf` 运行时只读此名，见 §6）：
+项目根 `team-flow.config.json`：
 ```json
 {
   "artifacts": { "order": ["proposal","specs","design","tasks"], "skip": [] },
@@ -122,80 +144,72 @@ git clone <your-repo> && cd team-flow && claude
   }
 }
 ```
-读取：`tf runtime config --get prototype.designSystem`（插件层自读，字段命名避开原生 key 冲突）。
+读取：`tf runtime config --get prototype.designSystem`
 
-### 4.3 初始化本地原型（首次）
-```bash
-cp -r skills/prototype/references/prototype-scaffold/ <project>/prototype/
-# 随后按 prototype/design-system.md 填 token；prototype/ 与 prd/ 同级、git 分支隔离版本
-```
-
-### 4.4 开发与验证命令
+### 4.3 开发与验证命令
 ```bash
 npm install
 npm run build          # tsc 编译 src/ → dist/
-npm test               # node --test 集成测试
-npm run validate       # 校验 artifacts（用 docs/examples 数据）
-npm run check-versions # 版本一致性守卫（当前应 ✅ 全 0.10.0）
+npm test               # node --test 集成测试（421 个）
+npm run validate       # 校验 artifacts
+npm run check-versions # 版本一致性守卫（当前应 ✅ 全 0.22.4）
 ```
 
 ---
 
 ## 5. 关键机制与 SOP
 
-### 5.1 全局产物结构（Discoverability：设计/开发前先检索）
+### 5.1 全局产物结构
 ```
 prd/                    PRD（有版本 v1→v2→v3，git 分支隔离）
-prototype/             全局原型系统（UI 契约真相源）：index.html / pages / components / assets / design-system.md / flow.md
-docs/architecture/     全局架构锚点：ARCHITECTURE.md / DATABASE.md / <bc>/（限界上下文目录）
-specs/<cap>/            每变更设计/任务/契约：spec.md / design.md / tasks.md / execution-contract.md / architecture.md / database.md / api.md
+prototype/             全局原型系统（UI 契约真相源）
+docs/architecture/     全局架构锚点
+specs/<cap>/            每变更设计/任务/契约
 STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 ```
 
 ### 5.2 标准工作流（SOP）
 ```
 模糊需求
-  → [ce-brainstorm → ce-plan 就地 enrich] → prd/vN
-  → 拆 change（一份 PRD 可拆多 change）
-  → team-flow: exploring → … → closing
-       每 change：引用全局 prototype/ 作 UI 契约（进 execution-contract.md）
-                 architecture-design 增量（As-Is 冻结 → To-Be → 复利回写）
-                 api.md 经 execution-contract.md 被 build-executor 硬消费
-  → change 完成：arch-merge → prototype-sync（顺序提交）复利回写全局
+  → [workflow-bootstrap]（一次性，已有 baseline.md 则跳过）
+  → [workflow-orchestrator]
+  → S1 路径路由器 → 需求选择 + 判断入口路径
+  → S2 PRD + 原型 → ce-brainstorm + prd-completeness-reviewer + prototype
+  → S3 计划 → ce-plan → plan.md
+  → S4 拆分验证与分发 → change-split-auditor 审计
+  → S5 全局监控（change≥2 必选）
+  → 每个 change：team-flow 8 态状态机
+       exploring → specifying → bridging → approved-for-build → executing → closing
+  → change 完成：arch-merge → prototype-sync → 复利晋升
 ```
 
 ### 5.3 关键约束
-- **原型全局一份**、与 PRD 同级、git 分支隔离版本；change 不直接拥有原型文件（引用全局 `prototype/` 作 UI 契约）。
-- **design.md 不可变**：架构增量经 `arch-merge` 回写全局 `ARCHITECTURE.md`，不就地改 change 的 design.md。
-- **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内），避免全局文档半更新态。
-- **膨胀防控**：`prototype/components/` 必须复用 `design-system.md`，禁止页面内联样式漂移；新增组件先沉淀进 design-system 再引用。
-- **分支约定**：原型随 PRD 当前版本分支维护；change 引用其所在 PRD 版本分支的 `prototype/`。
+- **原型全局一份**、与 PRD 同级、git 分支隔离版本
+- **design.md 不可变**：架构增量经 `arch-merge` 回写全局
+- **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内）
+- **膨胀防控**：`prototype/components/` 必须复用 `design-system.md`
+- **分支约定**：原型随 PRD 当前版本分支维护
 
 ### 5.4 team-flow 8 态状态机
 `exploring → specifying → bridging → approved-for-build → executing → closing`（另有 `onboarding` / `archived`）。
-`workflow-start` 做内容级状态检测与非法跳变拦截；详见 `docs/state-machine.md`。
+详见 `docs/state-machine.md`。
 
 ---
 
 ## 6. 剩余待办 / 已知项（按优先级）
 
-### P0 —— 不影响安装，但建议尽快收口
-- [ ] **品牌重命名残留**（当前仅 manifest 的 `name` 改了，以下仍写 `team-flow`）：
-  - `package.json` 的 `"name": "team-flow"`（npm 包名；bin 暴露 `tf` 与 `team-flow`）。建议保留 bin `tf`，包名可改 `team-flow`。
-  - `GEMINI.md` 第 1/3/5 行、`llms.txt` 第 1/3-5 行、`.claude/always/phase-guard.md` 第 1 行头部 `# team-flow v0.10.0 |`（**注意**：`check-version-consistency.mjs` 的 GEMINI/phase-guard 版本正则硬编码了 `team-flow`，若改头部须同步改该脚本的正则，否则一致性检查会失败）。
-  - `INSTALL.md` 的 marketplace 命令 `MageByte-Zero/team-flow`、`/plugin install team-flow@team-flow`（第 44-45、53 行等）—— 要发布到 Claude Code marketplace 前必须替换。
-  - 各 team-flow skill 内 `npx --yes --package @xulthekl/team-flow@0.10.0 tf`（由 `check-version-consistency.mjs` 的 RUNTIME_FILES 校验，必须保持 `team-flow@0.10.0` 直到 team-flow 发布到 npm）。
-- [ ] **实测 v0.3 修正 A**：验证 `tf runtime config --get prototype.designSystem` 真能读到扩展字段（当前未跑，是设计假设）。
+### P1 —— 质量与验证
+- [ ] **实测 v0.3 修正 A**：验证 `tf runtime config --get prototype.designSystem` 真能读到扩展字段
+- [ ] **验证 23 个 skill 被各宿主正确发现加载**（`.claude-plugin/plugin.json` 的 `skills: "./skills/"` 路径）
 
-### P1 —— 质量与发布
-- [ ] 跑通 `npm test` 与 `npm run validate`（开发期尚未执行，确认底座未因复制/改名损坏）。
-- [ ] 验证 17 个 skill 被 Claude Code 与各宿主正确发现加载（`.claude-plugin/plugin.json` 的 `skills: "./skills/"` 路径）。
-- [ ] 更新 `CHANGELOG.md`（当前仍为 team-flow 历史）。
-- [ ] 补一张团队 flow 图（可选）。
+### P2 —— 发布与治理
+- [ ] **pre-commit hook 检测未发布版本**：防止本地版本领先 npm 公共源（§27.3 step 9 设计）
+- [ ] **v1.0.0 GA 发布标准规划**：里程碑定义、稳定性标准、正式发布公告
+- [ ] **marketplace.json 注册**：Claude Code / Cursor / GitHub 等 plugin marketplace 如需注册项，确认包名与元数据
 
-### P2 —— 语义与发布决策
-- [ ] **版本语义**：当前 0.10.0 对齐 base。要 bump 到 team-flow 自有 semver（如 0.1.0）时，须：① `npm run version <x.y.z>`（会跑 `tf version` + `check-version-consistency` + 改所有 manifest + 文本戳）；② 同步改 README/INSTALL/`docs/README_en.md`/`hooks/session-start`/`llms.txt`/GEMINI.md/phase-guard.md 里的版本戳；③ 把 `npx team-flow@` 改 `npx team-flow@`（需先 `npm publish`）。
-- [ ] **注册到平台**：`ima_skill_create` 仅注册单个 skill（非插件）；team-flow 作为 plugin.json 插件通过宿主 `/plugin add` 安装，不通过 ima 平台注册。不要在未明需求时调用 `ima_skill_create`。
+### P3 —— 可选
+- [ ] **用户文档迁移指引**：给已安装旧版用户一个迁移说明（`tf doctor` 自动迁移已有，评估是否足够）
+- [ ] **外部文档同步**：GitHub repo README、npm 主页描述同步新包名
 
 ---
 
@@ -203,17 +217,28 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 
 1. 打开 `team-flow/` 目录启动 Claude Code。
 2. `/plugin add ./`（或绝对路径）加载插件；新会话会注入 `AGENTS.md` + `GEMINI.md` 上下文。
-3. 读 `HANDOFF.md` + `docs/architecture-api-db-design-enhancement-v0.3.md` 建立全局认知。
+3. 读 `HANDOFF.md` + `docs/architecture-api-db-design-enhancement-v0.9.md` 建立全局认知。
 4. 想改能力 → 改 `skills/<name>/SKILL.md`（或 `references/`）；想改运行时 → 改 `src/` 后 `npm run build`。
 5. 改完跑 `npm run check-versions` 与 `npm test` 守门。
-6. 按 §6 清单逐项收口品牌与验证。
 
 ---
 
-## 8. 交付物清单（本次 workspace）
+## 8. 身份统一历史（P1-6 三阶段）
+
+| 阶段 | 版本 | 时间 | 内容 |
+|------|------|------|------|
+| 第一阶段 | v0.15.0 | 2026-07 | 产品级状态文件 `.team-flow/` 化 |
+| 第二阶段 | v0.22.3 | 2026-07-27 | spec-superflow → team-flow 全量迁移（721+ 处）|
+| 第三阶段 | v0.22.4 | 2026-07-27 | npm 包 scope 化 `@xulthekl/team-flow`，发布 npm |
+
+详细记录见 `CHANGELOG.md` 与 `docs/architecture-api-db-design-enhancement-v0.9.md` §27。
+
+---
+
+## 9. 交付物清单（本次 workspace）
 
 - `team-flow/` —— 统一插件工程（本 handoff 的载体）。
-- `architecture-api-db-design-enhancement-v0.3.md` / `prototype-design-research.md` —— 权威设计文档（已复制进 `team-flow/docs/`）。
-- `team-flow/`、`compound-engineering/`、`team-flow-main/`、`compound-engineering-plugin-main/` —— 上游源工程（参考/溯源用）。
-- `ce.zip` / `team-flow.zip` —— 上游源 zip（溯源用）。
-- `skills/architecture-design/`、`architecture-design-source/` —— 蒸馏源（已并入 team-flow/skills/architecture-design）。
+- `architecture-api-db-design-enhancement-v0.9.md` / `prototype-design-research.md` —— 权威设计文档。
+- `skills/` —— 23 个 skill 全部就位。
+- `agents/` —— 8 个顶层 agent。
+- `@xulthekl/team-flow@0.22.4` —— 已发布 npm 公共源。

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.22.4**。
+当前发布版本：**v0.24.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.22.4`
+> 当前版本：`v0.24.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.22.4`
+- Current: `v0.24.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/solutions/INDEX.md

@@ -0,0 +1,5 @@
+# Solutions Index
+<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
+| date | phase | domain | type | severity | summary | file |
+|------|-------|--------|------|----------|---------|------|
+| 2026-07-28 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-28-no-summary.md |

package/docs/solutions/cross-phase/2026-07-28-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-07-28
+source: 
+---
+
+## 问题描述
+(no summary)
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）