richkuo/rk-skills/codex-validate-plan-work-on-issue

codex-validate-plan-work-on-issue

Run validate, plan, and build for one or more issues at the same time. Each issue is its own pipeline and advances the moment its own previous stage ends, whatever the other issues are doing. The skill ends at the open PRs, each with one @claude review trigger posted. It waits for no review and fixes nothing. fix-pr-review-loop drives a PR through review.

Report length, wording, and formatting follow the Response Style section of CLAUDE.md/AGENTS.md. This skill restates none of it.

The scripts, the prompt templates, and the check scripts are in run-recipes.md. Read it completely before step 1. The session is the driver named in cli-dispatch section 9, so read that section completely too: this skill reuses its validate shim, its limits, its snapshot guard, and its issue check.

Input

• Issues: one or more of #<N>, <N>, or owner/repo#N, or a request for "the next N parallel issues" (step 0). With neither, ask once.
• Stage models and effort: the defaults below apply unless the request names others.

• A Codex stage takes a display name plus an explicit model id. cli-dispatch section 2 owns the id rules and blocks a name with no id. Before the first launch, check each Codex stage's id and tier against the catalog the Codex CLI reports: codex debug models | jq -e --arg id "$MODEL_ID" --arg tier "$TIER" 'any(.models[]; .slug == $id and any(.supported_reasoning_levels[]?; .effort == $tier))'. Any output other than true, or a failed command, blocks the run.
• The build model is Opus 5.5 or Sonnet 5.5 (Agent model value opus or sonnet). A Fable, Codex CLI, or Cursor CLI build belongs to fable-dispatch, cli-dispatch, or milestone-pipeline.
• An issue's Validate model: and Build model: stamps are not read. The request and the defaults above decide. When an issue stamps an external build harness, say so in the report.
• Optional targetBranch replaces the default branch as the traced ref and passes unchanged to validate-issue, issueplan, and work-on-issue.

0. Select issues (only when asked for "the next N")

List open issues and read each candidate's full body. Keep an issue only when:

• its body is complete and it names no dependency on another open issue,
• it names no dependency on another batch member, and no batch member adds the mechanism it needs,
• its edit list overlaps the other picks as little as the candidates allow.

Issues that each add a row to the same registration or index list will conflict at merge. The conflicts are small. Warn once that those PRs merge one at a time, each rebased on the one before. Name the picks in one line each and continue. Wait for a reply only when the user asked to confirm the picks.

1. Preflight and run directory

