workflow-kit

workflow-kit 是面向 Codex、Claude Code 和 OpenCode 等主流宿主 Agent 的 Jira 研发工作流控制平面（Control Plane）。

源码仓库：quliugithub/workflow-kit

它采用 “控制面与执行面分离” 的架构原则，负责创建和持久化每次研发任务的运行状态（Run）、隔离的 Git 工作区（Worktree）、三道 Gate 人工审批关卡以及生命周期事件；而宿主 Agent 则负责对接 Jira、调度角色 Agent、执行代码修改与通知。它不作为新的 Agent 运行时，也不会自行直接发起外部网络服务调用，而是通过本地标准的 CLI 和目录契约，把整个 AI 编码流程规范化为一条可追溯、可审计、高隔离的安全研发链路。

核心模式与机制

Gate 2 与审查模式

planner 给出完整计划后，Gate 2 一次提供三个选择：“严格审查并确认当前计划”“宽松审查并确认当前计划”“调整计划”。该选择同时完成计划授权并决定计划、执行两个阶段的审查方式；正常流程在 Gate 3 前不会再次询问：

workflow-kit set-review-policy --target . --run-id <RUN_ID> --stage plan --mode strict

严格模式先由独立 reviewer 审查计划；通过后自动确认 Gate 2 并开始实施，findings 会返回修改计划并要求对新版本重新决策。宽松模式跳过独立 reviewer，在 OpenSpec 检查和 bypass 成功后自动确认 Gate 2。宽松模式不跳过 OpenSpec、测试、人工 Gate 或 Gate 4 校验；宽松执行必须有非空验证计划，且每项计划验证均已通过。

只回复“严格模式”或“宽松模式”不等于确认计划，宿主必须取得包含“确认当前计划”的明确回复。同一 Session 在 reviewer/bypass 后异常中断时，仅当能追溯该回复且 planner_updates 未变化才可补执行 confirm-plan；跨 Session 或计划已变化时必须重新展示 Gate 2。

审查模式不是项目初始化时选择的全局运行模式，而是每个 Run 在 Gate 2 由用户显式选择一次。确认 Gate 2 时，执行审查策略自动继承同一选择；.workflow-kit/config.json 中的 single-agent / mixed-subagent 等字段表示 Agent 编排方式，与审查模式无关。Gate 2 通知使用 <run_id>:gate2:<planner_updates> 作为版本 Key，同一计划不重复发送，计划更新后可以重新通知。

它不是新的 Agent runtime，也不会自行调用 Jira MCP 或 planner / executor / reviewer。

受控并行子代理

默认由主代理内联完成阶段工作，避免小任务因角色交接增加耗时和 Token。只有至少两个任务可独立执行、存在明确的自动处理时间收益时，宿主才可通过 record-orchestration 记录并行理由、预期节省和子任务边界。

并行写入任务会获得独立 Git workspace 和唯一文件所有权；在集成前必须执行 audit-orchestration-subtask。宿主若提供受控写入工具，应在每次写入前调用 verify-orchestration-write-scope；workflow-kit 不能直接拦截 Agent 原生文件 API，事后 Git 审计仍不可省略。越权文件会阻断该子任务，主 Executor 只能集成已审计的独立成果。共享文件需求应由子任务上报后串行处理。

并行子任务的局部测试只作为局部证据。主 Executor 完成集成并提交后，必须在干净的交付 worktree 使用 run-final-integration-validation 记录最终集成验证；宽松 Gate 3 只接受与当前最终 Commit SHA 匹配的该证据。重跑同一验证命令会保留历史 attempt，并以 supersedes 链表达当前有效结果。

能力概览

• Jira 任务启动时创建 feature/<ISSUE-KEY> 分支和独立 worktree。
• 提供需求、规划、完成三个必经人工 Gate；可选接入发版 Gate 4。
• 为 planner、executor、reviewer 生成宿主适配文件和交接约束。
• 记录 run、事件、OpenSpec 产物和生命周期指标；支持补发、放弃和安全清理 worktree。
• 支持 codex、claude-code、opencode 三种宿主。

