# pr-shepherd

> pr-shepherd gathers all context for a GitHub pull request in one poll and returns exactly one deterministic next action for a calling agent: WAIT, MARK_READY, FIX_CODE, MERGE, CANCEL, or ESCALATE. It never classifies signal vs. noise and never mutates git itself — the calling agent decides, and Shepherd only emits what to run.

## Start here

- [pr-shepherd](https://jongleberry.com/pr-shepherd/): Deterministic Draft → Merged PRs for agents. Gather all PR context in one poll, get back exactly one next action.

## Principles

- [Principles](https://jongleberry.com/pr-shepherd/principles/): The beliefs behind pr-shepherd's design, and why each one is load-bearing rather than decorative.
- [Full context over streaming](https://jongleberry.com/pr-shepherd/principles/full-context-over-streaming/): One batched poll replaces a tool-call fan-out — and beats CI-only waiters that hide review comments until checks finish.
- [Deterministic orchestration, agentic judgment](https://jongleberry.com/pr-shepherd/principles/deterministic-over-agentic/): A split, not a hierarchy: Shepherd decides the next state deterministically; the agent decides what the state means.
- [Surface data, don't classify it](https://jongleberry.com/pr-shepherd/principles/surface-data-dont-classify/): Ship the raw field, not a one-liner enum over it — unless removing the enum would cost the agent a second tool call.
- [Never mutate git](https://jongleberry.com/pr-shepherd/principles/never-mutate-git/): Shepherd emits the commit, push, and merge commands; it never runs them. The calling agent already owns the git lifecycle.
- [Every item surfaces at least once](https://jongleberry.com/pr-shepherd/principles/every-item-surfaces-once/): Outdated, resolved, and minimized review items are never silently dropped — filtering them before the agent sees them discards reviewer intent.
- [A portable state machine, not a hosted agent](https://jongleberry.com/pr-shepherd/principles/portable-not-hosted/): The same action model over CLI, MCP, and the programmatic API — safe to interrupt, and agent-neutral by construction.

## Full specification

- [docs/](https://github.com/jonathanong/pr-shepherd/tree/main/docs): the canonical, exhaustive spec this site links out to for every claim.