vibeflow-build-work

VibeFlow Build Work

通过每次循环实现一个功能来执行多会话软件项目。每个循环遵循严格管线：Orient -> Gate -> Plan -> TDD -> Quality -> ST 验收 -> Review -> Persist。

在 Claude Code 插件的默认路径中，本 skill 是 Build 自动继续链路的核心内部子步骤。只有在调试单个阶段、重跑某个功能、或处理失败恢复时，才把它当成显式入口。

启动宣告： "正在使用 vibeflow-build-work。让我先定位当前状态。"

核心原则： 每个子步骤有其专属 skill。严格遵循编排顺序。

执行模式选择

模式一：Sequential（顺序执行）

每次循环一个功能，主会话上下文顺序执行。

适用场景：

• 调试阶段，需要逐步观察
• 小项目（< 5 个 feature）
• 依赖关系复杂的场景

模式二：Parallel（并行执行）

使用 Agent 工具同时启动多个 subagent，每个 subagent 在独立 200k token 上下文中执行一个 feature。

适用场景：

• 中大项目（≥ 5 个 feature）
• feature 之间无文件重叠（设计阶段已验证）
• 需要快速完成多个独立功能

启动并行模式：

在调用 build-work 时明确告知模式选择：

请使用并行模式执行所有 failing features。

或

请使用顺序模式执行。

默认模式为 Sequential（更稳定）。

---

workflow.yaml 步骤裁剪

.vibeflow/workflow.yaml 是步骤启用的权威来源。在执行前读取它，跳过标记为禁用的步骤。典型可裁剪步骤：

• tdd — 是否强制 TDD（prototype 模板可能禁用）
• quality_gates — 是否运行覆盖率/变异测试门禁
• feature_st — 是否运行功能验收测试
• spec_review — 是否运行规格合规审查

即使步骤被裁剪，功能仍需测试和验证才能标记为 passing。裁剪仅影响形式化门禁流程。

检查清单

1. Orient（定位）

• 加载 .env（如存在）
• 运行 python scripts/get-vibeflow-paths.py --json
• 读取 .vibeflow/logs/session-log.md 的 ## Current State — 进度、上一个完成的功能、下一个功能
• 读取 feature-list.json — 注意 constraints[]、assumptions[]、required_configs[]、功能状态
• 优先读取 feature-list.json 中当前功能的归一化合同，并补读 design.md、tasks.md、rules/
• 读取 tasks.md 中当前功能对应的执行级任务块；将其视为已审批、已门禁的 handoff plan，而不是可随意改写的草稿
• 优先读取 feature 条目中的 build_contract_ref 与 design_section
• 读取 .vibeflow/guides/build.md — 项目专属工作流指导
• 读取 .vibeflow/guides/services.md（如存在）— 服务名、端口、健康检查 URL
• 读取设计文档第 1 节（docs/changes/<change-id>/design.md）— 项目概览和架构快照
• 运行 git log --oneline -10 — 近期提交上下文
• 选取下一个 "status": "failing" 的功能，按优先级然后按数组位置（第一个合格的胜出）— 跳过 "deprecated": true 的功能
• 依赖满足检查：选择候选功能后，验证其 dependencies[] 中所有功能 ID 在 feature-list.json 中状态为 "passing"。如有依赖未满足：
  • 记录："功能 #{id}（{title}）被跳过 — 未满足依赖：#{dep1}、#{dep2}"
  • 选取下一个合格的功能
  • 如无功能的依赖都已满足 -> 通过 AskUserQuestion 警告用户
• 如目标功能有 "ui": true 且 UCD 文档存在，读取 UCD 风格指南

文档查找协议：

当需要功能的设计章节或 SRS 需求时，不要 grep 功能标题。而是：

1. 先读取任务包中的 design_contract.design_section
2. 读取设计文档的第 4 节标题区域，找到对应 ### 4.N 子节
3. 如任务包缺失 section，再回退到设计文档标题区域手动定位 ### 4.N 子节
4. 读取该子节的完整内容（从 ### 4.N 到 ### 4.(N+1) 前）
5. 如任务包提供 design_contract.build_contract_ref，再补读 ## Build Contract 代码块
6. 同理读取 SRS 的完整 FR-xxx 子节
7. 存储为 {build_contract}、{design_section} 和 {srs_section} 供后续步骤使用

