1
Issue
The GitHub issue is the contract for the change. PRFlow reads its description and its acceptance criteria.The optional spec workflow clarifies unresolved decisions and waits for explicit approval before it creates the issue.
2
Run
An implementation command starts the run.PRFlow loads repository guidance and configuration, then creates or resumes the workpad on issue 123.A local run can ask you questions. A cloud run works from the issue and the recorded workpad, because no person is present in the session.
3
Branch and Setup Gates
PRFlow creates, reuses or adopts a feature branch, pushes it and records it in the workpad. The workpad mirrors the issue’s acceptance criteria and tracks the run’s status. See Workpads and Resume.Three gates can stop the run here, before any code is written:
- A declared open dependency. If the issue declares a dependency on another issue that is still open, or if the state of that dependency cannot be established, the run stops as
Blocked. This check runs before branch work, so a blocked run leaves no new branch behind. - A claim in the issue that does not match the repository. PRFlow checks the issue’s claims about the codebase against the current tree before it treats them as instructions. It also checks that the acceptance criteria represent every independently testable outcome the issue describes. An uncovered outcome sends the issue back for refinement instead of being guessed at.
- A workpad already marked
Blocked. PRFlow surfaces the recorded cause instead of continuing through it.
4
Implement and Verify
PRFlow explores the affected code, plans the change and implements it.For an issue classified as a bug report, reproduction is a hard gate. PRFlow captures a reproduction signal, such as a failing test or an error log, before it plans the fix. If it cannot reproduce the defect, the run stops as
Blocked and records why. It does not proceed on an unreproduced bug.PRFlow then runs the repository’s own checks in the run environment, commits and pushes the work and opens a draft pull request that closes the issue. The checks run before the draft pull request is opened, not after it. See How PRFlow Verifies a Change.The pull request stays a draft while the remaining review and documentation work happens.5
Cleanup, Review and Fix
First PRFlow runs a cleanup pass over the code the change added or modified. Its charter is quality only: reuse, simplification, efficiency and altitude. It does not hunt for bugs and it never owns correctness. Every finding it produces is checked against the issue’s acceptance criteria before it is applied, so a cleanup cannot quietly undo something the issue required.Then the review-and-fix loop runs. The review engine builds a verification checklist, checks it against evidence and dispatches specialized reviewers. Findings can trigger corrections and another review iteration. See The Review System.Before the run can finish, every in-scope acceptance criterion must be verified, or explicitly routed to a follow-up issue or to post-merge verification.
6
Documentation
PRFlow files follow-up issues for deferred work, updates the internal and external documentation the change affects, adds release-note material when it is needed and refreshes the pull-request description.By default the pull request is then published as ready for review. Repository configuration can leave it as a draft instead.
7
Human Merge
A person reviews the pull request, the repository’s own checks, the workpad and the review findings. Branch protection and your team’s normal approval process still apply.PRFlow never performs the merge. The lifecycle ends with a review-ready or deliberately draft pull request, not with code on the default branch.