@xulthekl/team-flow 0.53.0 → 0.54.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.53.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.54.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 + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.53.0",
+      "version": "0.54.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.53.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
+  "version": "0.54.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) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {
     "name": "LT",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.53.0",
+  "version": "0.54.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.53.0"
+    "version": "0.54.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
-  "version": "0.53.0",
+  "version": "0.54.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.53.0"
+    "version": "0.54.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.53.0",
+      "version": "0.54.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.54.0] - 2026-09-10
+
+### Added（设计系统 → 原型贯通：组件契约 + Primer + Showcase + 逆向建库）
+
+设计来源：`docs/plan/design-system-prototype-enhancement-design.md` v1.7（2026-09-10；P4 偏差记录见其附录 A.4）。输入 = open-design 迁移管线研究 + 设计系统核对工具 L0-L5 方法论 + LT 三项补充需求（持续迭代 / 逆向建库 / Design Showcase）；本方案按 **P1.5 完整档（3 轮对抗式验证 + 逐轮闭合表）** 收敛：问题数 39→9→6，Critical 4→2→0。
+
+**核心承诺**：设计系统从「token 定义文档」升级为「**能约束 AI 生成原型的契约体系**」——正向白名单（primer，prompt 层劝告）+ 反向拦截（guard / P0 grep，代码层）双层防护。
+
+- **组件契约表（L2 结构化）**：base.md 的 components 段由散文升级为表格（组件 × 类型 × variants × sizes × states × 用途 × 禁止）；**类型列决定 states 下限**（交互 ≥3 / 轻量 ≥2 / 豁免）；数量三档阈值（<10 FAIL 标签 / 10-14 WARN 可用 / ≥15 PASS）；`contract: v1|legacy` 标记区分存量（legacy 降级 WARN，不阻断）。
+- **AI Primer（L5 补齐）**：新增 `scripts/gen-primer.mjs`——确定性生成 `.team-flow/design-system/primer.md`（零 LLM、纯字符串拼接）+ digest 头部；`--check` 模式供 builder Step 0 gate 校验新鲜度（exit 0 一致 / exit 2 STALE）；内容 = 组件白名单 + Token 速查 + 硬规则。配「生成物 == 源表」单测。
+- **六层审计 guard**：新增 `scripts/guard/design-token-guard.mjs`——硬校验（exit 1）+ 六层审计报告（恒 exit 0，不输出总分，`--strict` 存量当 v1 标签 / `--json`）；配套 `scripts/lib/ds-parse.mjs` 共享解析器（guard / gen-primer / import 三方复用，消除同契约多实现漂移）。
+- **Design Showcase**：新增展示板机制——**草案阶段**产出 1-3 页 Board（让用户在确认设计系统前先看到实际效果，解决「确认后才见效果」的时序倒置）；内置车企场景 brief（`showcase-board-{b,c}-end.md`，虚构品牌「星驰汽车」：B 端线索管理后台 6 区块 / C 端官网 + 车主 APP）；`prototype-builder` 新增 `mode: showcase`（gate 豁免 `confirmed_plan`/`prd_path`，flat 单文件最小交付契约）。
+- **持续迭代（不新增第二账本）**：原型阶段的组件 / token 增量经 builder 既有 `outstanding_questions` 通道回传（`ds_increment` 字段），在原型人工评审 ⑥ 由用户确认（全部 / 逐项 / 暂不处理）；"暂不处理"入 `.team-flow/design-system/pending.md`——**单写者 = design-system skill**（主代理 / release-archivist 只读）；两级确认节点（⑥ 即时 + change closing 兜底），不新造流程。
+- **逆向建库**：新增 `scripts/token-extract.mjs`（8 类正则证据机器 + ΔE<2 颜色聚类 + 频次排序 + directory skiplist + `--report` 只读报告）；新增 `scripts/design-system-import.mjs`（open-design DESIGN.md → team-flow base.md：A 类九节解析 + B 类兜底提取）；design-system skill 新增 create-from-code 模式（**确定性提取 + 人工策展**，语义角色由人定，不自动推断落盘）。
+- **L0 / L1 补齐**：base.md 新增 `principles` 段（≥3 条，guard 计数）+ `governance` 段（contract / version / 负责人 / 弃用策略）；`token-derivation.md` 新增**确定性 dark 派生规则** + `creation-flow.md` 新增维度 6（theme 输入）。
+- **open-design 资源内置（精选）**：新增 `templates/design-systems/`——`registry.json`（8 个 B 端相关参考：linear-app / stripe / vercel / supabase / sentry / posthog / notion / claude）+ `styles.json`（57 风格种子，扩充 mood → palette 映射）+ `references/*.md`（160KB 原文，MIT 归因 "inspired by"）。**全量扫描 143 个的真实分布**：A 类 63（44%）/ B 类 80（55%），B 类总体积 ~1.3MB → 精选内置而非全量（体积 + 相关性双重考量），未内置的按 registry 指引用 import 现取。
+- **首次接入提示**：`workflow-bootstrap` 新增 **B4.6**（advisory，不阻断）——检测项目无设计系统时 AskUserQuestion 四选一（模板库 / 逆向建库 / 从零创建 / 跳过）。
+- **流程制度化（父仓库 CLAUDE.md）**：新增 **P1.5 方案对抗验证**（可选，三档强度：轻量 1 轮 / 标准 2 轮 / 完整 3 轮；P1 完成后必须询问用户是否执行，可跳过）——本次方案本身即按完整档执行并借此收敛。
+
+### Changed（行为变更）
+
+| # | 变更 | 影响面 |
+|---|------|--------|
+| 1 | `prototype-builder` Step 0 新增 primer gate | `governance.contract: v1` 且 primer 缺失/过期 → **blocked**；legacy / 无标记 → WARN 放行（存量项目不受阻） |
+| 2 | design-system 创建流程新增六层审计 + 组件数量三档标签 | 创建完成时 guard 恒输出审计报告；组件 <10 类标 FAIL 标签（不阻断落盘，供用户判断） |
+| 3 | release-archivist closing 新增 **⑥ 设计系统待办检查** | 只读检查 pending.md → closing summary 新增 `design_system_pending` 字段（报告契约扩展，不执行 iterate） |
+| 4 | `workflow-bootstrap` 新增 B4.6 | advisory 步骤，不阻断；Output Standard 阶段清单同步 B4.6 |
+
+### P4 复验（双门禁独立复验：均 PASS）
+
+- **plugin-validator 复验 → PASS**：Major 闭合（指定 grep 空集 + 更宽 grep 交叉印证 + import 提示实测为绝对路径 + 新 lint 非空转）。release-archivist 的**描述性写法成立**（约束真实——`platform-runtime-distribution.test.mjs:38` 对 9 个 runtime skill 断言禁宿主变量；两处无解释器前缀、无调用动词，仓库内既有同写法先例）。**横展发现 3 处存量同类真调用点**：`build-executor/SKILL.md:150` 与 `references/execution-modes.md:46` 的 `` `scripts/task-brief PLAN_FILE N` ``、`code-reviewer/SKILL.md:87` 的 `` `scripts/review-package` ``——实测从用户项目 CWD 执行报 `No such file or directory`（脚本真实存在，文档写法解析不到）。**与本次修的那批不同**：属 runtime skill（禁 `${CLAUDE_PLUGIN_ROOT}`），唯一可行修法是**暴露为 `tf` 子命令**——已登记 **P1-69**（含证据链与替代解评估），不在本次范围内实施。
+- **skill-reviewer 复验 → 可转 PASS**：C1 闭合（新探针：base + 端变体传目录 / 传 base.md **均 PASS**，原 `EXIT=1` 的互斥论据失效）；6 Major 全闭合；8 Minor 中 6 闭合、2 项经复核**由评审方主动撤回**（release-archivist 描述性写法、⑥ 与 reference 的分层重复）；另有 2 项本轮改动引入的新观察，**已在 P5 前闭合**：
+  - **观察 A（合并断言掩盖单端残缺）**：`target=both` 时若 c-end 只有 typography，合并跑仍 PASS。修法（零代码）：Step 6 增加「**按端各跑一次**（`--variant b-end` / `--variant c-end`）」并在 SKILL.md / creation-flow 双处写明——`--variant c-end` 单跑报 3 项 FAIL（已固化为测试判据）。
+  - **观察 B（无关 md 可补齐缺失段）**：同目录 `notes.md` 含 `## spacing` 等段即可把 FAIL 洗成 PASS。修法：变体识别**收紧为约定集**（`*-end.md` + `variants/` 子目录），非约定命名用 `--variant <name>` 显式纳入（逃生通道）；含必选段但未被纳入的 md **显式告警**列出（不静默补齐、也不静默忽略）。3 例测试固化。
+- **lint 盲区加固**：`skill-path-convention.test.mjs` 正则补 `node ./scripts/x`（显式相对前缀）与 `node --flag scripts/x`（解释器带参数）两种形态 + 各自正向控制——正是上一轮 grep 漏检的同款盲区（当前语料零实例，属预防性加固）。
+- **前瞻风险记录**：三个 skill 目前依赖 `${CLAUDE_PLUGIN_ROOT}` 且不在 `RUNTIME_SKILLS` 名单（测试绿）；但 **design-system 由 prototype 运行期调用**——若平台策略将其收进 runtime 名单，guard / primer / importer 的调用方式需整体改造。已记入设计文档附录 A.4 第 7 行与 `design-token-guard.mjs` 头部注释。
+- **复验期间的一次外部操作已独立核实无污染**：plugin-validator 披露其误在仓库根执行 `install-zcode --local .` 并已自行清理；我已核实 `.zcode/` 恢复为原 3 个受跟踪文件、无未跟踪残留、全仓 `git status` 仅含本次变更。
+
+### Fixed（P5 提交期发现）
+
+- **内置参考库第 8 个文件被 `.gitignore` 静默吞掉**：`templates/design-systems/references/claude.md` 与 `.gitignore:9` 的 `CLAUDE.md` 规则同名，macOS 大小写不敏感文件系统上被判为忽略 → **registry.json 声明 8 个参考、git 只跟踪 7 个**（npm 包因读磁盘仍含 8 个，两边不一致；且 `git add -A` 永远不会收录它）。修法：`.gitignore` 加显式**例外规则**并注明原因；验证 `git ls-files templates/design-systems/references/` = 8。**该缺陷形态值得留意**：整个 P3/P4 的门禁（含我新加的两条 lint）都在查"文件引用是否存在"，而没有一条检查"文件是否真的会被提交"——已作为教训记入本轮复盘。
+
+### Tests
+
+- 新增 4 个测试文件：`design-token-guard.test.mjs`(23) + `gen-primer.test.mjs`(9) + `token-extract.test.mjs`(7) + `skill-path-convention.test.mjs`(3)，合计 **42 个新用例**
+- 全量 **935/935 通过**（原 893）；`npm run check-versions` 全绿
+- **P4 双评审闭环**：plugin-validator（1 Major + 8 Warning，全处置）+ skill-reviewer（1 Critical + 6 Major + 8 Minor，全处置）
+
+### Fixed（P4 门禁发现：skill-reviewer 一轮，含 1 Critical）
+
+- **【Critical C1】guard 的「单文件 9 段」模型与文档的「base + 端变体」拆分布局互斥**——`variant-schema.md` 明确 base 品牌层**不含** typography/spacing/layout/motion（随端变化，由端变体承载），而 guard 只接单个 md 且断言全 9 段 → **任何按文档创建的系统在 Step 6 落盘时被硬校验判 FAIL / exit 1**，返工死锁（P4 实证：合规拆分布局 exit=1 且 4 项 MISSING；而转换器产出的单文件 9 段版本 PASS——测试 fixture 站在工具侧，形成假保障）。**修法（补强代码）**：guard 输入解析支持**目录 / base.md / 变体文件**三种形态，主体不完整时自动合并端变体（`--variant <name>` 可限定；主体已含全 9 段则单文件模式，不卷入同目录无关 md）；合并按 base 优先、组件表按名去重（端差异行不重复计数）；无可合并变体时输出诊断提示。**证据**：`tests/lib/design-token-guard.test.mjs` 新增 6 例（拆分布局 base+变体过校验、目录输入、`--variant` 无匹配回退、单文件模式、L3 检测面、去重）。
+- **M1 L3 业务模式层对合规系统恒为假红灯**：检测面只读传入的 md，而唯一写「页面范式」的是 `gen-primer.mjs` 生成的 **primer.md**（L3 不读）→ 任何按规范创建的系统恒 ❌。修法：检测面 = 合并后文本 + 同目录 `primer.md`，并在报告中说明「设计系统侧只引用，节奏表在 prototype layouts.md」的归属。
+- **M2 模板库起点是死路**：`workflow-bootstrap` B4.6 的模板库分支**直接调转换器**、不经 design-system skill → 产出 `contract: v1` 但**无 primer** → prototype Step 0 稳定 `blocked`，且链路上三份文件都没提「还要生成 primer」。修法：B4.6 模板库分支改为**委托 `/team-flow:design-system`**（由该 skill 呈现 registry 并续跑 Step 5 评审 → Step 6 落盘，含 primer + guard）；SKILL.md Step 0 同步写明；转换器保持纯确定性转换（不自动生成 primer——避免用户人工核对配色后 primer 立即过期），输出提示改为**本脚本所在插件目录的绝对路径**且列出完整下一步链。
+- **M3 `variant-schema.md` 迭代口径自相矛盾**：「新组件进变体 `components`」与同文件「契约表全量真源在 base / 变体不再重复清单」直接冲突——按前者操作会破坏本版要建立的「消除双份维护」。已改为「新组件进 base 契约表，端特有点写变体覆盖说明」。
+- **M4 prototype 侧旧单文件路径残留 5 处 + description 越界**：`prototype/SKILL.md` 的 description 宣告了本属 design-system 的「创建/维护」职责（两个 skill 争夺触发）且引用 v0.19.0 起已废弃的 `design-system.md`；正文 5 处（用途/产出结构树/硬原则/内核/膨胀防控）同源残留。已统一为 `.team-flow/design-system/`（base + 端变体），产出结构树删除旧文件行并加注存放位置；横展同批修复 `prototype-env-scout.md`（3 处）、`builder-methodology.md`、`craft/anti-ai-slop.md`、`template.html` 与 scaffold `design-tokens.css` 的渲染说明。
+- **M5 `orchestration-flow.md` 派发输入契约未同步**：builder 派发清单仍写 `design-system.md` 且缺 `design_system_path`/`variant`/`prototype_root`/`mode`——而 `builder-methodology.md` 要求读 `<variant>.md`，该 `<variant>` **无来源**。已按 v0.54.0 契约补齐（含 showcase 模式豁免说明）；env-scout 探查项同步升级（合并后 9 段完整度 / primer 新鲜度 / 契约表分档）。
+- **M6 确定性数值在两份文档间冲突**（spacious 字号 18 vs 17 / `--space-4` 固定 16 vs 密度 12-16-20 / 字体栈两版 / `--focus-ring` 与 `--elev-raised` 几何有无）：收敛为**单一真相源** `token-derivation.md`（数值权威）——density 改为明确倍率语义（×0.75 / ×1.0 / ×1.25 作用于 4px 基准阶梯，`--space-4` = 12/16/20）；字体栈取更完整的系统栈（含 `Segoe UI`，与 `design-system-import.mjs` 一致）；A2 几何与 `template.html` / `preview-template.html` 对齐；dark 主题 `--accent` 提亮改为**有界确定性**（对比度 <4.5:1 时按 10% 步长至多 3 次取首个达标值，仍不足则记入 `extensions` 交人工，不静默继续）。`creation-flow.md` 顶部加权威指向。
+- 杂项（skill-reviewer Minor）：`showcase-board-c-end.md` 覆盖数「合计 18 类」错 → **本板 16 类 + 两板合计覆盖 20 类基线全量**（原注释把 b-end 已覆盖的 4 类误列为除外）；`variant-schema.md` 目录树补 `primer.md`/`pending.md`/`showcase/`，并写明**交互/轻量的 variants 亦必填**（guard 会判违规）；`design-system-architect.md` 删除写死的年份注记、段落标题 `design-system.md` → `base.md`。
+- **平台分发策略遵守**：release-archivist 属 **runtime skill**（9 个 runtime-dependent skill 之一，禁 `${CLAUDE_PLUGIN_ROOT}`——Cursor/ZCODE 等宿主无该变量，由 `platform-runtime-distribution.test.mjs` 守护），故其两处脚本引用改为**描述性写法**（「插件内 `scripts/…`（引用，非调用）」），不用宿主变量。
+
+### Fixed（P4 门禁发现：plugin-validator）
+
+- **【阻断级】插件内脚本/模板调用路径全部裸相对路径**（plugin-validator Major）：4 个新特性的 11 处调用写成 `node scripts/x.mjs` —— Bash 的 CWD 是**用户项目**，而插件零拷贝安装（marketplace，本插件推荐安装方式）时插件位于缓存目录，两者永不相等 → 模板导入 / primer digest 校验 / token 提取 / guard 四件全部不可执行；最严重处 `builder-methodology.md:27` 的 `--check` **exit code 是分支判据**（exit 0 继续 / exit 2 blocked），路径失败把确定性分支退化为猜测。修复：11 处统一改为 `${CLAUDE_PLUGIN_ROOT}/…`（对齐 `workflow-bootstrap` / `install-cursor.mjs` 既有范式与 `$SKILL_DIR` 同类解法）。**机械预防**：新增 `tests/lib/skill-path-convention.test.mjs`（正/负向控制 + 全量语料扫描），把「裸相对路径」从每轮人工审查变成 CI 可拦截的 lint。
+- **plugin.json 描述缺 3 个 first-class skill**（plugin-validator Minor）：`design-system` / `test-strategy` / `project-initialize` 自引入起从未进入 marketplace 描述（`design-system` 为 v0.19.0 起缺失，本轮成为主线能力后更显突兀）→ 两份 manifest 同步补全。
+- `release-archivist/SKILL.md:288` 的设计方案引用改为 workspace 相对写法（`team-flow-workspace/docs/…`），对齐 `workflow-bootstrap/SKILL.md:122`——同一文档两类引用写法并存。
+- `skills/prototype/references/builder-methodology.md:54` 的「8 个 section 骨架」→ **14 个**：`layouts.md` 实际已有 14 个骨架（v0.24.0 扩至 C 端 6 个），该表述自 v0.24.0 起滞后；`prototype/SKILL.md:52` 已正确，横展确认全插件仅此一处残留。
+
+### Known Deviations（记录在案）
+
+- `skills/release-archivist/SKILL.md`（297→305 行，lint 计数）与 `skills/workflow-bootstrap/SKILL.md`（267→280 行，lint 计数）超出 250 行建议线——**存量既存超长**（同批超长另有 `workflow-start` 302 / `ce-brainstorm` 263 / `architecture-design` 260，本次未触碰）；本次新增内容已按渐进式披露做成指针（细节在 `references/closing-procedures.md`），净增 +7/+12 行记录在案，治理待办见 Roadmap。
+
 ## [0.53.0] - 2026-09-10
 
 ### Added（架构台账回写门禁：`arch-merged` 维度 + B' 时序前移）

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.53.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.54.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

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.53.0**。
+当前发布版本：**v0.54.0**。
 
 ---
 

