Workflow Lifecycle

Workflow Lifecycle

从用户模糊想法到上线后效果验证，7 道强制阶段门（plus post-launch 可选）。这是 AppGenesisForge 的核心交付链路。

完整鸟瞰图见 docs/product-workflow.md；本文做"step-by-step 怎么用"详解。

本文对齐主仓 v6.14.0（2026-07-01，ADR-011/012/013）。Wiki 与主仓冲突一律以主仓为准。

---

全景：7 道阶段门

flowchart LR
    U([用户想法]) --> G1[门1 变更文件夹]
    G1 -->|AC 摘录 + worktree 隔离| G2[门2 派单]
    G2 --> G3[门3 TDD 实现 + SIT 自跑]
    G3 -->|progress SIT 证据| G4[门4 Code Review + SIT Audit]
    G4 -->|approve/ approve with changes| G5[门5 UAT 部署]
    G5 -->|冒烟二元 gate| G6[门6 E2E]
    G6 --> G7[门7 UAT 业务签字]
    G7 --> POST([Post-launch 可选])
    G4 -. block .-> X[FAIL 回路]
    G5 -. 部署失败 .-> X
    G6 -. fail .-> X
    G7 -. request changes .-> X
    X -->|PL 重派执行层修复| G3

Loading

• 门 1-7 全部强制（任一失败一律回实现层重做，不发明跳过）
• Post-launch（release notes / 实验）可选，不在阶段门序列

Apple 轨（macOS / iOS）门 5 不同：用「签名分发包发布门」（apple-release-engineer，/agf-apple-release）替代 Web 轨的 UAT 部署门；其余六门结构对称。

---

门 1：变更文件夹（需求入口，v6.9.0 ADR-012）

取代 PRD（PRD 弃用 v6.9.0 → 删 v7.0.0，仍可 fallback）。

入口动作：

/agf-team-start 我想做一个支持 OAuth 登录的用户认证模块

PL 内部：

1. 判断需求是否模糊 / 多选项 / 跨角色 → 若是，必先调用 Skill({skill: "superpowers:brainstorming"}) 做澄清
2. 收敛 MVP 范围 + 识别开放问题（每条标 Owner）
3. 用 skill agf-writing-change 生成变更文件夹

输出路径：docs/changes/<change>/，四件套：

文件	内容
proposal.md	背景 / 目标 / Non-Goals / 开放问题
specs/<cap>/spec.md	对活规格 docs/specs/<cap>/spec.md 的 delta（ADDED/MODIFIED/REMOVED/RENAMED Requirements，每 Requirement ≥1 #### Scenario）
design.md	UI 引用 + API 契约 + 数据模型（引用 DESIGN.md token，禁内联重声明）
tasks.md	任务拆分

活规格是行为需求 SSOT（AGF 第三类"永远当前"SSOT，与 DESIGN.md / ADR-000 同构）。validate agf-spec-validate.sh（advisory）；UAT 签字后 agf-spec-archive 确定性 merge delta 进活规格 + 移 archive。

AC 仍 AC-N，语义源自 delta scenario；AC 可测试性硬要求不变（触发条件 + 可观察结果 + ≤30s curl 可验证，拒绝"体验流畅"类模糊描述）。

---

门 2：派单（实施计划 + Task 任务单）

触发：变更文件夹四件套就绪。多步 / 跨角色 / ≥3 AC 时 PL 必先调用 Skill({skill: "superpowers:writing-plans"}) 出实施计划（轻量，见 plans-format.md：无 inline 代码 / 每 Task ≤3 步 / 整个 Plan ≤500 字）。

关键规则：任务消息必须摘录 AC 原文，不可只引用变更文件夹路径（teammate 不继承会话上下文）。

六要素（缺一不可）：