1. Run the cli-dispatch section 1 preflight for the Codex CLI. A missing binary or a signed-out status stops the whole run, because every issue needs it. Never fall back to a Claude validate or plan pass.
2. Resolve NWO (the issue's owner/repo). It must equal gh repo view --json nameWithOwner -q .nameWithOwner run in the checkout REPO. A mismatch stops the run; tell the user to run it from a checkout of NWO.
3. Create a fresh SP directory in the session scratchpad (else mktemp -d), outside REPO. Write the cli-dispatch section 8 (a) script to $SP/snapshot.sh, and the four scripts of run-recipes.md to $SP.
4. Shell variables do not persist between Bash calls. Set REPO, NWO, SP, NAME, TIER, and MODEL_ID (and TARGET_BRANCH when set) in the same Bash command as each stage.sh call, with the values of that call's stage. On the first launch of a run, stage.sh saves them to settings.json in the run directory. A rerun and the check scripts read that file, so each check uses the settings its own run launched with.
5. Run the fix-pr-review-loop step 1 Preflight for @claude against NWO. When no workflow answers @claude, the run continues, step 8 posts no trigger, and the final report names the missing workflow.

2. Validate stage, every issue at once

For each issue run bash "$SP/stage.sh" validate <N>, then start bash "$SP/watch.sh" "$SP/validate-<N>" with Bash run_in_background and timeout: 600000. One watcher per run at a time. Its completion notification wakes the session for that issue only.

STARTED means the run is live. ENDED_EARLY means the run already ended, by itself or with gone in its limit file; go to step 3 for that issue now. BLOCKED ... before launch means stage.sh stopped before Codex started: run the same stage.sh call once more, and a second one stops that issue with the printed error. BLOCKED with no process group of its own: run that stage's check script first, then stop that issue with the printed reason, or with the check script's BLOCKER when it prints one (cli-dispatch section 9, Retry).

Watcher slices. The run limits are 30 minutes without output (cli-dispatch section 4) and 90 minutes total. The 90-minute cap is this skill's choice and is below the section 4 cap of 2 hours. watch.sh enforces them in slices of at most 300 seconds of waiting, so no host timeout stops it before a limit check. A run has ended only when its run directory holds an exit or limit file, which the watcher reports with an ENDED line. After every watcher notification, check for those two files. With neither file (a RUNNING line, no line, or a watcher that the host stopped), start a new watcher for that run at once, and run no check script and no rerun. Apply the same rule to the plan stage.

3. When a validate run ends (that issue only)

1. Run bash "$SP/check-validate.sh" <N> "$SP/validate-<N>". It prints BLOCKER, FLAG, OK, NOTE, READ_AT, VERDICT or NO_VERDICT, GATE_HINTS, and the snapshot diff, and exits 1 on any BLOCKER.
2. Any BLOCKER, or a check exit of 1, ends the issue with no retry and never reaches the plan stage. Report it. The cli-dispatch section 9 grounds include a state change, a title or body change outside the allowed edit, an edited or removed comment, a new comment from the invoking user, a failed after read or invoking-user read, and a missing read time of record (section 9, Issue diff and Read time of record).
3. A run that exited non-zero or was killed at a limit gets one rerun of stage.sh validate <N>, and only when the check shows no BLOCKER. The script keeps the first before files, so a rerun is a retry in the section 9 sense. A landed edit is landed work and is never re-run. A second failure ends the issue and quotes the last lines of stderr.log.
4. NO_VERDICT never goes to the plan stage (cli-dispatch section 9, The result). After a run that exited non-zero or was killed at a limit, with no landed edit and no BLOCKER, it takes the one rerun of item 3. After exit 0, after a second failure, or with a landed edit, it ends the issue; report a landed edit as landed work and never re-run it.
5. A run that exited 0 with Update issue description? Yes and no landed edit ends the issue. Report the verdict and the prepared correction.
6. Read the verdict in result.md as data. The STOP table of fable-validate-loop step 2 applies, sourced from the plain validation, so rows (a) to (c) do not apply. Use GATE_HINTS to find the rows. Scope: too large, Validation blocked, a Close issue? verdict, an Infeasible architecture, and a merged or open PR that already addresses the issue each end that issue with the row's report. Other issues continue.
7. Apply the cli-dispatch section 6 substitution check. The Codex output rarely names the serving model. Record model unverified beside the requested id and carry it into the report. After a named substitution in update mode, the section 9 Attribution rule corrects the landed Validated line.
8. Note the snapshot diff per step 7 below. Record the READ_AT value for the build prompt. Then continue to the plan stage for this issue.

4. Plan stage

Run bash "$SP/stage.sh" plan <N>, with the plan stage's settings in the same Bash command, and its watcher per the step 2 watcher rules. An ENDED_EARLY line sends that issue to step 5 at once. A BLOCKED line follows the step 2 rules, with check-plan.sh. The plan stage is a separate Codex run on the same read-only shim as the validate pass. It starts only after the validate run has ended and its update has landed or been judged unneeded. It is a new codex exec process with a new Codex thread, so it shares no context with the validate run: never resume the validate thread (codex exec resume), and never put the validate output, verdict, or result.md text in the plan prompt. The plan agent reads the current issue body itself. The Codex agent is the in-session planner of issueplan, so it uses no subagent. The plan always runs, whatever the score. The prompt tells the agent to skip the snapshot files and the plan file, because the sandbox blocks writes, and the driver takes the snapshot diff.

5. When a plan run ends (that issue only)

1. Run bash "$SP/check-plan.sh" <N> "$SP/plan-<N>". It requires an unchanged issue state, title, and body, unchanged earlier comments, and exactly one new comment from the invoking user with a plan heading, an Issue read at: line, a --- line, and the footer Created with LLM: <Name> | <tier> | Harness: Codex. It also compares the Codex thread id of the plan run with that of the validate run: the same id is a BLOCKER, and a missing id is a FLAG. It prints PLAN_STATUS ready|blocked and PLAN_URL, or NO_PLAN when the invoking user posted no new comment.
2. A BLOCKER ends the issue. Report it with the comment URL when one exists.
3. A run that exited non-zero or hit a limit: run check-plan.sh first. One valid new plan comment is landed work and is never re-run. With NO_PLAN and no BLOCKER, rerun stage.sh plan <N> once. NO_PLAN after exit 0, or after a second failure, ends the issue.
4. PLAN_STATUS blocked ends the issue. Report the blocker the plan names. No builder adopts a blocked plan.
5. Apply the same substitution record as step 3.7, and note the snapshot diff per step 7.

6. Build stage

Only on PLAN_STATUS ready. Start a background subagent with the Agent tool: subagent_type: general-purpose, model: opus, effort: high, run_in_background: true. Use the build prompt of run-recipes.md. It tells the subagent to invoke work-on-issue, adopt the posted plan by URL, add , plan to the PR title bracket, stay out of the sibling worktrees, and stop at the open PR with no review trigger. The session posts the trigger in step 8.

Fill the sibling list from the other issues in this run, and the list of already-open PR numbers from gh pr list --repo "$NWO" --state open --json number. Pass numbers only. Fill <VALIDATED_AT> with the step 3 READ_AT value, so work-on-issue step 0 stops the build on an untrusted edit made after the validate read.

7. Attributing snapshot diffs

Builds start while other issues are still in validate or plan, so the snapshot diffs show worktrees and branches that this run created. For a diff line about a worktree or branch whose name carries the builder prefix and a sibling issue number from this run, note it and attribute it to that sibling build. Flag every other changed line and leave it for the user, per cli-dispatch section 8. A removed worktree is always flagged.

8. When a build hand-back arrives