Run Workflow

The driver. Runs a work item from its current stage to completion, stopping only at the three gates. Read docs/workflow.md for the stages and gate rules, and the agent-runtime skill for how roles operate.

The loop

scripts/workflow-next.sh          # what runs next, and with which model
# ... run that stage; the role appends its own work-protocol entry ...
scripts/workflow-next.sh          # repeat

You do not call wp-append.sh --role. The role that ran the stage appends its own entry before returning, and that append is what advances the stage. A second append from the driver would advance past whichever role is now current, silently skipping it. wp-append.sh refuses a --role that does not match the current stage, so a duplicate call fails loudly rather than corrupting the run — but the rule is that completion has exactly one owner.

The driver does use wp-append.sh for --gate and --rework, which are its own decisions rather than a role's.

workflow-next.sh derives everything from the branch name and state.json. Note that it is not purely a query: it advances past a skipped UAT stage and records that UAT is required, so calling it is part of driving the run rather than inspecting it. Use scripts/workflow-gate.sh status when you only want to look. It costs almost nothing and needs no memory of previous turns, so a session that compacted or died resumes by calling it again.

Exit codes: 0 a stage is ready, 2 blocked at a gate.

Running a stage

Spawn the role as a subagent with the model workflow-next.sh reports — that isolation is why this workflow is affordable. Give it:

Act as the <Role> role. Read .agents/roles/<stage>.md and the agent-runtime skill, then do your stage for the work item in <work-item-dir>.

Do not paste the role file into the prompt; the subagent reads it. Do not add your own instructions about how to do the role's job — if they were needed, they belong in the role file.

One exception: the code-reviewer stage runs in Codex, not as a subagent:

scripts/codex-review.sh <work-item-dir>

Its exit code decides what happens next, and it advances the stage itself:

Exit 2 is not a rework signal. Treating it as one sends the Developer back for a review that never happened.

Starting a new work item

The entry role creates the branch, the folder, work-protocol.md and state.json:

Reserve NNN with the next-issue-number skill. Do not ask which role to start with — determine it from the request and delegate; the entry role asks the clarifying questions, because that is its job and not yours.

Gates

When workflow-next.sh exits 2, stop and put the question to the Maintainer, along with any open_questions accumulated since the last gate. Then record the answer:

scripts/wp-append.sh --gate spec --decision approved

arch is only pending when the Architect wrote contested into it. uat is skipped automatically when the diff does not touch user-visible output — the driver reports the skip and moves on.

After release

For features and bug fixes, the Release Manager completes the merge and verifies the published release before the Retrospective runs. The release deletes the source branch, so resume the final stage by its retained work-item directory from a worktree based on the merged branch, on a separate documentation follow-up branch. The driver selects the Retrospective; the role appends its own entry after completing the report:

scripts/workflow-next.sh --work-item docs/features/NNN-<slug>
# Retrospective role, after writing its report:
scripts/wp-append.sh --work-item docs/features/NNN-<slug> \
  --role "Retrospective" --summary "..."

Use docs/issues/NNN-<slug> for a bug fix. Keep the retrospective report in a separate post-release documentation follow-up, not in the PR for the work being reviewed. Recommendations may be presented to the Maintainer; start Workflow Engineer only when the Maintainer asks for workflow improvements.

Rework

The code reviewer routes its own rework. codex-review.sh calls --rework itself before exiting 1, so do not call it again — a second call counts the same rejection twice and can block the run after two failed reviews instead of three.

For a UAT failure, use the gate; for a build failure, call rework yourself:

scripts/wp-append.sh --gate uat --decision rejected      # UAT failed
scripts/wp-append.sh --rework release-manager --reason "PR validation failed"

Both route back to the Developer and increment attempts, which escalates the model one tier. Escalating forever is not a strategy: after three attempts at the same stage, stop and involve the Maintainer. Repeated failure at one stage is usually a specification problem wearing an implementation costume.

Before release

scripts/workflow-gate.sh all

Non-zero means a required role never logged its work, and the release does not proceed.

What not to do

• Do not do a role's work yourself. If the Developer's stage is next, spawn the Developer — writing the code yourself defeats the isolation the workflow is built on.
• Do not skip a stage because it seems unnecessary. The work-protocol gate will refuse the release, and you will have lost the intervening work.
• Do not block on a question away from a gate. Record it with an assumption (wp-append.sh --question ... --assumed ...) and continue.