SendMessage({to: "frontend-dev", message: "
工程任务: 登录表单
任务类型: 新功能       ← 决定开发者是否触发 superpowers:test-driven-development
平台 target: web       ← Apple 轨必填 macos/ios/universal
上下文:
  - 技术栈: 见 CLAUDE.md ## Tech Stack
  - 设计规范: docs/design/login/spec.md
  - API 契约: 与 backend-dev 确认 POST /api/auth/login
  - 相关文件: src/components/

验收标准（完成后逐条自验再报告）:
- [ ] AC-1: 邮箱格式错误时...
- [ ] AC-2: 提交后按钮 loading 态...

Change: docs/changes/login-auth/
", summary: "前端任务: 登录表单"})

并行派发 ≥2 执行层 teammate 时强制 worktree 隔离——见 .claude/standards/workflow.md Parallel Dispatch。

---

门 3：TDD 实现 + SIT 自跑（dev owned）

执行层（frontend / backend / ai / ml / miniapp / uiux / apple）实现 + AC 自验。

铁律：

• 收到"新功能" / "bugfix" → 必先调用 Skill({skill: "superpowers:test-driven-development"})
• 高风险（schema 迁移 / 认证改动 / LLM 厂商切换 / 生产 prompt / cross-cutting） → 必先 Plan Mode 拿授权
• 完成前 → 必先调用 Skill({skill: "superpowers:verification-before-completion"})

SIT 是 dev 自跑步骤（不是独立 QA 阶段，不产独立 docs/qa/*-sit-*.md）：

• 范围：起真实后端 + DB（不 mock）→ 按 AC 走集成链路 → 覆盖正常 / 错误 / 边界
• AI 产品专项：LLM 输出稳定性（同输入 3 次）+ P95 延迟 + 降级行为
• 证据落 progress/<role>.md 的 **SIT 证据** 段（不是独立报告文件）
• 流程见 skill agf-running-sit-tests（Apple 轨 agf-running-apple-sit）
• 报告前 + reviewer audit step 0 都先跑 bash .claude/scripts/agf-sit-precheck.sh progress/<role>.md 机筛（advisory，ADR-011 决策 2）

完成报告（dev → PL）：AC 自验逐条 ✅/⚠️（不隐藏偏差）+ 文件清单 + Skills used + 引用 progress/<role>.md 的 SIT 证据段。

---

门 4：Code Review（含 SIT Audit，review-only）

PL 触发：

SendMessage({to: "code-reviewer", message: "请审查 [功能名] 实现\n范围: [文件列表]\n参考: docs/changes/[change]/"})

输出：docs/reviews/[feature]-YYYY-MM-DD.md，verdict 三档：

Verdict	含义	下一步
approve	无 critical 无 warning	进入门 5
approve with changes	warning 可后续修但不阻塞	进入门 5
block	有 critical 必修	PL 重派 dev 修复 → 回门 3

SIT Audit：reviewer 不重跑 SIT，而是 audit progress/<role>.md 的 **SIT 证据** 段——证据缺失 / placeholder / 标记矛盾 → SIT Audit 给 Redo SIT，退回 dev 重跑。

SIT Audit 三档：Pass / Pass with concerns / Redo SIT（ADR-010）。code-reviewer + apple-code-reviewer 退出时 validate-verdict.sh 从报告 frontmatter 重算守门，堵"有 critical 却 approve"。

UI 变更额外审「审美纪律审查项」：对照 agf-design-discipline（Design Read + 三刻度 + AI Tells）+ 跑 agf-design-precheck.sh 机械初筛（ADR-013）。

Apple 轨换 apple-code-reviewer，verdict 三档同。

---

门 5：UAT 部署（deploy-only，二元 gate）

门槛：门 4 verdict ∈ {approve, approve with changes} + SIT Audit ∈ {Pass, Pass with concerns} + PL 合并到 main。

Web 轨——deploy-engineer 按 skill agf-deploying-uat 部署隔离 UAT 栈：

• 独立 compose project（与 dev worktree 隔离）
• 端口偏移（避开 dev worktree 占用端口）
• 容器内跑 migration（真实输出）
• 冒烟自检（健康检查 + 关键 API 实测）
• 二元 gate：✅ 部署成功（冒烟通过） / ❌ 部署失败（不发明新 verdict）

触发：/agf-deploy-uat 或 PL 手动派单。部署失败退回 PL → dev（deploy-engineer 不修业务源码）。

Apple 轨——门 5 替换为「签名分发包发布门」：apple-release-engineer 按 skill agf-releasing-apple 构建（fastlane match 签名 + notarytool 公证 + 四渠道 lane）+ 冒烟自检，二元 gate 同形。触发 /agf-apple-release。

隔离契约（端口字面值权威源）见 .claude/standards/deployment.md「UAT 环境部署」节。

---

门 6：E2E（qa-engineer，控件遍历）

门槛：门 5 冒烟通过（UAT 栈 / 签名分发包就绪）。

操作：

1. 对 UAT 栈 / 分发包全链路启动
2. 用 chrome-devtools-mcp 控制浏览器执行用户流程，控件遍历（不只验主流程，覆盖按钮 / 表单 / 异常路径）
3. 关键节点截图 + Read 读图四查（导航 / 裁切 / 控件可点 / 视觉达标对照 design spec）
4. 覆盖主流程 + ≥2 异常流程

小程序：miniprogram-automator + Jest，真机扫码（iOS + Android 各 1 台）。Apple：apple-qa-engineer 对 TestFlight build / 公证 DMG 跑 XCUITest。

E2E 失败 → 回 PL → dev（qa 不修源码）。

---

门 7：UAT 业务签字（PL，唯一签字角色）

门槛：E2E pass。

操作：

1. qa-engineer 先按 docs/qa/uat-cases-_TEMPLATE.md 生成 docs/qa/<feature>-uat-cases-<date>.md（每条 AC ≥1 用例 + AC 覆盖矩阵 + 界面渲染核查矩阵）→ 用户审核确认（frontmatter status: Approved）后才开测（MAJOR / MINOR 强制；用例可在 dev 实现期并行起草，ADR-011 决策 1）
2. 逐条执行 AC 对应测试场景，证据回填用例文档（SSOT）
3. 写报告 docs/qa/[feature]-uat-YYYY-MM-DD.md，报告级 verdict 三档：Promote / Block / Conditional promote（ADR-010）
4. 提交报告给 PL

PL 业务签字（唯一签字角色，对照活规格 delta scenario / AC 逐条确认）：

• UAT 签字 verdict 两档：approve / request changes
• approve 后向用户汇报：完成了什么 / 验收结果 / 已知限制
• UAT 界面用例必须 chrome-devtools 真渲染 + 截图 + Read 视觉读回（纯 API 断言不构成含界面用例的 Pass）

触发：/agf-uat <feature>。

approve 后 agf-spec-archive 把 delta merge 进活规格 + 移 archive。

---

full / fast lane（ADR-011 决策 3）

PL 派单按规模 + 风险显式选：

• full（默认；Medium/Large、MINOR/MAJOR、任何高风险）走全套 7 门
• fast（仅 Small + PATCH + 非高风险，显式选 + 记录风险接受）只减不跳——仍部署 + 冒烟 + P0 pass² + 受影响界面渲染核查，E2E 缩到改动面目标 AC

高风险（auth / schema migration / LLM 切换 / cross-cutting）一律 full，不得 fast。SSOT 见 .claude/standards/workflow.md §交付 lane。

---

Post-Launch（可选，不在阶段门序列）

UAT 签字后可选触发：

Release Notes

SendMessage({to: "content-writer", message: "请为 [feature] 起草 release notes\nChange: docs/changes/[change]/\nUAT: docs/qa/[feature]-uat-*.md"})

24h 内交草稿到 docs/content/release-notes/YYYY-MM-DD-[slug].md。

上线后实验

SendMessage({to: "growth-analyst", message: "请设计 [feature] 上线后效果验证实验\n北极星候选: ...\nCounter Metric: ..."})

上线前定指标 + 上线后 7-14d 出实验报告。

Release 复盘（MAJOR / MINOR 推 tag + gh release create 完成后，非强制）：可跑 /agf-release-retro vX.Y.Z（skill agf-running-release-retro，产出 docs/reviews/retro-vX.Y.Z-YYYY-MM-DD.md）；PATCH 不提醒。

---

失败回路

任一阶段门失败：

   FAIL → product-lead → 重新分派执行层修复 → 回门 3（实现 + SIT 自跑）

禁止：跳过门槛 / code-reviewer 直接改源码 / 跳过 PL 自行签字 / 发明新 verdict 词。

6 个 reviewer + qa role 退出时 validate-verdict.sh 从报告 frontmatter（唯一 SSOT）重算守门——code（critical_count>0 → block）+ SIT Audit（sit_checks 含 fail → Redo SIT）硬拦、QA 客观底线（critical_defect_count>0 非 Block / P0 未全 pass² 却 Promote）拦不可能组合（ADR-003 → ADR-010）。

---

完整 worked example

参考 docs/training/samples/postcard-feature/（明信片 feature，贯穿变更文件夹 → 派单 → 实现 + SIT 自跑 → review → UAT 部署 → E2E → UAT 签字全链路）。