builder-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Builder Phase Workflow

Builder 阶段工作流

You have been assigned a full phase to implement. Your spawn prompt contains the phase file path and plan folder. This skill teaches you how to handle the entire phase end-to-end.

你被分配了一个完整阶段的实现任务。你的生成提示中包含阶段文件路径和计划文件夹。本Skill将指导你端到端处理整个阶段。

Why This Workflow Exists

此工作流的存在意义

The user experienced builders that guessed at patterns, skipped tests, and produced inconsistent code. Each step below prevents a specific failure:

Step	Prevents
Read phase completely	Missing requirements, user has to re-explain
Pre-flight test check	Cascading failures from broken previous phases
Find reference file	Guessing at patterns, code doesn't match codebase
Invoke domain skill	Missing project-specific conventions
TDD first (Step 0)	Untested code, bugs discovered in production

用户遇到过会猜测模式、跳过测试且生成代码不一致的Builder。以下每个步骤都能预防特定的失败情况：

步骤	预防问题
完整读取阶段内容	遗漏需求，导致用户需要重新解释
预飞行测试检查	由前序阶段代码问题引发的连锁失败
查找参考文件	猜测代码模式，导致代码与代码库不匹配
调用领域Skill	遗漏项目特定的约定规范
先做TDD（步骤0）	代码未测试，在生产环境中发现bug

Step 1: Read the Phase

步骤1：读取阶段内容

Read the phase file from your spawn prompt. Extract:

Prerequisites & Clarifications — check for unanswered questions first
Requirements (Functional + Technical)
Implementation Steps (Step 0 through Step N)
Acceptance Criteria (your success metrics)

If ANY prerequisite question is unanswered:

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: "Phase has unanswered prerequisite questions. Cannot proceed.",
  summary: "Blocked: unanswered prerequisites"
})

Then STOP and wait for instructions.

从你的生成提示中读取阶段文件。提取以下信息：

前置条件与澄清事项 — 首先检查是否有未解答的问题
需求（功能需求 + 技术需求）
实现步骤（从步骤0到步骤N）
验收标准（你的成功衡量指标）

如果存在任何未解答的前置条件问题：

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: "Phase has unanswered prerequisite questions. Cannot proceed.",
  summary: "Blocked: unanswered prerequisites"
})

然后停止操作并等待指令。

Step 2: Pre-Flight Test Check

步骤2：预飞行测试检查

Skip for Phase 01 — no previous phases exist.

For Phase 02+:

bash

pnpm test

Exit code 0 → proceed to Step 3
Exit code ≠ 0 → check if failures are from current phase's TDD (expected) or previous phases
- Previous phase failures: fix them first, re-run to confirm green
- Current phase TDD failures: expected, proceed

阶段01可跳过 — 不存在前序阶段。

对于阶段02及以后：

bash

pnpm test

退出码为0 → 继续步骤3
退出码≠0 → 检查失败是来自当前阶段的TDD（预期情况）还是前序阶段
- 前序阶段失败：先修复问题，重新运行测试确认通过
- 当前阶段TDD失败：属于预期情况，继续执行

Step 3: Invoke Domain Skill and Find Reference

步骤3：调用领域Skill并查找参考文件

Your spawn prompt includes a

Skill:

field (extracted from the phase frontmatter by the orchestrator). If present, use that value. Otherwise, check the phase frontmatter for a

skill

field, or determine from content:

Phase Focus	Skill	Reference Glob
Database schema, migrations, RLS	`postgres-expert`	`supabase/migrations/*.sql`
Server actions, services, API	`server-action-builder`	`app/home/[account]/*/server-actions*.ts`
React forms with validation	`react-form-builder`	`app/home/[account]/*/_components/.tsx`
E2E tests	`playwright-e2e`	`e2e/tests/*/.spec.ts`
React components, pages	`vercel-react-best-practices`	`app/home/[account]/*/_components/.tsx`
UI/UX	`web-design-guidelines`	`app/home/[account]/*/_components/.tsx`
Service layer	`service-builder`	`app/home/[account]/*/service*.ts`

