team-ui

Team UI

如果未提供参数，请输出用法说明并退出，不要启动任何 Agent，也不要读取任何设计文件：

用法：/team-ui [UI 功能描述] [--review full|lean|solo] — 描述要构建的屏幕或 UI 功能（例如，inventory screen、main menu、combat HUD）。此处不要使用 AskUserQuestion；直接输出说明。

调用此技能时，通过结构化流程协调 UI 团队。

决策节点： 在每个阶段转换时，使用 AskUserQuestion 将子 Agent 的提案作为可选项呈现给用户。在对话中写出 Agent 的完整分析，然后用简洁标签记录决策。在 collaborative 模式下，必须先获得用户批准才能进入下一阶段。在 guided 模式下，除非某个阶段被 BLOCKED，否则流程会自动推进；在 autonomous 模式下，流程会端到端运行，并通过 log_decision 记录每个阶段的结果。automation_always_ask 类别（is_always_ask_category 助手）中的决策无论处于何种模式，都会始终提示用户。请参阅 .claude/docs/automation-modes.md。

阶段 0：解析配置

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,team.size

以上已解析——直接使用；--review 会覆盖 review_mode。若未阻止 → 使用 .claude/docs/config-resolution.md 中的默认值。

review_mode 决定 director-gate 的深度，而此流水线没有 director gate： 无论 review_mode 为何，以下阶段都不会生成 CD-、TD-、PR- 或 AD-PHASE-GATE。其阶段关卡是流水线自身的决策点（定义见下文的 team.size），在这些关卡上工作的 Agent 是团队成员，而非 director gate。

automation 决定上文「决策点」说明中的行为。有关各模式如何改变流水线行为，请参阅上文「决策点」说明和 .claude/docs/automation-modes.md。

team.size：决定哪些 Agent 会被激活（与 review_mode 的关卡深度及工作流文档相互独立）。

• individual（默认）：ui-programmer + ux-designer。其他 Agent 通过这两者征询，不会单独生成。
• small：+ accessibility-specialist + art-director。
• studio：+ 引擎 UI 专家 + 对抗性评审环节：告知阶段 4 的评审者「你的任务不是确认这与规范一致——而是找出不符合之处」，并在报告中说明已执行该环节。 在 individual 模式下，需要的非核心 Agent 会由最近的活跃核心 Agent 处理，并附带说明性备注。「阶段关卡」指本流水线明确列出的、以 AskUserQuestion 决策点结束的任何阶段——上文「决策点」中的转换，或下文流水线中写明的 Gate 步骤——无论 automation 模式为何。 guided 和 autonomous 会改变通过关卡的方式（自动推进，或使用 log_decision 记录），而非关卡是否存在，因此下文有界例外条件 (3) 在所有模式下都适用。仅限在「阶段关卡」执行的 Agent 会在这些关卡生成，其他时候不会生成。此活跃集合范围规则适用于下方整个流水线：任何阶段若指定了活跃集合之外的 Agent，都由最近的核心 Agent 处理，而非生成该 Agent。

在步骤 1 之前公布活跃集合——绝不能默默缩减。 生成任何内容之前，用一行说明本次运行实际会生成哪些 Agent，以及下方流水线列出了哪些 Agent、但在已解析的 team.size 下不会生成。例如：

活跃集合（team.size: <已解析值>）：<上方该规模所列的 Agent>。 本次运行不会生成：<此流水线列出的所有其他 Agent>——由 <最近的活跃核心 Agent> 代为征询。提高 team.size（或 modes.rigor）以扩大范围。

直接根据上方的 team.size 列表和此文件自身流水线列出的 Agent 填写，不要照抄示例。不同编排器的两组内容各不相同。

下方的流水线看起来会并行调用多个 Agent，但在已发布的默认配置下只会使用一到两个 Agent——team-release 列出十个 Agent，实际运行一个；team-narrative 在五个阶段中列出六个 Agent，实际仅运行 writer。这种缩减是正确的： team.size 以严谨度为导向，默认范围较窄是控制令牌消耗的手段。 如果不说明，读者就无法区分正确缩减的运行与失效的流水线；而上文「由最近的核心 Agent 处理，并附带说明性备注」规则只会在路由时触发，并不会说明整体运行的实际范围。

