PRFlow — agentic coding that ships on real codebases

AI coding agents dazzle on a demo repo, then stall on a real ticket in a large production codebase. PRFlow is the Claude Code plugin that closes that gap — it carries one feature request all the way to a complete, tested, reviewed, documented pull request, so you do the final review and merge, not the cleanup.

<a name="install"></a>

Quick start

[!TIP] Just ask your agent. Paste this into Claude Code and it handles step 1 for you — the install, the setup, and the PATH dependencies /plugin install doesn't cover. Then ship your first PR with step 2.

Read https://github.com/The01Geek/prflow#quick-start and install PRFlow and its dependencies.

1. Install and set up — run these commands in order:

claude plugin marketplace add The01Geek/prflow
claude plugin install prflow@devflow-marketplace
claude /prflow:init   # launches Claude Code and scaffolds your config

2. Ship a PR — turn a feature request into a reviewed, documented pull request:

/prflow:spec <user_story>
/prflow:implement <issue_number>

The local tier runs with zero configuration — every value already has a built-in default. /prflow:init is recommended: it registers the marketplace so Claude Code keeps the plugin auto-updated (an unpinned registration that tracks the plugin repo's default branch) and writes a .prflow/config.json you can tweak. See Installing and updating for the full options and Requirements for the handful of tools it expects on your PATH.

Why PRFlow

• Ships the whole PR, not a fragment — grounded in your architecture and patterns, with the tests the change actually needs, on production code. How it's different →
• Review that fixes what it finds — and audits itself — the review-and-fix loop applies fixes and re-reviews until it approves, then a structurally-independent shadow pass re-checks the approval. Skills and agents →
• Docs stay in sync — internal docs, external docs, and release notes kept aligned with the code in the same run.
• It learns every week — a retrospective loop reads the trail of merged PRs and files human-reviewed issues that prevent the next recurring failure.
• Zero-config to start — the local tier runs entirely inside Claude Code with no infrastructure; an optional cloud tier runs it autonomously on GitHub.

▶ Read the PRFlow documentation →

<details> <summary>Contents</summary>

• How it's different
• Who it's for
• The workflow, end to end
• Requirements
• Skills and agents
• Project configuration
• The self-improving loop
• Learn more
• Repository layout
• Contributing

</details>

How it's different

The thesis isn't code generation — it's disciplined, auditable AI software delivery at production scale. A single LLM pass is variable; PRFlow's architecture is built around not trusting any single pass.

• ✓ Works on real codebases, not just pet projects. Unlike a raw agent that drafts part of the change and stops, PRFlow delivers the full round — grounded in your architecture and patterns, with the tests the change needs — on production code.
• ✓ Review that fixes what it finds. It doesn't just hand you a list. The review-and-fix loop applies the fixes and re-reviews, iterating until it approves — backed by independent verification checklists, a panel of specialized reviewers, mechanical corroboration, and a shadow pass (a second, structurally-independent review that re-checks the approval before it stands). The shadow pass narrows the gap to a standalone review; it never closes it.
• ✓ It learns. Every run leaves a trail — a PRFlow Reflection logging assumptions and anything unverified, an effectiveness trace of which steps earned their keep, living docs, and a weekly retrospective that opens the smallest fix preventing the next recurring failure.

PRFlow delivers a review-ready PR for your final human review and merge — it is not auto-merged.

Who it's for

A developer or team shipping in a large, business-grade codebase, already on Claude Code + GitHub, who wants agentic coding to complete a real ticket — branch, tests, review, docs — not just draft a snippet.

The workflow, end to end

The intended way to drive PRFlow — from a feature request to a reviewed pull request:

   you: a feature request
       │
/prflow:spec   →  explore codebase → implementation options → detailed GitHub issue
       │
/prflow:implement      →  architect → code → build/test → /prflow:review-and-fix loop → /prflow:docs
       │
/prflow:review         →  (optional) independent, comprehensive check → PR ready for developer hand-off
       │
   you: final review & merge

1. Create the issue. /prflow:spec Add CSV export to the reports page interviews you until the issue is unambiguous, shows you the draft, and files it only after you confirm. Say it lands as #42.
2. Start implementation. Run /prflow:implement 42 in Claude Code — or, on the cloud tier, comment /prflow:implement 42 on the issue (gh issue comment 42 --body '/prflow:implement 42'). Because you posted the comment, GitHub fires the workflow natively (no @claude, bot comment or PAT needed — see cloud triggers).
3. PRFlow implements it. It creates a branch, plans against your codebase, writes the code and tests, opens a draft PR, self-reviews with a PRFlow code-reviewer cleanup pass, runs /prflow:review-and-fix, files follow-up issues for deferred findings, updates the docs, and flips the PR to ready.
4. Review and merge. On the cloud tier, /prflow:review runs as a gate and posts its verdict on the PR. You do the final human review and merge.

The cloud tier (steps 2–4 running automatically on GitHub) needs only a CLAUDE_CODE_OAUTH_TOKEN secret by default (routing a workflow through an optional third-party model provider adds one more, DEVFLOW_PROVIDER_API_KEY) — see Cloud setup. Everything else runs locally inside Claude Code with no infrastructure.

Requirements

Local tier — these must be on your PATH (in a checkout of this repo, bash lib/preflight.sh checks all of them for you):

• git and gh (GitHub CLI, authenticated via gh auth login) — you most likely already have these.
• jq — JSON wrangling inside the skills.
• Python 3.11+ — the config resolver and most helper scripts are Python. Config itself is JSON, read with the standard library alone.
• PyYAML 6 or newer — python3 -m pip install 'PyYAML>=6'. The step people miss: /plugin install never runs pip, so install it yourself. Name the package rather than reaching for -r requirements.txt: that path resolves against your working directory, not the plugin cache, so in a Python project it installs your project's dependencies instead. On the local tier PyYAML is an advisory dependency — bash lib/preflight.sh reports a missing PyYAML and still exits 0 (see below).

git, gh, jq and python3 are not optional — the core skills call them directly, and a missing one is a hard stop. Shell helpers avoid GNU-only flags, so macOS/BSD work without GNU coreutils.

PyYAML is on the list, but it is the one item that degrades rather than breaks — worth knowing before you block an install on it. Exactly one runtime helper imports it, match-deferrals.py, and only lazily, on the path where a pull-request body already carries a deferred-findings block. Without PyYAML that helper exits with an error the review engine logs and steps over, continuing with all findings intact; what you lose is the severity demotion of findings you previously deferred, which fails in the safe direction — it surfaces more, never fewer findings. That safety is not free: because the re-surfaced findings are re-fixed (not merely reported) in /prflow:review-and-fix and in /prflow:implement's inline fix loop, a PyYAML-less run can churn on work a prior run deliberately deferred behind follow-up issues. Implement, review, docs and config all work without it. On the local tier bash lib/preflight.sh reports a missing PyYAML as an advisory gap and exits 0 — it prints a distinct advisory final line naming the pip install remedy rather than treating the gap as a hard stop. (The test suite, CI, and the cloud tiers still require it.)

On Windows any POSIX bash works — WSL bash, Git Bash, or MSYS2 bash (PRFlow mandates none); point PRFlow at the one you want with DEVFLOW_BASH, and in a checkout of this repo bash lib/preflight.sh prints a devflow-bash: breadcrumb confirming which bash is in use (a host with no POSIX bash at all is out of scope). A non-executable gh or jq shim can also shadow the real binary on PATH; PRFlow resolves the first gh/gh.exe (and jq/jq.exe) that actually runs (execution-verified via the shared lib/resolve-bin.sh resolver), and you can force a specific binary by setting DEVFLOW_GH / DEVFLOW_JQ to the working one. Windows-form paths are normalized to the running shell's POSIX form by lib/normalize-path.sh. PRFlow's first-party Python helpers also force their stdout/stderr to UTF-8 on a non-UTF-8 default codec, so an em-dash or emoji in a helper's output never crashes it on a Windows host (e.g. a cp1252 codec). See Installation problems for Windows and missing-dependency guidance.

Cloud tier — nothing to install on your machine; the GitHub Actions runner provisions its own toolchain. By default every job in the three shipped workflows runs on ubuntu-latest, but the runner is configurable via the DEVFLOW_RUNNER repository/organization variable (a bare label or a JSON label array), which dispatch-enables self-hosted / Windows runners. A second optional variable, DEVFLOW_LIGHT_RUNNER, routes just the light one-core jobs (the review/implement helper jobs and a standalone /prflow:review) onto a cheaper runner while review-and-fix and the implement test suite keep DEVFLOW_RUNNER (the implement job preferring its own optional DEVFLOW_IMPLEMENT_RUNNER when set; issue #402). A standalone /prflow:review prefers a third optional variable, DEVFLOW_REVIEW_RUNNER, so that model-API-bound job can take a small dedicated runner without moving the one-core helpers with it. Unset, each falls back down the chain to DEVFLOW_RUNNER so nothing moves. For runners launched per job, a {1} in the implement or review runner variable expands to the issue/PR number. Read Cloud setup before treating a non-Linux runner as production-ready.

Withheld: automa