Scrum4Me/docs/manual/03-git-workflow.md

title	status	audience	language	last_updated	when_to_read
Git Workflow	active	contributor	en	2026-05-07	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 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 (to Forgejo, the worker's origin since PBI-86). The GitHub-PR comes later via the manual promote-Action — see forgejo-hybrid-flow.md.

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.

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 (see the End-to-end verificatie section).

5. Promote to GitHub at the end (PBI-86 hybrid model)

Once a story reaches DONE and the branch is pushed to Forgejo, a human operator triggers the promote-Action in Forgejo to land the branch on GitHub and open the PR. Path-filter / label rules then decide whether a Vercel deploy runs.

• Hybrid model + promote flow: docs/runbooks/forgejo-hybrid-flow.md
• Selective deploy controls (skip-deploy label, path-filter for app//components//lib/): docs/runbooks/deploy-control.md
• Historical auto-PR flow (removed in T-1005…T-1007): docs/runbooks/auto-pr-flow.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 push (and before promote to GitHub)

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 and log the change in docs/decisions/agent-instructions-history.md.

Deep links

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

What's next

→ 04 — MCP Integration covers how the Claude agent drives this workflow from the queue side.