Back to Details

codex-issue-coordinator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex issue coordinator

Codex Issue协调器

Use one Codex thread to coordinate a GitHub issue batch. Give each active issue its own worker thread, worktree, branch, and pull request. Workers hold implementation context. GitHub holds dependency state.
Explicitly naming 
/codex-issue-coordinator
, or explicitly telling the coordinator that agents may merge, authorizes in-scope workers to merge their own pull requests after every merge gate below passes. An implicit skill match does not grant merge authority: run in no-merge mode unless the user's words grant it. Neither mode authorizes deployment, release publication, destructive operations, branch-protection bypasses, or changes outside the supplied batch.
使用单个Codex线程协调GitHub issue批次。为每个活跃issue分配独立的worker thread、worktree、branch和pull request。Worker持有实现上下文，GitHub维护依赖状态。
显式命名
/codex-issue-coordinator
，或明确告知协调器agents可执行合并操作，将授权范围内的workers在满足以下所有合并准入条件后合并各自的pull requests。隐式的技能匹配不会授予合并权限：除非用户明确说明，否则默认运行在禁止合并模式。 无论哪种模式，均不授权部署、发布版本、破坏性操作、绕过分支保护规则，或对指定批次外的内容进行修改。

Preconditions

前置条件

  1. Read the repository instructions, parent issue, native sub-issues, declared dependencies, project board, issue state, and linked open or merged pull requests. A merged pull request is only evidence of completion when it closes or explicitly references the issue and its final change and proof satisfy the issue scope. Reconcile that issue and project state instead of dispatching it again. Do not infer completion from a link alone.
  2. Use Codex thread tools. If visible Codex threads and Codex-managed worktrees are unavailable, stop. Do not replace workers with hidden subagents.
  3. Make every issue a complete task before dispatch. If a missing product or technical decision could change behavior, data, security, compatibility, operations, cost, or proof, mark that issue as needing human input.
  4. Build a dependency graph. Treat GitHub as the durable source of issue, pull request, review, and merge state. Stop for human correction if the graph contains a dependency cycle. Do not create a second local tracker.
  5. Default to two active workers. Use another limit only when the user asks or the repository gives a stricter limit.
  1. 阅读仓库说明、父级issue、原生子issue、已声明的依赖项、项目看板、issue状态，以及关联的未合并或已合并pull requests。只有当已合并的pull request关闭或明确引用该issue，且其最终变更和验证结果符合issue范围时，才能视为该issue已完成。需先核对issue和项目状态，再进行任务分发，不可仅通过链接推断任务已完成。
  2. 使用Codex线程工具。若无法查看Codex线程和Codex管理的worktree，则停止操作。不得用隐藏子agents替代workers。
  3. 在分发前确保每个issue都是完整任务。若缺失的产品或技术决策可能影响行为、数据、安全性、兼容性、运维、成本或验证结果，则标记该issue需要人工输入。
  4. 构建依赖关系图。将GitHub作为issue、pull request、评审和合并状态的可靠来源。若依赖图存在循环依赖，则停止操作并请求人工修正。不得创建第二个本地跟踪器。
  5. 默认启用两个活跃workers。仅当用户要求或仓库有更严格限制时，才使用其他限制数量。

Coordinator workflow

