Change one contract across three repos

You need a hall with api, web, shared-types and infra, and a harness you can launch from it. The change: add an avatarUrl field to the user profile, return it from the API and render it on the web profile page.

ivar feature create avatar-url
ivar feature promote avatar-url api
ivar feature promote avatar-url web
ivar feature promote avatar-url shared-types
ivar session start avatar-url

In the session, run /ivar-plan and approve each gate. Then, from the hall:

ivar feature deliver avatar-url --preview

What happens

• feature create names the branch once. No repo carries it yet.
• Each feature promote puts a worktree on the avatar-url branch in that repo. shared-types describes the field in user.ts, api returns it and web shows it.
• infra is not promoted, so it stays read-only on its default branch and the agent cannot commit there.
• /ivar-plan writes one plan for the three repos. deliver --preview refuses to run until the plan gate is approved.
• The preview prints a summary and a fingerprint and pushes nothing. It lists three pull requests: api, web and shared-types. infra gets none.

To see where the feature stands before you deliver, run ivar feature status avatar-url. It lists every promoted repo and its state. If a repo needs another change later, promote it onto the same branch with ivar feature promote avatar-url <repo>. Nothing already in the feature moves.

The plan is the point of the order. /ivar-plan runs requirements, analysis and plan with an approval gate after each, so the agent writes code against one agreed contract in shared-types instead of three guesses. Delivery then pushes three branches that share a name and opens three pull requests that link to each other.

Read the full walkthrough

One feature across multiple repos covers the same flow with the preview output and the sibling-PRs comment. For the commands, see features and delivery.