Cross-repo PR and CI coordination

Cross-repo work lands as several pull requests with separate CI runs. Polygraph ties those PRs and CI runs to one session, so a change touching five repos behaves as closely as possible to a change touching one.

Create and link PRs

The agent can push branches and open draft PRs for each repo in the session. Ask an agent to do it:

Push the changes and open PRs.

Or use polygraph git push-branch and polygraph git create-pr when you want to drive that flow from the CLI.

Polygraph pushes branches and opens PRs through its own integration, not the GitHub CLI, for efficiency and security reasons.

Draft PRs keep related changes reviewable before the full cross-repo set is ready. Ask the agent to mark them ready for review:

Mark the created PRs as ready for review.

Or use polygraph git mark-pr-ready from the CLI.

Polygraph syncs the status of each PR in the session, so you get the same view from the Polygraph web app or from an agent using the Polygraph CLI.

Associate existing PRs

Not every PR has to be created by Polygraph. If a PR already exists, ask the agent to attach it to the session:

Associate https://github.com/myorg/backend/pull/482 with this session.

Or use polygraph git associate-pr from the CLI. That keeps manual PRs, agent-created PRs, and follow-up PRs in the same cross-repo record.

Track CI across repos

Ask the agent to get CI green and it treats the session's CI runs as one thing. When one repo fails, the agent decides whether the fix is local to that repo, whether the shared change breaks a downstream consumer, or whether the plan itself needs to change.

Wait for CI for this Polygraph session and address any failures.

Test downstream repos before release

Many cross-repo changes involve an artifact published by one repo and consumed by another. Polygraph handles this automatically: you validate downstream before anything lands, with no registry round-trip.

For example, change a design system, install the unpublished version into an application that depends on it, and run the application's CI before the design-system PR merges. For package-based validation, the agent can use pack_and_copy to pack the publisher and install the tarball into the consumer repo inside the session.

Can you pack and copy <package-name> package and update <app-name> to use it?

This is the validation loop a monorepo gives you, applied across separate repos.

Review the whole change

Each linked PR carries session context. Reviewers can open the session to see the repos involved, a description of the work, sibling PRs, CI state, and the agent traces.

You can perform an adversarial review of the whole change to make sure the cross-repo work holds together:

1. Search Polygraph sessions for relevant work and rank up to three useful past sessions.
2. Run polygraph:session-debrief on those sessions and wait for the consolidated debrief.
3. Run polygraph:adversarial-review on the current session. Pass the completed debrief, current session description, and repository plans to every reviewer. Have them verify the debrief's assumptions against the current code.
Keep everything read-only and return one consolidated review.