用途
gimbal-workflows 用于指导如何把 Gimbal 工作流写成普通 Go 代码：一个程序的目的、决策与证据都应能在源码中直接看到，追求接近一页伪代码的清晰度。研究、对比、批评、重试、worktree 与交付等，都被视为用普通 Go 和 Gimbal 原语内联编写的策略，而非隐藏在辅助函数里。
主要能力与设计原则
明确结果与其证明
先用文档注释为操作、作用域或条件给出人类可读标题与描述。设计时区分三件事：程序（角色、分支、并发、反馈与停止决策）、输入（本次调用的目标、项目、issue、计划或候选）、知识（智能体工作时可检索的材料）。任务数据应放入参数、作用域上下文和本地文件，而不是把每个新任务编码进编排逻辑。
选择最小的有用形态
文档给出按需选择的形态：单一明确任务用一次智能体轮次；依赖阶段用带显式结果传递的序列；独立调查或候选用并发分支加 join；多个智能体共享同一初始研究时先研究一次再分叉对话；竞争实现用独立 worktree 加裁判检查真实候选；批评与修订用带停止条件的显式往返；已知有限集合则迭代给定条目；下一步任务依赖新证据时用规划者驱动循环配合 worker 与验证反馈。
角色职责与独立判断
使用 roles.go 中既定角色常量。研究者确立事实与来源位置，规划者选择下一步任务，工作者执行，验证者检查结果与证据是否满足验收，监督者指导活跃智能体。分支名标识参与者，角色标识可复用的工作类型，运行绑定选择模型。不要为获得模型分配而向内部默认值添加工作流或供应商特定角色。共享研究可节省重复阅读，但裁判必须检查原始证据与真实候选；把 worker 对话分叉给裁判会连带其假设。
所有权与交接可见
会话按其工作生命周期放置。每个并发分支都需要所有者，并在所属工作结束前完成 join。取消与清理是两件事。并行编辑智能体若可能互相干扰，应给独立 worktree。关键信息在派发前落到本地，prompt 使用绝对路径指向 issue、计划、源码或研究。交接给出确切任务、相关文件、观察结果、未决发现与决策，不要依赖子作用域或供应商对话成为共享项目状态。
自适应规划与重试边界
自适应循环应从目标、当前待办和观察结果选择工作，并分配带完成定义的一致结果。把真实 worker 结果与验证反馈回规划。审查发现是针对目标调查的声明，而不是自动加入目标。让重试、限制与升级可见且与任务匹配。不确定性所在之处才投入能力：前沿规划者可以值得一次昂贵轮次，低风险后台工作可用更便宜的 worker，但验证者要足够强、每次拒绝反馈回规划并限制尝试次数。当工作不可逆、验证薄弱或坏尝试可能破坏共享状态时不要用该模式。供应商、harness 或执行错误不是被拒绝的实现尝试，除非工作流显式处理否则不重试。
防止范围漂移
为规划者、worker 和验证者提供范围教练，抵制过度工程、未请求功能、镀金以及在没有合理实际失败单元测试情况下的假设边界修复。教练是建议性的，绝不作为完成门槛。必要约束也要写进初始任务。
验证行为与完成度
在实现前选择有意义的验收证据，不要让 worker 削弱该条件以通过。用 Check 记录命令、工作目录、退出码、两个输出流与执行错误；非零退出是证据而非 Check 错误。用 RunCommand 时普通 Go 需要返回值本身。Check 收集证据但从不认证成功。前台依赖用 Service，成功启动不等于就绪，就绪检查留在普通工作流代码中。声明作用域是生命周期边界。
可调用与可理解
入口是普通 Go，接收 context.Context、gimbal.Env 及可选的包本地 Params 结构。支持字符串、整数、布尔及其 polytype.Optional；必填字符串非空、必填整数为正；Optional 保留省略与显式空值/零值区别，不接受 null。用已安装主机生成外部模块，声明 polytype 为 Go 工具并固定版本；生成后保持 Go 源码与字段注释为权威，输入、输出或形状变化后重新生成。插件主包导出 Register，注册生成的 Definition 与后端配置，用 go build -buildmode=plugin 构建并安装到配置的 --plugin-dir；中央与工作流守护进程各自加载排序后的目录，需部署匹配插件并重启。
路由、环境与输出声明
工作流与任务路由相互独立，分别用 --workflow-endpoint 和 --task-endpoint 选择。远程轮次用 WithTaskFiles 提供显式命名字节；用 WithYields 内联声明输出，不要把返回的 context 赋值，输出属于该生产者；服务即使无输出也必须发布空文件，有限生产者仅在退出零后发布。用 WithRequirements 声明消费需求，重复调用累积访问多个存储，用 DefaultStore 表示未命名存储。程序收到的是字符串环境变量，值不会自动插入 prompt，子定义会跨存储遮蔽祖先。
使用方式
通过 Godoc 查看当前 API；对已有命令使用 Gimbal，构建与安装应用参考 Build and release。在 Gimbal 应用中通过 /workflows/<name> 与人类审查内置工作流源码；在检出目录中运行 just dev 启动实时应用，工作流编辑会刷新其图、prompt、嵌套上下文检查与参数描述。阅读页面不会运行它，需用 gimbal run <name> 调用。生成外部模块可用 gimbal generate 命令，构建插件用 go build -buildmode=plugin，调用可用 --input 传 JSON 或 @file，或用参数标志，--follow 等待终态完成。
适用场景与限制
适用于在 Gimbal 中编写需要清晰结构、独立验证、明确交接与自适应规划的多智能体工作流。限制与注意：不要围绕连接丢失添加工作流重试；适配器恢复必须保留会话身份、避免重复工作、保持取消并让未验证的远程清理可重试；无效编辑保留上次成功视图，变更或移除标识符会重置而不猜测；读页面不运行；不要在角色默认值中为模型分配添加特定角色；要求导出新 API 名需仓库所有者明确请求。文档未提供的具体收费、价格、平台或效果信息暂未提供。