Spec Approval Bridge

规范批准桥

spec-approval-bridge 是仪表板审查结果和代理执行流程之间的桥梁。

为什么

此项目从规范工作流程中的一个摩擦点开始： 在一个人完成批准或在仪表板中留下更改请求后， 仍然需要有人返回代理提示符并手动传递该结果。

该存储库的目标是消除切换间隙，并将审查结果转化为代理可读的执行信号。 批准本身应作为执行信号，而不是等待第二个手动“开始工作”指令的提示。

最有价值球员

此存储库现在包括一个本地MCP服务器，用于监视规范工作流批准文件 在...之下 .spec-workflow/approvals 并让同一代理会话等待审查结果。

当前的MVP公开了两个工具：

• get_spec_approval_result
• wait_for_spec_approval

为了兼容性，旧别名仍然可用：

• get_review_result
• wait_for_review

wait_for_spec_approval 轮询审批JSON文件，直到状态结束 pending 或者超时已过，因此代理不需要单独的守护进程来“唤醒” 最初的会议稍后举行。桥梁响应还包括桥梁推断的工作流程阶段 提示如下 requirements -> design -> tasks，再加上继任者批准id 阶段批准已存在。这些阶段提示是来自该桥的辅助元数据， 不是来自的原始状态值 spec-workflow.

运作原理

1. 代理通过以下方式创建批准请求 spec-workflow
2. 代理人打电话来 wait_for_spec_approval 与返回 approvalId
3. 此网桥MCP服务器轮询 .spec-workflow/approvals//.json
4. 当文件变为 approved, needs-revision，或 rejected，工具返回
5. 如果当前审批因工作流已经创建了下一阶段审批而消失，则网桥将返回下一阶段和后续审批id，而不是立即失败
6. 同一代理会话在上下文中继续查看结果

代理使用合同

规范性消费者合同记录在 文档/消费者执行合同.md。以下规则为简短版本。

如果批准是通过创建的 spec-workflow，消费者应该继续使用 spec-approval-bridge.wait_for_spec_approval 直到响应变成终端或用户 明确要求停止等待。

实用规则：

1. 呼叫 wait_for_spec_approval
2. 如果返回 status 是 pending，继续等待
3. 如果回复说 shouldRetry: true 和 nextAction: "wait"，呼叫 wait_for_spec_approval 再次之后 retryAfterMs
4. 不要治疗 pending + timedOut 作为失败
5. 如果返回 status 是 approved，立即继续工作流
6. 如果返回 status 是 needs-revision，停止前进进度，并使用返回的反馈修改当前工件
7. 如果返回 status 是 rejected 或 error，停止工作流并清楚地报告阻塞状态
8. workflowStage 和 nextWorkflowStage 在您已经解释了实际的审批状态后，是否会推断出路由的桥接提示
9. 仅在以下情况下停止：

- terminal: true，或 - 用户明确地告诉代理不要继续等待

1. 当响应获得批准时，将该批准视为继续的信号，不要等待单独的“开始工作”消息
2. 当批准阶段为 tasks，将批准的任务文档视为执行队列，并按顺序处理任务，除非用户明确暂停或重定向运行
3. 当回复获得批准时，首选 nextWorkflowStage 和 successorApprovalId 消费者中的超自组织阶段推理

如果您的代理运行时没有自动遵循MCP重试提示，请添加编排或 重复的提示逻辑 wait_for_spec_approval 当 shouldRetry 是 true.

推荐的消费者设置：

• 将以下规则块放入代理或编排器系统提示符中
• 对待合同 docs/consumer-execution-contract.md 按要求行为，而非咨询指导
• 让消费者关注 nextAction, nextWorkflowStage，以及 successorApprovalId 机械地
• 不要要求用户手动传递网桥已经返回的批准结果
• 在获得批准后，不要要求用户再次手动指示开始工作 nextAction: "proceed"
• 当批准 tasks 舞台回归 nextAction: "proceed"，按顺序执行已批准的任务，而不是在第一个任务后停止

建议消费者提示：

When you create an approval request through spec-workflow, you must wait for the review result through spec-approval-bridge.wait_for_spec_approval.

Interpret the actual spec-workflow approval status mechanically first:

- If status="pending", keep waiting.
- If status="approved", continue the workflow immediately.
- If status="needs-revision", revise the current artifact using the returned feedback.
- If status="rejected" or status="error", stop the workflow and report the blocking state clearly.

Then apply the bridge control hints mechanically:

- If shouldRetry=true and nextAction="wait", call wait_for_spec_approval again after retryAfterMs.
- Do not treat pending + timedOut as failure.
- If nextAction="proceed", immediately continue to the next step that matches the current workflow.
- Treat dashboard approval itself as the execution signal. Do not wait for a separate "start work" or "go ahead" message after approval.
- If workflowStage="tasks" and nextAction="proceed", execute the approved tasks sequentially in their intended order until the task list is complete, unless the user explicitly pauses or redirects you.
- Treat workflowStage and nextWorkflowStage as bridge-inferred routing hints, not as native spec-workflow status values.
- When nextAction="proceed", use nextWorkflowStage and successorApprovalId instead of re-inferring the stage chain yourself.

Keep waiting until:
- terminal=true, or
- the user explicitly tells you to stop waiting.

Do not ask the user to manually relay approval results that are already available through spec-approval-bridge.

建议的编排器循环：

let review = await bridge.wait_for_spec_approval({ approvalId, timeoutMs: 120000 });

while (review.shouldRetry && review.nextAction === "wait") {
  await sleep(review.retryAfterMs ?? 2000);
  review = await bridge.wait_for_spec_approval({ approvalId, timeoutMs: 120000 });
}

switch (review.nextAction) {
  case "proceed":
    if (review.successorApprovalId) {
      setCurrentApprovalId(review.successorApprovalId);
    }
    // review.status comes from spec-workflow. nextWorkflowStage is a bridge hint.
    // Approval already means "continue"; no extra user kickoff message is needed.
    // If this was tasks-stage approval, resume by executing the approved tasks in order.
    resumeCurrentWorkflow();
    break;
  case "revise":
    reviseCurrentArtifact(review);
    break;
  case "stop":
    stopWorkflow(review);
    break;
}

本地开发

安装依赖项：

npm install

运行测试：

npm test

构建MCP服务器：

npm run build

直接在stdio上运行它：

node dist/server.js /home/tigeryoo/workspace/agent-feedback-bridge

Codex MCP配置

此存储库的本地 .codex/config.toml 已设置，因此Codex可以使用这两个服务器：

• spec-workflow 用于创建审批和状态文件
• spec-approval-bridge 等待同一会话审核

如果你想在Codex中手动注册此服务器，请添加一个配置块，如下所示：

[mcp_servers.spec-approval-bridge]
command = "node"
args = ["/this/repo/absolutePath/dist/server.js", "/your/workspace/absolutePath"]

路径注释：

• 第一个参数必须是此存储库构建的绝对路径 dist/server.js
• 第二个参数必须是包含以下内容的工作区根的绝对路径 .spec-workflow

Codex内部流程示例：

1. 请求批准 spec-workflow
2. 捕获返回的 approvalId
3. 呼叫 spec-approval-bridge.wait_for_spec_approval
4. 根据返回的状态和评论继续