The PR-First Workflow — Every Change Ships

In a lot of AI-assisted development, generated code lands directly on main — no review, no CI, no safety net. That works for prototyping but falls apart the moment you care about uptime, data integrity, or team coordination. The PR-first workflow treats every change an agent makes as a proposal, not a fait accompli, and that distinction is the difference between shipping confidently and firefighting at 2am.

What Happens Without PRs

Direct commits to main are the default in most AI-generated code workflows, and the failure modes are predictable. An agent rewrites a utility function, breaking three downstream consumers that didn't show up in its narrow test run. A bot 'fixes' an API response shape, but the frontend expected the old shape and now renders blank screens in production. Nobody notices until users report it because there was no diff to review.

In teams with multiple contributors — human or bot — direct commits create merge conflicts that are discovered after the fact. Two agents working on overlapping files simultaneously produce incompatible changes. Without a PR to surface the conflict before merge, the result is a broken main branch and an emergency revert. The coordination cost of direct commits scales quadratically with team size.

# Direct commit chaos timeline:
09:01 — Bot A commits auth middleware refactor to main
09:03 — Bot B commits API route changes (depends on old middleware)
09:05 — CI passes on Bot B's commit (tested against Bot A's new code? No — CI ran on the commit, not the merge)
09:12 — Deploy goes out. Auth is broken for all users.
09:14 — Engineer wakes up to PagerDuty alert.
09:30 — Manual revert. 18 minutes of downtime.

This scenario plays out in teams that trust AI agents with direct push access. The agents are not malicious — they are confidently wrong, and without a review gate, confident mistakes become production incidents. PRs exist precisely to create a deliberation step between intent and deployment.

Why Pull Requests Matter

The PR is the atomic unit of change. It carries a diff a person can read, a CI run, and a place to ask questions before anything reaches production. For agent work it should also carry context a raw commit never will: the ticket that motivated it and the acceptance criteria it was built against. AppHandoff does not write code or open pull requests. Your coding agent, such as Claude Code, Cursor or Codex, opens the PR in your repo the way a person would; AppHandoff holds the ticket, the claim and the record around it.

PRs also create an audit trail that matters for compliance and debugging. When a regression appears in production, you can trace it back to a specific PR, see who approved it, and follow its link to the ticket that explains why the change was made. With direct commits, you get a commit message — if you're lucky, a descriptive one.

The CI Safety Net

Every PR an agent opens runs your existing CI — linting, type checking, unit tests, integration tests, and any custom checks your team has configured, in whatever GitHub Actions, CircleCI, or Jenkins setup you already run. Nothing about that changes when the author is an agent, and it shouldn't: with branch protection on, the PR doesn't merge until CI passes, so bot-generated code is held to the same standard as human-written code. AppHandoff stays out of this path; it does not run your CI or block merges.

# The PR body your agent writes:
Add a rate limit to the invite endpoint

Closes HO-142

- Limits each project to 20 invites per hour
- Unit tests for the limit and the reset window

# Your CI: lint, type check and tests on the PR
# AppHandoff: links the PR to HO-142 through the Closes line

The CI gate catches a lot of agent mistakes before a human ever looks at the PR. Type errors, missing imports, broken tests — these are surfaced automatically. The human reviewer's job shifts from 'does this code compile' to 'is this the right approach,' which is a much better use of senior engineering time.

The Review Loop

Before an agent starts, it claims the ticket on the shared Kanban board (/shared-kanban-humans-bots). A claim is a 20-minute lease: while it is live, a second agent's claim is refused, so two agents don't build the same change at once. The agent reads the ticket's acceptance criteria, writes the code on a branch, and opens the PR with a Closes HO-n line, so reviewers can find the ticket that triggered the work without leaving the PR.

If a reviewer requests changes, the agent reads the review comments, pushes a new commit to the same PR, and the review cycle continues — exactly as it would for a person. Review comments attached to specific lines beat a free-text Slack thread because they point at exactly what needs to change. The agent can also post what it changed, and the evidence, on the ticket, so the next person or agent doesn't have to reconstruct it.

How AI Agents Use PRs

The PR is the delivery mechanism and the ticket is the record. An agent picks a ticket from the board, claims it, builds on a branch and opens a PR. It should never have push access to main: the PR is the only path to production, and your branch protection decides who can merge it. The merge is what moves the ticket.

# Ticket → PR → live:
1. Agent claims HO-142 (a 20-minute lease)
2. Agent reads the ticket and its acceptance criteria through the MCP server
3. Agent writes code on a feature branch
4. Agent opens a PR with 'Closes HO-142' on its own line
5. Your CI runs; a person reviews and merges
6. HO-142 moves to validation when the PR merges
7. HO-142 closes once the deploy is recorded

The last two steps are the point. A merged pull request is not a shipped change, so the ticket waits in validation until the deploy is recorded, and only then closes. A plain mention of HO-142 in a PR only adds a link note; it never closes the ticket. The MCP server (/mcp-server) gives the agent the ticket and its context, and the PR gives your team the review gate: AI speed with human judgment.

PR-First vs Trunk-Based Development

Some teams practice trunk-based development, where everyone commits to main with short-lived branches or no branches at all. That model works well for small, experienced teams with excellent test coverage and continuous deployment. But it assumes every contributor understands the full system — an assumption that breaks down with AI agents, which have narrow context windows and no institutional knowledge.

PR-first is not opposed to trunk-based development; it's a pragmatic adaptation for mixed human-AI teams. The branches stay short-lived — one ticket, one small PR. The key difference is the mandatory review gate. In a world where AI agents generate code at scale, that gate is what prevents a single confident mistake from cascading into a production incident.

The bottleneck shifts from writing code to approving it. Agents handle the mechanical work — writing the code, opening the PR, fixing what CI reports — while people spend their time on the review, where judgment matters most. Keeping each PR to one ticket keeps that review fast. The human in the loop guide covers which decisions belong with the reviewer.

This PR-first approach means you never lose control. Every change is auditable, reversible, and visible to the whole team. The shared Kanban board (/shared-kanban-humans-bots) shows what's in flight and who holds each claim, and a ticket closes only when its change is actually live. The result is a workflow where AI agents ship real production code — safely.