When to use it
Whenever you (or autopilot) face a PR that's drifted from main, has CI failures, or just needs to rebase + green up. The recommended flow:
1. xc pr provision <n> --install-deps # check the PR out into a temp worktree
2. cd <worktree-path>
3. xc pr classify # decide: clean | normal-merge | abandoned-stack
4. xc pr merge-base # if normal-merge — resolve conflicts manually
5. xc pr typecheck # QA — pass | fail | skip with structured findings
6. (fix → commit → push, then back to step 5)
7. xc pr teardown <worktree-path> # cleanupSubcommands
xc pr provision <n>
Provision a temp worktree at the PR's HEAD. Returns a JSON handle with the worktree path, branch, and PR metadata.
xc pr provision 185 --install-deps --prettyxc pr classify
Classify the PR's merge state to decide the right next action:
| Verdict | Meaning | Action |
|---|---|---|
| clean | PR is up-to-date with main and merge-able as-is. | Skip merge-base; go straight to typecheck. |
| normal-merge | Drifted from main; needs a merge or rebase. | Run xc pr merge-base, resolve conflicts. |
| abandoned-stack | Diverged so far that a merge isn't reasonable. | Cherry-pick or rebuild the work; don't try to merge. |
xc pr merge-base
Merge integration into the PR branch. Conflicts are NOT auto-resolved — they're surfaced as structured findings so the agent can address them deliberately.
xc pr typecheck
Run typecheck and emit structured findings (file, line, code, message). Returns { status: 'pass' | 'fail' | 'skip', findings: Finding[] }.
xc pr typecheck --prettyxc pr teardown <path>
Remove a temp worktree (and optionally delete its branch).
xc pr teardown ./.worktrees/pr-185 --branch feat/auth-#185xc pr playbook
Print the full agentic prompt that documents the loop, decision principles, and cross-iteration memory via diffFindings. Drop this into your agent's system prompt for PR-iteration work.
xc pr playbookAutopilot uses these too
The autopilot's verifying and merging phases call the same agent-tools/ primitives directly (no shell round-trip). So an interactive agent invoking xc pr typecheck and the autopilot ticking through verification both go through one code path.