功能合同规则：

• 当前功能的主输入是 feature 合同，也就是 feature-list.json 中的 feature 条目加上文档引用
• feature 条目中的文档引用就是正式索引；如引用不足，再补读原始章节
• 不要依赖父会话里残留的长上下文记忆来实现功能
• 不要直接修改共享状态文件；共享状态由主 orchestrator 统一回写

2. Bootstrap（引导）

• 确认开发环境就绪（如需运行 init.sh/init.ps1）
• 冒烟测试已通过的功能

3. Config Gate（配置门禁）

检查目标功能的 required_configs 是否齐备。缺失时通过 AskUserQuestion 向用户收集，追加到 .env。配置齐备前阻塞。

4. Plan（对齐执行计划）

读取并消费 docs/changes/<change-id>/tasks.md 中已批准的执行级任务计划，为当前功能建立本轮执行顺序。

• 必须使用文档查找协议读取完整 {design_section} 和 {srs_section}
• 如存在 {build_contract}，计划必须同时遵守其中的全局约束和 required configs
• 计划必须与审批的类图、序列流和架构决策对齐
• UI 功能必须指定适用的 UCD 风格 Token
• 默认按任务块顺序执行，不临场重新设计任务结构
• 每个任务块应至少包含：task_id、goal、exact_file_paths、steps、verification_steps、rollback_note、expected_duration_min
• 如发现当前功能缺少执行级任务块、任务粒度明显过粗、或字段缺失，停止实现并回退到 tasks 阶段，而不是在 build-work 阶段自行补写一套新计划
• 如需记录本轮执行情况，只允许追加轻量 execution_notes / status，不得覆写已批准任务的目标、文件范围、验证步骤或回滚说明

5-7. TDD 循环（Red -> Green -> Refactor）

如 workflow.yaml 启用了 tdd： 读取并遵循 skills/vibeflow-tdd/SKILL.md。

传递上下文：当前功能对象、quality_gates、tech_stack、计划文件路径、完整 {srs_section}、完整 {design_section}。

8. Quality Gates（质量门禁）

如 workflow.yaml 启用了 quality_gates： 读取并遵循 skills/vibeflow-quality/SKILL.md。

9-10. ST 验收 + 规范审查（并行执行）

Quality Gates 通过后，Feature-ST 和 Spec-Review 互不依赖，使用 Agent 工具并行执行：

Quality Gates 通过
        │
        ├──▶ Agent: vibeflow-feature-st（黑盒验收测试）
        │         产出：docs/test-cases/feature-{id}-{slug}.md
        │
        └──▶ Agent: vibeflow-spec-review（规范合规审查）
                  产出：审查裁定（PASS/FAIL）
        │
        ├── 两个 Agent 都返回 ──▶ 合并结果
        └── 任一失败 ──▶ 修复后重新运行失败的部分

执行方式：

在同一条消息中发起两个 Agent 调用：

1. Agent 1 — Feature-ST（如 workflow.yaml 启用了 feature_st）：

   • 提示词包含：功能对象、SRS 章节、设计章节、任务文档路径、.vibeflow/guides/services.md 路径
   • 指令：读取并遵循 skills/vibeflow-feature-st/SKILL.md，完成后返回执行结果摘要

2. Agent 2 — Spec-Review（如 workflow.yaml 启用了 spec_review）：

   • 提示词包含：功能对象、SRS 章节、设计章节、计划文档路径、UCD 路径（如 ui:true）、Git diff
   • 指令：读取并遵循 skills/vibeflow-spec-review/SKILL.md，完成后返回审查裁定

结果合并：

• 两个 Agent 都 PASS → 继续添加示例 + 持久化
• 任一 FAIL → 修复问题后，仅重新运行失败的 Agent
• 如仅启用其中一个步骤 → 单 Agent 执行，无需并行

