recipe-agent-team-design-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Team Design Spec Recipe

PREREQUISITE: Load
agent-team-shared
before any CLI command.
agent-team-run
and
agent-team-task
are required inside an agent-team run.

Worker integration: Inside an agent-team task, the worker must follow
recipe-agent-team-worker-checkpoint
for sync check, inbox handling, task start, and completion. This recipe defines artifact generation only.

前置要求： 在执行任何CLI命令前加载
agent-team-shared
。在agent-team运行过程中，
agent-team-run
和
agent-team-task
是必需的。

Worker集成： 在agent-team任务中，Worker必须遵循
recipe-agent-team-worker-checkpoint
进行同步检查、收件箱处理、任务启动与完成。本方案仅定义产物生成流程。

Prerequisites

前置条件

```
RUN_ID
```
exists. No inline fallback. If
```
RUN_ID
```
is missing, stop and ask the orchestrator to create one via
```
recipe-agent-team-run-lifecycle
```
; do not hand off to interview for this case.
If only an inline brief exists after a run is created, the orchestrator or assigned worker must materialize it unchanged to its Output Path as
```
design-brief.md
```
, updating only concrete path fields, then resume.

design-brief.md

exists at

_workspace/{run_id}/design/{slug}/design-brief.md

Brief's
```
Output
```
section sets a one-paragraph description, a
```
Slug
```
, and an
```
Output Path
```
.
Brief includes Acceptance source data (constraints, success criteria, priorities, tensions, failure modes).

RUN_ID

is missing, hand off to

recipe-agent-team-run-lifecycle

or the orchestrator. If brief content, Output, Slug, Output Path, source data, or confirmation is missing, hand off to

recipe-agent-team-design-interview

with the specific gap.

已存在
```
RUN_ID
```
，无内联回退方案。若
```
RUN_ID
```
缺失，需停止操作并请求编排器通过
```
recipe-agent-team-run-lifecycle
```
创建；此情况下不得转交至访谈流程。
若创建运行后仅存在内联简报，编排器或指派的Worker必须将其原封不动地生成到指定Output Path，保存为
```
design-brief.md
```
，仅更新具体路径字段后再恢复操作。

design-brief.md

已存在于

_workspace/{run_id}/design/{slug}/design-brief.md

路径下。

简报的
```
Output
```
部分需包含一段描述、一个
```
Slug
```
和一个
```
Output Path
```
。
简报需包含验收源数据（约束条件、成功标准、优先级、矛盾点、失败模式）。

若

RUN_ID

缺失，转交至

recipe-agent-team-run-lifecycle

或编排器。若简报内容、Output、Slug、Output Path、源数据或确认信息缺失，需将具体缺口信息一并转交至

recipe-agent-team-design-interview

。

Pattern Library

模式库

references/

holds non-binding artifact patterns.

Pattern Hints

use basenames only (for example,

ui.md

) and resolve relative to

references/

. The brief's

Output

description is authoritative; load patterns only when

Pattern Hints

cites them, and only as guidance for artifact shape, file naming, and acceptance heuristics.

Pattern Hint	Typical use
`ui.md`	Screens, flows, wireframes, components, surface tokens
`logo-branding.md`	Brand identity, wordmark, symbol, usage rules, palette
`design-system.md`	Reusable token catalog (DESIGN.md alpha spec) shared across surfaces
`character.md`	Playable/NPC character roster, skills, animation, assets
`environment.md`	Level/zone/biome layout, set dressing, lighting
`icon-illustration.md`	Icon set, illustration system, taxonomy, SVG manifest

When the Output spans multiple patterns (e.g., shared tokens + a UI screen), default to separate Outputs and sequential passes. Compose patterns inside one Output Path only when the requester or task explicitly asks for one combined Output; record pattern precedence in the artifact citation (e.g.,

patterns: ui.md > design-system.md

) and resolve conflicts by Output description first, then first-listed pattern.