Glob the reference pattern → read ONE file
Extract 3-5 key patterns: function signatures, imports, naming, error handling, post-operation hooks
Invoke the domain skill:
```
Skill({ skill: "skill-name" })
```

The reference file is your ground truth. Your code must structurally match it.

你的生成提示中包含

Skill:

字段（由编排器从阶段前置元数据中提取）。如果存在该字段，使用对应的值。否则，检查阶段前置元数据中的

skill

字段，或根据内容判断：

阶段重点	Skill	参考文件匹配模式
数据库模式、迁移、RLS	`postgres-expert`	`supabase/migrations/*.sql`
服务器操作、服务、API	`server-action-builder`	`app/home/[account]/*/server-actions*.ts`
带验证的React表单	`react-form-builder`	`app/home/[account]/*/_components/.tsx`
E2E测试	`playwright-e2e`	`e2e/tests/*/.spec.ts`
React组件、页面	`vercel-react-best-practices`	`app/home/[account]/*/_components/.tsx`
UI/UX	`web-design-guidelines`	`app/home/[account]/*/_components/.tsx`
服务层	`service-builder`	`app/home/[account]/*/service*.ts`

使用匹配模式查找参考文件 → 读取一个文件
提取3-5个关键模式：函数签名、导入方式、命名规则、错误处理、操作后钩子
调用领域Skill：
```
Skill({ skill: "skill-name" })
```

参考文件是你的事实依据。你的代码必须在结构上与它匹配。

Step 4: Create Internal Task List

步骤4：创建内部任务列表

Create tasks via

TaskCreate

for each implementation step. This is not optional — tasks survive context compacts and are your only recovery mechanism if context is compacted mid-phase. Without them, you must restart the entire phase from scratch.

Prefix all task subjects with
[Step]
to distinguish from the orchestrator's phase-level tasks in the shared team task list. Mark each task

in_progress

before starting and

completed

when done.

Task descriptions must be self-contained:

File paths to create/modify
Function signatures, key parameters
Which services/actions to call
Acceptance criteria for that step

Bad:

"Create the dropdown component"

Good:

"[Step] Create change-role-dropdown.tsx at app/home/[account]/roles/_components/. Props: { membershipId, accountSlug }. Fetch roles via listRolesAction, filter by hierarchy_level. Use @/components/ui Select, Badge."

Always start with Step 0: TDD.

为每个实现步骤通过

TaskCreate

创建任务。此步骤为必填项——任务会在上下文压缩后保留，是你在阶段执行中途遇到上下文压缩时的唯一恢复机制。如果没有任务列表，你必须从头开始重新执行整个阶段。

所有任务主题前缀为
[Step]
，以便在共享团队任务列表中与编排器的阶段级任务区分开。开始执行前将每个任务标记为

in_progress

，完成后标记为

completed

。

任务描述必须独立完整：

要创建/修改的文件路径
函数签名、关键参数
要调用的服务/操作
该步骤的验收标准

错误示例：

"Create the dropdown component"

正确示例：

"[Step] Create change-role-dropdown.tsx at app/home/[account]/roles/_components/. Props: { membershipId, accountSlug }. Fetch roles via listRolesAction, filter by hierarchy_level. Use @/components/ui Select, Badge."

始终从步骤0：TDD开始。

Step 5: Implement

步骤5：执行实现

Step 0 (TDD) first — write failing tests before implementation code
Remaining steps sequentially — follow the phase document exactly
After each step: run
```
pnpm test
```
, fix failures before moving on
Mark each task completed via
```
TaskUpdate
```
as you finish it

Scope boundary — implement ONLY what's in the phase:

Do NOT add improvements not specified in the phase
Do NOT refactor adjacent code
Do NOT create documentation files

Key project patterns:

Server actions: validate with Zod, verify auth before processing

Services:

createXxxService(client)

factory wrapping private class,

import 'server-only'

Imports: path aliases, ordering: React > third-party > internal > local
After mutations:
```
revalidatePath('/home/[account]/...')
```

IMPORTANT: Before using the Write tool on any existing file, you MUST Read it first or the write will silently fail. Prefer Edit for modifying existing files.