前置条件

• Node.js 20 或更高版本。
• 目标项目必须是 Git 仓库，且默认基线分支为 dev。
• 如需从 Jira 启动工作流，宿主 Agent 需显式配置可用的 Jira/通知 MCP。workflow-kit 不预设服务地址、Token 环境变量或组织私有 MCP。

安装

推荐全局安装，随后可在任意项目根目录调用：

npm install -g @freedomallen/workflow-kit

开发本仓库时：

npm install
npm test

初始化项目

在目标项目根目录执行：

workflow-kit init

交互模式会依次选择宿主、角色模型策略和已安装的 MCP。初始化会：

• 写入 .workflow-kit/config.json（运行时配置）和 .workflow-kit/project-config.json（宿主、模型与 MCP 映射）；
• 安装所选宿主需要的 skill、命令模板和角色 Agent 文件；
• 保留已有的远端、验证命令和 worktree 设置。

若只需要在离线环境验证安装和生成宿主文件，可以显式指定宿主和默认模型：

workflow-kit init --target . --host codex --default-models

该模式使用 project-mcp 等 provider-neutral 占位映射，不连接任何远程服务。正式启动 Jira 工作流前，必须通过 configure-mcp 或重新初始化写入真实工具映射。

升级 workflow-kit 后，已初始化项目需要重新执行 workflow-kit init 或对应的 install-host，才能刷新项目内的宿主 skill/command。Codex、OpenCode 等宿主可能在会话开始时缓存 skill；刷新文件后应新开会话再验证。

CLI 最多每 24 小时查询一次公共 npm Registry 的稳定版本。发现新版本时，提醒只写入 stderr，不会改变 JSON stdout 或原命令退出码；离线、超时和缓存写入失败均会静默跳过。设置以下环境变量可完全关闭检查：

WORKFLOW_KIT_DISABLE_UPDATE_CHECK=1

版本缓存只保存检查时间、包名、当前版本和最新版本，不保存项目路径、命令参数、Issue 或 Run 数据。

对于 Codex，入口是 .codex/skills/workflow-kit/SKILL.md，不是 slash command。安装后即可在宿主对话中使用：

workflow-kit OPS-123

显式激活与 Session 续接

workflow-kit 只在用户明确输入 workflow-kit ...（Claude Code 使用对应 slash command）时首次激活。仅出现 Jira、OpenSpec、Gate、reviewer、worktree、分支、活动 Run，或者询问 workflow-kit 原理和失败原因，都不会启动或推进工作流。

首次激活后，同一宿主 Session、同一 Run、直接响应最近 workflow-kit 提示时，可以自然回复“继续”“确认计划”“宽松审查并确认当前计划”，无需每轮重复关键词。新 Session、多个 Run、对话关系不明确、Run 已完成/放弃，或者用户已切换到无关任务时，必须使用 workflow-kit continue <RUN_ID> 或宿主公开的等价命令恢复。Claude Code 只有在同一线程能够追溯显式 command、唯一 Run 和最近提示时才允许自然续接；单次 command、新线程或 Thread Context 缺失时必须显式恢复。

Gate 2 等待计划确认期间，只有用户明确表示“纳入当前需求/计划”的反馈才会交给 Planner。独立 TypeScript 报错等无关问题按普通任务处理，Run 继续停留在 Gate 2，不增加 planner_updates，也不默认写入当前 Run worktree；归属不明确时，宿主只询问它应纳入当前计划还是独立处理。

与 Superpowers 等外部 Skill 共存

