Skip to main content
Use this workflow when an open GitHub issue describes work you want built. It creates a branch, commits and pushes changes and opens a pull request. The result is a pull request with recorded verification evidence, or a Blocked result that names the human action needed to continue.

​
Run It

1

Pick an open issue

You need the issue number. The issue does not have to be perfect, but the more precisely it states the outcome you want, the closer the result lands. See Create an Issue for how PRFlow writes one.
2

Start the run

In Claude Code:
Or, if you installed the cloud tier, leave this as a comment on issue 123 itself:
The comment form works on an issue only, not on a pull request. Only a comment body triggers a run, so a command written in the issue description starts nothing.
3

Watch the workpad

Within a minute or two, a comment appears on the issue. This is the workpad: the single place the run records what it is doing. It is created before any code is written and updated in place for the rest of the run.
4

Read the result

The run ends with the workpad at one of the terminal statuses below and, on success, a pull request linked from the workpad’s PR: line.

​
What the Workpad Looks Like

The freshly created workpad is a checklist of the whole run. For example:
The Status line is the fastest way to read a run. It moves through Setup, Discovering, Reproducing, Planning, Implementing, Reviewing and Documenting, and ends at one of four terminal words: The branch is named issue-<number>-<title-slug>, with a date suffix added when that name is already taken.
A run you interrupt is resumable. Start it again with the same issue number and it adopts the same branch, the same workpad and the same pull request instead of creating a second set. See Workpads and Resume.

​
What PRFlow Does

The run has four phases:
  1. Fetch the issue, parse its acceptance criteria and create or resume its workpad.
  2. Create or adopt the issue branch, explore the affected code, plan the change, write it, run the code-reviewer cleanup pass and test it.
  3. Open a draft pull request and run the review-and-fix loop.
  4. File any required follow-up issues, update documentation, refresh the pull request description and finish.
The issue defines the intended outcome. Before implementation starts, PRFlow checks the issue’s own claims about the repository against the current tree rather than trusting them, and it checks that the acceptance criteria cover every independently testable outcome the issue’s Desired Behavior section states. An outcome no criterion covers stops the run for issue refinement. PRFlow never invents a criterion to fill the gap.

​
Bug Reports Must Be Reproduced First

When PRFlow classifies an issue as a bug report, reproducing the defect is a hard gate, not a best effort. If it cannot reproduce the bug, the run stops at Blocked and records the obstacle. It does not proceed to write a fix for a defect it never observed.
PRFlow decides “is this a bug report?” from what the issue’s title and body describe, not from the bug label and not from a sentence in the issue telling it how to classify. A reproduction is one of three things: a failing test, a quoted error log or a recorded shell command. Whichever it captures is written into a ## Reproduction section of the workpad, and planning cannot start until that section has content. If the reproduction was not a failing test, PRFlow writes one before it writes the fix, and confirms it fails for the right reason first.

​
Acceptance Criteria Decide What Gets Checked

Before finalization, every in-scope acceptance criterion must be supported by a passing test, a documented manual check or a code reference. Two independent checkers run in a fresh context and have to agree; if they disagree, the criterion counts as unestablished and blocks, exactly as a failing one would. PRFlow checks the criteria for conflicts when it writes the plan: two criteria that cannot both hold, one that leaves out a qualifier another criterion or the issue’s Desired Behavior states for an input the criterion covers, or one that promises a result no change the issue’s Desired Behavior asks for would produce. It checks again when one of the sweeps it runs between writing and testing the code adds, removes or changes a path from a condition to an outcome that the plan did not describe, such as a failure path, and it records the result in the workpad. When a sweep’s change makes false a criterion the Desired Behavior supports, it fixes or reverts that change. It handles a conflict it finds, for example, by rewriting the criteria in the workpad to follow the Desired Behavior or, when a rewrite would drop a guarantee the Desired Behavior states, by deferring every criterion in the conflicting set to a follow-up issue. A criterion that can only be confirmed in a real deployed environment stays unticked and moves to the pull request’s Post-Merge Verification section.
An issue with no acceptance criteria does not fail this gate — it passes it, because there is nothing to check. A prose-only issue therefore gets a run with no criteria gate at the end of it. If you want that gate to mean something, write acceptance criteria in the issue. PRFlow still stops when the issue’s Desired Behavior section states a testable outcome no criterion covers, but an issue that states no such outcomes leaves nothing to compare against.
When a large issue deliberately defers some criteria to a later pull request, PRFlow files follow-up issues before it finishes and discloses them in the pull request description. Deferral never marks the work complete quietly.

​
When a Run Stops

