Skip to main content
Follow one complete run and learn to read the progress workpad PRFlow writes while it works. The examples below use Claude Code’s /prflow:<skill> spelling. In Codex CLI or a Codex chat in the ChatGPT desktop app, use $prflow:<skill> instead, or select the skill from /skills in Codex CLI. See Commands and Arguments.

​
Before You Start

Confirm all of the following:
  • Your current directory is inside the Git repository you want to change.
  • The GitHub repository you want to work in is the origin remote.
  • gh auth status succeeds for an identity that can read the issue and create issue comments, branches and pull requests.
  • The repository’s tests and linters run from your local environment.
  • The issue you plan to use has a clear outcome and acceptance criteria someone could check.
Initialization is not a prerequisite. Local runs work on built-in defaults with no .prflow/config.json.

​
The Walkthrough

1

Create or Pick an Issue

Skip this step if a suitable issue already exists. Otherwise describe the change in one sentence:
PRFlow asks about anything the description leaves undecided, saves the issue draft to a file and shows you its path (printing the full draft in chat only on request), and creates the issue only after you approve that draft. Note the issue number it reports.See Create Issue for the full workflow.
2

Run Implementation

Pass the issue number:
PRFlow reads the issue, creates a feature branch, posts a workpad comment on the issue, plans the change, writes it, runs your repository’s verification commands, reviews the diff and updates documentation.Expect this to take a while. Every step reports into the workpad as it happens, so you can follow along on the issue page.
3

Read the Workpad on the Issue

Open the issue in GitHub. PRFlow keeps one comment there and edits it in place for the whole run, so it always shows the current state rather than a history you have to scroll.It looks like this, abridged:
The header fields tell you where the work lives. Status is the current phase. Branch is the branch PRFlow created or adopted. Run links to the cloud run, or reads _(local run)_ when you started it yourself. PR reads _not yet created_ until the pull request exists, then holds its link. Last updated is the time of the most recent edit, in UTC.The Progress checklist has one top-level row per phase, with sub-rows beneath. Notes are timestamped and nest under the phase they belong to. Plan and Acceptance Criteria start as placeholders and fill in once PRFlow has read the issue and planned the work.PRFlow Reflections collects anything PRFlow wants a human to know: a limitation it hit, work it deferred, an assumption it had to make. Read it before you review the code. (The section reader also still accepts the older Devflow Reflection heading, so a workpad written before the rename stays readable.)
4

Review and Merge

Read the code, the tests, the documentation changes and the acceptance-criteria evidence, plus any reflections. Run a standalone review when you want a second, independent verdict.Then merge the pull request through your repository’s normal human review and branch-protection process.
PRFlow never merges the pull request and never approves its own work. The merge decision is always yours.

​
Reading the Status Glyph

Every status word carries a glyph, so you can tell the state of a run at a glance without reading the word. A local run you start yourself never writes Failed or Cancelled. Those two are written for cloud runs that ended without reaching a decision of their own.

​
What a Run Produces

  • A branch named issue-<number>-<title-slug>. PRFlow adds a date suffix when the plain name is already taken. A resumed run can adopt the head branch of an existing open pull request instead of creating one.
  • A workpad, which is the single issue comment shown above.
  • A pull request, opened as a draft during review. By default PRFlow publishes it as ready for review once verification, review and documentation finish. A repository can set implement_pr_state to draft to leave it unpublished. See Implementation Settings.

​
When a Run Reports Blocked

👎 Blocked means PRFlow stopped on purpose because something needs a human. It is not a crash. Common causes are a dependency that is missing, an acceptance criterion the change cannot satisfy, a verification command that fails or will not run and a repository state PRFlow refuses to work around, such as an unpushed branch tip. Do this:
  1. Read the PRFlow Reflections section. The reason is recorded there, along with what PRFlow observed.
  2. Fix that specific cause. Install the tool, correct the acceptance criterion, repair the failing test or resolve the repository state.
  3. Run /prflow:implement 123 again with the same issue number.
PRFlow resumes from the latest workpad and the last pushed commit on the branch. Anything it did after that last push may be repeated. A re-run on a blocked workpad surfaces the recorded reason and pauses for your confirmation before it continues, so an automated retry cannot run straight past the gate that stopped the previous run. See Workpads and Resume for how resume decides what to redo, and Implementation Troubleshooting for specific blocked causes.

​
Next Steps

The PRFlow Lifecycle

The complete sequence a run follows, phase by phase.

Review Workflow

Ask for an independent verdict on a pull request or branch.

Human Control

Where you approve, and what PRFlow will never decide for you.

Configuration

Adjust verification, review and documentation behavior.