这与本文件其他位置报告跳过检查的规则相同：已执行但从未明示的约束，在阅读输出的人看来，与从未执行过的约束无法区分。

团队组成

• ux-designer — 用户流程、线框图、无障碍设计、输入处理
• ui-programmer — UI 框架、屏幕、控件、数据绑定、实现
• art-director — 视觉风格、布局润色、与美术规范的一致性
• engine UI specialist — 根据引擎特定的最佳实践验证 UI 实现模式（来自 project.yaml 中的 specialists.ui；如果不存在，则使用 .claude/docs/technical-preferences.md 中 ## Engine Specialists 下的 UI Specialist 条目）
• accessibility-specialist — 在 Phase 4 审查无障碍合规性

specialists.ui: null 表示未设置。 将其视为不存在，并跳过引擎 UI 专家；切勿将 null 作为 Agent 名称启动。v1.0 迁移会在设置任一成员时写入整个 specialists 块，因此此处的 null 很常见——而配置读取器会将其作为非空字符串 "null" 返回。

此流水线使用的模板：

• ux-spec.md — 标准屏幕/流程 UX 规范
• hud-design.md — HUD 专用 UX 规范
• interaction-pattern-library.md — 可复用的交互模式
• accessibility-requirements.md — 已确定的无障碍等级和要求

如何委派

使用 Agent 工具将每位团队成员作为子 Agent 启动：

• subagent_type: ux-designer — 用户流程、线框图、无障碍访问、输入处理
• subagent_type: ui-programmer — UI 框架、屏幕、控件、数据绑定
• subagent_type: art-director — 视觉风格、布局润色、美术圣经一致性
• subagent_type: [UI engine specialist] — 特定引擎的 UI 模式验证（例如 unity-ui-specialist、ue-umg-specialist、godot-specialist）
• subagent_type: accessibility-specialist — 无障碍合规审查

向每位 Agent 提供简明任务说明——不要倾倒所有上下文。 只读取一次共享输入，并在提示中传递提炼后的任务说明：只提供每位 Agent 实际需要的内容，绝不要提供你已读过的文档路径（Agent 收到路径后会重新读取整个文件）。仅当你尚未读过某份文档且只有该 Agent 需要时，才提供路径。

以交付约定结束每条 Agent 提示：“将完整输出写入 [path]——该指定路径即为你在下方限定例外范围内的写入授权，因此无需另行请求批准即可写入。仅返回：(1) 写入的路径；(2) 不超过 5 条的决策摘要；(3) 任何 BLOCKED/CONCERNS 项，每项一行。不要复述你读过的文档。”如果没有这段约定，Agent 会把读过的所有内容都返回到当前会话。**实现文件除外：**编写代码或资源的 Agent 应先返回将创建或修改的文件列表；只有你询问过一次文件列表且用户表示同意后，其交付约定才能列出这些文件（文件写入协议）——授权写入的是用户对此的答复，而非限定例外。

将 [path] 替换为实际路径。 工作产物应放在 production/ui/[feature-name]/ 下，其中 slug 与 Phase 1b 的 design/ux/[feature-name].md 中所用的 slug 相同。每位 Agent 使用一个文件，这样并行进行的 Phase 4 审查就不会共用同一个文件：

阶段 / Agent	写入位置
2 art-director	production/ui/[feature-name]/visual-design.md
3 engine UI specialist	production/ui/[feature-name]/engine-notes.md
3 ui-programmer	代码根目录——一次实现请求中列出的文件（文件写入协议），不属于限定例外范围
4 ux-designer、art-director、accessibility-specialist	production/ui/[feature-name]/review-[agent].md，每位 Agent 各写一个

UX 规范（Phase 1b）和任何模式库更新都应放在 design/ 下，不属于限定例外范围：使用 /ux-design，或者由 Agent 在写入前询问。

