---
title: "Git Workflow"
status: active
audience: [contributor]
language: en
last_updated: 2026-05-07
when_to_read: "Before creating a branch, before committing, and especially before pushing or opening a PR."
---

# 03 — Git Workflow

The Scrum4Me git workflow is shaped by two pressures that don't usually appear together:

1. An **AI agent** that can produce many commits per hour without human review,
2. A **Vercel Hobby plan** that meters preview deployments and bills for them.

These two together drive a workflow that looks unusual compared to "feature-branch + PR-per-story". This chapter explains the *why*; the authoritative *how* lives in the runbooks linked at the bottom.

## The five guiding rules

### 1. One branch per milestone, not per story

A milestone (e.g. `M10-qr-login`) groups multiple stories that ship together. The agent runs through them on a single branch named `feat/M{N}-{slug}` (or `feat/ST-XXX-{slug}` for one-off stories without a milestone). All commits accumulate on that branch.

> **Why?** Every push to a feature branch triggers a Vercel preview build. Pushing per story would multiply the build cost without producing more reviewable units of work — the user reviews the milestone, not the story.

See [`docs/adr/0003-one-branch-per-milestone.md`](../adr/0003-one-branch-per-milestone.md) for the full rationale.

### 2. Commit per layer, not per task

A single task can touch the database, the API, and the UI. Each of those layers gets its own commit. The pattern:

```
feat(ST-XXX): add field X to Prisma schema       # DB
feat(ST-XXX): add Y endpoint accepting X          # API
feat(ST-XXX): wire X into the editor component    # UI
chore(ST-XXX): configure sharp for X processing   # config
docs(ST-XXX): document the X feature              # docs
```

> **Why?** Reviewers and `git bisect` both benefit when one commit can be reverted without touching unrelated layers. A `feat: add profile system` mega-commit is an antipattern.

### 3. Push only after the user has tested

Commits accumulate **locally** until the milestone is functionally complete and the user has confirmed it works. Then — and only then — `git push` and `gh pr create`.

> **Why?** Same cost reason as rule 1. Mid-milestone "save points" should be local tags or `git stash`, not pushes. Some exceptions exist (planning-only PRs, emergency hotfixes); they're enumerated in [`branch-and-commit.md`](../runbooks/branch-and-commit.md#uitzonderingen-op-de-push-regel).

### 4. One PR per batch → one preview build

When the worker runs through a queue of jobs, the entire run produces **one** PR with one commit per task. No interim pushes, no force-pushes to clean up history, no PR-per-story splits.

The end-to-end verification — that one batch produces exactly one Vercel deployment — is in [`branch-and-commit.md`](../runbooks/branch-and-commit.md) (see the *End-to-end verificatie* section).

### 5. Auto-PR flow at the end

Once a story reaches `DONE`, the auto-PR flow takes over: it pushes the branch, opens a PR, waits for the scope to be complete, waits for checks, and merges. The contract for "scope complete" and the path-filter / label rules that decide whether a deploy actually runs are split between two runbooks:

- **End-to-end pipeline**: [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md)
- **Selective deploy controls** (`skip-deploy` label, path-filter for `app/`/`components/`/`lib/`): [`docs/runbooks/deploy-control.md`](../runbooks/deploy-control.md)

## Commit message format

```
<type>(ST-XXX): short description
```

Where `<type>` is one of `feat`, `fix`, `chore`, `docs`. The story code in parentheses links the commit back to the Scrum4Me MCP entity.

For PBI-level work (no single story), use the PBI code: `docs(PBI-58): scaffold developer manual`.

## Merge conflicts

| Scenario | Conflict? | Mitigation |
|---|---|---|
| Multiple tasks on the same batch branch | No — they stack linearly on one branch | None needed |
| Two parallel batches touching the same files | Yes, possible | Serialise batches via the MCP `get_claude_context` flow (one story at a time per agent), or rebase before push |
| Long-lived branch drifting from `main` | Yes, possible | `git fetch origin main && git rebase origin/main` before `gh pr create` |

`git push --force` to "wipe" earlier preview builds is forbidden — it costs the same build again on recreation, defeating the purpose of the cost-control rules.

## When **not** to follow the strict rules

When the Vercel account moves to Pro (or another billing tier without per-build cost), this workflow can revert to the more conventional "branch + PR per story". When that happens, update the rule in [`branch-and-commit.md`](../runbooks/branch-and-commit.md) and log the change in [`docs/decisions/agent-instructions-history.md`](../decisions/agent-instructions-history.md).

## Deep links

| Topic | Authoritative source |
|---|---|
| Branch & commit rules (full normative spec) | [`docs/runbooks/branch-and-commit.md`](../runbooks/branch-and-commit.md) |
| Auto-PR flow (story-DONE → merged-PR pipeline) | [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md) |
| Deploy controls (labels, path-filter) | [`docs/runbooks/deploy-control.md`](../runbooks/deploy-control.md) |
| Vercel deployment specifics | [`docs/runbooks/deploy-vercel.md`](../runbooks/deploy-vercel.md) |
| Decision rationale (one-branch-per-milestone) | [`docs/adr/0003-one-branch-per-milestone.md`](../adr/0003-one-branch-per-milestone.md) |
| Worker idempotency & job-status protocol | [`docs/runbooks/worker-idempotency.md`](../runbooks/worker-idempotency.md) |

## What's next

→ [04 — MCP Integration](./04-mcp-integration.md) covers how the Claude agent drives this workflow from the queue side.