--- name: run-workflow description: Drive a work item through the workflow in auto mode - resolve the next stage, run it, advance state, and stop only at gates. --- # Run Workflow The driver. Runs a work item from its current stage to completion, stopping only at the three gates. Read [docs/workflow.md](../../../docs/workflow.md) for the stages and gate rules, and the `agent-runtime` skill for how roles operate. ## The loop ```bash 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. Read `.agents/roles/.md` and the `agent-runtime` > skill, then do your stage for the work item in ``. 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: ```bash scripts/codex-review.sh ``` Its exit code decides what happens next, and it advances the stage itself: | Exit | Meaning | What you do | |------|---------|-------------| | 0 | APPROVED | Continue the loop | | 1 | REWORK | Continue the loop — it has already routed back to the Developer | | 2 | codex unavailable or failed twice | Spawn the `Code Reviewer` subagent instead, and pass `--problems "reviewer: claude-fallback"` on its work-protocol entry so the retrospective can see the review was single-family | 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`: | Request | Entry role | Branch | |---------|-----------|--------| | New feature | Requirements Engineer | `feature/NNN-` | | Bug | Issue Analyst | `fix/NNN-` | | Workflow improvement requested by the Maintainer | Workflow Engineer | `workflow/NNN-` | | Website change | Web Designer | `website/NNN-` | 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: ```bash 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: ```bash scripts/workflow-next.sh --work-item docs/features/NNN- # Retrospective role, after writing its report: scripts/wp-append.sh --work-item docs/features/NNN- \ --role "Retrospective" --summary "..." ``` Use `docs/issues/NNN-` 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: ```bash 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 ```bash 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.