为什么这不违反协作协议。 CLAUDE.md 要求 Agent 在 Write/Edit 之前询问“可以将此内容写入 [filepath] 吗？”。在此启动的子 Agent 无需询问即可写入，这是有意设定的有限例外，并非疏忽——与已允许 consistency-check 追加内容到 active.md 的做法相同。只有同时满足以下三项条件时，例外才适用：(1) 路径由你在提示中指定，因此用户在批准该阶段时已批准目标位置；(2) 写入的是 production/、docs/ 或 tests/ 下的新产物，绝不修改现有源文件或配置；(3) 产出该文件的阶段本身受 AskUserQuestion 控制，必须先获得确认才能进入下一阶段。除此之外，Agent 必须先询问。不要通过逐个询问子 Agent 来“修复”此问题——每个阶段都逐个询问每位 Agent 会让协调流程无法使用，因此才需要此例外。

在工作流允许的情况下，并行启动相互独立的 Agent（例如，Phase 4 的审查 Agent 可以同时运行）。

工作流

阶段 1a：收集上下文

在设计任何内容之前，先阅读并综合信息。按章节阅读每份 GDD：使用 Grep 工具查找所需标题（模式为 ^#，内容模式），再使用 offset 和 limit 阅读相应范围。

• design/gdd/game-concept.md — 平台目标和预期受众（或者 design/game-brief.md，当 rigor: minimal 时用于替代它的一页式简介——其中的 "Who it's for" 一行说明了受众；不包含平台信息）
• design/player-journey.md — 玩家到达此界面时的状态和上下文
• 与此功能相关的所有 GDD UI Requirements 章节
• design/ux/interaction-patterns.md — 可复用的现有模式（不要重新发明）
• design/accessibility-requirements.md — 已承诺的无障碍等级（Basic、Standard、Comprehensive 或 Exemplary）

在开始设计之前，报告上述每份文档的状态。 阶段 1a 会读取五份输入，其中任何一份都可能缺失。逐一列出，并标明存在或 ABSENT。

绝不能默默略过 design/accessibility-requirements.md。 该文件记录了已承诺的无障碍等级，阶段 3 将据此实施，而阶段 4 将据此设定门槛（“根据已承诺的无障碍等级验证是否合规……将任何违规项标记为阻塞项”）。如果文件缺失，就没有等级，因此该门槛没有评判标准，检查内容为空却会判定通过——这相当于一个永远不会失败的断言。文件缺失时：

• 在此处说明，并在后续阶段继续注明：阶段 4 必须报告 Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent) 且不得报告无障碍门槛已通过。
• ux-designer 应明确说明设计所依据的等级，并将其标为假设，让后续读者知道这只是推定，而非已承诺的要求。
• 建议使用 /ux-design accessibility 来确立该等级。

概念文档（design/gdd/game-concept.md 和 design/game-brief.md 均不存在）、design/player-journey.md 或 design/ux/hud.md 缺失并不构成阻塞，但要在传递给 ux-designer 的简介中列出每份缺失的文档，让其了解缺少哪些上下文，而不是自行推断。

如果 design/ux/interaction-patterns.md 不存在，应立即指出这一缺口：

"interaction-patterns.md does not exist — no existing patterns to reuse."

然后使用 AskUserQuestion 提供以下选项：

• (a) 先运行 /ux-design patterns 建立模式库，再继续
• (b) 在没有模式库的情况下继续——ui-programmer 会将创建的所有模式视为新模式，并在完成时将每个模式添加到新的 design/ux/interaction-patterns.md 中

不得仅凭功能名称或 GDD 编造或假设模式。如果用户选择 (b)，应在阶段 3 明确指示 ui-programmer 将所有模式视为新模式，并在实施完成后将其记录到 design/ux/interaction-patterns.md 中。在最终摘要报告中注明模式库的状态（已创建 / 缺失 / 已更新）。

向 ux-designer 提供简要的上下文摘要：玩家正在做什么、他们需要什么、有哪些约束，以及哪些现有模式与之相关。

阶段 1b：编写 UX 规范

调用 /ux-design [feature name] 技能，或直接委派给 ux-designer，按照 ux-spec.md 模板生成 design/ux/[feature-name].md。

如果设计的是 HUD，则改用 hud-design.md 模板，而不是 ux-spec.md。

特殊情况说明：

• 如果要专门设计 HUD，请使用 argument: hud 调用 /ux-design（例如 /ux-design hud）。
• 对于交互模式库，请在项目启动时运行一次 /ux-design patterns，并在后续阶段引入新模式时更新它。

输出：填写了所有必需规范章节的 design/ux/[feature-name].md。

