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.

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.

text 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 separate 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 →

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 review with prior findings withheld from its prompts). 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 opt-in effectiveness record 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, self-reviews it with a PRFlow code-reviewer cleanup pass, runs the tests, opens a draft PR, 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. One helper the review calls 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, so the review report leaves out its Deferrals section; findings and verdicts are unaffected. 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 the pip install remedy and a distinct advisory final line 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: automatic review on pull request

One cloud-tier feature was withdrawn before this release rather than shipped: the workflow that ran /prflow:review automatically on every pull request. Reviewing it turned up a design flaw we chose not to patch — its caller triggered on pull_request, called a reusable workflow with secrets: inherit, checked out the pull-request head, and had no actor-authorization gate, so a fork could reach a privileged job. Rather than harden a feature we were not confident in, we removed it. The two issues describing the flaw (#930, #920) are closed as not planned because the feature they describe no longer exists — not because the problem was dismissed.

If you are installing PRFlow now, there is nothing to do. A fresh install never receives those workflow files, so the flaw is not reachable. Review still works: a repository collaborator comments /prflow:review on a pull request and the review runs, gated by an actor-authorization check. An outside fork contributor cannot self-trigger one. You can additionally configure an automatic /prflow:review request after CI passes; see Cloud triggers. Automatic requests must exclude fork pull requests before any token is minted.

The tier has been decommissioned and removed from the repository (issue #237). If you installed an earlier version that did ship it, your own tree may still carry .github/workflows/devflow-review.yml, devflow-runner.yml and telemetry-push.yml. To remove them, delete those workflow files and set workflows["prflow-review"] to false in .prflow/config.json. Then remove the Devflow Review context from any branch protection rule or ruleset that requires it — skipping it wedges every later pull request behind a required check nothing will report. After removal, use the supported review commands in Cloud triggers.

Skills and agents

Agents (agents/): spec-risk-investigator checks request-specific assumptions and conditional failure paths before spec drafts an issue; the review-engine pair checklist-generator and checklist-verifier build and verify the review engine's verification checklist; the five pr-review-toolkit reviewers (code-reviewer, comment-analyzer, pr-test-analyzer, silent-failure-hunter, type-design-analyzer) run the deep-dive review passes and requesting-code-review runs the final pass; review-engine runs that review for the fix loop, and fix-delta-reviewer reviews a fix's own diff; and the /prflow:implement agents handle intake (implement-intake), branch setup (branch-setup), the issue-claim audit (issue-claim-auditor), discovery and planning (code-explorer, code-architect), the review-and-fix worker (review-fix-worker), acceptance-criteria verification (ac-claim-verifier, ac-evidence-verifier), deferral drafting (deferral-drafter) and finalization (implement-finalization).

Namespacing matters where names collide with built-ins. /review, /init, and /security-review are built-in Claude Code commands — always use the /prflow:-prefixed form to reach PRFlow's engine (a bare /review reaches Claude Code's reviewer, not PRFlow's). Local slash commands are /prflow: only — the plugin was renamed from devflow, and the old /devflow:* local commands do not survive that rename. Cloud comment triggers still accept both: a GitHub comment reading /devflow:implement 42 or /prflow:implement 42 fires the same workflow, so existing automation and muscle memory keep working there. Either way the trigger is a bare comment (no @claude), so PRFlow coexists with Anthropic's Claude GitHub App, which owns plain @claude mentions and /security-review.

No companion plugins. PRFlow declares zero companion-plugin dependencies — /plugin install prflow@devflow-marketplace resolves on its own, with no claude-plugins-official prerequisite and none of the old dependency-unsatisfied Errors-tab friction. Every external asset its engine once dispatched is now a first-party PRFlow file: the pr-review-toolkit review agents, the feature-dev code-explorer/code-architect subagents and the superpowers final-pass reviewer (requesting-code-review) under agents/, and that reviewer's requesting-code-review launcher skill and the superpowers fix-loop fix skill under skills/ — all hard-forked with upstream licenses retained verbatim under LICENSES/. See Installation.

Project configuration

The local tier needs no config — every value has a built-in default. To customize, run /prflow:init to scaffold .prflow/config.json from PRFlow's shipped template (it never clobbers a config you've filled in) and refresh .prflow/config.schema.json (your editor reads it for autocomplete + field descriptions).

Common keys the skills read: documentation paths (docs.internal, docs.external, docs.release_notes_file, docs.changelog_file, docs.labels), the workpad marker (prflow.workpad_marker), the bot allowlist (prflow.allowed_bots), the review base (base_branch), retrospective settings (prflow_retrospective.*), and — cloud tier only — runtime provisioning (setup.*) and the plugin ref (prflow_version). See Configuration settings.

The self-improving loop

Every bot-authored PR leaves evidence — review comments, post-bot commits, CI signals, workpad state. Once a week, /prflow:retrospective-weekly reads the accumulated trail, finds failure patterns that recur, and files a human-reviewed issue proposing the smallest change that would prevent the next occurrence (a CLAUDE.md tweak, a skill rewrite, a missing doc, a new lint rule). You triage it, and it runs through the normal implement → review pipeline like any other change.

/prflow:retrospective-weekly

Run it interactively from the repo root, ideally weekly; it confirms a clean default branch, runs the full pipeline, and prints a status report with the issues to triage. Deterministic scripts handle all scanning, gating, and git/issue mechanics — the LLM is invoked only at the two genuine-judgment points (per-PR retrospective and per-pattern issue-spec drafting). The loop proposes, it does not dispose: it files one well-formed GitHub issue per actionable pattern and lets the normal implement → review pipeline execute it, rather than auto-editing the repo.

See PRFlow workflows for the supported user-facing workflow guides.

Learn more

• Public documentation — installation, workflows, local and cloud runs, configuration and troubleshooting.
• Installing and updating — supported clients, initialization and updates.
• Cloud setup — credentials and repository setup for autonomous runs.
• Review and fix · Review-agent configuration · Cloud triggers
• Releases — release history, with notes at prflow.ai.

Repository layout

.claude-plugin/   # plugin.json (no companion-plugin dependencies) + marketplace.json (this repo is its own marketplace)
skills/           # one SKILL.md per command (/prflow:implement, /prflow:review, /prflow:docs, …)
agents/           # one definition per subagent: the review-engine trio, the pr-review-toolkit reviewers, the fix-loop and implement-phase agents
scripts/          # Python + shell CLIs (workpad.py, config-get.sh, match-deferrals.py, …)
lib/              # retrospective-loop helpers (*.sh, *.jq) and preflight.sh
.github/          # optional cloud tier: workflows + composite actions (incl. vendor-plugin)
.prflow/          # config.example.json, config.schema.json, tool-presets.json, lint-manifest.json, install-state.json
.release/         # per-release provenance: source.json + a SHA-256 for every published file
docs/             # source for https://prflow.ai
LICENSES/         # third-party licences for the vendored skills and agents
install.sh        # one-command cloud-tier install/update (thin by default; DEVFLOW_VENDOR=1 to commit the plugin)

Skills reference bundled helpers via the portable single-statement anchor ($CLAUDE_SKILL_DIR on Claude Code, with a runner-reported base-directory fallback on other agentic CLIs) so they resolve from any install location and runner.

Contributing

See CONTRIBUTING.md. Security reports: SECURITY.md.

License

MIT © 2026 Daniel Radman.

Third-party components. PRFlow redistributes several agents and skills authored by others, which remain under their own upstream licenses (Apache-2.0 from Anthropic's feature-dev and pr-review-toolkit plugins; MIT from Jesse Vincent's superpowers) and have been modified by PRFlow. LICENSES/README.md maps each vendored file to its upstream project, license, and copyright holder; the full license texts are in LICENSES/.