How Claude Handles Git
You don’t run git commands during a Stadium 8 build. Claude creates branches, commits, pushes, and opens and merges pull requests. Two things stay under your control: the merge into main, and, if you choose, each commit and push.
What Claude needs
Section titled “What Claude needs”Claude uses the GitHub CLI (gh) to open and merge pull requests. Install it from cli.github.com and sign in once:
gh auth loginYour project also needs a GitHub remote. Without one, Claude finishes each epic on its local branch and leaves the merge to you.
Your commit and push preference
Section titled “Your commit and push preference”The first time you run /start, Claude asks how to handle commits and pushes:
| Choice | What Claude does |
|---|---|
| Auto-approve both (recommended) | Commits and pushes without asking |
| Commits only | Commits without asking, and asks before each push |
| Pushes only | Asks before each commit, and pushes without asking |
| Always ask | Asks before every commit and every push |
Claude saves your choice in .claude/preferences.json and follows it for the whole project. When it needs to ask, it asks every time. It never assumes a yes from an earlier answer.
What Claude does
Section titled “What Claude does”- Commits the project setup and epic plan to
mainafter you approve Intake - Creates a branch for each epic when its build starts
- Commits the approved stories to the epic’s branch
- Commits each story once its tests pass
- Commits any fixes from the end-of-epic checks
- Brings the branch up to date with
mainand opens a pull request - Merges the pull request once you confirm, deletes the branch, and marks the epic complete on
main
Commit messages
Section titled “Commit messages”Commits follow the Conventional Commits format. <slug> is the epic’s short name, such as user-accounts.
| Commit | Message |
|---|---|
| Project setup and epic plan | docs(project): project setup + epic plan |
| Start of an epic | docs(<slug>): start epic |
| Approved stories | docs(plan): stories for epic <slug> |
An epic planned ahead with /plan | docs(plan): plan epic <slug> (ready to build) |
| Each story | feat(<slug>/story-<N>): <story title> |
| Fixes from the end-of-epic checks | chore(<slug>): apply epic-end quality auto-fixes |
| Epic marked complete after the merge | chore(<slug>): mark epic complete |
A story commit uses feat, fix or refactor, depending on what the story does. For example: feat(user-accounts/story-2): add user profile page.
The pull request is titled feat(<slug>): <epic name>. Its description lists every story with its commit.
Merge strategy
Section titled “Merge strategy”Claude always merges with a merge commit, never a squash. This keeps one commit per story on main, so you can trace exactly when each story landed and what it changed.
To see one line per epic instead, run git log --first-parent main. To undo a whole epic, revert its merge commit.
GitHub repositories allow merge commits by default. If your repository only allows squash merges, the merge fails, and you need to enable merge commits in the repository settings.