阶段 1c：UX 评审

规范完成后，调用 /ux-review design/ux/[feature-name].md。

关卡：在评审结论为 APPROVED 之前，不得进入阶段 2。如果结论为 NEEDS REVISION，ux-designer 必须在同一份规范中解决标出的问题，并重新运行评审——保留并修订该规范，绝不丢弃。用户可以明确接受 NEEDS REVISION 带来的风险并继续，但必须经过慎重决定——在询问是否继续之前，通过 AskUserQuestion 呈现具体问题。

结论为 NOT ASSESSED 时同样不得继续，用户也可以用相同方式选择继续。修复它需要补充输入，而不是修订：列出 /ux-review 无法评估的维度，以及每个维度缺少的输入（例如，未确定某个层级时使用 /ux-design accessibility）。没有该输入就重新运行评审，只会得到相同结论，因此应先提出生成所需输入。

用户在 NEEDS REVISION 或 NOT ASSESSED 后选择继续时，最终报告必须记录这一覆盖决定：评审结论、尚未解决的问题或未评估的维度，以及用户选择继续这一事实。

阶段 2：视觉设计

委派给 art-director：

• 审查完整的 UX 规范（流程、线框图、交互模式、无障碍说明），而不只是线框图图片
• 根据艺术圣经应用视觉风格：颜色、字体、间距、动画风格
• 检查视觉设计是否保留无障碍合规性：验证颜色对比度，并确认颜色绝不是状态的唯一标识（必须通过形状、文本或图标加以强调）
• 详细说明美术资源流程所需的所有资源：指定尺寸的图标、背景纹理、字体、装饰元素，以及精确的尺寸和格式要求
• 确保与现有已实现的 UI 屏幕保持一致
• 输出：包含风格说明和资源清单的视觉设计规范

阶段 3：实现

开始实现前，启动 engine UI specialist（从 project.yaml 中读取 specialists.ui；如果不存在，则使用 .claude/docs/technical-preferences.md 中 ## Engine Specialists 的 UI Specialist 条目），请其审查 UX 规范和视觉设计规范，并提供特定于引擎的实现指导：

• 此屏幕应使用哪种引擎 UI 框架？（例如，Unity 中的 UI Toolkit 或 UGUI、Godot 中的 Control 节点或 CanvasLayer、Unreal 中的 UMG 或 CommonUI）
• 对于拟定的布局或交互模式，有哪些引擎特有的注意事项？
• 针对此引擎，推荐使用怎样的控件/节点结构？
• 输出：交给 ui-programmer 的引擎 UI 实现说明，供其开始实现前参考

如果未配置引擎，则跳过此步骤。**在本次运行的输出中记录 Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)。**如果跳过检查时不做任何说明，就无法区分检查未进行和检查已通过；读者将无法得知从未寻求引擎指导。

委派给 ui-programmer：

• 遵循 UX 规范和视觉设计规范实现 UI
• 使用 design/ux/interaction-patterns.md 中的模式——不要重新发明已有说明的模式。如果某个模式基本适用但需要修改，请记录偏差并标记给 ux-designer 审查。
• UI 绝不拥有或修改游戏状态——仅用于显示；玩家的所有操作都必须触发事件
• 所有文本都必须通过本地化系统处理——不得硬编码面向玩家的字符串
• 支持两种输入方式（键盘/鼠标和游戏手柄）
• 根据 design/accessibility-requirements.md 中已确定的等级实现无障碍功能
• 将数据绑定到游戏状态
• 如果实现过程中创建了任何新的交互模式（即模式库中尚未包含的模式），必须在标记实现完成之前将其添加到 design/ux/interaction-patterns.md
• 输出：已实现的 UI 功能

第 4 阶段：评审（并行）

并行委派：

• ux-designer：确认实现与线框图和交互规范一致。测试仅使用键盘和仅使用游戏手柄的导航。检查无障碍功能是否正常运行。
• art-director：确认视觉风格与美术规范一致。至少检查最低和最高支持分辨率。
• accessibility-specialist：根据 design/accessibility-requirements.md 中已承诺的无障碍等级检查合规性。发现任何违规都应标记为阻塞问题。如果该文件不存在，则没有已承诺的等级，因此此关卡没有评判标准：报告 Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)，不要报告该关卡已通过。沿用第 1a 阶段记录的假设等级，并明确说明该等级是假设的。

