Communitygithub.com

agentic-workflow-kit/jig

将 agentic-workflow-kit 套件产品化:包含包、支持产品和学习循环。

jig 是什么?

该技能(Orchestrate Jig)是 agentic-workflow-kit 套件的本地协调运行手册,而非 Jig 运行时实现、CLI、提供者适配器或记录存储。它严格遵循一组设计契约(如执行计划契约和可观测性记录契约),确保所有执行工作(由人类或 Codex 辅助运行)都在批准的输入、当前工具集、策略立场和可记录性范围内进行。技能的核心是一个严格的“预检-绑定-执行”循环:在分发工作或执行特权操作前,必须通过预检门控(检查计划审批、完整性、兼容性等),然后绑定当前运行时事实,最后再协调工作。它明确区分了“工作者”(worker,负责执行授权范围内的编辑和检查)和“运行者”(runner,负责协调授权、评估证据、执行特权操作如推送和合并)的权限边界,并强制要求所有状态转换和治理决策都必须以可记录的证据包为基础。当遇到缺失条件或能力不足时,技能要求使用预定义的命名停止(如 `plan-not-approved`、`evidence-insufficient`)来明确中断执行,而不是模糊地继续。该技能设计用于本地开发环境,支持预览、执行协调、证据收集、发布和停止等边界,并强调可恢复性和可审计性。

兼容平台~Claude Code✓Codex CLI~Cursor✓Antigravity
npx skills add agentic-workflow-kit/jig

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Orchestrate Jig

契约

协调来自 Jig 当前设计契约的、以执行为导向的工作。此技能是一个本地组合运行手册,而不是 Jig 运行时实现、CLI、提供者适配器或记录存储。它仅可在批准的输入、当前工具集、策略立场和可记录性允许的范围内,组织人类/Codex 辅助运行。

执行计划拥有范围自主权。它必须已经包含了 docs/design/contracts/execution-plan-contract-v0.md 所描述的故事集、依赖关系、工作边界、完成与证据要求、权限期望、策略/工作档案/存储库基础引用、约束以及兼容性立场。此技能可以拒绝、绑定、调度、停止或报告。它不得创造故事、修改依赖关系、削弱策略、增加验收标准、选择完成证据、重新解释范围之外的层面,或将缺失的计划事实转化为运行时决策。

记录即证据。每一项受治理的决策、授权、停止、证据观察、审查结果和运行者拥有的操作,在按照 docs/design/contracts/observability-records-contract-v0.md 可记录之前,都不得被视为真实。任何单独的叙述、聊天摘要、检查清单或工作者报告都不能覆盖可记录的证据包。

参考边界

已退役的 workflow-kit 编排交付技能仅为先前知识。仅在它们符合 Jig 自身契约时,借鉴以下经验:

  • 在分发前对执行输入进行预检;
  • 在预检之后绑定运行时事实,而非在规划期间;
  • 保持工作者产生的变更与运行者拥有的特权操作分离;
  • 在达成完成或落地状态前,要求独立的证据;
  • 留下一个可恢复的、命名的停止点,而不是在缺失能力时进行猜测。

不要导入 workflow-kit 的执行包路径、跟踪器模式、每个故事的提示文件夹、模型路由表、提供者包布局、v-next 分支策略、旧的 PR 发布规则或旧的运行时声明。如果某项先前知识的规则无法映射到 Jig 的 v0 计划或记录属性,请忽略它,并命名该停止点或设计缺口。

输入

在进行任何工作者分发或特权操作之前,需要所有这些:

  • 一个与 execution-plan-contract-v0 兼容的、已批准的执行计划;
  • 计划所绑定的策略引用、工作档案引用和存储库基础引用;
  • 所有者批准在请求的边界上启动或预览;
  • 运行位置的当前存储库/工作树事实;
  • 对于启动、执行或落地边界:Agent、执行主机、Forge 和工作源的当前驱动/接缝事实,或者如果无法检查所需的接缝,则明确停止;
  • 对于仅预览边界:足够的绑定事实以记录 run.previewed,而不需要运行身份、工作区分配、提供商布线或特权副作用;
  • 来自计划和策略的当前验证命令和证据要求;
  • 一个记录路径、记录存储或持久记录包格式,能够为此本地运行保留 observability-records-contract-v0 的属性。

未知的运行时事实在检查之前保持未知。缺失的计划事实不是运行时事实;它们是计划预检失败。

