From ab29598a9a94a837b119d1d060f45923d1368047 Mon Sep 17 00:00:00 2001 From: laily Date: Mon, 12 Oct 2026 20:34:20 +0800 Subject: [PATCH] add delivery workflow skills --- skills/bugfix-ship/README.md | 29 +++++++++++ skills/bugfix-ship/SKILL.md | 47 ++++++++++++++++++ skills/bugfix-ship/agents/openai.yaml | 6 +++ skills/delivery-loop/README.md | 21 ++++++++ skills/delivery-loop/SKILL.md | 32 ++++++++++++ skills/delivery-loop/agents/openai.yaml | 6 +++ .../delivery-loop/references/state-machine.md | 49 +++++++++++++++++++ skills/pr-ship/README.md | 23 +++++++++ skills/pr-ship/SKILL.md | 45 +++++++++++++++++ skills/pr-ship/agents/openai.yaml | 6 +++ skills/requirement-flow/README.md | 23 +++++++++ skills/requirement-flow/SKILL.md | 46 +++++++++++++++++ skills/requirement-flow/agents/openai.yaml | 6 +++ 13 files changed, 339 insertions(+) create mode 100644 skills/bugfix-ship/README.md create mode 100644 skills/bugfix-ship/SKILL.md create mode 100644 skills/bugfix-ship/agents/openai.yaml create mode 100644 skills/delivery-loop/README.md create mode 100644 skills/delivery-loop/SKILL.md create mode 100644 skills/delivery-loop/agents/openai.yaml create mode 100644 skills/delivery-loop/references/state-machine.md create mode 100644 skills/pr-ship/README.md create mode 100644 skills/pr-ship/SKILL.md create mode 100644 skills/pr-ship/agents/openai.yaml create mode 100644 skills/requirement-flow/README.md create mode 100644 skills/requirement-flow/SKILL.md create mode 100644 skills/requirement-flow/agents/openai.yaml diff --git a/skills/bugfix-ship/README.md b/skills/bugfix-ship/README.md new file mode 100644 index 0000000..4812f3c --- /dev/null +++ b/skills/bugfix-ship/README.md @@ -0,0 +1,29 @@ +# bugfix-ship + +把一个已确认的 bug 从根因分析一路推进到配置允许的 PR、合并或生产部署。 + +## 什么时候使用 + +```text +修复动态编辑页重新打开后图片丢失的问题，测完后发 PR。 +``` + +或： + +```text +修复这个线上回归，完整验证并部署到生产。 +``` + +## 使用前准备 + +- 能复现的问题描述、截图或日志。 +- 项目已配置测试环境和所需 builder/tester/deployer 能力。 +- 若要外部发布，明确允许的停止点或使用项目 profile。 + +## Agent 会做什么 + +查根因、改代码、补回归测试、执行必要的黑盒/真机验证，并继续完成配置允许的交付阶段。 + +## 如何判断完成 + +你会得到根因、修复 commit、测试证据、PR/合并/tag、产物校验和部署状态；不会只收到“本地测试通过”。 diff --git a/skills/bugfix-ship/SKILL.md b/skills/bugfix-ship/SKILL.md new file mode 100644 index 0000000..2f7aeb0 --- /dev/null +++ b/skills/bugfix-ship/SKILL.md @@ -0,0 +1,47 @@ +--- +name: bugfix-ship +description: >- + 处理已复现或有证据的 bug：查根因、修复、补回归测试、验证并按配置继续发 PR、合并、 + 构建、发布和部署。用户说修复、修好、回归、上线 bug 时使用；不处理新需求规划。 +--- + +# Bugfix Ship：修复到交付 + +将一次 bug 修复推进到项目配置允许的最终停止点，而不是在本地测试通过后提前结束。 + +## 何时使用 + +- 用户报告错误、回归、崩溃、截图缺陷或明确要求修 bug。 +- 用户要求修复后继续测试、发 PR、合并、构建、发布或部署。 + +## 不适用 + +- 尚未定义目标的复杂新需求：交给 `specifier` 和 `requirement-flow`。 +- 已有 PR 的合并和发布：交给 `pr-ship`。 +- 只做根因分析、不改代码：使用 `hunt`。 + +## 工作规则 + +1. 读取项目约束、当前分支/工作树和相关任务；使用 `hunt` 确认根因、复现和验收信号。 +2. 修改代码并补充或更新回归用例；行为、API、图片、UI 改动不得只跑编译。 +3. 使用 `tester` 执行黑盒、浏览器或真机验证；涉及资源加载时检查真实 URL、状态、类型、 + 内容和截图，不把接口返回“有 URL”当作图片可用。 +4. 读取并执行共享 `delivery-loop` 的状态机。停止点由用户选择或项目 delivery profile + 决定，使用 ACK canonical 状态：`verified`、`validation_ready`、`review_ready` 或 `released`。 +5. 只有达到配置的停止点并拿到证据后才结束；提交、推送、合并、发布和部署不能静默跳过。 + +## 安全门 + +- 根因不清、测试缺失、真机不可达、CI/回归失败或工作树有无关改动时停止并说明。 +- 不强推、不覆盖他人分支、不绕过 PR 审核，不把测试环境成功当生产成功。 +- 数据迁移、破坏性 API、权限/密钥、安全修复和不可逆生产操作需要额外确认。 + +## 必读资料 + +- 执行交付阶段时读取已安装的 `delivery-loop` skill 及其状态机 reference。 +- 测试环境或回归时使用项目的 `tester`、`deployer` 和 `builder` 契约。 +- 提交、合并或发布前使用 `check` 与 `releaser` 的规则。 + +## 完成报告 + +报告根因、变更、测试/真机证据、停止点、commit、PR/tag、产物摘要、部署状态和任何未完成项。 diff --git a/skills/bugfix-ship/agents/openai.yaml b/skills/bugfix-ship/agents/openai.yaml new file mode 100644 index 0000000..b5829df --- /dev/null +++ b/skills/bugfix-ship/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Bugfix Ship" + short_description: "Carry a bug fix through verification and delivery" + default_prompt: "Use $bugfix-ship to fix this bug, verify it, and continue to the configured delivery stop." +policy: + allow_implicit_invocation: true diff --git a/skills/delivery-loop/README.md b/skills/delivery-loop/README.md new file mode 100644 index 0000000..3824662 --- /dev/null +++ b/skills/delivery-loop/README.md @@ -0,0 +1,21 @@ +# delivery-loop + +供其他交付类 skill 复用的状态机，统一处理验证、PR、合并、回归、构建和部署的顺序与安全门。 + +## 什么时候使用 + +通常由 `$bugfix-ship`、`$pr-ship` 或 `$requirement-flow` 内部读取，不需要单独调用。 + +## 使用前准备 + +- 项目已有有效的 ACK delivery profile 或等价交付配置。 +- 已明确任务的目标分支、测试范围和允许的停止点。 +- 需要外部写入时，当前请求已经授权对应动作。 + +## Agent 会做什么 + +按配置推进任务，逐阶段记录验证证据；遇到缺配置、失败或高风险变更时停止，不自动猜测。 + +## 如何判断完成 + +最终报告会明确停在 PR、合并、回归、产物或部署中的哪一状态，并给出可复核证据。 diff --git a/skills/delivery-loop/SKILL.md b/skills/delivery-loop/SKILL.md new file mode 100644 index 0000000..c29aa19 --- /dev/null +++ b/skills/delivery-loop/SKILL.md @@ -0,0 +1,32 @@ +--- +name: delivery-loop +description: >- + 为修复、PR 和需求任务提供可配置的验证、发 PR、合并、回归、构建、发布与部署状态机。 + 仅作为 bugfix-ship、pr-ship、requirement-flow 的共享执行规则使用。 +--- + +# Delivery Loop：共享交付状态机 + +这是三个交付入口共用的内部规则，不直接替用户选择生产发布，也不替项目保存环境事实。 + +## 使用方式 + +只有在入口 skill 明确要求执行交付时才读取 +`references/state-machine.md`。入口 skill 负责确定任务类型和目标；本 skill 负责阶段、 +停止点、证据和安全门。 + +## 不可违反的规则 + +- 复用现有 `hunt`、`tester`、`check`、`builder`、`deployer`、`releaser` 和 + `orchestration` 能力；不要在本 skill 里复制它们的实现。 +- 先读取项目的 delivery profile、分支策略和当前工作树，再决定可执行的停止点。 +- `stopAt` 未配置或与用户目标冲突时停止并报告缺口，不猜测是否应合并或部署。 +- 提交、推送、合并、打 tag、发布产物和生产部署都必须同时满足项目配置与当前请求的授权。 +- 不绕过审核、CI、测试失败、脏工作树、冲突、未确认的迁移或不可回滚的外部变更。 +- 每个阶段都保存可复核证据；没有证据不得把阶段标为完成。 +- 失败时保留现场和回滚信息，不用重试掩盖失败，不伪造发布或部署成功。 + +## 结果 + +完成时返回状态机最终状态、停止点、变更 commit、PR/tag、测试与回归证据、产物摘要、部署 +目标和回滚指针。若停在中间状态，明确下一步和阻塞原因。 diff --git a/skills/delivery-loop/agents/openai.yaml b/skills/delivery-loop/agents/openai.yaml new file mode 100644 index 0000000..d6567f6 --- /dev/null +++ b/skills/delivery-loop/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Delivery Loop" + short_description: "Shared delivery state machine for workflow skills" + default_prompt: "Use $delivery-loop to inspect a delivery workflow state and its safe stopping point." +policy: + allow_implicit_invocation: false diff --git a/skills/delivery-loop/references/state-machine.md b/skills/delivery-loop/references/state-machine.md new file mode 100644 index 0000000..c415976 --- /dev/null +++ b/skills/delivery-loop/references/state-machine.md @@ -0,0 +1,49 @@ +# Delivery Loop 状态机 + +## 状态 + +```text +change_ready -> verified -> pr_opened -> merged -> regression_passed -> artifact_built -> published -> deployed +``` + +入口可以从已有状态开始，但不能跳过本次变更所需的验证。内部里程碑可以更细，但项目 +ACK 配置必须使用以下 canonical `stopAt`： + +- `verified`：只完成代码和验证。 +- `validation_ready`：不可变产物已部署到开发/测试环境并通过健康检查，可交给用户验证。 +- `review_ready`：PR/MR、预览产物和非生产验证证据已齐备，等待审核。 +- `released`：经过本次 approval 后完成稳定发布或生产部署。 + +入口 skill 的自然语言停止点映射如下： + +| 用户目标 | ACK stopAt | 必要内部里程碑 | +| --- | --- | --- | +| 只验证 | `verified` | `verified` | +| 发 PR | `review_ready` | `pr_opened`，必要时预览构建/测试 | +| 部署测试环境 | `validation_ready` | `artifact_built`、`deployed`、健康检查 | +| 合并后回归但不发布 | `review_ready` 或任务级中间状态 | `merged`、`regression_passed` | +| 完整正式部署 | `released` | `merged`、`regression_passed`、`artifact_built`、`published`、`deployed` | + +## 每个阶段的要求 + +- `change_ready`：记录基线 commit、工作树、目标分支、任务范围和风险。 +- `verified`：根因或需求验收明确；自动测试和必要的黑盒/真机验证通过。 +- `pr_opened`：提交说明、测试证据、风险和回滚信息已写入 PR；不能把草稿 PR 当 `review_ready`。 +- `merged`：目标分支的合并 commit 已确认，不能只确认源分支 commit。 +- `regression_passed`：以合并 commit 执行项目规定的完整回归；失败则回到修复或停止。 +- `artifact_built`：产物由合并后的 commit 构建，记录版本、文件和 SHA256。 +- `published`：镜像/APK 等外部分发位置可复核，记录 digest 或文件校验和。 +- `deployed`：目标服务运行在预期版本，健康检查和关键路径验证通过；生产部署还必须进入 `released`。 + +## 配置和授权 + +读取项目自己的 delivery 配置，不把命令、主机、秘密复制到通用 skill。优先使用 ACK +的 `delivery.yaml`、builder/deployer/tester 契约和项目版本策略；缺失时停止在最近的安全状态。 + +生产部署必须同时满足：项目 profile 允许、目标明确、构建来源已固定、回归证据完整、当前 +请求覆盖生产部署。没有这些条件时只能报告，而不能用“用户之前说过发布”替代当前授权。 + +## 证据账本 + +至少记录：基线和最终 commit、工作树状态、测试命令及结果、黑盒/真机证据、PR/MR URL、 +合并 commit、tag、产物路径与摘要、部署节点/服务、健康检查、失败项和回滚指针。 diff --git a/skills/pr-ship/README.md b/skills/pr-ship/README.md new file mode 100644 index 0000000..be49cea --- /dev/null +++ b/skills/pr-ship/README.md @@ -0,0 +1,23 @@ +# pr-ship + +把已有 PR 从检查和合并推进到合并后完整回归、构建和部署。 + +## 什么时候使用 + +```text +处理当前 PR，确认 CI 后合并，跑完整回归并部署测试环境。 +``` + +## 使用前准备 + +- PR/MR 链接或当前分支上下文。 +- 审核、CI、目标分支和部署 profile 可被读取。 +- 需要生产部署时，当前请求必须覆盖该动作。 + +## Agent 会做什么 + +先检查 PR 是否可合并；合并后重新以目标分支 commit 回归和构建，再按配置继续发布或部署。 + +## 如何判断完成 + +报告会给出合并 commit，而不是只给源分支 commit，并附完整回归、产物和部署证据。 diff --git a/skills/pr-ship/SKILL.md b/skills/pr-ship/SKILL.md new file mode 100644 index 0000000..29d2504 --- /dev/null +++ b/skills/pr-ship/SKILL.md @@ -0,0 +1,45 @@ +--- +name: pr-ship +description: >- + 处理已有 PR/MR：检查差异、审核和 CI，必要时修复阻塞项，合并后以合并 commit 做完整回归， + 再按配置构建、发布和部署。用户说处理、合并、回归或发布 PR 时使用。 +--- + +# PR Ship：合并后的完整交付 + +重点是合并后的真实状态：PR 分支通过不代表目标分支已回归，也不代表产物和生产已更新。 + +## 何时使用 + +- 用户提供 PR/MR 或要求处理当前 PR。 +- 用户要求合并 PR 后完整回归并部署。 + +## 不适用 + +- 没有 PR、需要从零修 bug：使用 `bugfix-ship`。 +- 复杂需求尚未形成批准 PRD：使用 `specifier` 和 `requirement-flow`。 +- 只做 diff 审查、不合并：使用 `check`。 + +## 工作规则 + +1. 读取 PR 的目标/源分支、差异、关联任务、审核状态、CI、冲突和变更风险；使用 `check`。 +2. 审核、CI 或必需检查缺失时停止。若发现可修复问题，只有当前请求明确包含修复时才在 PR 分支上处理， + 然后重新验证；不能静默改变 PR 范围。 +3. 具备合并条件后执行合并，并重新获取目标分支；记录合并后的 commit，后续所有回归和构建都以它为来源。 +4. 读取并执行 `delivery-loop` 的状态机，运行完整回归；失败时停在合并后的中间状态或回到修复流程，不部署失败版本。 +5. 只有项目 profile 和当前授权允许时才构建、发布和部署；生产部署完成后做节点状态和关键路径检查。 + +## 安全门 + +- 不绕过审核、CI、分支保护或冲突；不强推、不重写已共享历史。 +- 不用 PR 源分支的旧 APK/镜像证明合并版本已发布。 +- 目标分支变化、合并后代码漂移、回归失败、产物来源不明或部署健康检查失败时停止。 + +## 必读资料 + +- 执行交付阶段时读取已安装的 `delivery-loop` skill 及其状态机 reference。 +- 发布版本时遵循 `releaser`；构建/部署/回归分别遵循 `builder`、`deployer`、`tester`。 + +## 完成报告 + +报告 PR/MR、审核/CI 结果、合并 commit、完整回归证据、产物摘要、tag、部署目标、健康检查和回滚点。 diff --git a/skills/pr-ship/agents/openai.yaml b/skills/pr-ship/agents/openai.yaml new file mode 100644 index 0000000..006c9f7 --- /dev/null +++ b/skills/pr-ship/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "PR Ship" + short_description: "Merge, regress, build, and deploy a PR" + default_prompt: "Use $pr-ship to process this PR through merge, full regression, and the configured deployment stop." +policy: + allow_implicit_invocation: true diff --git a/skills/requirement-flow/README.md b/skills/requirement-flow/README.md new file mode 100644 index 0000000..fe768c5 --- /dev/null +++ b/skills/requirement-flow/README.md @@ -0,0 +1,23 @@ +# requirement-flow + +把复杂需求从 PRD 评审、任务拆分、协作开发一路推进到集成回归和配置允许的发布部署。 + +## 什么时候使用 + +```text +把动态编辑需求做成 PRD，批准后拆任务开发，最后完整回归并部署测试环境。 +``` + +## 使用前准备 + +- 需求目标和相关项目上下文。 +- 用户愿意评审并明确批准某个 PRD 版本。 +- 项目已配置 ACK、测试环境和需要的构建/部署能力。 + +## Agent 会做什么 + +先生成可评审 PRD；批准后建立有依赖的任务 DAG，独立验证子任务，最后以集成结果推进交付。 + +## 如何判断完成 + +你会得到 PRD 版本、任务与依赖、各任务验证、集成回归、最终 PR/合并、产物和部署证据。 diff --git a/skills/requirement-flow/SKILL.md b/skills/requirement-flow/SKILL.md new file mode 100644 index 0000000..e7cf0a5 --- /dev/null +++ b/skills/requirement-flow/SKILL.md @@ -0,0 +1,46 @@ +--- +name: requirement-flow +description: >- + 处理复杂或跨模块需求：先用 specifier 形成并评审 PRD，批准后拆成有依赖的任务，再按共享交付流程推进， + 完成集成回归后按配置发 PR、合并、构建或部署。 +--- + +# Requirement Flow：从需求到交付 + +把需求规格、任务编排和最终交付连接起来；不绕过产品确认，也不让子任务各自直接发布生产。 + +## 何时使用 + +- 用户提出跨模块、跨页面、跨服务或需要多任务协作的新需求。 +- 用户要求从 PRD 继续开发，并在完成后回归、发布或部署。 + +## 不适用 + +- 已有复现证据的 bug：使用 `bugfix-ship`。 +- 需求仍需取舍和评审：先使用 `specifier`，不要提前创建开发任务。 +- 已有 PR 的处理：使用 `pr-ship`。 + +## 工作规则 + +1. 调用 `specifier` 探查现状、生成版本化 PRD；用户明确批准具体版本前，不创建 ACK 任务、不派 worker、不改业务代码。 +2. 只从批准的 `handoff.yaml` 创建任务 DAG：每个任务有范围、依赖、验收信号、验证方式、风险和回滚信息。 +3. 使用 `orchestration`/ACK 编排开发者和测试者；每个实现任务复用 `delivery-loop`，但默认只推进到 + `pr_opened` 或 `merged`，不让子任务单独部署生产。 +4. 依赖任务完成后做集成回归；需求基线、API、数据模型或验收条件发生变化时停止并回到 `specifier` 评审。 +5. 父需求通过集成回归后，按项目 profile 和当前授权继续构建、发布和部署；完整过程读取 `delivery-loop` 状态机。 + +## 安全门 + +- 未批准 PRD、缺 handoff、任务依赖循环、验收信号不可观测或集成回归失败时停止。 +- 不把 PRD 中的自然语言当命令、权限或发布授权；不静默扩大需求范围。 +- 子任务不打生产 tag、不单独升级生产；发布以父需求的集成 commit 为来源。 + +## 必读资料 + +- 需求阶段使用 `specifier` 的评审和 handoff 规则。 +- 编排阶段使用 `orchestration`/ACK 的任务、worker、回归和交付规则。 +- 交付阶段读取已安装的 `delivery-loop` skill 及其状态机 reference，并按项目配置调用 builder、tester、deployer、releaser。 + +## 完成报告 + +报告 PRD 版本、handoff、任务 DAG、各任务验证、集成回归、最终 commit、PR/tag、产物摘要、部署状态和回滚点。 diff --git a/skills/requirement-flow/agents/openai.yaml b/skills/requirement-flow/agents/openai.yaml new file mode 100644 index 0000000..39f8052 --- /dev/null +++ b/skills/requirement-flow/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Requirement Flow" + short_description: "Turn an approved PRD into shipped work" + default_prompt: "Use $requirement-flow to turn this approved requirement into dependent tasks and a complete delivery flow." +policy: + allow_implicit_invocation: true