package/README.md

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

package/agents/prototype-builder.md

@@ -21,12 +21,13 @@ You are a write-focused builder. You read design artifacts (HTML/CSS/JS from the
 
 | Parameter | Description |
 |-----------|-------------|
-| `design_files_dir` | 设计稿目录路径（e.g., `prototype/designs/`） |
-| `design_system_dir` | 设计系统目录路径（e.g., `prototype/design-system/`） |
-| `output_dir` | 原型输出目录路径（e.g., `prototype/runnable/`） |
-| `requirements` | 构建要求（可选：响应式、性能目标、浏览器兼容性） |
+| `design_system_path` | 设计系统 base.md 路径（e.g., `.team-flow/design-system/base.md`） |
+| `confirmed_plan` | 已确认的原型方案（页面清单/组件清单/导航流） |
+| `prd_path` | PRD 路径（页面内容依据） |
+| `prototype_root` | 原型输出根目录（e.g., `prototype/`） |
+| `mode` | （可选）`default` \| `showcase`——showcase 模式用于设计系统展示板（输入换为 showcase-board brief + 设计系统草案，见 references/builder-methodology.md） |
 
-If `design_files_dir` or `design_system_dir` is missing or unreadable, report `BLOCKED` with reason `INPUT_ERROR`.
+If `design_system_path` or `confirmed_plan` or `prd_path` is missing or unreadable, report `BLOCKED` with reason `INPUT_ERROR`（showcase 模式豁免 `confirmed_plan`/`prd_path`）。
 
 ## Output Contract
 

package/agents/prototype-env-scout.md

@@ -1,6 +1,6 @@
 ---
 name: prototype-env-scout
-description: 原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（9 段 schema 完整度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 + readiness verdict。只读，不写 prototype/，不改 design-system.md。
+description: 原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（base + 端变体 9 段 schema 完整度 + primer 新鲜度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 + readiness verdict。只读，不写 prototype/，不改 design-system.md。
 
 model: inherit
 color: cyan
@@ -11,13 +11,13 @@ You are a Prototype Environment Scout. You are dispatched by the `prototype` ski
 
 ## The Iron Law
 
-You NEVER write, edit, create, or delete any file. Your only output is the brief in your final response. Writing `prototype/` is `prototype-builder`'s job; writing `design-system.md` is `design-system-architect`'s job.
+You NEVER write, edit, create, or delete any file. Your only output is the brief in your final response. Writing `prototype/` is `prototype-builder`'s job; writing `.team-flow/design-system/` is `design-system-architect`'s job.
 
 ## Invocation Contract
 
 The dispatch prompt provides (some may be absent — probe to discover):
 - `prd_path` or a hint to locate the current PRD version (e.g., `requirement/v1/prd.md`).
-- `design_system_path` (from `prototype.designSystem` config) or a hint to find `design-system.md`.
+- `design_system_path` (from `prototype.designSystem` config) or a hint to find `.team-flow/design-system/`.
 - `prototype_root` (default `prototype/`).
 - The intent: new prototype from scratch / iterate on existing / sync after a change.
 
@@ -105,7 +105,7 @@ Produce:
 ```
 
 ## Red Lines
-- Do NOT write to `prototype/` or edit `design-system.md` — you are read-only.
+- Do NOT write to `prototype/` or edit `.team-flow/design-system/` — you are read-only.
 - Do NOT draw the prototype — that is `prototype-builder`'s job.
 - A missing design system is normally NOT your blocker — flag it via `needs_design_system` verdict for the orchestrator to decide.
 

package/agents/release-archivist.md

@@ -43,6 +43,7 @@ writebacks:
   arch_merge: "merged N docs | skipped"
   prototype_sync: "synced N pages | no UX delta | conflicts: N"
   compound_promotion: "promoted N learnings | no learnings"
+  design_system_pending: "N items pending (needs user confirmation) | none"  # v0.54.0 ⑥：只读检查 .team-flow/design-system/pending.md，不执行 iterate
 summary: "..."                       # closing summary + any WARNs needing user acceptance
 ```
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.53.0`
+- Current: `v0.54.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/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) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.53.0: auto-sync CLI version with plugin version
+# v0.54.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.53.0"
+PLUGIN_VERSION="0.54.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.53.0.
+Current version: v0.54.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.53.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) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
+  "version": "0.54.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) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"
   },