先执行步骤0（TDD） — 在编写实现代码前先编写失败的测试
按顺序执行剩余步骤 — 严格遵循阶段文档的要求
每完成一个步骤后：运行
```
pnpm test
```
，修复失败后再继续
完成每个任务后通过
```
TaskUpdate
```
标记为已完成

范围边界——仅实现阶段中指定的内容：

请勿添加阶段中未指定的改进内容
请勿重构相邻代码
请勿创建文档文件

关键项目模式：

服务器操作：使用Zod进行验证，处理前先验证权限

服务：

createXxxService(client)

工厂函数包装私有类，

import 'server-only'

导入：路径别名，顺序：React > 第三方库 > 内部模块 > 本地模块
变更操作后：
```
revalidatePath('/home/[account]/...')
```

重要提示： 在对任何现有文件使用Write工具前，你必须先使用Read工具读取该文件，否则写入操作会静默失败。修改现有文件时优先使用Edit工具。

Step 6: Final Verification

步骤6：最终验证

Run the full verification before reporting:

bash

pnpm test
pnpm run typecheck

Both must pass. Fix any failures before proceeding.

Scope boundary: Your job ends here. Do NOT run

/code-review

— an independent validator teammate will review your work after you report. This separation ensures blind spots are caught by a fresh set of eyes.

报告完成前运行完整的验证：

bash

pnpm test
pnpm run typecheck

两项检查都必须通过。修复所有失败后再继续。

范围边界： 你的工作到此为止。请勿运行

/code-review

——独立的验证团队成员会在你报告后审核你的工作。这种分工确保盲点能被新的视角发现。

Step 7: Report Completion

步骤7：报告完成

Send completion message to the orchestrator:

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: "Phase [NN] implementation complete — ready for review.\n\nFiles created/modified:\n- [list]\n\nTests: passing\nTypecheck: passing\n\nAcceptance criteria met:\n- [list key criteria]",
  summary: "Phase NN implemented — ready for review"
})

Then go idle. The orchestrator will either assign the next phase or send a shutdown request.

向编排器发送完成消息：

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: "Phase [NN] implementation complete — ready for review.\n\nFiles created/modified:\n- [list]\n\nTests: passing\nTypecheck: passing\n\nAcceptance criteria met:\n- [list key criteria]",
  summary: "Phase NN implemented — ready for review"
})

然后进入空闲状态。编排器会分配下一个阶段任务或发送停止请求。

Resuming After Context Compact

上下文压缩后恢复执行

If your context was compacted mid-phase:

```
TaskList
```
→ find the
```
in_progress
```
or first
```
pending
```
task
```
TaskGet
```
on that task → read the self-contained description
Continue from that task — don't restart the phase
The task list is your source of truth, not your memory

如果在阶段执行中途遇到上下文压缩：

```
TaskList
```
→ 找到
```
in_progress
```
或第一个
```
pending
```
任务
对该任务执行
```
TaskGet
```
→ 读取独立完整的任务描述
从该任务继续执行——无需重新开始整个阶段
任务列表是你的事实依据，而非你的记忆

Troubleshooting

故障排除

Tests fail but code looks correct

测试失败但代码看起来正确

Cause: Reference patterns may have changed since the phase was written. Fix: Re-read the reference file (Step 3). If the phase's code blocks differ from the current reference, follow the reference — it's the ground truth.

原因： 参考模式可能在阶段编写后发生了变化。 解决方法： 重新读取参考文件（步骤3）。如果阶段中的代码块与当前参考文件不同，遵循参考文件——它是事实依据。

Domain skill not found

找不到领域Skill

Cause: Skill name in phase frontmatter doesn't match available skills. Fix: Check the table in Step 3 for the correct skill name. If the phase focus doesn't match any skill, skip skill invocation and rely on the reference file.

原因： 阶段前置元数据中的Skill名称与可用Skill不匹配。 解决方法： 查看步骤3中的表格获取正确的Skill名称。如果阶段重点与任何Skill都不匹配，跳过Skill调用，依赖参考文件。