员工可以在个人宿主环境中安装 Superpowers 或其他研发 Skill，无需卸载。只有 workflow-kit 已在当前 Session 为对应 Run 显式激活后，它才是该 Run 唯一的工作流编排器；仅存在活动 Run 不会触发 workflow-kit，也不会阻止无关任务使用其他 Skill。激活后 OpenSpec 是唯一实施计划，任务只使用 run.worktree_path，reviewer 只由 strict/relaxed 策略决定，Gate 3～5 和 Git 集成仍由 workflow-kit 管理。

外部 Skill 可以把 TDD、系统化调试、完成前验证、只读分析等能力作为从属技术使用，但不能创建 docs/superpowers/specs、docs/superpowers/plans、第二个任务 worktree、额外 reviewer 或新的人工批准节点，也不能自行执行 merge、PR、push、pull --rebase、rebase、amend、squash、force push、分支完成或 worktree 清理。测试通过、提交或外部审查结果只能作为实施证据，不能替代 workflow-kit Gate。

该规则只约束当前 workflow-kit 任务，不影响员工在其他任务中独立使用 Superpowers。workflow-kit 不会扫描、修改或卸载员工个人目录中的第三方 Skill。旧项目升级后需要重新执行 workflow-kit init 或对应的 workflow-kit install-host，并在宿主缓存 Skill/command 的情况下新开 Session。

MCP 配置

先将 MCP 服务安装到需要使用的宿主客户端；令牌使用环境变量保存，不会写入项目配置：

workflow-kit mcp init --clients codex --server-name project-mcp \
  --url https://mcp.example.com/ --token-env PROJECT_MCP_TOKEN

交互式初始化会把 Token 持久化到当前用户范围，并要求重启已运行的 MCP 客户端：

• Windows：当前用户环境变量；
• macOS：LaunchAgent、~/.zprofile 和 ~/.bash_profile；
• Ubuntu/Linux：~/.config/environment.d、~/.profile 和当前 systemd user manager 环境。

相同 --token-env 再次初始化时会原位更新 workflow-kit 受管内容，不会重复追加旧 Token。若 macOS/Linux 的当前会话刷新失败，命令会输出 token_persistence_warnings；持久化文件仍然有效，重新登录并重启客户端即可。Token 不会写入项目配置或命令 JSON 输出。

mcp init 不提供远程地址或 Token 环境变量默认值；交互和非交互模式都必须由用户明确提供这些信息。

查看已发现的服务：

workflow-kit mcp list --client codex

## 工作流

宿主 Agent 是推荐入口：它读取 Jira 上下文、运行各角色并在每个 Gate 处请求人工确认。底层 CLI 也可用于调试、恢复和集成。

完整的用户使用路径、严格/宽松分支、中断恢复和可选 Gate 4/5，参见 [用户使用流程图](docs/user-workflow-flowchart.md)。

### 宿主 Agent 试用流程

在配置好宿主客户端（如 Codex、Claude Code）并初始化项目后，您可以在宿主 Agent 的对话会话中按照以下标准流程开始试用：

1. **激活工作流与需求确认 (Gate 1)**：
   * **启动**：在对话中输入指令激活工作流（如在 Codex 中输入 `workflow-kit OPS-101`，或在 Claude Code 中运行对应命令）。
   * **后台行为**：宿主 Agent 会自动通过 MCP 拉取 Jira 工单的详细描述与验收标准，并在本地创建 `feature/OPS-101` 隔离分支和专用的 Git worktree。
   * **人工确认 (Gate 1)**：Agent 在会话中输出对需求的梳理、默认假设与需要澄清的问题。确认无误后回复 “确认” 或 “按默认假设继续” 即可进入规划。

2. **方案规划与审查 (Gate 2)**：
   * **规划**：Agent 自动调度 **Planner 子代理** 在隔离的工作区内生成 OpenSpec 设计方案（包含 Proposal, Design, Tasks 结构化文件）。
   * **审查**：随后自动调度 **Reviewer 子代理** 对方案的完整度与合规性进行第一轮把关。
   * **人工确认 (Gate 2)**：在审查通过后，宿主 Agent 在对话中向用户提问。用户选择审查策略（**严格模式** / **宽松模式**）并回复“确认当前计划”，即可进入代码实施。