package/scripts/design-system-import.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// design-system-import.mjs — open-design DESIGN.md → team-flow base.md 转换器（v0.54.0，设计 §4.5.2）
+//
+// 解析 open-design 九节 DESIGN.md，映射到 team-flow 的 9 段 schema（A1/A2/B-slot + 组件契约表 + principles/governance）。
+// 关键约束：**A 类转换后必须补齐完整度**（palette 阶梯 / A2 派生公式 / B-slot 别名 / 组件契约表基线）——
+//           open-design 原文没有这些，转换器按 team-flow 规则生成。
+//
+// Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]
+// 输出后建议运行：node scripts/guard/design-token-guard.mjs <base.md>
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const idIdx = argv.indexOf('--id');
+const idArg = idIdx !== -1 ? argv[idIdx + 1] : null;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1) && !(idIdx !== -1 && i === idIdx + 1));
+const srcPath = positional[0];
+
+if (!srcPath) {
+  console.error('Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]');
+  process.exit(1);
+}
+const srcAbs = resolve(srcPath);
+if (!existsSync(srcAbs)) {
+  console.error(`DESIGN.md not found: ${srcAbs}`);
+  process.exit(1);
+}
+
+const src = readFileSync(srcAbs, 'utf-8');
+const id = idArg || basename(dirname(srcAbs));
+
+// ── 解析 open-design 九节 ──
+
+function grab(pattern) {
+  const m = src.match(pattern);
+  return m ? m[1].trim() : null;
+}
+
+const title = grab(/^#\s+(.+)$/m) || `Design System Inspired by ${id}`;
+const category = grab(/> Category:\s*(.+)/) || 'Uncategorized';
+const summary = grab(/>\s*(?!Category)(.+\S)/) || '';
+
+// A 类模板格式：`**Primary:** \`#hex\``
+let primary = grab(/\*\*Primary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let surface = grab(/\*\*Surface:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let text = grab(/\*\*Text:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+
+// B 类精细格式 fallback：找 brand/accent/primary 上下文附近的 hex（自动提取，需人工核对）
+let autoExtracted = false;
+if (!primary) {
+  const m = src.match(/(?:brand|accent|primary)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  if (m) { primary = m[1]; autoExtracted = true; }
+}
+if (!surface) {
+  const m = src.match(/(?:background|surface|canvas)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  surface = m ? m[1] : '#FFFFFF';
+  if (m) autoExtracted = true;
+}
+if (!text) {
+  const m = src.match(/(?:text|foreground)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  text = m ? m[1] : '#111827';
+  if (m) autoExtracted = true;
+}
+
+const secondary = grab(/\*\*Secondary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+const success = grab(/\*\*Success:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#16A34A';
+const warning = grab(/\*\*Warning:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#D97706';
+const danger = grab(/\*\*Danger:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#DC2626';
+const families = grab(/\*\*Families:\*\*\s*(.+)/) || 'primary=Inter, display=Inter, mono=ui-monospace';
+const scale = grab(/\*\*Scale:\*\*\s*(.+)/) || '12/14/16/20/24/32';
+const spacingScale = grab(/\*\*Spacing scale:\*\*\s*(.+)/) || '4/8/12/16/24/32';
+
+if (!primary) {
+  console.error(`未能从 ${srcAbs} 解析出 Primary 色。`);
+  console.error('A 类格式需 `**Primary:** \\`#hex\\``；B 类格式自动提取失败。');
+  console.error('B 类设计系统建议走人工路径：浏览参考文档 → 提取配色 → 用 create-from-code 或手工创建。');
+  process.exit(1);
+}
+if (autoExtracted) {
+  console.warn('⚠️  B 类格式：配色为自动提取（brand/surface/text 上下文匹配），**请人工核对后再采用**。');
+}
+
+// 字体族解析：primary=X, display=Y, mono=Z → 系统栈兜底（零依赖：不引 webfont，仅保留字体名首选 + 系统栈）
+function fontStack(family) {
+  const f = (family || 'Inter').trim().replace(/^['"]|['"]$/g, '');
+  const isMono = /mono|code|menlo|consolas/i.test(f);
+  if (isMono) return `'${f}', ui-monospace, SFMono-Regular, Menlo, monospace`;
+  return `'${f}', -apple-system, 'Segoe UI', system-ui, 'PingFang SC', 'Microsoft YaHei', sans-serif`;
+}
+const famMap = Object.fromEntries(families.split(',').map(p => {
+  const [k, v] = p.split('=').map(x => (x || '').trim());
+  return [k, v];
+}));
+const fontDisplay = fontStack(famMap.display || famMap.primary);
+const fontBody = fontStack(famMap.primary);
+const fontMono = fontStack(famMap.mono || 'ui-monospace');
+
+// 字号阶梯：open-design 的 "12/14/16/20/24/32" → type scale 名称映射
+const scaleNums = scale.split('/').map(s => s.trim()).filter(Boolean);
+const typeScale = scaleNums.slice(0, 7).map((v, i) => {
+  const names = ['--text-xs', '--text-sm', '--text-base', '--text-lg', '--text-xl', '--text-2xl', '--text-3xl'];
+  return `${names[i]}: ${v}px`;
+}).join('；') || '--text-xs: 12px；--text-sm: 14px；--text-base: 16px；--text-lg: 20px；--text-xl: 24px；--text-2xl: 32px';
+
+// ── 组件契约表基线（20 类，来自 design-system-architect.md 的完整基线）──
+
+const CONTRACT_ROWS = [
+  '| Button | 交互 | primary / secondary / ghost / danger | sm / md / lg | default / hover / focus-visible / active / disabled / loading | 触发动作 | 用颜色单独传状态 |',
+  '| Input | 交互 | default / error / success | sm / md / lg | default / focus / disabled / readonly / error / filled | 文本录入 | 无 label |',
+  '| Select | 交互 | default / multiple / searchable | sm / md / lg | default / focus / disabled / error / open | 选项选择 | 超 10 项不用搜索 |',
+  '| Checkbox | 交互 | default / indeterminate | sm / md | default / hover / focus / disabled / checked | 多选 | — |',
+  '| Radio | 交互 | default | sm / md | default / focus / disabled / selected | 单选 | 超 7 项改用 Select |',
+  '| Switch | 交互 | default | md | default / focus / disabled / on / off | 二元开关 | 高危操作须确认 |',
+  '| Tag | 轻量 | default / success / warning / danger / info | sm / md | default / hover / closable¹ | 状态标记 | 用作按钮 |',
+  '| Icon | 豁免 | — | sm / md / lg | — | 语义图示 | emoji |',
+  '| Avatar | 轻量 | circle / square | sm / md / lg | default / fallback / loading | 用户标识 | — |',
+  '| Tooltip | 轻量 | default | — | hidden / visible | 补充说明 | 承载关键操作 |',
+  '| Modal | 交互 | default / confirm / destructive | sm / md / lg | open / loading / error / closing | 阻断式交互 | 嵌套 Modal |',
+  '| Drawer | 交互 | left / right / bottom | sm / md / lg | open / loading / error | 侧边任务面板 | — |',
+  '| Tabs | 交互 | line / pill | — | default / active / disabled / loading | 内容分组 | 超 7 个 tab |',
+  '| Table | 交互 | default / compact / striped | — | default / loading / empty / error / selected | 结构化数据 | 无分页超长列表 |',
+  '| Form | 交互 | single / two-column | — | untouched / dirty / submitted-pending / error | 字段集合 | 单页超 20 字段 |',
+  '| Card | 交互 | default / interactive / stat | — | default / hover / selected / loading | 内容容器 | 嵌套超 2 层 |',
+  '| Pagination | 交互 | default / simple | sm / md | default / disabled / loading | 分页导航 | — |',
+  '| FilterBar | 交互 | default / collapsible | — | default / expanded / applied | 筛选条件集合 | — |',
+  '| EmptyState | 豁免 | default / filtered / error | — | — | 空态承载 | 只有"暂无数据" |',
+  '| Toast | 交互 | success / warning / error / info | — | entering / visible / exiting | 轻量反馈 | 承载需用户操作的信息 |',
+];
+
+// ── 生成 base.md ──
+
+const base = `# ${title}
+
+> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）
+
+> 由 open-design 设计系统 \`${id}\`（Category: ${category}）转换生成（scripts/design-system-import.mjs v0.54.0）。
+> ${summary}
+> 来源归因：open-design（nexu-io）MIT License，"inspired by" 逆向工程描述，非官方资产。
+
+## color
+
+**A1-identity（8 必选）**
+- \`--bg\`: color-mix(in oklab, var(--surface), var(--fg) 3%)
+- \`--surface\`: ${surface}
+- \`--fg\`: ${text}
+- \`--muted\`: color-mix(in oklab, var(--fg), var(--surface) 45%)
+- \`--border\`: color-mix(in oklab, var(--fg), var(--surface) 88%)
+- \`--accent\`: ${primary}
+- \`--font-display\`: ${fontDisplay}
+- \`--font-body\`: ${fontBody}
+
+**语义色**：success ${success} / warning ${warning} / danger ${danger}${secondary ? ` / secondary ${secondary}` : ''}
+
+**A2-derived（color-mix 公式）**：--accent-hover / --accent-active / --focus-ring / --elev-raised（公式见 token-derivation.md）
+
+**B-slot 别名**：--fg-2 → var(--fg) / --meta → var(--muted) / --border-soft → var(--border) / --surface-warm → var(--surface)
+
+## typography
+
+- 字阶：${typeScale}
+- 行高：正文 1.5 / 标题 1.2
+- 字重：400（正文）/ 500-600（标题）
+
+## spacing
+
+- 阶梯（4 基数）：${spacingScale.split('/').map((v, i) => `${v.trim()}px`).join(' / ')}
+
+## layout
+
+- 栅格 12 列 / 断点 sm(640) md(1024) lg(1440) / 容器 max-width 1200px
+
+## components
+
+| 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |
+|------|------|----------|-------|--------|------|------|
+${CONTRACT_ROWS.join('\n')}
+
+## motion
+
+- duration 150–250ms / easing ease-out（\`cubic-bezier(0.2, 0, 0, 1)\`）
+
+## voice
+
+- 语气：${category} 语境的简洁专业表达——具体文案要求由项目 PRD 补充。
+
+## brand
+
+- 品牌主色：${primary}（accent 用法：主 CTA / 链接 / 选中态）
+
+## anti-patterns
+
+1. 禁止内联样式漂移
+2. 禁止非 token 颜色
+3. ${category} 语境：不得引入与来源风格冲突的装饰效果
+
+## palette
+
+- neutral / primary / success / warning / danger 各 50–900 阶梯（primary 以 ${primary} 为 500 锚点，公式见 token-derivation.md）
+
+## principles
+
+1. 一致性优先于局部创意——同类信息用同一呈现
+2. 清晰优于装饰——信息层级先于视觉效果
+3. 可访问性默认开启——所有交互元素满足 WCAG AA
+
+## governance
+
+- contract: v1
+- version: 0.1.0
+- 负责人: {项目角色}
+- 弃用策略: 组件弃用需在 changelog 记录 + 保留 1 个迭代周期
+- changelog: 见文末"变更履历"段
+
+## 变更履历
+
+| 时间 | 变更内容 | 来源 |
+|------|---------|------|
+| ${new Date().toISOString().slice(0, 10)} | 从 open-design \`${id}\` 转换生成 | design-system-import.mjs |
+`;
+
+const outPath = outArg ? resolve(outArg) : resolve(`.team-flow/design-system/base.md`);
+mkdirSync(dirname(outPath), { recursive: true });
+writeFileSync(outPath, base, 'utf-8');
+
+console.log(`base.md 已生成：${outPath}`);
+console.log(`  来源：open-design ${id}（${category}）`);
+console.log(`  accent=${primary} / surface=${surface} / text=${text}`);
+console.log(`  组件契约表：20 类基线（待审阅调整）`);
+// 提示中的脚本路径用**本脚本所在插件目录**解析（绝对路径，可直接复制执行）——
+// 裸 `node scripts/...` 在插件零拷贝安装下不解析（v0.54.0 P4 根因）。
+const pluginDir = dirname(dirname(fileURLToPath(import.meta.url)));
+console.log('\n下一步（由 design-system skill 的 Step 5 评审 → Step 6 落盘承接）：');
+console.log(`  1) node ${join(pluginDir, 'scripts', 'gen-primer.mjs')} ${outPath}     # 生成 primer（组件白名单 + digest，缺失会阻断 prototype Step 0）`);
+console.log(`  2) node ${join(pluginDir, 'scripts', 'guard', 'design-token-guard.mjs')} ${dirname(outPath)}  # 硬校验 + 六层审计`);