references/

目录下存放非绑定性产物模式。

Pattern Hints

仅使用基础文件名（例如

ui.md

），并相对

references/

目录解析路径。简报的

Output

描述为权威依据；仅当

Pattern Hints

引用模式时才加载，且仅作为产物结构、文件命名和验收启发的参考。

Pattern Hint	典型用途
`ui.md`	界面、流程、线框图、组件、surface tokens
`logo-branding.md`	品牌标识、文字商标、符号、使用规则、调色板
`design-system.md`	可复用令牌目录（DESIGN.md alpha规范），跨表层共享
`character.md`	可操控/非玩家角色（NPC）列表、技能、动画、资源
`environment.md`	关卡/区域/生物群系布局、场景装饰、灯光
`icon-illustration.md`	图标集、插画系统、分类体系、SVG清单

当Output涉及多种模式（例如共享令牌+UI界面）时，默认拆分为独立Output并按顺序生成。仅当请求者或任务明确要求合并为单一Output时，才在同一Output Path下组合模式；需在产物引用中记录模式优先级（例如

patterns: ui.md > design-system.md

），冲突时优先以Output描述为准，其次按列表首个模式处理。

Pipeline

流程 pipeline

Validate brief → consult pattern hints → produce artifacts → acceptance.

验证简报 → 参考模式提示 → 生成产物 → 验收

Validate Brief

验证简报

Before producing any artifact, confirm:

Brief's

Output Path

equals

_workspace/{run_id}/design/{slug}/