协调器工作流

  1. Keep the calling thread as coordinator. Name it 
    #<parent> Coordinator
    when the batch has a parent issue. Use 
    set_thread_pinned
    to pin it at the start of every new or resumed coordinator run, before inspecting or dispatching workers.
  2. Reuse an existing active worker for the same issue. Inspect an unclear or interrupted worker before creating another. If the issue already has an open pull request, create or resume its worker on that pull request's exact head branch and include the branch and pull request URL in its prompt. Otherwise create a Codex project thread in a managed worktree from the latest remote default branch and include the required new branch name.
  3. Name every worker 
    #<issue-number> <short title>
    .
  4. Start only issues whose prerequisites are merged. Independent issues may run together up to the worker limit. Do not stack dependent branches in this workflow.
  5. Give the worker the full issue URL, dependency state, repository location, resolved branch and pull request state, and the worker contract below. Tell it to use 
    /task-to-pr
    and pass the coordinator's explicit merge or no-merge mode. Merge mode grants authority only for that worker's issue.
  6. Monitor workers with compact 
    wait_threads
    snapshots. Use 
    read_thread
    only when a worker needs help. Send decisions or corrected scope back with 
    send_message_to_thread
    ; do not edit the worker's files from the coordinator.
  7. Continue independent work when one issue is blocked. After three failed attempts at the same check or review finding, pause that issue, record the evidence on GitHub, and request human input.
  8. In merge mode, when a worker reports completion, verify GitHub says the pull request is merged, the issue contains final proof, and the issue is closed. Close it explicitly if the merged pull request did not close it. Then mark the issue Done when the project supports it and archive the worker thread. In no-merge mode, stop that worker after its pull request passes all agent-completable gates, leave the issue in Review, record any pending human approval or merge as its blocker, and leave the thread available.
  9. Refresh the dependency graph after every merge and dispatch newly ready issues from the updated remote default branch. In no-merge mode, when a dependent issue is waiting only for a passing prerequisite pull request to be merged, record that human-merge dependency as its blocker. Do not wait indefinitely or dispatch the dependent from an unmerged branch.
  10. In merge mode, finish only when every in-scope issue is merged, closed, and Done when the project supports that state, or every unfinished issue has a recorded blocker that needs human action. In no-merge mode, finish when every in-scope issue has a ready pull request with all agent-completable gates passing or a recorded human blocker.
  1. 将调用线程作为协调器。当批次存在父级issue时，将其命名为
    #<parent> Coordinator
    。在每次启动或恢复协调器运行时，先调用
    set_thread_pinned
    固定该线程，再检查或分发workers。
  2. 为同一issue复用现有活跃worker。在创建新worker前，先检查状态不明确或中断的worker。若该issue已有未合并的pull request，则基于该pull request的精确head branch创建或恢复其worker，并在提示中包含该branch和pull request URL。否则，从最新远程默认分支在Codex管理的worktree中创建Codex项目线程，并指定所需的新branch名称。
  3. 为每个worker命名为
    #<issue-number> <short title>
    。
  4. 仅启动前置条件已合并的issue。独立issue可同时运行，直至达到worker数量限制。此工作流中不得堆叠依赖分支。
  5. 向worker提供完整的issue URL、依赖状态、仓库位置、已解析的branch和pull request状态，以及以下Worker协议。告知其使用
    /task-to-pr
    ，并传递协调器明确指定的合并或禁止合并模式。合并模式仅授予该worker处理对应issue的权限。
  6. 通过简洁的
    wait_threads
    快照监控workers。仅当worker需要帮助时使用
    read_thread
    。通过
    send_message_to_thread
    发送决策或修正后的范围，不得从协调器编辑worker的文件。
  7. 当某个issue被阻塞时，继续处理独立任务。若同一检查或评审问题连续三次尝试失败，则暂停该issue，在GitHub上记录证据，并请求人工输入。
  8. 在合并模式下，当worker报告完成时，需验证GitHub显示pull request已合并、issue包含最终验证结果且已关闭。若已合并的pull request未关闭issue，则显式关闭它。若项目支持，标记该issue为Done，然后归档worker线程。在禁止合并模式下，当worker的pull request通过所有agents可完成的准入条件后，停止该worker，将issue标记为Review状态，记录待人工批准或合并的阻塞项，并保留线程可用。
  9. 每次合并后刷新依赖关系图，并从更新后的远程默认分支分发新就绪的issue。在禁止合并模式下，当依赖issue仅等待前置pull request通过并合并时，记录该人工合并依赖为阻塞项。不得无限等待，也不得从未合并分支分发依赖issue。
  10. 在合并模式下，仅当所有范围内的issue均已合并、关闭（若项目支持则标记为Done），或所有未完成的issue均已记录需要人工操作的阻塞项时，才结束工作。在禁止合并模式下，当所有范围内的issue均已生成就绪的pull request且通过所有agents可完成的准入条件，或已记录人工阻塞项时，结束工作。

Worker contract

Worker协议