3. **代码实施与自动化验证**：
   * **执行**：**Executor 子代理** 在隔离的工作区内编写代码，并自动根据修改的文件范围，运行指定的构建与测试脚本以生成动态的验证证据（测试日志和 Commit 校验指纹）。

4. **交付审查与完成确认 (Gate 3)**：
   * **审计**：Executor 编写并自测完毕后，**Reviewer 子代理** 对其最终 Commit 进行差分审查，并对主目录执行“越权脏写”审计以防代码越界。
   * **人工确认 (Gate 3)**：通过后，宿主 Agent 整理最终测试日志、Commit SHA 和剩余风险输出（宽松模式下明确提示未进行独立 Reviewer），在对话中请求确认。用户回复“确认完成”，Agent 自动执行分支合并与 Jira 工单关闭，并安全回收临时创建的工作区资源。

```text
Jira issue
  → Gate 1：同时确认需求上下文和开发基线
  → planner
  → Gate 2：选择审查模式并确认规划
  → strict：计划 reviewer 通过 / relaxed：计划审查 bypass
  → executor
  → strict：实施 reviewer 通过 / relaxed：实施审查 bypass
  → Gate 3：确认完成
  → （可选）Gate 4：确认发版

宿主在创建 Run 前一次展示需求上下文、建议开发基线和“需求分析代码来源”。用户可确认并使用建议分支、确认并改用其他本地分支，或调整需求；完整确认后才创建 feature/<ISSUE-KEY> 与 .workflow-kit/worktrees/<ISSUE-KEY>，并自动进入规划，不再出现第二次 Gate 1 确认。Detached HEAD 下不提供空的建议分支选项，必须显式指定本地分支。

Gate 3 后的小范围返工

Gate 3 审查完成、但尚未确认交付时，如人工验收提出的是明确、局部、可回滚的低风险调整，可在用户明确同意后使用轻量返工。它不重复规划和 reviewer，但会清空返工前的验证证据，要求重新执行最小相关验证，并重新回到 Gate 3 等待确认：

workflow-kit begin-lightweight-rework --target . --run-id <RUN_ID> --reason "调整人工验收反馈"
# 在该 Run 的 worktree 中修改并执行相关验证
workflow-kit run-validation --target . --run-id <RUN_ID> --kind backend
workflow-kit complete-lightweight-rework --target . --run-id <RUN_ID> --summary "已完成局部调整并重新验证"

权限、安全或敏感数据、数据迁移/回填/删除、公开契约、跨服务或前后端协同、不可逆操作、验收不明确等情况不得使用轻量返工，应走标准流程。若验证不可用，只有用户明确承担风险时才可追加 --acknowledge-unverified。

可选 Gate 5：知识沉淀

任务完成后，宿主只在发现稳定且有证据支持的可复用结论时才提供可选知识沉淀。用户可跳过、沉淀或修改后沉淀；该选择不重新打开任务。确认沉淀后，先在对应 worktree 初始化并校验知识文件，再记录审计：

workflow-kit init-knowledge --target <WORKTREE>
workflow-kit validate-knowledge --target <WORKTREE> --entry .agent/lessons/example.md
workflow-kit record-knowledge-capture --target . --run-id <RUN_ID> \
  --decision captured --entry .agent/lessons/example.md --knowledge-root <WORKTREE>

Gate 4 已完成时必须使用新的独立知识维护分支/worktree 与 change，不能直接修改目标分支或主工作区。未发现候选时仅记录 not_applicable，不会产生文档或额外通知。

若启用了发版集成，Gate 3 后的 run 会进入发版阶段：

workflow-kit prepare-release --target . --run-id <RUN_ID> --target-branch main
workflow-kit confirm-release --target . --run-id <RUN_ID> --target-branch main
workflow-kit finalize-release --target . --run-id <RUN_ID>

Gate 4 会把已验收的 feature 内容 squash 为目标分支上的唯一普通提交，固定使用 Issue:<ISSUE_KEY>;<JIRA_TITLE>，例如 Issue:GSSFY-7632;【门诊辅诊站站】治疗单执行界面确认执行的治疗医嘱没有同步医嘱执行状态。feature 分支仍可保留初始实现和多轮轻量返工提交，但这些过程提交不会成为目标提交的祖先；从同步后的目标 SHA 到 Gate 4 结果只增加一个单父提交。冲突恢复后执行 finalize-release 时会校验唯一父 SHA、提交数量和这条消息。详细操作见 Gate 4 发版集成。

executor 在进入执行审查、宽松执行 bypass 或 Gate 3 摘要前，必须先核对 git status 和 diff，只暂存计划范围内的文件，使用普通 git commit 将包括新增文件和 OpenSpec 产物在内的全部实现提交到 Run feature 分支，并确认 Issue worktree 完全清洁。轻量返工使用新的追加提交保留真实历史，不自动 amend、rebase、squash 或 force push。Gate 4 的 prepare-release 和 confirm-release 都会拒绝 staged、unstaged 及 untracked 遗留内容；确认阶段发现变更时，提交后必须重新执行 prepare-release。配置的 release validation 会在 Gate 4 最终 candidate commit 上重新执行并绑定该 SHA，失败时不会追加第二个目标提交。

验证策略

验证只在当前 Run 的 worktree 和当前仓库内执行，不会隐式构建分离的前端或后端仓库。可在 .workflow-kit/config.json 中声明 validation.topology（backend-only、frontend-only 或 monorepo）、目录根和命令；未声明命令时 workflow-kit 不会猜测或执行前端构建。

executor 应先查看并执行最小必要验证：

workflow-kit plan-validation --target . --run-id <RUN_ID>
# 仅当计划返回 backend 的非空配置命令时执行
workflow-kit run-validation --target . --run-id <RUN_ID> --kind backend

# 没有静态配置、但执行者确定了真实检查命令时使用
workflow-kit run-executed-validation --target . --run-id <RUN_ID> \
  --kind backend --command "npm test"

可用 kind 为 backend、frontend-fast、frontend-build 和 release。run-validation 只用于 plan-validation 实际返回了非空配置命令的 kind；若该 kind 没有配置命令，workflow-kit 会记录计划外的“不可用”观察，但不会生成 command: null 计划项。此时如有经过执行者确认的真实测试、构建或源码检查命令，应使用 run-executed-validation 记录并执行，不能为了凑出非空计划而误跑 run-validation。

reviewer 默认审查验证证据，只在证据不足或存在具体构建风险时补跑目标验证。完整前端 build 超时会记录为“未验证”，不会被报告为通过或失败；Gate 3 必须明确展示通过、失败、未验证、不可用项和计划外观察。若有效计划存在未验证项，完成 Gate 3 需要显式传入 --acknowledge-unverified。旧版本自动生成的“未配置命令”空命令哨兵会保留审计记录，但不再作为永久无法通过的有效计划项；排除后若有效计划为空，宽松执行 bypass 仍会被拒绝。release_integration.validation_commands 中配置的命令必须由 run-validation --kind release 通过后才可准备 Gate 4。

approve <RUN_ID> context|plan|complete 是对应 Gate 确认命令的简写。规划 Gate 会校验 OpenSpec 产物是否已准备好，不能仅凭摘要绕过。

运维与恢复

# worktree 被误删或 run 元数据缺失时修复
workflow-kit repair-worktree --target . --run-id <RUN_ID>

# 补发本地生命周期事件（每次默认最多 5 条）
workflow-kit report-lifecycle-events --target . --pending --limit 5

# 取消 run；不会删除分支或 worktree
workflow-kit abandon-run --target . --run-id <RUN_ID> --reason "需求取消" --yes

# 先预览，再删除已完成且干净的 worktree
workflow-kit prune --target . --dry-run
workflow-kit prune --target . --yes

# 按保留策略预览和执行 worktree 清理 + Run 归档
workflow-kit maintain-runs --target . --dry-run
workflow-kit maintain-runs --target . --yes

# 只读查看归档，或显式恢复为 completed Run
workflow-kit list-archived-runs --target .
workflow-kit inspect-archived-run --target . --run-id <RUN_ID>
workflow-kit restore-archived-run --target . --run-id <RUN_ID> --yes

运行数据保存在 .workflow-kit/runs/<run-id>/，包括 run.json、events.jsonl、Jira 上下文、角色交接文件、评审报告和完成记录。

默认保留策略为：completed worktree 满 7 天后进入安全清理候选，worktree 已清理且 completed Run 满 90 天后进入 .workflow-kit/archive/<YEAR>/<RUN_ID>/。维护命令默认不自动删除归档、Git 分支、tag、远端引用或 .agent/。归档前会检查 live lock、dirty/untracked worktree、发布状态以及待上报生命周期/统计事件；跨磁盘卷 rename 会安全失败，不会降级为 copy-then-delete。团队可在人工 dry-run 稳定后，通过 CI 或系统计划任务显式调用 maintain-runs --yes。

.agent/ 是后续任务默认读取的长期项目知识库；Run 归档是只读审计证据。Gate 1 不会默认扫描大量归档。如果需要从历史 Run 提炼知识，应先只读检查归档证据，再通过独立知识维护 change 更新 .agent/。

Jira Issue Key 会先去除首尾空格并转为大写，例如 omnis-1011 会规范化为 OMNIS-1011。项目维度 OMNIS 由该 Key 自动提取并写入 Run；新生命周期事件和 Gate 4 指标使用带 project_key 的 v2 报文，升级前已落盘的 v1 Outbox 仍按原报文重试。

隐私与远程统计

全新项目默认关闭统计上报，statistics.endpoint、statistics.lifecycle_endpoint 和 statistics.token_env 均为空。workflow-kit 不会因为安装、查看帮助、查看版本或离线初始化而向维护者服务发送项目数据。

需要上报到自有服务时，必须在 .workflow-kit/config.json 中显式启用并提供 endpoint 与 Token 环境变量。升级会保留已有项目明确保存的启用状态、地址和 Token 环境变量，不会把它们替换为维护者默认值。

公共 npm 发布维护

公共候选版本必须依次通过：

npm test
npm pack --dry-run
npm run pack:smoke

pack:smoke 会生成真实 tarball，在全新临时目录安装，并验证唯一的 workflow-kit 命令、版本、帮助和离线初始化。普通测试、构建和 prepublishOnly 不得隐式修改 npm dist-tag 或 Git Tag。

每次发布使用唯一 SemVer，并使用 v<version> 格式的 Git Tag。预发布版本先使用 beta dist-tag，验证安装命令为 npm install -g @freedomallen/workflow-kit@beta；完成全新环境验证并取得独立批准后，才能发布正式版本或提升 latest。已发布版本不可覆盖；问题版本应通过新的补丁版本、dist-tag 回退或 deprecate 处理。

canonical npm 包名为 @freedomallen/workflow-kit，安装后提供的 CLI 命令仍是 workflow-kit。首个公共候选版本为 0.1.0-beta.0，发布时必须显式使用 npm publish --tag beta，不得直接写入 latest。首次发布前不存在可回退的稳定版本；若 beta 有问题，应 deprecate 问题版本并发布新的 0.1.0-beta.N。稳定版发布后再记录最后一个已验证版本，并使用 npm dist-tag add @freedomallen/workflow-kit@<VERSION> latest 进行显式回退。

文档

• 工作流契约
• 命令与数据契约
• 运行模式
• 能力边界
• 当前实现状态

License

MIT