(the brief's own directory).

Brief's
```
Output
```
description is a non-empty paragraph (not a single label).
Brief's
```
Slug
```
is kebab-case and matches the directory name.
Synthesis Gate confirmation is recorded as a requester quote or
```
quick-draft requested
```
.

Any mismatch → stop and hand off to the interview recipe with the specific gap.

生成任何产物前，需确认：

简报的
```
Output Path
```
等于
```
_workspace/{run_id}/design/{slug}/
```
（简报自身所在目录）。
简报的
```
Output
```
描述为非空段落（而非单一标签）。
简报的
```
Slug
```
采用短横线命名法（kebab-case）且与目录名匹配。
综合门限确认已记录为请求者引用或
```
quick-draft requested
```
。

若存在任何不匹配，需停止操作并将具体缺口信息转交至访谈方案。

Dispatch

调度 Dispatch

Read brief's
```
Output
```
description and
```
Pattern Hints
```
.
Load only patterns cited in
```
Pattern Hints
```
, resolving basenames under
```
references/
```
. If hints are
```
none
```
, infer artifact shape from the Output description.
Produce artifacts under the brief's Output Path. File names and section structure come from cited patterns when applicable, or from the Output description when not.
Every artifact cites the brief at the top:

markdown

<!-- routed by recipe-agent-team-design-spec; brief: <brief path>; patterns: <patterns used or "none"> -->

Exception: a

DESIGN.md

(token catalog) cites the brief through YAML frontmatter (

routed_by

brief

patterns

) instead — see

references/design-system.md

读取简报的
```
Output
```
描述和
```
Pattern Hints
```
。
仅加载
```
Pattern Hints
```
中引用的模式，相对
```
references/
```
目录解析基础文件名。若提示为
```
none
```
，则根据Output描述推断产物结构。
在简报的Output Path下生成产物。文件名和章节结构优先使用引用模式的规则，无引用时则依据Output描述。
每个产物顶部需引用简报：

markdown

<!-- routed by recipe-agent-team-design-spec; brief: <brief path>; patterns: <patterns used or "none"> -->

例外情况：

DESIGN.md

（令牌目录）需通过YAML前置元数据引用简报（

routed_by

、

brief

、

patterns

）——详见

references/design-system.md

。

Acceptance

验收 Acceptance

Every artifact exists under the brief's Output Path.
Each artifact addresses at least one Priority Ranking entry and at least one Success Criterion; orphan artifacts are rejected.
Cited pattern constraints are followed where applicable; deviations from file naming or section structure are documented in the artifact's citation.
Every Pattern Hint listed in the brief is a valid Pattern Library basename and is either used or explicitly rejected with a reason.
When running as an agent-team task, the worker calls
```
agent-team task complete
```
with
```
--artifact
```
set to the Output Path directory (e.g.,
```
_workspace/{run_id}/design/dashboard/
```
), and
```
--evidence
```
listing every produced filename plus the brief path. A single-file Output (e.g., DESIGN.md) may point
```
--artifact
```
at the file directly.

所有产物均存在于简报的Output Path下。
每个产物至少对应一项优先级排名条目和一项成功标准；孤立产物将被拒绝。
适用情况下需遵循引用模式的约束；若偏离文件名或章节结构，需在产物引用中记录说明。
简报中列出的每个Pattern Hint均为模式库中的有效基础文件名，且已被使用或明确标注拒绝理由。
作为agent-team任务运行时，Worker需调用
```
agent-team task complete
```
，并将
```
--artifact
```
设置为Output Path目录（例如
```
_workspace/{run_id}/design/dashboard/
```
），
```
--evidence
```
列出所有生成的文件名及简报路径。单一文件Output（例如DESIGN.md）可直接将
```
--artifact
```
指向该文件。

Multi-Output Runs

多Output运行

A single

RUN_ID

may host multiple design Outputs (e.g., a token catalog followed by a UI screen that cites it). Each pass:

has its own brief and Output Path
consults only the patterns its brief hints at
may cite earlier pass artifacts via Upstream Inputs

Passes are sequential. Do not parallelize Output passes in the same context window.

单个

RUN_ID

可包含多个设计Output（例如先生成令牌目录，再生成引用该目录的UI界面）。每个阶段：

拥有独立的简报和Output Path
仅参考自身简报提示的模式
可通过上游输入引用早期阶段的产物

阶段需按顺序执行，不得在同一上下文窗口中并行处理多个Output阶段。

Do Not

禁止操作

Re-interview the requester; that responsibility belongs to the interview recipe.
Render PNG, SVG, Figma, or binary assets.

Promote

design_md_version

past

alpha

without verifying the upstream

google-labs-code/design.md

spec.

Force the Output into a pattern shape the brief did not endorse.

不得重新访谈请求者；该职责归属于访谈方案。
不得生成PNG、SVG、Figma或二进制资源。
未经验证上游
```
google-labs-code/design.md
```
规范，不得将
```
design_md_version
```
升级至
```
alpha
```
版本之后。
不得强行将Output转换为简报未认可的模式结构。

Hand Off

转交规则

Situation	Hand off
Artifacts ready, implementation needed	Downstream tasks cite brief + artifacts; workers use `recipe-agent-team-worker-checkpoint`
Brief incomplete or ambiguous	`recipe-agent-team-design-interview`
Plan gaps surface mid-spec	`recipe-agent-team-planning-grill`
Term ambiguity surfaces	`recipe-agent-team-terminology-context`
Backend gaps surface	`recipe-agent-team-architecture-design`
Output requires a shared token catalog the brief did not produce	Interview for an Output of `reusable token catalog` ; resume here for the consumer Output after `DESIGN.md` exists

场景	转交目标
产物已就绪，需进行实现	下游任务引用简报+产物；Worker使用 `recipe-agent-team-worker-checkpoint`
简报不完整或存在歧义	`recipe-agent-team-design-interview`
规范生成过程中发现计划缺口	`recipe-agent-team-planning-grill`
出现术语歧义	`recipe-agent-team-terminology-context`
发现后端缺口	`recipe-agent-team-architecture-design`
Output需要简报未生成的共享令牌目录	访谈生成 `reusable token catalog` 类型的Output；待 `DESIGN.md` 生成后，在此恢复消费者Output的生成