Each worker owns one issue and follows this order:
  1. Read the issue, repository instructions, relevant design, code, tests, and dependency pull requests. Move the issue to In Progress when possible.
  2. Use the Codex-managed worktree. If the issue has an open pull request, reuse its exact head branch and pull request. Otherwise create the repository's required issue-linked branch from the updated default branch.
  3. Implement only the issue. Add or update tests for every acceptance criterion, affected failure path, regression risk, and named edge case.
  4. Use 
    /test
    . Browser-facing work requires a real browser check of the affected success and failure flows, responsive widths, keyboard behavior, console errors, and failed requests when relevant.
  5. Commit and push the tested change. Open a draft pull request if one is not already open. Include a short summary and current proof.
  6. Mark the pull request ready for review and move the issue to Review. Do this before requesting independent review or waiting for GitHub review.
  7. Use 
    /review
    with a fresh subagent that did not implement the change. Wait for required CI and automated review. In merge mode, also wait for every repository-required approval. In no-merge mode, do not wait indefinitely for human feedback; record a pending required approval as a human blocker.
  8. Address every valid in-scope finding. Reply to review threads with the fix or evidence for making no change. Resolve a thread only when it is fully addressed.
  9. After any code change, repeat affected 
    /test
    proof and fresh 
    /review
    , commit and push, update the pull request evidence, and wait for CI and automated review again. Iterate until the mode's gates pass; do not manufacture extra rounds or wait indefinitely for optional human feedback.
  10. In merge mode, merge the pull request using the repository's preferred method after every merge gate passes. Never use an admin bypass. Wait until GitHub reports the pull request as merged, record final proof, and verify the issue is closed. Close it explicitly if the pull request did not. In no-merge mode, leave the passing pull request open for a human to merge. Report the final state to the coordinator.
每个worker负责单个issue，并遵循以下步骤：
  1. 阅读issue、仓库说明、相关设计、代码、测试和依赖pull requests。若可能，将issue状态改为In Progress。
  2. 使用Codex管理的worktree。若该issue已有未合并的pull request，则复用其精确的head branch和pull request。否则，从更新后的默认分支创建仓库要求的与issue关联的branch。
  3. 仅实现该issue的内容。为每个验收标准、受影响的失败路径、回归风险和指定边缘情况添加或更新测试。
  4. 使用
    /test
    。面向浏览器的工作需通过真实浏览器检查受影响的成功和失败流程、响应式宽度、键盘行为、控制台错误及相关失败请求。
  5. 提交并推送经过测试的变更。若尚未打开草稿pull request，则创建一个。包含简短摘要和当前验证结果。
  6. 将pull request标记为ready for review，并将issue状态改为Review。在请求独立评审或等待GitHub评审前完成此操作。
  7. 使用
    /review
    调用未参与实现的全新subagent。等待必要的CI和自动化评审完成。在合并模式下，还需等待仓库要求的所有批准。在禁止合并模式下，不得无限等待人工反馈；将待处理的必要批准记录为人工阻塞项。
  8. 处理所有有效的范围内评审意见。在评审线程中回复修复方案或无需修改的依据。仅当问题完全解决后才关闭评审线程。
  9. 每次代码变更后，重复受影响的
    /test
    验证结果和全新的
    /review
    ，提交并推送，更新pull request的验证结果，再次等待CI和自动化评审。循环直至满足当前模式的准入条件；不得额外增加循环次数，也不得无限等待非必要的人工反馈。
  10. 在合并模式下，当所有合并准入条件满足后，使用仓库首选方法合并pull request。不得使用管理员绕过权限。等待GitHub报告pull request已合并，记录最终验证结果，并验证issue已关闭。若pull request未关闭issue，则显式关闭它。在禁止合并模式下，将已通过准入条件的pull request保持打开状态，等待人工合并。向协调器报告最终状态。

Merge gates

合并准入条件

A worker may merge only when all of these are true:
  • The pull request is ready for review, not draft.
  • The complete issue scope and acceptance criteria have recorded proof.
  • Focused and required wider tests pass on the final commit.
  • A fresh 
    /review
    verdict is 
    Approve
    on the final code.
  • Every required GitHub check passes.
  • Every actionable automated or human review thread is resolved.
  • Every repository-required approval is present.
  • The pull request is mergeable and current with its required base.
  • No security, data-loss, compatibility, operational, or product decision is unresolved.
  • The pull request changes only the worker's issue.
