The Branch-Per-Epic Model

Each epic is built on its own branch and merged into main only when it’s built, tested and confirmed by you. main holds only finished epics.

Branch names

Each epic branch is named epic/<slug>, where <slug> is the epic’s short name. For example: epic/user-accounts.

The life of an epic

Status	Where it lives	What’s happening
Draft	main	In the approved plan, with a brief, but its stories aren’t planned yet
Ready to build	main	Stories approved with /plan, waiting for /start
Plan	epic/<slug>	Claude proposes the stories and you approve them
Build	epic/<slug>	Claude builds and commits the stories one by one
Epic end	epic/<slug>	Full quality gates, code review and browser tests
Manual test	epic/<slug>	You test the epic in your browser
Ready to merge	epic/<slug> and a pull request	Waiting for the GitHub checks and your confirmation
Complete	main	Merged, branch deleted, record kept in generated-docs/epics/<slug>/

Type /status to see which status the current epic is in.

What this means for you

• main stays clean: only finished, tested epics land there.
• Pausing is safe: the branch keeps everything. Check it out later and type /continue to pick up where you left off.
• Epics can run side by side: you can plan one ahead with /plan, or two people can build two epics at once.
• You can review before merging: the pull request shows the epic’s full history.

When another epic merges first

Before opening its pull request, Claude brings the epic’s branch up to date with main. If another epic has changed the same shared files, such as styling tokens or mock API handlers, Claude combines the changes.

If both epics changed the same application source file, Claude stops and shows you both versions. You decide which to keep.

Epics that depend on each other

If one epic depends on another that hasn’t merged yet, its pull request says so at the top: the other epic must merge first.

Abandoning an epic

To drop an epic you no longer want, delete its branch and start the next one:

git checkout main
git branch -D epic/<slug>
git push origin --delete epic/<slug>

The last command removes the branch from GitHub, if it was pushed. Then type /start to build the next epic.