ADR-0003: One branch per milestone, push only after user test

Context and Problem Statement

Every git push to a feature branch triggers a Vercel preview deployment. On the Hobby plan, preview builds are limited and cost money. How should we structure branches and pushes to minimize preview-build spend while still supporting a fast AI-driven development loop?

Decision Drivers

Vercel Hobby plan: preview builds are finite and billed per deployment.
Small team (primarily solo developer + AI agent): branch overhead should be minimal.
AI-driven flow: the agent commits frequently in small logical layers; we don't want a push per commit.
User acceptance is done interactively per milestone, not per story.

Considered Options

Branch per story — one branch per story, PR per story.
Branch per milestone — one branch for all stories in a milestone, single PR after user test.
Trunk-based development — commit directly to main with feature flags.

Decision Outcome

Chosen option: Branch per milestone, because it is the only option that keeps preview-build count proportional to milestones (not stories), while still enabling isolated review via a single PR.

Consequences

Good, because preview deployments are rare — only one per milestone reaching review.
Good, because PR history maps to milestones, not micro-stories.
Bad, because branches live longer; merge conflicts are larger but less frequent.
Bad, because a single failed story blocks the milestone PR.

Confirmation

Before pushing, the developer/agent must confirm explicitly. git push is never automated. See docs/runbooks/branch-and-commit.md.

Pros and Cons of the Options

Branch per story

Good, because small, focused PRs are easy to review.
Bad, because each push triggers a preview build — N stories = N builds per milestone.

Branch per milestone

Good, because minimal preview builds.
Good, because the PR represents a coherent feature set.
Bad, because long-lived branches.

Trunk-based development

Good, because no branch management overhead.
Bad, because requires feature flags to hide incomplete work — too much infrastructure for this scale.

More Information

Revisit this decision if/when the Vercel account upgrades to Pro (unlimited preview builds). At that point, branch-per-story is the preferred default. Update docs/runbooks/branch-and-commit.md and this ADR when that happens.

2.5 KiB Raw Blame History