If a gate cannot pass, do not merge. Record the blocker and continue other independent work.
仅当满足以下所有条件时，worker才可执行合并：
  • pull request已标记为ready for review，而非草稿状态。
  • issue的完整范围和验收标准已记录验证结果。
  • 最终提交的聚焦测试和必要的全面测试均通过。
  • 针对最终代码的全新
    /review
    verdict为
    Approve
    。
  • 所有必要的GitHub检查均通过。
  • 所有可处理的自动化或人工评审线程均已解决。
  • 所有仓库要求的批准均已获取。
  • pull request可合并且与所需基准分支保持同步。
  • 无未解决的安全、数据丢失、兼容性、运维或产品决策问题。
  • pull request仅变更该worker负责的issue内容。
若任一准入条件无法满足，则不得合并。记录阻塞项并继续处理其他独立任务。

Worker prompt

Worker提示词

Use this shape and replace every placeholder:
text
Use /task-to-pr to complete <issue URL> in this Codex-managed worktree.

Your thread owns only this issue, branch, worktree, and pull request.
Branch state: <reuse PR head branch and PR URL, or create new branch name>.
Delivery mode: <merge after all gates pass, or leave the passing PR open>.
Read the issue and repository instructions as the source of truth.
Implement the smallest complete change and prove acceptance criteria, edge
cases, failure paths, and regressions.

After local proof passes, commit, push, open or update the pull request, and
mark it ready for review. Only then run fresh independent /review and wait for
CI and GitHub review. Address valid findings and repeat test and review after
every code change.

<If merge mode: The user explicitly authorized this /codex-issue-coordinator run to
merge this issue's pull request after every merge gate passes. Wait until
GitHub reports the merge, update and close the issue, and return the result.>
<If no-merge mode: Leave the passing pull request open for human merge and
return its URL and proof.>
Do not deploy, publish a release, bypass repository rules, or change unrelated
work.
使用以下格式并替换所有占位符：
text
Use /task-to-pr to complete <issue URL> in this Codex-managed worktree.

Your thread owns only this issue, branch, worktree, and pull request.
Branch state: <reuse PR head branch and PR URL, or create new branch name>.
Delivery mode: <merge after all gates pass, or leave the passing PR open>.
Read the issue and repository instructions as the source of truth.
Implement the smallest complete change and prove acceptance criteria, edge
cases, failure paths, and regressions.

After local proof passes, commit, push, open or update the pull request, and
mark it ready for review. Only then run fresh independent /review and wait for
CI and GitHub review. Address valid findings and repeat test and review after
every code change.

<If merge mode: The user explicitly authorized this /codex-issue-coordinator run to
merge this issue's pull request after every merge gate passes. Wait until
GitHub reports the merge, update and close the issue, and return the result.>
<If no-merge mode: Leave the passing pull request open for human merge and
return its URL and proof.>
Do not deploy, publish a release, bypass repository rules, or change unrelated
work.

Return

返回结果

For each issue, report its worker, pull request, gate state, and blocker. State which issues are complete and which need human action. Do not repeat worker logs that do not change the result.
针对每个issue，报告其worker、pull request、准入条件状态和阻塞项。说明哪些issue已完成，哪些需要人工操作。不得重复不影响结果的worker日志。

Boundaries

边界规则

  • Use visible Codex threads for workers. Fresh subagents are only for the independent 
    /review
    inside a worker.
  • Never dispatch two workers for one issue or let two workers share a worktree.
  • Never replace or duplicate an existing pull request for the issue. Resume it.
  • Reconcile already-merged pull requests and closed issues before dispatch, but only after their change and proof satisfy the issue scope.
  • Never start dependent work from an unmerged pull request in this workflow.
  • Never merge an unrelated pull request merely because it blocks the batch.
  • Never infer deployment or release authority from merge authority.
  • Do not archive a worker until its merge and final issue state are verified.
  • 使用可见的Codex线程作为workers。全新subagents仅用于worker内部的独立
    /review
    操作。
  • 不得为单个issue分配两个workers，也不得让两个workers共享同一个worktree。
  • 不得为同一issue替换或重复创建已有的pull request，需复用现有pull request。
  • 在分发前核对已合并的pull requests和已关闭的issue，但仅在其变更和验证结果符合issue范围时才进行。
  • 此工作流中不得从未合并的pull request启动依赖任务。
  • 不得仅因某个无关pull request阻塞批次就合并它。
  • 不得从合并权限推断部署或发布权限。
  • 不得归档worker，直至其合并操作和最终issue状态得到验证。