所有三个评审流都必须提交报告后，才能进入第 5 阶段。

第 5 阶段：润色

• 处理所有评审反馈
• 确认动画可以跳过，并遵循玩家的动态效果减少偏好
• 确认 UI 音效通过音频事件系统触发（不得直接调用音频）
• 在所有支持的分辨率和宽高比下测试
• 确认 design/ux/interaction-patterns.md 是最新的——如果在此功能的实现过程中引入了任何新模式，确认它们已添加到模式库中
• 确认所有 HUD 元素均符合 design/ux/hud.md 中定义的视觉预算（元素数量、屏幕区域分配、最大不透明度值）

快速参考 — 何时使用哪项技能

• /ux-design — 从头为某个屏幕、流程或 HUD 编写新的 UX 规范
• /ux-review — 在实现前验证已完成的 UX 规范
• /team-ui [feature] — 从概念到润色的完整流程（内部调用 /ux-design 和 /ux-review）
• /quick-design — 无需完整 UX 规范的小型 UI 更改

错误恢复协议

首先，验证产物。 如果返回约定中指定了路径，在认定阶段已完成前，请先检查该路径是否存在——指定的产物若未写入磁盘，即表示阶段失败，无论回复读起来多么流畅。 Agent 可能耗费整个阶段，最后返回一段看似合理的开场白，却什么也没写；这既不属于 BLOCKED，也不是错误或“无法完成”，因此下面的触发条件永远不会生效。请明确指出未满足的约定并恢复执行；上下文通常仍然可用。

如果任何已启动的 Agent 返回 BLOCKED、出错或无法完成：立即报告，不要越过其阻塞的依赖，并始终提供部分报告。 被跳过的 Agent 部分必须保留为明确标注的缺项——不得自行补写内容。完整流程见：.claude/docs/error-recovery-protocol.md。

常见阻塞问题：

• 输入文件缺失（未找到 story、GDD 缺失）→ 转交给负责创建该文件的技能
• ADR 状态为 Proposed → 不要实现；待其决议后，使用 /architecture-decision accept ADR-NNNN 接受
• 范围过大 → 通过 /create-stories 拆分为两个 story
• ADR 与 story 之间的指示冲突 → 报告冲突，不要自行猜测

文件写入协议

所有文件写入（UX 规格、交互模式库更新、实现文件）均交由子 Agent 和子技能完成。两者遵循不同的规则：

• 通过 Agent 启动的子 Agent（例如 ui-programmer）遵循上文“为什么这不违反协作协议”中记录的有限例外——路径由你指定，产物是在 production/、docs/ 或 tests/ 下新建的文件，并且该阶段受 AskUserQuestion 控制。子 Agent 在这些范围内无需每次写入前都征求同意；超出范围则必须先询问。 实现文件（ui-programmer 在代码根目录下创建的代码）不在这些范围内：ui-programmer 会返回将要创建或修改的文件清单，你一次性就这组文件征求同意，得到肯定答复后再写入。
• 子技能（/ux-design）不是子 Agent，例外规则不适用于它们。它们须遵循常规协作协议，并在写入前征求同意。

此协调器不会直接写入文件。

输出

提供一份总结报告，涵盖：UX 规格状态、UX 评审结论、视觉设计状态、实现状态、无障碍合规性、输入方式支持、交互模式库更新状态，以及任何待解决的问题。

结论：COMPLETE — UI 功能已通过完整流程交付（UX 规格 → 视觉设计 → 实现 → 评审 → 润色）。

如果无障碍检查门槛（尚无已提交的级别）或引擎验证（尚未配置引擎）未评估，结论必须逐项列明——不得只写 COMPLETE：

结论：COMPLETE — [accessibility | engine validation] NOT ASSESSED ([reason]) — UI 功能已交付；无法执行指定检查。

结论：BLOCKED — 流程已中止；停止前须说明阻塞问题及其所属阶段。

后续步骤

• 如果最终规格尚未获批，请运行 /ux-review。
• 结束事项前，请对 UI 实现运行 /code-review。
• 如果需要进行视觉或音频润色，请运行 /team-polish。