From grimoire
Applies GitHub Flow: short-lived feature branches, PRs with passing CI, deploy immediately on merge. Keeps main deployable for continuous deployment teams.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-github-flowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Keep `main` always deployable. Every change lives in a short-lived feature branch, ships through a PR with passing CI, and deploys immediately on merge.
Keep main always deployable. Every change lives in a short-lived feature branch, ships through a PR with passing CI, and deploys immediately on merge.
Adopted by: GitHub itself (the originating team), Netlify, Vercel, Shopify, and the majority of SaaS teams practising continuous delivery; Scott Chacon (GitHub co-founder) published the canonical description in 2011; Forsgren, Humble & Kim's "Accelerate" (2018) empirically validates the single-mainline approach as a differentiator of elite-performing engineering teams
Impact: Forsgren et al. "Accelerate" (2018): elite DevOps performers — who deploy from a single trunk/mainline — achieve 46× more frequent deployments and 440× faster lead time than low performers; GitHub internal data shows GitHub Flow teams average < 24h feature branch lifetime vs > 5 days for GitFlow teams, directly reducing merge conflict frequency; eliminating the develop/main divergence that GitFlow requires removes the most common source of "integration hell" in multi-week sprints
Why best: GitFlow solves a problem (coordinating infrequent scheduled releases) that continuous deployment teams do not have; applying GitFlow to a team that deploys daily adds branch management overhead — develop, release/*, hotfix/* — with no benefit; GitHub Flow is the minimal viable branching strategy for teams where main can always be in a releasable state; the alternative (feature flags without branching) requires more infrastructure; GitHub Flow is the sweet spot between no-branch chaos and GitFlow ceremony
Sources: Chacon "GitHub Flow" (scottchacon.com, 2011); GitHub Docs "GitHub flow" (docs.github.com); Forsgren, Humble & Kim "Accelerate" (IT Revolution, 2018, Ch. 4); Humble & Farley "Continuous Delivery" (Addison-Wesley, 2010)
main is always deployableGitHub Flow only works if the team commits to one rule: main must be in a deployable state at all times.
This requires:
mainmain require passing CI before mergemain at any time (ideally automatically on merge)If main is not currently always deployable, fix that before adopting GitHub Flow — the workflow is built on this invariant. A broken main in GitHub Flow is worse than a broken develop in GitFlow because main is production.
maingit checkout main
git pull origin main
git checkout -b <descriptive-branch-name>
Branch naming conventions:
feature/add-user-avatar-upload
fix/auth-token-expiry-off-by-one
chore/upgrade-node-18
docs/update-api-authentication-guide
feature/, fix/, chore/, docs/)feature/PROJ-42-user-avatarBranch lifetime target: < 1–2 days. Branches that live longer accumulate drift from main and increase merge conflict probability. If a branch will take > 2 days, break the work into smaller increments or use a feature flag to ship the partial implementation safely.
Push the branch to origin and open a draft PR before the work is complete:
git push -u origin <branch-name>
# Then open PR via GitHub UI or CLI:
gh pr create --draft --title "feat: add user avatar upload" --body "Work in progress..."
Why open early:
Mark the PR ready for review only when all CI checks pass and the work is complete.
Commit early, commit often. Push to the branch after each logical unit of work:
git add -p # stage hunks, not files
git commit -m "feat: add S3 presigned URL generation for avatar upload"
git push
Frequent pushes to the feature branch:
Before marking the PR ready for review, verify:
✅ All CI checks pass (tests, lint, type check, security scan)
✅ No merge conflicts with main (rebase if needed)
✅ Self-review: read your own diff as a reviewer would
✅ PR description explains WHY, not just what (link to issue/ticket)
Handle conflicts by rebasing, not merging:
git fetch origin
git rebase origin/main
# resolve conflicts if any
git push --force-with-lease
Use --force-with-lease (not --force) — it fails if someone else pushed to the branch since your last fetch, preventing accidental overwrite.
mainAfter PR approval and merge:
# GitHub merges PR → CI runs on main → deploy pipeline triggers automatically
The deployment should be automatic — triggered by merge to main. If deployment requires a manual step, it will be skipped under pressure, breaking the "always deployable" invariant.
If immediate auto-deploy is not possible: use feature flags to merge safely before the feature is activated. Merge to main (invisible behind flag) → deploy → enable flag when ready.
git push origin --delete <branch-name>
git branch -d <branch-name>
GitHub can be configured to delete branches automatically on PR merge (repository Settings → General → "Automatically delete head branches"). Enable this.
Stale branches pollute the branch list, confuse git branch -a output, and occasionally get accidentally re-opened. Delete them.
main is always deployable — never merge a broken PR; never commit directly to mainmain, target main — no develop branch; no release branchesmain that merge becomes a multi-hour project; break large features into vertical slices or hide behind feature flagsmain: bypasses CI and PR review; enable branch protection rules to make this physically impossible: Settings → Branches → Add rule → "Require pull request reviews" + "Require status checks"main but deploy weekly have GitHub Flow's simplicity with none of its benefit; the workflow only pays off when merge = deployapply-gitflow insteadapply-gitflowmain is high-risk; establish CI firstnpx claudepluginhub jeffreytse/grimoire --plugin grimoireAdopts trunk-based development to increase deployment frequency, reduce merge conflicts, and improve CI/CD practices. Useful for teams transitioning from long-lived branches.
Design branching strategies (git flow, trunk-based development, etc.) that support parallel work while maintaining stability. Use when establishing version control discipline or managing deployment complexity.
Guides teams in choosing a branching strategy (trunk-based, GitHub Flow, Git Flow, GitLab Flow), defining commit conventions (Conventional Commits), setting up PR workflows, managing releases, and establishing git standards.