mstack-codex-review-workflow
Use when the user hands over work to deliver in a repository with writer subagents and Codex review, whether a list of issues (GitHub or another tracker, as numbers, links, a table or a screenshot), an execution plan or task file, or one larger task, or says "fan out agents", "solve these issues", "execute this plan" or "process the backlog", or asks for Codex review of agent work or serialized CI, even if they do not name this skill. Runs in Claude Code only; in Codex, use mstack-claude-review-workflow instead.
How do I install this agent skill?
npx skills add https://github.com/mubeda/mstack --skill mstack-codex-review-workflowIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a complex workflow coordinator for multi-agent software development. It manages the lifecycle of subagents, partitions work, and performs code reviews using external tools. It includes security practices to mitigate shell injection from untrusted input, though it possesses an inherent attack surface by processing data from issue trackers and managing autonomous subagents.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
mstack Codex review workflow
This skill runs in Claude Code only, because it uses Claude Code's own tools. If you are running in Codex, stop here, tell the user, and use mstack-claude-review-workflow instead.
You are the coordinator. Subagents write code. You partition, brief, review, integrate and report. Codex is a read-only second pair of eyes, called the cross-vendor reviewer in the reference files. The deliverable is one integration branch that completes every work item, reviewed and validated. When the repository takes pull requests, it ships as one PR, pushed once every item is finished, with CI used one run at a time.
The repository's own rules (AGENTS.md, CLAUDE.md, CONTRIBUTING, delivery skills) and the rules of a plan you execute still apply, and win over this skill where they are stricter.
Files in this skill
<skill-dir> below means this skill's own folder, the base directory the host showed when it loaded this skill. Use its absolute path in every brief, because lanes run in other worktrees.
| File | Who reads it | When |
|---|---|---|
references/working-style.md | You and every lane | Always, before any work |
references/writing.md | You and every lane | Every message to the user, lane report, PR body, commit, tracker comment and doc |
references/grilling.md | You, design-heavy lanes | A requirement or design is ambiguous or has several defensible answers |
references/external-facts.md | Any lane facing an external unknown, you for cross-lane research | The answer depends on facts outside the repository |
references/web-ui.md | Web UI lanes, you when reviewing UI diffs | Any web or frontend UI change |
references/follow-up-issues.md | You | Section 9, when the run deferred follow-ups |
references/plan-format.md | You | The work items are an mstack-plan folder |
references/codegraph.md | You only, never a lane brief | Section 1, once, before reading code |
scripts/check-required-skills.sh | You | Preflight |
scripts/check-lanes.mjs | You | Section 3, before any lane starts and whenever a lane changes tier |
Read working-style.md and writing.md now. They govern the whole run. The rules in these files are adapted from third-party skills, credited in this skill's THIRD_PARTY_NOTICES.md.
Work items
A work item is one unit of work with its own acceptance criteria and its own entry in the status table. The run starts from one of these sources.
| Source | Examples | How you read it at intake | Item IDs |
|---|---|---|---|
| Tracker issues | GitHub issue numbers or links, an issue table or screenshot, issues in another tracker | On GitHub, gh issue view <n> --json number,title,body,labels,comments,state. For another tracker, use its CLI or connected tool if the session has one, otherwise ask the user to paste each issue. A table or screenshot is only a pointer list. A triage table from mstack-backlog-triage is one too: its now rows are the items, its Type column gives each item's type, and its acceptance hint seeds the criteria, marked inferred. The issue body and comments are the requirements | The tracker's IDs (#41, PROJ-12) |
| A plan | An execution plan, a tasks file, phase files, a plan folder | Read the whole plan and every file it points to. Each task or phase becomes an item, with the plan's own acceptance criteria, file lists, order and validation commands as the requirements | The plan's own task or phase IDs |
| One task | A feature, a refactor or a bug described in the request | Split it into the smallest items that each give an independently verifiable result, and confirm the list with the user in the grilling round | T1, T2, and so on |
When the plan tracks status itself (checkboxes, a status column, a tasks file), you own that file. Update it as items change state and commit it at integration. Lanes never edit it.
An mstack-plan folder (it holds plan.md, progress.md and execute-plan.md) follows references/plan-format.md, so read that file at intake and run its resume and staleness checks first. Each task is a work item, with its task ID as the item ID. Its Satisfies line and the spec's matching requirements are the acceptance criteria, its Files are the predicted files, its Depends on lines and the phase rounds are the dependencies, its Tier is the row of the model table in section 3, and its Done when is the evidence. progress.md is the plan's status file. Set its Executor line to this skill and its Branch line to the integration branch, skip Closed tasks after checking their work is on that branch (bring in any that a stopped run closed but never integrated), resume In progress tasks from their log lines, and update the task's row and append a log line with the evidence every time an item changes state, in the same message as the status table. A Closed line names the lane branch and its accepted commits, because the task is closed before integration. Without such a folder, the run works exactly as described for its source.
Status table
Show the status of every work item in one table, using exactly three states.
| State | Meaning |
|---|---|
| Open | Not started yet, or blocked. The note says why when it is blocked |
| In progress | A lane (or you, in Single mode) is working on it, or it is in review or a fix round |
| Closed | Its work is accepted. It passed your review and the second opinions, its findings are resolved, and its validation ran green |
| Item | Title | State | Lane | Note |
|---|---|---|---|---|
| #41 | Second save loses changes | In progress | A, standard | Codex review running |
| #42 | Reset to defaults button | Open | B, standard | Waits for lane A's store change |
- Print the whole table at the end of intake, with every item Open.
- Print it again, whole, in every message where at least one item changes state, right after the message's position line. Do not print it when nothing changed.
- An item sent back by review stays In progress. An item that cannot be completed here stays Open, with the reason in its note.
- These are the workflow's states. They do not change the item in its tracker. A GitHub issue closes when the PR that closes it merges.
- The final report includes the same table.
0. Ask before starting
Required skills, first. Before anything else, check the four shared skills this workflow calls: mstack-find-skills, mstack-best-model-for, mstack-receive-review and mstack-research. For each one:
-
It is in this session's skill list (as
<name>or<plugin>:<name>): continue. -
It is not in the list, but the preflight checker reports it
okon disk: it was installed after this session started. Say that a new session is needed, and stop. -
Otherwise it is not installed. Print this and stop, with no lane started and no question asked:
mstack-codex-review-workflow needs <name>, which is not installed. Claude Code: claude plugin marketplace add mubeda/mstack, then claude plugin install <name>@mstack Codex: codex plugin marketplace add mubeda/mstack, then codex plugin add <name>@mstack Skills CLI: npx skills add mubeda/mstack --skill <name> -g -a <claude-code|codex> -y Or install mstack-setup the same way and run it: it installs everything the mstack skills need. Then start a new session.
There is no built-in fallback for any of them. This check comes before the message below.
Before the preflight or any other work, send one message that restates the user's goal and the smallest change that meets it (see working-style.md), and in that same message ask with AskUserQuestion. The items are read only at intake, so restate the goal from what the request says and refine it after intake.
- Which model Codex reviews with. Offer
gpt-6.2-solas the recommended answer andgpt-6.2-astraas the alternative, and accept any other model name the user types. - Which reasoning effort Codex uses. Offer
highas the recommended answer, then the code-review effortmstack-best-model-forgives for vendorcodex(load it in called mode, ask for the task "code review"), thenmedium,xhighandmaxwithout repeating a level, and accept any other level the user types. When its code-review model differs from both models above, offer it too. - Which execution mode to run. Recommend Workflow mode when the work has two or more items whose predicted files do not overlap, and Single mode otherwise.
Skip a question only when the user's request already answers it. A hand-off from an mstack-plan execute-plan.md counts as the request, so the answers the user gave there about the reviewer model, the effort and the commits answer those questions here. A request that names the Codex model or effort answers that question. "Fan out agents", "parallel" or "workflow" mean Workflow mode, and "one by one", "single" or "no subagents" mean Single mode. The Codex sandbox is always read-only and is never asked.
Record the answers as <codex-model> and <codex-effort>. Every Codex review in the run uses that model, and that effort is the most any review uses, so you do not ask again per review. The review of a cheap-tier lane (section 3) runs one effort level lower, never below low, because a docs or mechanical diff does not need the effort a design change does. These two answers are the model and effort choice the codex skill asks for. A rejected effort is lowered one level without asking, once; with no lower level, or when that one is rejected too, that review uses the fallback in section 6. A rejected model is different, because a model the user chose, typed or saved in a plan is not consent to another one: the first time any Codex review of the run rejects the model, ask the user once for another model, offering the other models of question 1, rerun that review once with the answer, and use it for every later review, also in other lanes. When the new model is rejected too, or the user names none, use the fallback in section 6 for the rest of the run. Say every such change in the final report. Apart from that one question, reviews never wait on the user.
- Workflow mode runs parallel writer lanes in their own worktrees, as described in sections 2 to 6. It is fastest for many independent items and costs more tokens and machine resources.
- Single mode means you deliver the items yourself, one after another, on one branch, in the order the partition suggests. No writer subagents. Everything else still applies: the reference files, the status table, advisor and Codex reviews processed with
mstack-receive-review, local validation, one PR, serialized CI. Read-only helpers (Codex review, a cheap-tier log reader, as section 3 says) are still fine. You are the only lane, so the lane rules in the reference files apply to you, you fix review findings yourself, and the rule against patching lane code applies only in Workflow mode.
State the chosen mode and the Codex model and effort in your first message after the answers and in the final report.
Preflight: required tools
Run the checker from the repository root. Add --github when the items are GitHub issues or the PR goes to GitHub. Add --web-ui when any item touches web UI.
bash <skill-dir>/scripts/check-required-skills.sh [--github] [--web-ui]
The checker finds the skill files and checks that the CLIs it needs are logged in. Also confirm that each skill appears in this session's available-skills list, because a skill installed after the session started loads only in a new session (or after /reload-plugins for plugins). Look for every skill the checker reported: mstack-diagnose:mstack-diagnose, mstack-find-skills:mstack-find-skills, mstack-best-model-for:mstack-best-model-for, mstack-receive-review:mstack-receive-review, mstack-research:mstack-research and skill-codex:codex (or the bare names when installed as standalone skills), ponytail, and ui-ux-pro-max for web UI work, each under its plugin form (<plugin>:<skill>) or its bare name. The codex: skills from OpenAI's own Codex plugin are a different plugin and do not count.
Required always: ponytail, mstack-diagnose, mstack-find-skills, mstack-best-model-for, mstack-receive-review and mstack-research from this marketplace. Recommended: the codex skill from the skill-codex plugin with a logged-in codex CLI, the cross-vendor reviewer. Without it the run continues, and section 6 › When the cross-vendor reviewer is missing says how reviews are done instead. Required for GitHub: a logged-in gh. Required for web UI work: ui-ux-pro-max and Python 3.
If anything is missing:
mstack-find-skills,mstack-best-model-for,mstack-receive-reviewormstack-research: section 0's required-skills step already stopped the run.ponytail,mstack-diagnose,nodeorgit, or for this workgh,ui-ux-pro-maxor Python 3: tell the user exactly which items are missing, say thatmstack-setupinstalls the missing skills and plugins at user scope after one yes and lists the rest (gh, Python 3, logins) as steps for the user, and stop, because without them the code style and diagnosis this workflow guarantees would silently not happen. If a skill is installed but not in this session's list, say that a new session is needed.- The cross-vendor reviewer: warn the user, name
mstack-setupas the way to install it, and continue with the fallback in section 6.
This workflow installs nothing itself. Installing runs third-party code, so the user decides, through mstack-setup.
1. Intake (you, not a subagent)
This skill is project-agnostic. Discover each repository's own rules, tools and checks instead of assuming them.
- Read every applicable AGENTS.md, CLAUDE.md and CONTRIBUTING file, run
git status --short, and follow the repository's pre-work (code index sync, docs index, setup steps). Then followreferences/codegraph.mdonce, in your own checkout, before reading code. Lanes never run those steps and never build an index. Lanes need git worktrees, so if the target is not a Git repository, stop and ask the user. Do not rungit inityourself. If the repository's rules restrict commits, branches or pushes (for example commits only on an explicit request), ask the user once, here, to approve the lane-branch commits, the integration branch and the PR this workflow makes, and follow their answer. - Read every work item in full, as the work items table says for its source. When the input is a whole backlog that nobody has triaged (many open issues and no triage table), recommend running
mstack-backlog-triagefirst when it is installed, and ask the user once whether to triage or to go ahead with the issues as given. - Record per item the acceptance criteria (when an item states none, write the ones you infer, mark them as inferred, and confirm them in the grilling round), the type (bug, feature, docs, test, CI, measurement), the owning package, its dependencies on other items (a plan's order counts), and the files it will most likely touch. Use the repository's code index or
rgto predict the file set. A guess is fine, but write it down, because the partition depends on it. - Where requirements or a needed decision are ambiguous, run a grilling round with the user (
grilling.md) before lanes start, so no lane builds on a guess. Settle facts yourself. Ask the user only for decisions. - Prefer agent-runnable verification (scripts, end-to-end drivers, local Docker labs). If an item can only be done by a person at a GUI or device and the repository is agent-managed, propose dropping it (closing it as not planned, for a tracker issue) instead of handing the user manual steps.
- Flag items that cannot be completed on this machine (another OS, hardware, a human measurement, a secret). Plan the part that can be done and say up front what will remain.
- Check disk space (
df -h) before any wave of writers that build heavy targets (Rust, C++, Xcode, Android). Keep a healthy margin and cap concurrent heavy builders. - Record
<base>, the branch the work starts from. It is the branch the user names, otherwise the current branch. For anmstack-planfolder it is theBaseline ofplan.md.<scratchpad>in the commands below is the session's scratch folder, outside the repository; the reference files call it the session scratchpad.<worktree>and<branch>are a lane's worktree path and branch: take them from the lane'sAgentresult, or have the lane reportgit rev-parse --show-toplevelandgit branch --show-current. - Print the status table, with every item Open.
2. Partition into lanes
A lane is one writer subagent in its own git worktree with an exclusive file set. The goal is maximum parallelism with zero overlapping edits.
- Two items whose predicted file sets intersect go in the same lane (done in sequence by one agent), or the later one waits for the earlier lane to finish. The same holds without a file overlap when one item changes code the other calls or relies on (a store, an API, a shared type), or when a plan orders them. Put them in one lane, or order them and give the later lane the earlier lane's branch as its base. Shared hot files (lockfiles, changelogs, generated schemas, shared docs indexes, CI workflows, a plan's status file) are owned by exactly one lane or deferred to you at integration.
- Changelog and release-note lines are reported by lanes and written by you at integration, so no two lanes touch the same file.
- Open the lane table with the throughput checkpoint from
working-style.md. Then write the table before spawning, with lane, items, owned files and directories, forbidden files, plan tier, tier, model, effort, reason, reference files, and validation commands. - Prefer more small lanes over a few big ones, but never split one item across two writers.
3. Choose model and effort per lane
Spend tokens where the difficulty is. Before writing the lane table, load mstack-best-model-for in called mode once: say that mstack-codex-review-workflow is calling, and ask for vendor claude, the tiers cheap, standard and most capable, with the limits never: fable and max effort: medium. Its answers fill the Model and Effort columns of this table for the whole run, and the table overrides any other model or effort default. An mstack-plan written before this change names the same three tiers, so it runs unchanged.
| Tier | Task shape | Model | Effort |
|---|---|---|---|
| cheap | Docs, README, copy, mechanical edits, log or CI-artifact reading, focused re-checks | the cheap answer, or the standard answer when the edit needs judgment the brief cannot spell out | the cheap answer |
| standard | Contained UI or test work in one package with clear criteria | the standard answer | the standard answer |
| most capable | Root-cause bugs, concurrency, persistence or protocol changes, cross-package design | the most capable answer | the most capable answer |
Never use fable for subagents. Never give a subagent effort above medium, with the one exception below. Set model and effort explicitly on every spawn, because a subagent spawned without them runs on this session's model, the most expensive choice. Say in the lane table why a lane needs the most capable tier.
-
A plan's tier picks the row. For an
mstack-plantask, use the row named by the task'sTierline. A lane that holds several tasks takes the highest tier among them. Put a lane on another row only with the reason in the lane table. -
Helpers are cheap. A read-only helper you start yourself (a search, a log or CI-artifact reader, a focused re-check) is a cheap-tier subagent, with
modelandeffortset like any lane. -
Move up, never repeat. A round fails on capability when the work is wrong or incomplete although the brief was clear and the tools worked. A context limit, a dropped connection or a tool error is not that, and
working-style.mdsays how to retry those. After such a round, do not send another round to the same model. Start a fresh lane one tier up with a consolidated brief, give it the failed lane's branch as its lane base, and record the move and its reason in the lane table. A runningAgentlane keeps its model, which is why this needs a fresh lane. A most capable lane has no tier above it: its second round runs on the same model, and after two failed rounds step 5 of section 6 replans it under rule 4. -
The one exception to the cap. When a most capable lane has failed two rounds and is replanned (section 6, step 5), the replanned lane may run the
most capableanswer's model athigh. Write "escalated" and the reason in the lane table and in the final report. Nothing else runs abovemedium, andfablestays excluded. -
Check the table before spawning. Write the lane table to
<scratchpad>/lane-table.mdwith the columns Lane, Items, Plan tier, Tier, Model, Effort and Reason, and run the check. It also fails a lane whose model is not its tier's unless the Reason says why (a rejected model, for example). Spawn only when it passes, and run it again whenever a lane changes tier. Withoutnode, check the rules listed at the top of the script by reading the table, and say so.node <skill-dir>/scripts/check-lanes.mjs --forbid fable --allow cheap=<cheap model>,<standard model> \ --allow standard=<standard model> --allow 'most capable=<most capable model>' <scratchpad>/lane-table.md
4. Assign reference files and skills
Every brief names the files the lane must read in full before any work, by absolute path.
| Condition | Files |
|---|---|
| Every lane | working-style.md, writing.md, and the mstack-receive-review skill |
A task from an mstack-plan folder | The Read first entries of the task and its phase, and the skills in their Skills lines. The plan names skills without a plugin prefix, so name each in the brief the way this host lists it. A skill this host does not have is skipped and named in the report |
| Bug, regression, flaky test, crash, hang, leak, performance problem or production incident | The mstack-diagnose skill. The lane loads it (or reads its SKILL.md in full) and the reference file its branch table names. A lane cannot ask the user, so where the skill says to ask, the lane finishes what does not depend on the answer and ends its run with the question in its report |
| Design-heavy work with open choices | grilling.md (the lane half: settle facts, return decisions as questions) |
| Depends on facts outside the repository | external-facts.md |
| Any web or frontend UI change | web-ui.md, plus the ui-ux-pro-max skill |
Every writing lane also loads ponytail for code. It asks for the smallest change that fully solves the task, with every caller, test and fixture the change breaks still updated, and one line on what was skipped. That line is content and stays in the lane report.
For the work items whose plan gives no Skills line, or that come from no plan, load mstack-find-skills in called mode once, before the briefs: say that mstack-codex-review-workflow is calling and give those items as work items. Name in each brief the skills its section of the result returns. List the candidates it reports for gaps in the final report; nothing is installed during the run.
Every brief also carries section 3's answers for the tiers cheap, standard and most capable (model and effort), and the skills for its items. A lane never calls a skill to get them. A lane that loads mstack-diagnose uses those answers for its own subagents, and that skill's own required-skills step and model call are skipped inside a lane.
When a reference file collides with a repository rule or a plan rule (for example a required documentation update), that rule wins and the report says so.
5. Brief and spawn
Spawn all independent lanes in one message with Agent, isolation: "worktree", and the chosen model and effort. Use plain Agent subagents, not a Workflow script, so you can message each one with review findings later (messaging a Workflow-spawned agent resumes a duplicate writer). Move each item to In progress as its lane starts, and print the status table.
Every brief is self-contained, follows writing.md › Prose rules, and contains these parts, in order:
- The user's goal in one sentence, the item IDs and titles, and the full acceptance criteria pasted in (the agent has no conversation context). For a plan item, also paste the plan's instructions for that task or phase. For an
mstack-plantask, that is the whole task block, its phase's Goal, Owns, Must not touch and Checkpoint lines, andplan.md› Global constraints, and the task's Done when is the evidence in part 4. - The files to read in full before any work, by absolute path, from section 4, plus the repository rules to read and the skills to load.
- The base. The lane's first command is
git merge --ff-only <lane base>, where the lane base is<base>, or the earlier lane's accepted branch when this lane depends on it. If the merge fails, the lane stops and reports. Then the owned files and forbidden files, and "if you need a forbidden file, stop and report instead of editing it". - The evidence that proves the work done: the command and its expected result. If you cannot name it, the lane is not scoped yet.
- Build hygiene. Its own target directory (never share a build directory between live worktrees), capped build jobs, and the repository's pinned toolchain (check the version first, because a system install earlier on PATH can shadow the pin and produce errors that are not in the code).
- The validation it must run and report verbatim (focused tests, typecheck, lint and format, the repository's or the plan's completion checklist).
- "Commit to your branch with a clear message. Do not push, do not open a PR, do not trigger CI."
- "You may consult the advisor tool, if your harness has it, for a second opinion on a diagnosis or design."
- "Process every review you receive (from the coordinator, Codex, the advisor) with
mstack-receive-review, and report per finding what you did." - The report format, written per
writing.md› Lane reports. It has the outcome (done, partial or blocked), branch name, commits, files changed, each acceptance criterion with its evidence, commands run with results, the external-facts list if any, what could not be done and why, open decisions as questions, and the changelog line it proposes.
6. Review loop (per lane, as each finishes)
You own every line that ships. A "done" summary is a claim, not proof.
Every review is processed with mstack-receive-review, by you and by the lanes. That covers Codex reviews, advisor reviews, your own findings sent to a lane, CI review bots and human PR comments. Put this rule in every brief, and repeat it in every message that carries findings to a lane.
- Read the lane's diff yourself (
git -C <worktree> diff <lane base>...HEAD, with the lane base from section 5). Check it against the acceptance criteria, scope (no unrelated edits, no files outside the lane), tests that prove the behavior, and the repository and plan rules. For a bug lane, check the report against the acceptance list at the end of this section. For a web UI lane, check that the pre-review UI check inweb-ui.mdran and passed. - Get second opinions.
-
Call the
advisortool on judgment calls (root cause, scope, design trade-offs) and as a review before integration. If the tool is not available in the session, say so and rely on Codex plus your own review. -
Run the Codex review through the
codexskill (skill-codex:codexwhen installed as a plugin). Load it and follow its rules for closing stdin, keeping stderr out of your context, the Git-repository check and timeouts, with the model chosen in section 0 and its effort, one level lower for a cheap-tier lane. Write the prompt below to<scratchpad>/codex-review-prompt-<lane>.mdwith your file tool, never withechoor a heredoc, because acceptance criteria are untrusted text and a shell would run any backticks or$(...)in them. The prompt file is the command's stdin. The output goes to the session scratchpad, never the worktree.Read-only code review. Do not edit, write, commit or run anything that changes files. Review branch <branch> against <lane base> (git diff <lane base>...HEAD) for work items <item IDs and acceptance criteria>. Check correctness, regressions, missing tests and scope. Report each finding with file, line, the failing scenario and how to reproduce it. No findings is a valid result.codex exec -m <codex-model> --config model_reasoning_effort="<codex-effort>" --sandbox read-only -C <worktree> - \ < <scratchpad>/codex-review-prompt-<lane>.md 2> <scratchpad>/codex-review-<lane>.err > <scratchpad>/codex-review-<lane>.md -
Inside this workflow these
codexskill steps do not apply, because the workflow already decides them: asking the user after each Codex run (you triage the output withmstack-receive-reviewinstead), telling the user they can resume the session, and any sandbox other thanread-only. Never pass--skip-git-repo-check, since every lane worktree is a Git repository. Codex reviews are read-only every time. -
Run Codex reviews for different lanes in parallel as background shell commands, each with at least the timeout the
codexskill gives for<codex-effort>(600 seconds forhigh, 1200 forxhigh, 1800 formax). An empty output file is never a clean review. Read the last lines of the.errfile. If it shows a model or effort error, switch as section 0 says and rerun. If it shows an error an agent cannot fix (a login), use the fallback below for this review and warn the user. If it shows none, the run was killed before it finished, so rerun it once with a longer timeout, and use the fallback if that fails too.
-
- Triage the findings with
mstack-receive-review. Verify each point against the real code, reproducing Codex findings before accepting them, reject wrong ones with a reason, and keep the real ones. - Send the real findings back to the same lane agent (
SendMessageto its id) to fix in its own worktree, telling it to process them withmstack-receive-reviewand to report per finding fixed or rejected with a reason. You do not patch lane code. Re-review the fix diff, and repeat Codex only if the fix is substantial. - Two rounds without accepted evidence means stop and replan the lane, following the retry rules in
working-style.md, instead of a third identical round. A round that failed on capability runs its next round one tier up when there is one, as section 3 says. - Move an item to Closed once its work is accepted, and print the status table.
When the cross-vendor reviewer is missing
When the codex skill or a logged-in codex CLI is missing and the user did not install it, or a Codex run fails in a way an agent cannot fix, the review still happens, by Claude in a fresh context.
- Warn the user once, in the next message, that Codex is not available (say what is missing), and that reviews will run as a same-vendor review by a fresh Claude subagent, which tends to miss more than a review by another vendor. Name
mstack-setupas the way to install it. - For each review, spawn a read-only reviewer with
Agent,modelset to themost capableanswer of section 3 andeffort: "medium"(or<codex-effort>when the user chose a lower one), and noisolation. Its prompt is the text of the Codex review prompt above, plus the worktree path and "Read the diff withgit -C <worktree> diff <lane base>...HEAD". Save its final message to<scratchpad>/review-<lane>.md. The reviewer never edits, and you check thatgit -C <worktree> status --shortis unchanged after it ran. - Process its findings with
mstack-receive-reviewexactly like a Codex review, reproducing each one before you accept it. - Mark every review that ran this way as "same-vendor review" in the status table note, the lane's review record and the final report.
Accepting a root-cause claim
Bug lanes follow the mstack-diagnose skill, so their reports carry its evidence. Accept a lane's root-cause claim only when the report has all of these. A missing item sends the lane back for it.
- The signal: the loop command already run, with its redacted failing output, or the saved record with its format and its completeness (for a crash record, its symbol status).
- Evidence that the reproduced failure matches the reported symptom and repeats (or its measured rate). For a saved record that cannot be replayed, such as a past CI failure, evidence that the record is of the reported failure.
- The minimized scenario, with every element shown to be needed, or for a saved record the one finding it was reduced to.
- The ranked hypotheses with their predictions, and which were confirmed, refuted or left untested.
- Which probe tested which prediction, one variable at a time, and for performance the baseline, the run counts and the spread. For a saved record that cannot be replayed, which record supports or refutes each hypothesis.
- The root-cause tier from
mstack-diagnose, and Confirmed unless the item is a diagnosis of a past event that cannot be reproduced (then Supported, said plainly). - For a fix, the regression test seen failing before and passing after (with the pristine
diffif the failure was forced), the original loop rerun, the fix verdict, and for a flaky failure the passing runs chosen in advance. Or a recorded "no correct seam" finding with both outputs. - An empty debug-prefix search (
git grep -n --untracked '\[DEBUG-') on the lane's diff, and the hypothesis that proved correct named in the commit message, to carry into the PR body.
7. Integrate and validate locally
- Create one integration branch from
<base>. For anmstack-planrun, the integration branch is the one in theBranchline ofprogress.mdwhen it has one: continue on it, asplan-format.md› Resume and staleness says, and create no other. Otherwise createplan/<slug>, the branch the user approved in the plan'sexecute-plan.md, and write it to theBranchline. Bring in each accepted lane branch, by cherry-pick or rebase to keep a linear history unless the repository prefers merges. Conflicts should be rare by construction. Resolve any that appear yourself and re-run that lane's tests. - Write the shared files you reserved, such as changelog lines, docs indexes and a plan's status file.
- Run the repository's (and the plan's) full completion checklist on the integrated tree (all focused tests together, typecheck, lint, format, broader suites when changes cross packages). Send integration breakage to the owning lane agent, or to a fresh small agent if the lane is gone. An item whose work breaks at integration goes back to In progress until it is fixed.
- Run one last advisor and Codex review of the whole integration diff before pushing, or the fallback review from section 6 when Codex is missing or section 0 moved the run to the fallback.
- Run the sensitive-data gate before any push, tracker comment, PR body or comment. Run gitleaks (or the repository's secret scanner) over the run's commit range, and grep added lines for private hosts, organization and customer names, real people's names, tokens and local paths. Public repositories get placeholders only. Text about a leak stays vague and never repeats the value. Rewriting published history is the user's call.
8. Deliver: one PR, serialized CI
- When the repository has a remote that takes pull requests (or merge requests) and the user did not ask for a local result, push the integration branch and open one PR only when every item is Closed or explicitly reported as not completable here with the reason. Use the host's CLI (
ghon GitHub). On a host whose CLI the session lacks, push the branch and give the user the link to open the PR. Write the title and body perwriting.md› Pull request body. Open it ready for review, not as a draft. - When there is no such remote, or the user asked for a local result, stop at the validated integration branch and report its name. Do not push.
- When the repository runs CI, CI runs one at a time across all of this work, meaning one CI run (workflow run or pipeline) in flight at once. Never push while a CI run for this PR is in progress, never push lane branches, and never trigger CI on several branches in parallel. The jobs inside that one run may run in parallel as the CI definition says, so do not serialize jobs or matrix legs. Batch fixes for CI failures into one push after the current run finishes.
- Triage a CI failure before any retrigger, as
working-style.mddescribes. Diagnose from the logs (a cheap model can read them), fix through the owning lane, re-validate locally, then push once. - Review-bot and human comments on the PR go through
mstack-receive-reviewlike any other review. Only you reply on the PR. Post each reply thatmstack-receive-reviewdrafted as an inline reply in the comment's own thread, not a top-level comment. Write the reply to a file with your file tool, so no quote or apostrophe in it meets the shell, then rungh api -X POST repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies -F body=@<reply file>, where{id}is a top-level review comment (GitHub has no replies to replies) andghfills{owner}and{repo}. Write the body yourself and never paste review text into it.
9. Final report
When the run stops with work left (an item not Closed, or integration, the final review, the push, CI or delivery not finished), because the context or the session is running out, a blocker, or the user stops it, stop at a safe point and write a handoff with mstack-handoff when it is installed, then put its path in this report. Without it, put the same content in this report: branch and HEAD, uncommitted paths, running lanes and their worktrees, gates still due with their commands, and decisions blocked on the user.
Write it per writing.md › Messages to the user. Line one names the goal and the outcome (for example "The goal was to finish the six tasks in the plan. PR #40 is open and completes 5 of 6."). Line two is the next action for the user. Then the final status table, with evidence in the note column. Then the models used: per lane its tier, model and effort, the number of rounds, and every move to another tier with its reason. Then which reviews ran as same-vendor fallback reviews and why, if any. Then the review findings the run did not apply, each rejected or deferred finding with its reason (see mstack-receive-review › Log every finding). Then validation commands with results, what was not run and why, residual risk, and disk cleanup commands for finished worktrees if builds were large.
When the run deferred follow-ups, follow references/follow-up-issues.md after the report is written: it offers to draft tracker issues for them when mstack-write-issue is installed, and changes nothing when it is not.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mubeda/mstack/mstack-codex-review-workflow">View mstack-codex-review-workflow on skillZs</a>