Ship feature across repos

Use Polygraph to ship a feature that spans multiple repos.

• A new endpoint needs to be coordinated with UI/UX changes.
• Or, perhaps you are adding a new event field that three microservices need to agree on.

Either way, the work is a single feature. In a monorepo this would be one PR.

Scenario: Backend API and frontend

You're adding a feature that touches both an API and the UI that calls it. The repos sit on separate teams' release schedules, but the change has to land coherently or one side breaks the other.

Example prompt

I'm inside the backend repo and run polygraph session start.

Add acme/frontend to this session.

Refer to my feature spec at <specification-file>.
This requires both API (backend) and UI/UX (frontend) changes.

Read both repos first. Confirm the auth contract and the shared response
type, then propose a plan with one bullet per repo before you write code.

Replace acme/frontend with the actual repo. The <specification-file> describes the feature so AI agents know what to build (e.g. PRD.md). You can try a short test example such as:

greeting-spec.md

I want to add a "random greeting" feature.
- In backend: a new `GET /api/greeting` endpoint
  - It returns a random greeting from a list of 5 hardcoded greetings
  - e.g. hello, hola, what's shaking, etc.
- In frontend: Call `GET /api/greeting` and show the greeting phrase in the header.

The agent reads both repos before writing code, so it understands the architecture and existing patterns. It then produces a plan for the current session that the child agents can execute on.

Once the work is complete, ask the agent to open PRs against both repos.

Push both branches and open PRs. Use title "feat: random greeting in header"

The PRs are linked to the Polygraph session as you can see from polygraph session show <session-id>.

Scenario: Cross-microservice contract change

You're adding a field to an event or message shape that three services touch (one publisher, two consumers). Before the publisher change can land, you need to be sure the consumers don't break.

Example prompt

Add `acme/orders-service`, `acme/billing-service`, and `acme/notifications-service`
to this session.

Add a `currency` field to the `OrderPlaced` event.
- `orders-service` publishes it
- `billing-service` and `notifications-service` consume it.

Read every consumer first, list every place the event shape is referenced,
then propose a plan. Treat the publisher and consumers as one change.

The agent reads every consumer before touching the publisher. That order prevents the "publisher ships, consumers explode" problem. Polygraph helps you detect which downstream consumers may break with the changes. Open PRs to consumer repos to gracefully handle the publish changes prior to shipping it out.

Everything is tracked in a single session so you and your agents don't lose context.

Coordinating merge order

For contract changes, merge order matters. Usually the publisher merges last and consumers first, so consumers tolerate the new field before it appears on the wire. Encode that in the session:

Once both consumer PRs are reviewed and green in CI, mark them ready. Hold
the publisher PR as a draft.

Once the consumer changes are live, you can resume the session with polygraph session resume <session-id> and prompt:

Verify the live consumer endpoints are compatible with the publisher changes.
If the consumers are ready, mark the publish PR as ready for review.