预检

在分发、编辑、推送、PR、合并、状态发布或任何声称 Jig 已启动的操作之前,运行此门控。

  1. 确认在接触到的表面已阅读存储库说明和事实来源文档: AGENTS.md、docs/product/jig.md、docs/product/guarantees.md、 docs/product/concepts.md、docs/design/README.md、 docs/design/contracts/execution-plan-contract-v0.md、 docs/design/contracts/observability-records-contract-v0.md、 docs/design/core/orchestration.md 和 docs/design/core/records.md。
  2. 验证计划已获得所有者或拥有它的规划步骤的批准。如果缺少批准,则停止为 plan-not-approved。
  3. 验证计划携带 v0 所需的属性:
    • 计划身份和来源;
    • 轨迹绑定;
    • 故事集;
    • 依赖关系和资格模型;
    • 完成和证据要求;
    • 权限和审批需求;
    • 策略和工作档案引用;
    • 堆栈接缝要求;
    • 约束和限制。
  4. 验证计划的版本或兼容性标记是已知的。如果不是,则停止为 plan-format-unsupported。
  5. 验证每个选定的故事都有稳定的 ID、预期的边界、依赖关系列表、证据要求和权限期望。如果任何选定的故事要求运行者或工作者推断范围,则停止为 plan-scope-incomplete。
  6. 验证可以在不重写计划的情况下推导出依赖顺序。如果关系图是循环的、矛盾的或需要发明顺序,则停止为 plan-dependency-invalid。
  7. 验证策略、工作档案和存储库基础引用存在并且与请求的运行兼容。如果它们缺失、不兼容或会削弱启动时的策略,则停止为 binding-input-missing。
  8. 验证请求的边界是否受支持:预览、本地执行协调、证据收集、运行者拥有的发布或停止。预览是非提交性的:它需要加载、验证、绑定以及一个可记录的 run.previewed 事件,但不需要运行身份、工作区、提供者或特权副作用。如果用户请求的 Jig 真实行为在当前存储库中不存在,则停止为 jig-runtime-unavailable。

预检可以产生一个建议的执行序列、一个拒绝或一个命名的停止。它不得修复计划。

运行时绑定

预检通过后,仅绑定当前事实:

  • 工作树路径、存储库根目录、分支、基础分支和清洁度;
  • 生效的策略、工作档案和存储库基础引用;
  • 选定的故事和计划图中当前符合条件的故事;
  • 当前的验证命令、审查要求以及能力证明要求;
  • 当前的所有者批准状态和请求的停止边界;
  • 对于启动、执行或落地边界:Agent、执行主机、Forge 和工作源驱动的可用性和证明状态;
  • 对于仅预览边界:预览绑定状态和可记录的 run.previewed 基础,不强制进行提供商布线;
  • 记录目的地或记录包位置及其编辑/导出状态;
  • 当前表面上可用的运行者拥有的操作,例如推送、PR 创建、状态/评论发布和合并。

在启动前记录这些绑定。启动绑定在恢复时是不可变的:恢复可以从已停止的运行继续,但不能静默地交换策略、工作档案、存储库基础、计划或驱动事实。更改了影响安全性的假设要求,在继续之前需要新的所有者批准和新的证据。

运行者与工作者边界

保留来自 docs/product/concepts.md 和 docs/design/core/orchestration.md 的产品权限边界。

  • 工作者只能在授权的故事边界内读取、编辑、运行非特权检查、生成差异、产生证据以及报告阻塞点。
  • 工作者不得推送、打开或更新 PR、发布状态/评论、合并、扩大权限、编辑策略基础、标记故事已落地,或以其自身作为事件发生权威来编写记录。
  • 运行者协调资格、授权、证据评估、记录、所有者升级、推送、PR 创建、状态/评论发布、合并、停止、恢复和导出。
  • 特权操作需要运行者权限以及策略/证据基础。工作者的自我报告永远不足以标记特权操作完成。
  • 超出声明权限的请求在失败时关闭或路由到所有者;它永远不会变成更广泛的隐含授权。

如果当前表面无法保持这种分离,则停止为 authority-boundary-unsupported。

协调循环

