codex-issue-coordinator

Codex issue coordinator

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.

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.

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.