A Blocked result is a normal outcome, not a crash. The workpad’s status becomes 👎 Blocked and the reason is recorded in the workpad. No pull request is published, so nothing half-finished reaches your reviewers. Ordinary branch and working-tree problems no longer stop the run. When the feature branch carries commits it cannot link to the issue, when the working tree is dirty (unless the changes block bringing a resumed branch to its pushed commits), when the branch is checked out in another worktree, when a base merge conflicts, or when a push is rejected, setup recovers on its own: it either carries on with the branch it found or cuts a fresh one from the base — leaving the old branch’s commits untouched — and records what it did on the workpad. A run interrupted after its work was committed but before its pull request opened resumes on its own instead of stranding. Setup itself stops for only three reasons: the setup step failed, no working branch could be established at all, or a resumed branch that no other worktree has checked out could not be brought to the commits already pushed for it and pointed at its own remote branch (for example, because it has diverged from them with local commits that are on no branch fetched from the remote). It stops early when the issue declares an open Blocked by #N dependency, when it cannot establish whether that dependency is still open, or when the issue body still has a ## 🚫 Blocked section of unsettled decisions. Later stopping points include a bug it could not reproduce, an acceptance criterion that fails or cannot be established, a verification command the run is not permitted to execute, an instruction change with three failing versions of the case it was written for, a read showing that a case the change exists to change, named in the issue or picked by the run, is already correct (or, when the issue names no such case, that every case it points to is), and an unresolved Critical review finding. Before publishing, PRFlow also confirms the branch tip reached the remote; if a commit was made but never landed there, the run stops rather than publish a pull request whose description cites a commit the remote does not have.
Read the reason on the workpad first — it names the specific obstacle.
  • Cannot reproduce. Add the missing detail to the issue: the exact trigger, the environment, the observed and expected behavior. Then run the command again.
  • An uncovered outcome in Desired Behavior. The workpad quotes the exact sentence no criterion covers. Add a criterion for it, or narrow the Desired Behavior section.
  • An open dependency. Close or unblock the prerequisite issue, then run again.
  • A ## 🚫 Blocked section in the issue. Settle each question in the issue, remove the section, then run again.
  • A verification command that is not permitted. Grant it in your tool-permission settings. See Tool Permissions.
  • A motivating case that failed three versions. The workpad’s verification notes hold each version’s results. Change the design the issue prescribes for that case, then run the command again. If no replay can recreate the case’s failure, mark the case not replayed in the issue’s testing strategy and give the reason. The run then skips that case’s replays. Unless the run finds that case’s current outcome already correct, which stops it as the next item describes, it records the reason in the workpad as the case’s accepted limit.
  • A motivating case whose current outcome is already correct. The workpad names the case or cases and the read that showed it. Change the case or the rule in the issue, then run the command again.
Running the command again after the fix resumes the same workpad and the same branch. It does not start over.
Continuous integration is a post-pull-request merge gate. It never stands in for the verification the run does inside its own environment.

​
Draft Pull Request and Review

The pull request is opened as a draft, titled with the issue title, before the review phase begins. PRFlow runs the review-and-fix loop while the pull request is still a draft, so your reviewers see the converged state rather than every intermediate one. PRFlow can run one additional bounded review-and-fix pass after the loop reaches its iteration cap, for example to review a fix made in its final iteration. The workpad records the decision and its evidence. Remaining findings can be surfaced for human judgment. Once the review is complete, PRFlow commits no fix for a finding the review raised; a repair that acceptance-criterion verification, a failing CI check or finalization calls for can still touch that finding’s code. Some findings still block the run, including a genuine unresolved Critical finding. When the fix loop disputes an acceptance criterion — for example, a reviewer asks for a change the criterion rules out — PRFlow can record each dispute as a Disputed criterion "<criterion>": <declined findings, summarized> — amend the issue or accept the criterion. line in the pull request body, quoting the criterion. The line is a note for the maintainer and changes no review outcome; a fix stricter than a criterion is disclosed as a Stricter than criterion "<criterion>": <case> — <why> line, which the review ignores once that criterion is reworded or removed until a fix pass discloses it again, and ignores in its older numbered form written before the upgrade. A dispute does not decide publication: a run that reaches publication publishes the pull request, or leaves it a draft, as implement_pr_state decides, and some findings still stop the run first — for example, an unresolved Critical one. When the criterion is wrong, the maintainer amends it on the issue.

​
Ready or Draft

The prflow_implement.implement_pr_state setting decides the final state:
  • ready_for_review — the default. PRFlow marks the pull request ready after final verification.
  • draft — the pull request stays a draft for a human to publish.
The workpad can reach Complete either way, and its PR marked ready checklist row is ticked only when the pull request was actually published — so a draft delivery is distinguishable from a published one at a glance. If publication was requested and failed, the workpad records the failure and the pull request stays a draft until a human resolves it. Human reviewers and your branch protection rules own the merge decision. PRFlow prepares the branch and the evidence. It does not approve or merge its own work.