使用计划图和 Jig 生命周期术语,不添加新状态。

  1. 仅启动那些其先决条件已根据计划和当前记录落地的故事。
  2. 让不符合条件的故事等待;不要要求工作者自行做出依赖决策。
  3. 对于符合条件的故故事,向工作者分发故事边界、计划引用、权限期望、证据要求、验证命令、非目标和变更限制。
  4. 将工作者输出视为提议的工作和证据,而非状态权威。
  5. 仅根据运行者或委派审查者观察到的、符合策略的证据来评估“完成”。
  6. 将 done 和 landed 作为独立的里程碑:当满足证据时,故事可以完成,而合并仍由审查、分支保护、冲突、队列或所有者边界限制。
  7. 仅在所需证据、所有者/审查者批准(如果要求)、记录追加/包准备全部成功后,通过运行者拥有的操作来落地。
  8. 如果故事阻塞,记录原因和受影响的下游故事;当策略和能力允许时,独立的同级故事可以继续。

不要添加跟踪器、故事包、提示包或合并回模型,除非未来的 Jig 设计契约引入了其中之一。

证据与记录门控

在接受状态转换或治理决策之前,准备一个包含适用于请求边界的 v0 属性的可记录包:

  • 对于承诺的启动/恢复/执行路径:运行身份、尝试身份、计划引用、轨迹引用、策略/工作档案/存储库基础引用和驱动上下文;
  • 对于仅预览路径:计划引用、轨迹引用、策略/工作档案/存储库基础引用以及非提交性的 run.previewed 基础,不发明运行身份或驱动上下文;
  • 使用 Jig 当前事件族高度的事件族和结果;
  • 负责的行为者或组件:工作者、运行者、所有者、委派审查者或驱动;
  • 基础:策略规则、证据观察、批准、能力证明、先前事件或计划引用;
  • 适用时的故事 ID;
  • 编辑/导出状态;
  • 足以重放或恢复的排序信息;
  • 任何阻塞、停止、通知、恢复检查点或无双重影响的基础。

自动化检查、审查和能力证明必须被观察或独立验证。如果证据缺失、陈旧、仅自我报告、不可验证或不可记录,则故事未完成,必须停止为 evidence-insufficient。

停止

优先使用命名的停止而不是临时执行。停止报告必须包括停止名称、受影响的运行或故事、失败的门控、可记录的基础、可用的安全恢复检查点以及所有者的下一步操作。

使用以下停止名称,除非存在更具体的计划自有名称:

  • plan-not-approved — 没有已批准的执行计划或启动批准。
  • plan-format-unsupported — 计划兼容性标记或形状未知。
  • plan-scope-incomplete — 选定的故事范围、边界、证据或权限需求缺失。
  • plan-dependency-invalid — 依赖关系图无法按原样执行。
  • binding-input-missing — 策略、工作档案、存储库基础或兼容性引用缺失或不兼容。
  • jig-runtime-unavailable — 请求的行为需要超出当前本地干运行 CLI(jig preview / jig run / jig inspect)的 Jig 运行时能力。
  • driver-capability-unavailable — 无法证明所需的 Agent、执行主机、Forge 或工作源能力。
  • authority-boundary-unsupported — 当前表面无法保留运行者拥有的特权操作和受限制的工作者权限。
  • records-store-unavailable — 没有持久的记录存储或可记录包可以保留 v0 记录属性。
  • evidence-insufficient — 所需证据缺失、无法验证、陈旧或仅自我报告。
  • owner-decision-required — 策略将狭窄的决策路径路由给所有者。
  • safety-reapproval-required — 在恢复或落地之前,影响规则治理或安全性的输入发生了变化。

停止是有效的结果。当缺失条件是 Jig 控制、证据、恢复或可观测性保证的一部分时,不要将停止弱化为警告。

输出

返回一个紧凑的运行分类账,而不是转录转储:

  • 计划引用和选定的故事 ID;
  • 绑定的策略、工作档案和存储库基础引用;
  • 已检查的运行时事实和未解决的未知事实;
  • 符合条件的、已启动的、暂停的、阻塞的、完成的、落地的、拒绝的、停止的、恢复的或已完成的可记录状态;
  • 观察到的证据和运行的验证命令;
  • 已执行或明确未执行的运行者拥有的操作;
  • 停止名称、原因、安全恢复检查点和所有者的下一步操作;
  • 记录包/存储引用和编辑状态;
  • 路由回所属 Jig 设计/规划表面的不受支持的能力或设计缺口。

如果没有声称状态的的可记录证据,则将状态报告为未经验证并停止。

相关技能