PRFactory Documentation
How the process runs, what the agent team does, and where you decide.
Contents
Getting started
What is PRFactory?
A visual process layer around the AI agents you already use. You bring the agent, PRFactory holds the process: the epic and its slices, the running team, the artefacts each phase leaves behind, and the checkpoints where a human decides.
How it works
Bring your agent, plan the epic, watch the team build it, approve at every checkpoint. The walk-through of a first run lives on its own page: what you add first, what the team looks like while it works, and the six points where you are asked to decide.
Agent teams
A phase can run sequentially (one agent per work item, as before) or as a team. In team mode the worker starts a lead agent that spawns child agents in other harnesses, coordinates them, and reports up. The ticket shows the whole team while it runs.
Agent states
| State | What it means | What you can do |
|---|---|---|
| running | Working right now. The only state that animates. | Read the output tail, or open the transcript |
| waiting | Parked on the lead or on a human checkpoint. | Answer, or message the agent directly |
| idle | Session alive, not spending tokens. | Send it work, or leave it |
| done | Finished. The row collapses to one dim line. | Read its transcript |
| queued | In the recipe, not spawned yet. | Nothing (it starts when there is room) |
Every agent is identified by three axes, in this order: the tool it runs in (Codex, Claude Code, Pi, Cursor CLI), the model family (GPT-5, Claude Opus, Claude Sonnet, Gemini), and the reasoning effort it was started with (low, medium, high, xhigh). A dated point release is not part of the identity and is not shown. A family and an effort are what you choose, and they do not go stale.
Codex GPT-5 xhigh
Messaging and transcripts
- Every agent has a transcript; it is newest-first, and paged with Load older output.
- Transcripts are visible to everyone in the tenant, on the same terms as the ticket.
- They are retained until the ticket is closed or archived, then purged with the rest of the team state. A transcript is working state, not a permanent audit log.
- You can message one specific agent. Delivery is confirmed; a message to a dead agent fails loudly and queues nothing.
- Sequential phases get the same transcript surface, and team mode adds the tree, not the transcript.
Epic planning
An epic too large for one build session is decomposed into build-sized slices before anyone starts. Decomposition produces three things: the slices, the acceptance criterion ownership map, and one decision round.
Slices and waves
- A slice is one build session's worth of work with its own spec, plan and AC → test matrix.
- Waves are derived from the dependency edges, never stored: a wave is simply the set of slices whose dependencies have landed.
- A slice is buildable, waiting on a dependency, blocked on an open decision, or done.
- A slice blocked on a decision is not planned: a plan written across an open question is a guess.
The decision round
- Open questions are collected once and ranked by how many slices each one blocks.
- Each decision carries a proposed default, the slices it binds, and three actions: Answer, Accept default, Defer.
- Answering re-checks every bound slice and lists the documents the answer invalidates, per file.
- Questions that could be settled from the codebase are resolved automatically and recorded, not asked.
Coverage is a composition figure, not progress: 27 / 28 owned means 25 criteria owned solely, 2 split across slices, and 1 still unplaced. An unplaced criterion blocks the cut rather than being force-assigned.
Connect your agent (MCP)
PRFactory has a built-in MCP server, hosted inside the web app at /mcp over streamable HTTP, so the agent you already work with can connect directly: it reads tickets, plans and governance rules, fetches the prompt for the next step, reports progress, and advances the workflow, without leaving the terminal.
claude mcp add --transport http prfactory https://app.prfactory.dev/mcp- Connect from Connections → Agents (MCP) in the app. Your agent opens your browser, you sign in and choose the workspace and the repositories it may reach, and no token is copied. For CI jobs and agents that cannot open a browser, a static MCP token is created on the same page.
- Run hybrid with the local worker, or MCP-only with no worker at all.
- Whether MCP may satisfy human checkpoints is a tenant setting (Settings → General → Workflow Settings), and it is off by default.
What the agent can do
- Read tickets, artefacts and governance: search-tickets, get-ticket, list-artefacts, download-artefact, get-governance (the repository's requirement constitution).
- Create and update: create-ticket, update-ticket, add-comment, upsert-artefact.
- Fetch the next step's prompt: get-step-prompt renders the exact prompt PRFactory would run for the ticket's current step.
- Advance the workflow: set-ticket-status moves through validated transitions and satisfies human checkpoints; complete-step advances the current step without queueing worker work.
Workflow phases
The built-in development process runs seven phases, with two optional pre-phases, and any phase can run as a team. It is one process, not the only one — see Custom processes below.
| Phase | What the agents do | Your checkpoint |
|---|---|---|
| 0 · Discovery / PRD | Optional. Turns an idea into a requirement, with research and a decision log. | Answer PRD questions; approve the PRD |
| 1 · Refinement | Analyses the ticket and the codebase and rewrites it as a refined requirement. | None, just read the refined ticket |
| 2 · Planning | Raises clarifying questions, then writes a reviewable implementation plan against real code. | Answer the questions; approve, refine or reject the plan |
| 3 · Test plan | Proposes automated and manual coverage. | Approve or refine |
| 4 · Implementation | Builds the plan, sequentially or as a team with a lead. | Read the diff as it lands (nothing to approve) |
| 5 · Code review | An independent review round, by the reviewer set in the agent settings. | Read the findings; approve or send back |
| 6 · Testing | Runs the gate: build, tests, formatting. | Sign off on manual testing |
| 7 · Pull request | Branch, commit, open the PR on GitHub, Bitbucket or Azure DevOps. | Review and merge (always a human) |
Custom processes
A tenant can define its own processes beside the built-in development flow — support triage, incident follow-up, anything with steps and decisions. A process is a portable JSON document: import it, export it, hand it to someone else, re-import it unchanged. The document format is written up in docs/processes/custom-process-format.md.
- Import is atomic and validated. An unknown agent backend, an outcome pointing at a step that does not exist, a missing prompt or a duplicate step name is reported per field and creates nothing.
- Importing a name that already exists creates a new version. Tickets already running an earlier version keep running it to completion.
- Every step declares its agent backend, model and reasoning effort — all three are required — and its own system prompt and user prompt template. The prompts land in the same store the built-in phases use, so they are editable afterwards in the prompt editor, and an export reflects the effective text.
- A step's named outcomes route the run: each outcome names the step it leads to. An output that names no recognised outcome halts the ticket visibly rather than guessing; from a halted run an authorised user may pick one of the declared outcomes by hand, recorded as a human decision with who made it.
- A step marked as a checkpoint pauses when it completes. You see its output and artefacts and then approve, reject, or rerun the step.
- A read-only step gets a working copy to read and publishes nothing. No branch is created until the first step that writes needs one, so a process whose steps are all read-only leaves the repository untouched.
- An outcome may hand the ticket over to the built-in development flow instead of another step. It enters Phase 1 with everything the custom run produced, and continues as an ordinary development ticket. The handover is one-way.
- Each active process appears as its own row in the left navigation, listing the tickets running it. A ticket on a custom process opens on the same ticket page a development ticket does, with its steps and artefacts on it.
- An MCP-connected agent can create a ticket on a named custom process, so a request can be filed from wherever it arrives.
- A support-triage starter process ships with the product and is imported through the same path as your own documents.
Worker fleet
Several developers can each run a worker on their own machine. The /workers page is the fleet: every registered machine by name, who registered it, its online state and last-seen time, the CLI agents it has available, and the work item it is running. A machine that stops heartbeating reads as offline, and its in-flight work is attributed to an offline machine rather than continuing to look like it is running.
- Affinity. The first claim on a ticket pins its later phases to that machine, so the worktree, the branch and the previous phase's commits are still there. Other tickets keep being distributed across the fleet — the pin is per ticket.
- Release and handover. Someone with access releases the ticket from its machine, with a reason. The branch is pushed to a work-in-progress namespace first and the next worker starts from that branch; a release that cannot preserve the work fails visibly instead of discarding it. Who released it, when and why stays on the ticket.
- Unattended handover. A machine offline past the threshold, and an agent parking because its account hit a usage limit, both produce the same handover with the trigger recorded as the reason.
- Dependency gates. A dependency blocks from a named phase onward — implementation by default, settable per dependency — so a blocked ticket still refines, plans and test-plans. It becomes claimable with no manual step once the blocker's pull request is merged. A dependency that would close a cycle is refused, naming the cycle.
- Fair share. When more work is queued than the fleet can run, it is shared across the people with work waiting rather than draining one person's queue first.
- Owner and machine are separate. A ticket has an accountable owner — a person — and checkpoint questions route to them. Changing the owner does not move the machine affinity, and a handover does not change the owner.
UI operations
- The ticket list searches by key or title and filters by status group — To do, In progress, Needs me (including failed tickets) and Done — and by repository.
- The ticket detail page shows the phase progress, the current checkpoint panel and the repositories. In team mode it also shows the agent tree with a sticky team summary bar.
- An epic additionally has Overview, Decisions, Coverage and Facit views.
- Updates arrive over SignalR; nothing needs a refresh.