回退规则： 如 Agent 工具不可用或执行异常，回退为顺序执行（先 ST，后 Review）。

11. 添加示例

在 examples/ 中创建可运行的示例展示已完成的功能。纯基础设施功能可跳过。

12. Persist（持久化）

• Git 提交（实现、测试、示例、测试用例文档）
• 更新 RELEASE_NOTES.md（Keep a Changelog 格式）
• 更新 .vibeflow/logs/session-log.md：
  • 更新 ## Current State：进度计数（X/Y 通过）、上一个完成的功能、下一个功能
  • 追加会话条目
• 标记功能 "status": "passing" 在 feature-list.json 中
• Git 再次提交（进度文件）

13. Continue（继续）

• 如还有失败的非废弃功能且上下文允许 -> 继续下一功能（回到步骤 1）
• 如无失败的非废弃功能 -> 进入 vibeflow-review
• 如上下文耗尽 -> 结束会话（确保 .vibeflow/logs/session-log.md 已更新）

关键规则

• 每次循环一个功能 — 防止上下文耗尽
• 严格步骤顺序 — 不跳过，不重排
• workflow.yaml 为启用步骤的权威 — 被禁用的步骤可跳过
• 不启用也需验证 — 即使 TDD 被禁用，仍需写测试和验证
• 配置门禁在计划前 — 缺配置时不计划不编码
• 只消费已验证计划 — tasks.md 是 handoff plan，不是 build-work 临时重写的草稿
• 不标记 "passing" 无新鲜证据 — 运行测试，读取输出，然后标记
• 不修改 verification_steps — 需求变更使用增量流程
• 系统化调试 — 出错时追踪根因，不猜测修复
• 每次提交后更新 RELEASE_NOTES.md
• 结束会话前必须提交 + 更新进度
• 不留下破损代码 — 回退不完整的工作

红线

合理化借口	正确行动
"配置之后再补"	运行配置门禁。需要真实配置。
"这功能太简单，跳过测试用例"	运行 vibeflow-feature-st。每个功能。
"这功能太简单，跳过 TDD"	运行 vibeflow-tdd。每个功能。
"测试通过了，标记完成"	先运行 vibeflow-quality。
"覆盖率差不多够了"	阈值是硬门禁。运行工具。
"我自己快速审查一下"	运行 vibeflow-spec-review。始终。
"让我快速试试这个修复"	先系统化调试。
"任务太粗，我边做边重新规划"	停止实现，回退到 execution planning gate。
"端口占用，手动杀掉"	使用 .vibeflow/guides/services.md 的停止命令
"后端没准备好先 mock"	依赖检查存在是有原因的。先开发后端功能。

出错时

遵循系统化调试流程 — 不猜测修复：

1. 收集证据（错误消息、堆栈跟踪、git diff）
2. 复现问题
3. 追踪根因
4. 为 bug 写失败测试
5. 单一有针对性的修改
6. 3 次尝试后放弃 -> 升级到用户

---

Parallel Mode（并行执行）

当选择并行模式时，使用 Agent 工具同时执行多个 feature。

执行流程

1. 读取 feature-list.json
   → 找出所有 status=failing 的 feature
   → 按优先级排序

2. 读取每个 feature 的设计章节
   → 确认 feature 之间无文件重叠

3. 同时 Spawn N 个 Agent（每个 failing feature 一个）

4. 等待所有 Agent 完成

5. 汇总结果
   → 更新 feature-list.json
→ 更新 `.vibeflow/logs/session-log.md`
   → 报告汇总

Agent 提示词模板

每个 subagent 收到：

# Feature Implementation Agent

你是 VibeFlow 的 feature 实现 Agent。你的上下文是**全新的 200k token**，没有任何历史包袱。

## 你的任务

实现 feature：
- **ID**: {feature_id}
- **名称**: {feature_name}
- **优先级**: {priority}

## 上下文文件（请先读取）

