issue-delivery
当已就绪 GitHub Issue 要形成可独立核验交付物时,从远端恢复范围、依赖、授权、成功条件、交付形态和所有权,按合同交付 Draft PR 或自足证据评论,并记录实际运行、未运行与缺口。已有授权不重问;不建任务图,不审查/合并自己的 PR,也不判生命周期。Use to deliver one ready Issue as its contracted Draft PR or evidence comment. Restore remote authority and ownership, validate proportionately, and return facts without task-graph, merge, or lifecycle decisions.
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 1
- Forks
- 2
01 前言 Front Matter
- name
- issue-delivery
- description
- 当已就绪 GitHub Issue 要形成可独立核验交付物时,从远端恢复范围、依赖、授权、成功条件、交付形态和所有权,按合同交付 Draft PR 或自足证据评论,并记录实际运行、未运行与缺口。已有授权不重问;不建任务图,不审查/合并自己的 PR,也不判生命周期。Use to deliver one ready Issue as its contracted Draft PR or evidence comment. Restore remote authority and ownership, validate proportionately, and return facts without task-graph, merge, or lifecycle decisions.
02 资源文件 1
- 参考文档agents/openai.yaml156 B
03 SKILL.md 正文
交付一个 Issue
把一个已经存在的 GitHub Issue 从领取推进到合同指定的可独立核验交付物。GitHub 保存持久合同,本 Skill 只规定交付行为;具体命令、终端、Session 生命周期和消息由当前实际使用的工具提供,不复制进本文。
边界:本 Skill 负责哪一段
任务图与就绪 Issue → 【本 Skill】领取 → 边界 → 实现 → 验证 → 远端交付物
├─ Draft PR → 审查与授权合并
└─ 评论/证据 → 回收
- 上游不属于本 Skill:长程目标对齐、父 Issue、子 Issue 拆分和依赖关系由
objective-to-issues或负责人建立。 - 下游不属于本 Skill:PR 的独立审查、当前 head 校验、Draft → ready、合并授权与合并后复核由
pr-integration负责;任务图更新和回收仍归驱动者。 - 本 Skill 不合并自己的 PR,也不把自己的交付当作已经验收。
本 Skill 是一段行为,不是驱动者。它只返回事实与段结果:本段完成后把交付事实交回 issue-workflow,由它决定进入审查、继续下一切片还是收口。本段不反向调用驱动者,不自建模式判定,也不判定父级或本 Issue 是否完成。被直接调用时同样只完成本段,并在结束时说明状态判定尚未作出、下一段归谁。
一、进入条件
进入本流程需要同时成立:
- 当前任务已经指向一个具体 GitHub Issue,或已经授权从既有任务图中领取;
- Issue 合同已经唯一指定交付形态;
- 已有覆盖该形态的远端写入授权:PR 适配器至少包含推送工作分支和创建 Draft PR,评论/证据适配器至少包含向该 Issue 发布交付评论。
不进入的情况:目标尚未对齐;Issue 还只是未获准交付的想法或方案讨论;只需要一次不进入 GitHub 合同的临时回答;改动小到不需要 Issue,且当前任务没有要求走 GitHub 交付。
二、从远端 Issue 恢复合同
每次开始或恢复时重新读取远端当前状态,不从记忆、聊天上下文或本地草稿恢复。至少取得:
- 目标来源:父 Issue、批准来源和当前权威链接;
- 范围与明确不做事项;
- 依赖与就绪状态:blocked-by、sub-issue 关系、需要先落地的 PR;
- 授权:允许修改什么、允许哪些外部操作、哪些决定仍属于负责人;
- 成功条件与验收方式;
- 写入所有权:本 Issue 拥有哪些文件和资源,哪些明确属于其他执行者;
- 交付形态:代码/配置变更使用 PR 适配器,调研/审计/只读证据使用评论/证据适配器;不得同时保留两个候选让执行者临场选择;
- 既有状态:已有讨论、交付评论、分支和 PR,避免重复交付或覆盖他人工作。
GitHub Issue 只优先于聊天记忆、本地草稿和运行期协调状态:与这三者冲突时以远端 Issue 为准,并把差异写回 Issue 或升级给协调者。协调工具中的 Run、Task 和消息只帮助找回活动 Session 与执行者,不是持久合同。
Issue 不是权威本身,必须链接当前权威与批准来源。缺少这类链接,或 Issue 与当前权威、当前授权、负责人在该 Issue 之后给出的明确指令冲突时,不要用 Issue 覆盖它们:保持相关范围只读,把冲突写入 Issue 或当前任务,由协调者或负责人裁决后再继续。
第 1–7 项中会改变实现结果的内容缺失时,不要自行补写需求。
三、就绪判定与领取
一次只领取一个 Issue,且需要同时满足:
- 依赖已解决,没有未完成的 blocked-by;
- 范围、成功条件和文件所有权足够清楚,能在不猜测负责人偏好的前提下开始;
- 写入授权覆盖需要修改的全部范围;
- 没有其他执行者正在同一范围内工作。
多个就绪 Issue 需要同时推进,或者当前 Issue 实际上是一棵需要选择切片的子树时,不要在一个 Session 内串起来自行扩张:把控制权交回 issue-workflow,由它判定模式和切片顺序。
确实需要多个执行者时,分工和所有权由 orchestrated-collaboration 建立,且由驱动者决定何时进入,本段不自行派发。
不就绪时按最小动作处理:
- 只缺可自行查明的事实 → 自己查清,把结论写回 Issue,然后继续;
- 缺会改变结果的负责人决定 → 停止实现,在 Issue 上提出一次合并后的问题,或按当前协作关系升级;
- 边界与另一个 Issue 重叠 → 先取得明确分区,不凭猜测缩小或扩大范围;
- 依赖未完成 → 不领取,说明它在等什么。
停止和升级是正常结果,不是失败。不要为了推进而把未确认的假设写成需求。
四、建立执行边界
开始改动前确定并记录:
- 执行者与 Session/终端标识;
- PR 适配器使用基于当前远端默认分支、只服务这一个 Issue 的专用分支或 worktree;评论/证据适配器没有版本化文件改动时不为形式创建分支;
- 允许写入的文件与资源范围,以及明确只读的范围;
- 合同指定的唯一交付形态与停止条件(时间、成本或阶段)。
共享单点的唯一规范源是 agent-control/authority/04-collaboration.md 的“共享单点清单的唯一权威外延”,本段不复列或改写六类。本段的分支/worktree 约束只投影其中“Agent 系统的共享工作目录/分支”这一子集;若动作触及其余类别,返回规范源核对。worktree 只提供目录内文件隔离,不授予其他共享单点的写入权。所有权不明,或可能与其他活动 Session 重叠时,保持相关范围只读,并按 orchestrated-collaboration 取得明确分区后再写入。
任何两个执行者不能推送同一个分支。
五、按风险选择路径
默认直接实现。 普通、低风险、可回退的 Issue 不进入多轮 Challenge、三阶段深度规划、强制自审循环或额外调研。
已有预授权时不重复索要批准。 Issue 合同已经写明实施授权时,实现、验证和合同指定的远端交付都直接进行:PR 适配器还包括推送工作分支与创建 Draft PR,评论/证据适配器则包括发布自足评论并回读。只有合同没有覆盖的新决定才升级。把已经授权的事再问一次,是把成本转嫁给负责人。
只有出现以下信号时才升级,并且只升级到需要的程度:
- 存在多个会显著改变结果的实现方向,且选错代价明显;
- 关键假设不成立,或实际范围、成本明显超出 Issue 描述;
- 需要难回退操作、共享状态修改或破坏性动作;
- 连续尝试没有减少关键未知。
不要因为“看起来复杂”或“想更稳妥”就升级:升级要指出命中了上面哪一条具体信号。全链共用的三级风险判据在 issue-workflow,本节只覆盖叶子段;两处出现分歧时以那张表为准,不在本 Skill 复制它。
升级路径:
- 问题界定、方向、方法或投入产出不清 →
adaptive-problem-solving; - 需要多个执行者、跨 Session 协作,或已出现共享写入碰撞 →
orchestrated-collaboration; - 需要可复用的当前知识或多来源调研 →
knowledge-maintenance。
发现值得做但超出本 Issue 范围的工作时,把它留给任务图或在 Issue 中登记,不在本次 PR 里顺手扩张。
六、实现并做相称验证
实现只覆盖本 Issue 分配的范围。发现范围外的问题时记录并报告,不顺手修改其他执行者拥有的文件。
评论/证据适配器同样需要“实现”:完成合同要求的读取、实验、核验与综合,并把事实、推断、未运行项和证据等级分开;“没有改文件”不等于可以跳过验证。交付评论必须能让新 Session 不读聊天或终端就逐条复核成功条件。
先服从仓库自己的规范、类型系统和风险门,再按改动相关性裁剪下面的通用正确性扫描;低风险改动不需要机械跑完整清单,但任何被跳过的相关维度都要进入验证缺口:
- 正确性与边界输入:主路径、空值/空集合、上下界、无效输入、编码、时区与精度等是否符合合同;
- 异步/错误路径:并发、取消、超时、重试、部分失败、回退和错误传播是否保持一致;
- API 与兼容性:公开接口、配置、序列化格式、schema 与既有调用方是否被有意兼容或迁移;
- 测试真实性:测试是否真正经过改动路径、能在缺陷存在时失败,并避免只验证 mock、快照或实现细节;
- IO/数据/迁移:输入输出、持久化、事务、幂等、迁移和回滚是否保全数据;
- 权限/安全/隐私:授权边界、秘密、日志、敏感数据和最小权限是否守住;
- 性能/资源:复杂度、延迟、内存、句柄、连接、并发上限和清理是否与使用规模相称;
- 可维护性:命名、结构、重复、错误可诊断性和必要文档是否让下一位执行者能安全修改。
验证报告使用同一组可恢复字段,至少做到:
- 发现:按严重度排列可定位、可复查的问题与证据;没有可执行发现时明确写“无”,不让空白承担含义;
- 能实际运行或检查的改动要真正运行,不用“应该可以”代替;
- 纯文档、配置或清单类改动,至少做格式、必需字段、相对引用和边界自检;
- 实际运行:命令或检查、预期结果和真实结果;
- 未运行:没有执行的相关检查及原因,不用“无”掩盖环境或权限限制;
- 剩余验证缺口:当前证据尚未覆盖的风险和它对交付结论的影响;
- 开放问题:需要后续证据、负责人决定或另一个所有者处理的未知;
- 检查是否产生了范围外的副作用。
不要为了让检查通过而放宽验收条件或改写 Issue 的成功条件。
七、发布合同指定的远端交付物
PR 适配器
- 提交前确认改动范围与写入所有权一致,且不包含其他执行者的未提交改动;
- 推送到本 Issue 专用的分支;普通交付推送不使用强制更新。已推送分支确因变基需要改写时,只能按
pr-integration的分支安全链核验同一特性分支和远端旧 head,并使用 lease 保护;lease 拒绝后停止并重新读取远端,不改用无保护强推; - 创建 Draft PR;本 Issue 已有对应 PR 时更新同一个 PR,不再开新的;
- 创建或更新后重新读取远端 PR,确认目标分支、当前 head、链接和正文是实际状态。本地命令成功不等于远端合同已经建立。
PR 保持 Draft。本段和交付者都不执行 Draft → ready;唯一执行者是持有当前 PR 整合写入所有权的 pr-integration 执行者,且必须先通过其当前 head、合同、验证、反馈与授权前置门,转换后再重读远端。转换不等于合并授权。不要自行开启自动合并或合并自己的 PR。
评论/证据适配器
- 在目标 Issue 发布一条自足交付评论;不得把多条零散进度评论拼成只有原执行者才能解释的结果。
- 评论至少逐条对应成功条件,区分事实、推断与未知,并列出证据链接、实际运行、未运行及原因、剩余验证缺口、开放问题和下一责任人。
- 发布后重新读取评论,确认稳定 URL、作者、目标 Issue 与正文都是实际远端状态;本地输出或写入响应不能代替该复核。
- 合同只要求评论/证据时,不创建空提交或占位 Draft PR;稳定评论 URL 就是交付来源,随后把事实交回
issue-workflow回收。
八、交付物与 Issue 必须说明什么
PR 正文或评论/证据交付至少包含:
- 使用安全引用链接对应 Issue,以及父 Issue(如果存在);
- 实际完成的结果,与 Issue 成功条件的对应关系;
- 做过的验证:命令或检查、预期、真实结果;
- 失败项、未执行的检查及其原因;
- 副作用,包括范围外发现和已经产生的外部影响;
- 剩余项、已知未知和下一步所有者;
- 需要负责人决定的内容(如果有)。
入口批尚未落地全局不变量前,PR 正文引用其他 Issue 的规则只引用 objective-to-issues 第三节第 4 项:统一写 关联 #N,不在本段重列或变造规则。评论/证据交付也使用同一安全渲染。
同一批信息要让 Issue 本身可恢复:PR 适配器至少在 Issue 留下指向 PR 的来源,评论/证据适配器以稳定评论 URL 作为来源。不要把交付说明只留在聊天、终端输出或本地文件中。
九、停止、升级与恢复
遇到以下情况停止实现并升级,而不是继续猜测:
- 需要负责人决定;
- 需要超出授权的写入或外部操作;
- 与另一个执行者的范围发生冲突;
- 达到本次的停止条件。
升级时说明:当前状态、已经存在的交付评论或已推送的分支/提交/Draft PR、已验证和未验证的内容、阻塞点和建议。
中断后恢复:交付状态只从远端 Issue、交付评论、PR 和分支恢复;PR 适配器重新读取当前 head,评论/证据适配器重新读取稳定评论 URL,不假设本地工作区仍然代表远端状态。当前权威、当前授权和负责人的最新明确指令仍按第二节优先,不被 Issue 上的旧记录覆盖。
收到纠偏时先判断它推翻了哪条假设:本 Issue 的结论依赖那条假设,或与受影响范围共享写入时,停止并等待裁决;本 Issue 有独立合同和独立写入所有权、结论不依赖被推翻假设时,继续交付并记录这次判断。不要因为同一批次里另一条分支被纠正就整体停摆。冻结范围的完整判据在 issue-workflow。
十、完成本段
本段完成的判据按合同交付形态唯一确定:
- PR 适配器:Draft PR 已存在于远端、用安全引用关联对应 Issue、正文说明结果与验证,且分支当前 head 就是被说明的内容;
- 评论/证据适配器:自足评论已存在于目标 Issue、稳定 URL 可重读、逐条覆盖成功条件与验证缺口,且合同没有要求版本化资产变更。
“实现完成”不等于“验收通过”,也不等于“产品决定成立”。三者不能互相替代。PR 的审查与合并授权、所有交付的任务图更新和父目标重新验收属于下一段。
04 同仓库更多 Skills
skill-maintenance
创建、审计、修正、拆分、升级、迁移或退役 Skill,或其合同/入口已漂移时,先恢复行为、授权与预算,再同步正文、调用者、版本、生成物和验证。普通业务维护、纯格式修正、承载位置未定的纠正不触发。Use for explicit Skill maintenance, not carrier choice.
skill-appraisal
判定一个 Skill 组该不该进当前装配、归哪些事项、与谁重叠,或对已判定过的组按节拍复核。三种进入:首次判定新候选、补判早已在用但从未判定过的组、按失效条件复核。判定单位是组不是单个 Skill;产出必须留下失效条件与下次最少复核步骤。用于外部来源、他人所写、疑似重复或从未被判定过的组。从零设计新 Skill 用 agent-skill-design;已定下后的改造、迁移、退役用 skill-maintenance;只要外部标准与版本事实用 capability-lifecycle;对象是 knowledge 用 knowledge-maintenance。本 Skill 只产出判定,不安装、不写配置、不改 profile。Appraise a Skill group, or recheck an adopted one. Judgement only, never installs.
self-improvement
当用户指出 Agent 漂移、误解、重复犯错,要求把任务经验固化为系统改进,或讨论只增概念却不减关键未知、形成决定或可检验资产时,只暂停依赖被推翻假设的路径,重锚原问题、持久记录纠正、诊断原因,并在授权内改进入口提示词或 Skill。最小实验不能验收产品交付;普通一次性错误、偏好或任务内修复不触发完整自我优化。Use for reported drift, misunderstanding, repeated mistakes, durable Agent improvement, or abstraction loops without decisions or testable assets. Freeze only affected paths and avoid a full detour for ordinary one-off corrections.
resource-observability
当用户查询 Codex/Claude 账户额度、重置时间、Codex 重置券、单 Session Token,或高成本/多 Agent 工作要决定启动、并行、降级、延后或停止时,按需读取 Orca 账户快照与固定 ccusage 回执,区分状态、来源、可信度和未知值。不要用于低风险任务、轮询、自动调度/消费权益、账单推断或长期保存快照。Use for account capacity, reset times, credits, session tokens, or consequential resource decisions. Skip routine work, polling, scheduling, automatic credit use, billing inference, and durable snapshot storage.
orchestrated-collaboration
当用户明确要求多 Agent/多 Session/跨 Provider 协作、任务已授权委派,或活动 Session 发生共享写入碰撞时,建立目标来源、排他所有权、可追踪交付、独立验收与综合;按共享资源和 Issue 子树确定唯一协调者,只冻结重叠或受推翻假设影响的路径。协调者参与高价值多交付件能力的拆分或设计时,由未参与者复核父目标;使用已选后端,选 Orca 时动态读 orchestration 指南。不要因复杂、额度或空闲 Agent 擅自并行,也不把试用变成长期依赖。Use for authorized multi-agent work, cross-session delegation, or shared-write collisions. Establish exclusive ownership, traceable delivery, independent acceptance, and bounded synthesis; add parent-goal review when required and avoid invented coordination or permanent platform commitments.
knowledge-maintenance
用于多来源调研、可重复实验、会影响权威/Agent 配置/重要决定的研究,或用户要求复用、复核、更新当前知识时:先找已认可知识和失效条件,只补变化、冲突与缺口,再经价值门和可信门更新。不用于低成本一次性事实、原始材料/研发过程留存、私域结构设计、定时全量重查或旧仓导入。Use before multi-source research, repeatable experiments, consequential authority/configuration decisions, or explicit knowledge reuse. Skip cheap one-off facts, raw retention, private architecture, scheduled full re-research, and bulk legacy imports.