forge-deliver · git:20260704.cb84167 · 2026-07-04 · sha256 c0962c54948d65b8
forge-deliver git:20260704.cb84167A
Immutable. This exact content never changes and is served at /api/v1/blob/c0962c54948d65b8.
---
name: forge-deliver
description: |
端到端交付纯编排层：调用 forge-* 子 skill 从需求一路编排到发布和文档，.deliver/state.json 检查点，支持 --auto / --resume。
触发方式：用户说"forge-deliver"、"端到端交付"、"全自动交付"。
allowed-tools:
- Bash
- Read
- Write
- Edit
- Glob
- Grep
- AskUserQuestion
- Agent
---
> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/.claude/skills/forge-doc-policy/doc-paths.md`。
> **当前文档加载顺序**：编排层先读项目 `CLAUDE.md`、`docs/README.md`、`docs/INDEX.md`、
> `.features/_registry.md` 和相关根级当前真相源；历史账本只按需追溯。
> 详细规则见 `~/.claude/skills/_shared/current-doc-loading.md`。
# /forge-deliver v2：端到端交付编排层
一句话描述你的想法，拿到完整交付。
---
## 三条铁律
1. **编排不实现** — deliver 不写任何业务逻辑、不做设计、不写代码。所有领域工作由对应 forge-* 子 Skill 完成。deliver 只负责：调度顺序、传递输入输出、管理状态。
2. **状态必持久** — 每个 Phase 完成必须更新 state.json + 保存检查点。崩溃后 `--resume` 能从任意 Phase 恢复。
3. **证据先于断言** — 每个 Phase 完成必须有可验证的产出文件。不接受"已完成"的口头声明，必须检查文件存在且非空。
---
## 前置脚本（每次先运行）
```bash
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "当前分支: $_BRANCH"
echo "项目根目录: $_ROOT"
# 检测项目环境
[ -f "$_ROOT/package.json" ] && echo "检测到: Node.js 项目" && head -5 "$_ROOT/package.json"
[ -f "$_ROOT/requirements.txt" ] && echo "检测到: Python 项目"
[ -f "$_ROOT/go.mod" ] && echo "检测到: Go 项目"
[ -f "$_ROOT/Cargo.toml" ] && echo "检测到: Rust 项目"
[ -f "$_ROOT/Makefile" ] && echo "检测到: Makefile"
# 检查 .deliver 状态
if [ -f "$_ROOT/.deliver/state.json" ]; then
echo "====== 发现未完成的交付流水线 ======"
cat "$_ROOT/.deliver/state.json"
echo ""
echo "提示：使用 --resume 从检查点恢复"
fi
```
---
## 参数解析
从用户输入中解析：
| 参数 | 默认值 | 示例 |
|------|--------|------|
| 模式 | 交互 | `--auto`（全自动） |
| 需求 | 用户输入的文字 | `"给信息雷达加 RSS 订阅"` |
| 恢复 | 否 | `--resume`（从检查点恢复） |
---
## 模式说明
### 交互模式（默认）
在 3 个硬卡点暂停等待用户确认：
1. **Phase 0 完成后** — 需求方案确认
2. **Phase 2 完成后** — 工程实现确认
3. **Phase 7** — 验收报告交付
其他 Phase 自动推进，遇到不确定问题时用 AskUserQuestion 询问。
### 自动模式（`--auto`）
**前置沟通（1-2 轮，必须）：**
执行任何阶段之前，先完成前置沟通。这不是可选的。
**第 1 轮（必选）— 需求对齐：**
通过 AskUserQuestion 确认：
- "我理解你要做的是 [复述需求]，对吗？"
- "项目类型判断：[frontend / backend / fullstack]"（决定是否跳过 Phase 1 的设计部分）
- "我的方案大纲是：[1-3 句话概括方案方向]"
- "预计影响 [N 个文件 / 新建 N 个文件]"
**第 2 轮（按需）— 依赖确认：**
只在以下情况触发：
- 检测到需要外部依赖（API key、数据库、第三方服务）
- 需求存在歧义
- 项目结构复杂（多个入口、微服务架构）
**前置沟通完毕后：** 全自动执行 Phase 0-7，不再暂停。
**自动模式特殊规则：**
- **不 git commit** — 代码改动只存在于工作区
- **每个阶段结束保存检查点** — `git diff > .deliver/checkpoints/phase-N-done.patch`
- **文档产出实时写入** `.deliver/` 目录
- **遇到阻塞不死等** — 记录阻塞原因，跳到下一个可执行阶段，在验收报告中标注
---
## 恢复模式（`--resume`）
读取 `.deliver/state.json`，从上次中断的阶段继续：
```bash
cat .deliver/state.json
```
1. 显示当前进度摘要
2. 通过 AskUserQuestion 确认："上次停在 Phase X，要从这里继续吗？"
3. 选项：
- A) 从 Phase X 继续
- B) 从 Phase Y 重新开始（选择具体阶段）
- C) 全部重来
---
## 状态管理
### .deliver/ 目录结构
```
.deliver/
├── state.json # 流水线状态（持久化）
├── requirement.md # Phase 0 产出（forge-prd）
├── visual-decision.md # UI/设计任务的视觉决策索引（可选）
├── design.md # Phase 1 产出（forge-design，可能不存在）
├── design-impl-report.md # Phase 1 产出（forge-design-impl，可能不存在）
├── eng-report.md # Phase 2 产出（forge-eng）
├── qa-report.md # Phase 3 产出（forge-qa）
├── review-report.md # Phase 4 产出（forge-review）
├── ship-report.md # Phase 5 产出（forge-ship）
├── doc-release-report.md # Phase 6 产出（forge-doc-release）
├── acceptance-report.md # Phase 7 最终验收报告
└── checkpoints/
├── phase-0-done.patch
├── phase-1-done.patch
├── phase-2-done.patch
├── phase-3-done.patch
├── phase-4-done.patch
├── phase-5-done.patch
└── phase-6-done.patch
```
### state.json 格式
```json
{
"task": "需求描述",
"mode": "auto|interactive",
"type": "frontend|backend|fullstack",
"branch": "分支名",
"started_at": "ISO 8601 时间",
"current_phase": 0,
"qa_loop_count": 0,
"phases": {
"0": { "name": "需求理解", "skill": "forge-brainstorm + forge-prd", "status": "pending", "output": "", "note": "" },
"1": { "name": "设计", "skill": "forge-design + forge-design-impl", "status": "pending", "output": "", "note": "" },
"2": { "name": "工程", "skill": "forge-eng", "status": "pending", "output": "", "note": "" },
"3": { "name": "QA", "skill": "forge-qa", "status": "pending", "output": "", "note": "" },
"4": { "name": "审查", "skill": "forge-review", "status": "pending", "output": "", "note": "" },
"5": { "name": "发布", "skill": "forge-ship", "status": "pending", "output": "", "note": "" },
"6": { "name": "文档", "skill": "forge-doc-release", "status": "pending", "output": "", "note": "" },
"7": { "name": "验收", "skill": "（deliver 自身汇总）", "status": "pending", "output": "", "note": "" }
}
}
```
### 状态流转规则
**进入阶段时：**
1. 将该阶段标记为 `in_progress`
2. 更新 `current_phase`
3. 写入 state.json
**完成阶段时：**
1. 验证产出文件存在且非空（铁律 3）
2. 将该阶段标记为 `done`，记录产出文件路径到 `output`
3. 写入 state.json
4. 保存检查点
### 检查点保存
每个 Phase 完成后保存检查点：
```bash
mkdir -p .deliver/checkpoints
git diff > .deliver/checkpoints/phase-N-done.patch
echo "Phase N checkpoint saved at $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .deliver/checkpoints/phase-N-done.patch.summary
git diff --stat >> .deliver/checkpoints/phase-N-done.patch.summary
```
**回退方法（供用户手动使用）：**
```bash
git checkout -- . # 清除当前工作区
git apply .deliver/checkpoints/phase-N-done.patch # 恢复到阶段 N
```
---
## AskUserQuestion 格式规范
每次提问结构：
1. **重新聚焦**：当前项目、分支、流水线阶段、在做什么
2. **通俗解释**：高中生能懂的语言描述问题
3. **给出建议**：推荐选项 + 一句话原因
4. **列出选项**：`A) B) C)` + 工作量估算（如适用）
---
# ========================================
# 流水线阶段定义（8 个 Phase）
# ========================================
## Phase 0：需求理解
**调用子 Skill：** `forge-brainstorm`（可选）→ `forge-prd`
**编排逻辑：**
1. **判断是否需要头脑风暴**
- 用户需求模糊、方向不明确 → 先调用 `forge-brainstorm` 讨论，产出思考文档
- 用户需求清晰 → 跳过 brainstorm，直接进入 forge-prd
2. **调用 forge-prd**
- 输入：用户需求描述（+ brainstorm 产出，如有）
- 指令：让 forge-prd 产出/更新 PRD 当前事实、`.features/{feature-id}/feature-spec.md` 和必要 changelog
- 期望产出：项目中的 `docs/PRD.md` 仍是当前产品真相源，且本次功能有独立 Feature Spec
3. **收集 forge-prd 产出，写入 .deliver/**
- 将 PRD 当前事实和 Feature Spec 核心内容（目标、用户故事、功能点、约束条件、项目类型、验收场景）摘要到 `.deliver/requirement.md`
- 确定项目类型：`frontend / backend / fullstack`
4. **产出验证**
- 检查 `.deliver/requirement.md` 存在且非空
- 检查项目类型已确定
5. **[交互模式] 硬卡点暂停**
通过 AskUserQuestion：
- "需求理解完成。项目类型：[type]。核心目标：[一句话]。继续进入设计/工程阶段？"
- A) 继续
- B) 调整需求后继续
- C) 重新讨论（回到 brainstorm）
6. 更新 state.json，进入 Phase 1（或 Phase 2，如果 `type == "backend"`）
---
## Phase 1：设计
**跳过条件：** `type == "backend"` 时跳过，在 state.json 中标记为 `skipped`。
**调用子 Skill：** `forge-design` → `forge-design-impl`
**编排逻辑：**
1. **调用 forge-design**
- 输入：指向项目中的 PRD.md
- 指令：让 forge-design 产出/更新 DESIGN.md；如涉及前端页面、组件、状态或布局，必须执行 Image 2 视觉稿门禁（见 `~/.claude/skills/_shared/visual-decision-layer.md`）
- 期望产出：项目中的 DESIGN.md 已更新
2. **调用 forge-design-impl**
- 输入：指向项目中的 DESIGN.md
- 指令：让 forge-design-impl 将设计规范转化为样式代码；若有 Image 2 视觉稿，作为观感参考，最终用真实截图验证
- 期望产出：样式/布局代码已实现
3. **收集产出**
- 将设计摘要写入 `.deliver/design.md`
- 将实现报告写入 `.deliver/design-impl-report.md`
- 如有视觉稿/真实截图，将路径、prompt、确认结论汇总写入 `.deliver/visual-decision.md`
4. **产出验证**
- 检查项目中 DESIGN.md 存在
- 检查设计代码已写入
5. 更新 state.json + 保存检查点，进入 Phase 2
---
## Phase 2：工程
**调用子 Skill：** `forge-eng`
forge-eng 是一个重量级 Skill，内部自行完成：文档管理、Worktree 隔离、任务拆分、TDD、Wave 执行、Verification Gate。deliver 只需要启动它并收集结果。
**编排逻辑：**
1. **调用 forge-eng**
- 输入：指向项目中的 PRD.md、DESIGN.md（如有）、ENGINEERING.md（如有）
- 指令：让 forge-eng 完成工程方案设计和代码实现
- 模式提示：如果是 deliver 自动模式，建议 forge-eng 使用轻量模式（跳过文档直接实现），除非是新项目
- 期望产出：ENGINEERING.md 已更新 + 代码已实现 + 测试通过
2. **收集产出**
- 将工程摘要（架构、实现清单、测试结果）写入 `.deliver/eng-report.md`
3. **产出验证**
- 检查 `.deliver/eng-report.md` 存在且非空
- 检查 forge-eng 报告中测试是否通过
4. **[交互模式] 硬卡点暂停**
通过 AskUserQuestion：
- "工程实现完成。共修改/新增 X 个文件。测试 [通过/失败]。要继续 QA 还是先看看代码？"
- A) 继续进入 QA
- B) 让我先看看代码（暂停）
- C) 有问题需要调整
5. 更新 state.json + 保存检查点，进入 Phase 3
---
## Phase 3：QA
**调用子 Skill：** `forge-qa`
forge-qa 是纯验收模式：只测不修。发现的 Bug 回 forge-eng 修复。
**编排逻辑：**
1. **调用 forge-qa**
- 输入：指向项目中的 PRD.md、ENGINEERING.md
- 指令：让 forge-qa 执行测试计划并产出 QA 报告
- 期望产出：QA.md 或测试报告
2. **检查 QA 结果**
- 读取 forge-qa 的报告
- 如果发现 Bug：
3. **QA-Eng 修复循环**（最多 2 轮）
```
forge-qa 发现 Bug
→ 调用 forge-eng 修复（传入 Bug 清单）
→ 再次调用 forge-qa 验证
→ 如果还有 Bug 且循环次数 < 2，重复
→ 如果循环次数 >= 2，记录遗留 Bug 到报告，继续
```
- 每轮循环更新 `state.json` 中的 `qa_loop_count`
4. **收集产出**
- 将 QA 摘要（测试方式、Bug 统计、健康评分）写入 `.deliver/qa-report.md`
5. **产出验证**
- 检查 `.deliver/qa-report.md` 存在且非空
6. 更新 state.json + 保存检查点，进入 Phase 4
---
## Phase 4：审查
**调用子 Skill：** `forge-review`
**编排逻辑：**
1. **调用 forge-review**
- 输入：当前分支的 diff（forge-review 会自行收集）
- 指令：让 forge-review 执行代码审查，发现问题直接修复
- 期望产出：审查完成，问题已修复
2. **收集产出**
- 将审查摘要（发现问题数、修复数、安全问题）写入 `.deliver/review-report.md`
3. **产出验证**
- 检查 `.deliver/review-report.md` 存在且非空
4. 更新 state.json + 保存检查点，进入 Phase 5
---
## Phase 5：发布
**调用子 Skill：** `forge-ship`
**编排逻辑：**
### 自动模式
跳过 git commit/push/PR。在 state.json 中标记为 `done`，附注："自动模式不创建 PR，代码在工作区中，用户验收后决定。"
将跳过说明写入 `.deliver/ship-report.md`。
### 交互模式
1. **调用 forge-ship**
- 输入：forge-ship 会自行检测未提交更改、远程分支状态
- 指令：让 forge-ship 完成提交、推送、创建 PR
- 期望产出：PR 已创建（或代码已推送）
2. **收集产出**
- 将发布摘要（PR URL、提交数、CHANGELOG 更新）写入 `.deliver/ship-report.md`
3. **产出验证**
- 检查 `.deliver/ship-report.md` 存在且非空
4. 更新 state.json + 保存检查点，进入 Phase 6
---
## Phase 6：文档
**调用子 Skill：** `forge-doc-release`
**编排逻辑：**
1. **调用 forge-doc-release**
- 输入：forge-doc-release 会自行扫描项目文档和 diff
- 指令：让 forge-doc-release 更新项目文档使之匹配已发布内容
- 期望产出：项目文档已更新
2. **收集产出**
- 将文档更新摘要写入 `.deliver/doc-release-report.md`
3. **产出验证**
- 检查 `.deliver/doc-release-report.md` 存在且非空
4. 更新 state.json + 保存检查点，进入 Phase 7
---
## Phase 7：验收
**调用子 Skill：** 无（deliver 自身汇总所有子 Skill 产出）
这是唯一一个 deliver 自己执行的阶段——但它只做汇总，不做领域工作。
**编排逻辑：**
1. **读取所有前序产出**
```bash
ls -la .deliver/*.md .deliver/checkpoints/ 2>/dev/null
cat .deliver/state.json
```
2. **产出 `.deliver/acceptance-report.md`**
```markdown
# 验收报告
## 基本信息
| 字段 | 值 |
|------|---|
| **任务** | {从 state.json 读取} |
| **模式** | {auto / interactive} |
| **项目类型** | {frontend / backend / fullstack} |
| **开始时间** | {从 state.json 读取} |
| **完成时间** | {当前时间} |
| **分支** | {从 state.json 读取} |
## 流水线执行摘要
| Phase | 名称 | 子 Skill | 状态 | 产出文件 | 备注 |
|-------|------|----------|------|----------|------|
| 0 | 需求理解 | forge-prd | {status} | {output} | {note} |
| 1 | 设计 | forge-design + forge-design-impl | {status} | {output} | {note} |
| 2 | 工程 | forge-eng | {status} | {output} | {note} |
| 3 | QA | forge-qa | {status} | {output} | {note} |
| 4 | 审查 | forge-review | {status} | {output} | {note} |
| 5 | 发布 | forge-ship | {status} | {output} | {note} |
| 6 | 文档 | forge-doc-release | {status} | {output} | {note} |
| 7 | 验收 | deliver | done | acceptance-report.md | — |
## 需求回顾
{从 .deliver/requirement.md 提取核心目标}
## 工程摘要
{从 .deliver/eng-report.md 提取：架构、实现文件数、测试结果}
## QA 结果
{从 .deliver/qa-report.md 提取}
- 测试方式：{浏览器 / 纯代码 / 自动化测试}
- Bug 统计：发现 X，修复 Y，遗留 Z
- QA 循环次数：{qa_loop_count}
## 代码审查结果
{从 .deliver/review-report.md 提取}
- 发现问题：X 个，修复 Y 个
- 安全问题：{有/无}
## 发布状态
{从 .deliver/ship-report.md 提取}
- [自动模式] 代码在工作区中，未提交。检查点可用。
- [交互模式] PR：{URL}
## 文档更新
{从 .deliver/doc-release-report.md 提取}
## 已知遗留
{汇总各阶段的遗留问题：未修复的 Bug、跳过的 Phase、阻塞项}
## 检查点清单
| 阶段 | 检查点文件 | 大小 |
|------|-----------|------|
{列出 .deliver/checkpoints/ 中所有文件}
## 下一步建议
{基于遗留问题和项目状态，建议 1-3 个后续动作}
```
3. **输出总结给用户**
```
+================================================================+
| 交付完成 |
+================================================================+
| 任务：{一句话} |
| 阶段：8/8 完成（跳过 X 个） |
| QA：发现 X / 修复 Y / 遗留 Z |
| 发布状态：{PR URL / 代码在工作区} |
| 验收报告：.deliver/acceptance-report.md |
+================================================================+
```
4. 更新 state.json，所有阶段标记为 `done`
---
## 重要规则
### 编排规则（最高优先级）
- **deliver 不写代码** — 所有代码由 forge-eng / forge-design-impl 完成
- **deliver 不做设计** — 所有设计由 forge-design 完成
- **deliver 不做测试** — 所有测试由 forge-qa 完成
- **deliver 不做审查** — 所有审查由 forge-review 完成
- **deliver 只做三件事** — 调度子 Skill、传递文档、管理状态
### 子 Skill 调用规则
- **输入明确** — 调用子 Skill 时，明确告知它需要读取哪些文件
- **产出收集** — 子 Skill 完成后，将关键信息摘要到 .deliver/ 对应文件
- **失败处理** — 子 Skill 报告失败时，记录原因到 state.json 的 note 字段，决定是重试、跳过还是终止
### 自动模式规则
- **前置沟通不可省略** — "自动"是沟通完毕后的执行自动，不是跳过沟通
- **绝不 git commit** — 代码改动只在工作区，检查点用 patch 保存
- **遇阻不死等** — 记录阻塞原因，跳到可执行阶段，在报告中标注
### 交互模式规则
- **3 个硬卡点必须暂停** — Phase 0 后、Phase 2 后、Phase 7
- **其他阶段有问题才问** — 不要每一步都暂停确认
### 质量规则
- **一个想法，一个交付** — 不在一次流水线中塞入多个不相关功能
- **每个阶段的产出是下个阶段的输入** — 严格按顺序执行
- **状态文件实时更新** — 每次阶段状态变更都写 state.json