1. `docs/changes/<change-id>/design.md` — 技术设计（找到第 4.N 节）
2. `feature-list.json` — 功能详情（找到 id={feature_id} 的条目）
3. `.vibeflow/workflow.yaml` — 启用了哪些步骤
4. `.vibeflow/guides/build.md`（如存在）— 项目专属指导

## 执行步骤

按顺序执行：

### Step 1: Orient
理解功能需求，确认设计章节。

### Step 2: TDD
读取 `skills/vibeflow-tdd/SKILL.md`，执行红→绿→重构循环。

### Step 3: Quality Gates
读取 `skills/vibeflow-quality/SKILL.md`，运行覆盖率 + 变异测试。

### Step 4: Feature-ST
读取 `skills/vibeflow-feature-st/SKILL.md`，执行验收测试。

### Step 5: Spec-Review
读取 `skills/vibeflow-spec-review/SKILL.md`，检查实现是否符合 SRS。

### Step 6: Persist
1. **不要直接 commit** — 并行模式下由 orchestrator 统一处理 git 操作
2. 将实现结果回写到 `feature-list.json` 对应 feature 的 `execution_result` 字段，并生成 `.vibeflow/build-reports/feature-{id}.md`
3. 如实现完成但测试失败，status 仍为 "failing"

**重要**：不要同时写入 `feature-list.json`、`.vibeflow/logs/session-log.md`、`RELEASE_NOTES.md` 等共享文件，这些由 orchestrator 统一更新。

## 产出

完成后返回结构化结果：

RESULT: {feature_id}: PASS COMMIT: {git_hash} SUMMARY: {一句话总结}

如失败：

RESULT: {feature_id}: FAIL ERROR: {具体错误描述} RETRY: {是否可自动重试}

## 重要约束

- **每个 feature 独立执行**，不知道其他 feature 的存在
- **不要与其他 subagent 通信**，结果通过文件共享
- **遇到错误不要放弃**，尽力完成，能走多远走多远

Orchestrator 汇总逻辑

所有 Agent 完成后：

1. 读取 `feature-list.json` 中各 feature 的 `execution_result`

2. 对于每个 PASS 的 feature：
   a. git add {implemented_files}
   b. git commit -m "feat({feature_id}): {summary}"
   c. 获取 commit hash

3. 更新 feature-list.json（统一操作，非并行）：
   - status = "passing"（如 PASS）
   - status = "failing" + last_error（如 FAIL）
   - completed_at = timestamp
   - commit = hash（如 PASS）

4. 更新 `.vibeflow/logs/session-log.md`（统一操作）

5. 更新 RELEASE_NOTES.md（统一操作）

6. 生成汇总报告：

═══════════════════════════════════ Parallel Execution Results ═══════════════════════════════════ Total: N | PASS: M | FAIL: K

✅ Feature A — PASS (commit: abc123) ✅ Feature B — PASS (commit: def456) ❌ Feature C — FAIL (覆盖率不足)

Next: [处理失败 feature 的建议] ═══════════════════════════════════

7. 如有失败：
- 询问用户是否继续 Sequential 模式逐个修复
- 或在下一个会话处理

使用场景

场景	推荐模式
项目启动，第一次执行所有 feature	Parallel
调试某个具体 feature	Sequential
有 feature 失败后的重试	Sequential（修复单个）
多个独立 feature 需要快速完成	Parallel

前提条件

并行模式要求：

• feature 之间无文件重叠（Plan 阶段已分配好文件范围）
• 所有 feature 的依赖都已满足（依赖的 feature 状态为 passing）
• 开发环境已初始化（build-init 已完成）

如不满足条件，自动降级为 Sequential 模式。

集成

调用者： vibeflow-router 的 Build 自动继续链路（默认）或 vibeflow-build-init 的手动 fallback 调用顺序：

1. vibeflow-tdd（步骤 5-7）— 顺序
2. vibeflow-quality（步骤 8）— 顺序（依赖 TDD 产出）
3. vibeflow-feature-st + vibeflow-spec-review（步骤 9-10）— 并行（通过 Agent 工具） 读/写： feature-list.json、.vibeflow/logs/session-log.md、RELEASE_NOTES.md