From 625cf8a6062afd620da75233b4ab6c7f9a33c3df Mon Sep 17 00:00:00 2001
From: amcheste-ai-agent <278991699+amcheste-ai-agent@users.noreply.github.com>
Date: Mon, 11 May 2026 22:10:04 -0400
Subject: [PATCH] feat(skill): setup-repo respects release state when setting
 GitHub default branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Companion to amcheste/engineering-handbook#19 (branch-model
clarification) and #84 in this repo (publish-release default flip).

The branch model distinguishes two concepts that share the word
"default":
1. Integration trunk (always develop — where work integrates)
2. GitHub's "default branch" repo setting (UX pointer: landing page,
   git clone target, PR-base UI default)

Under the new rule, the GitHub setting is develop only until the
first release, then flips to main. setup-repo previously set it to
develop unconditionally, which is wrong for a repo that already has
releases (e.g. running setup-repo against a pre-existing repo that
just hasn't been protected yet).

Update Step 2 to check release count: develop if zero, kept as-is if
one or more. Integration trunk (Step 1, create develop) is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
---
 claude-skills/setup-repo/SKILL.md | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/claude-skills/setup-repo/SKILL.md b/claude-skills/setup-repo/SKILL.md
index 57db089..f1062ac 100644
--- a/claude-skills/setup-repo/SKILL.md
+++ b/claude-skills/setup-repo/SKILL.md
@@ -44,15 +44,30 @@ gh api repos/<owner/repo>/git/refs \
   --field sha="$MAIN_SHA"
 ```
 
-## Step 2 — Set develop as default branch
+## Step 2 — Set the GitHub default branch (conditional on release state)
+
+Two distinct concepts: **integration trunk** (always `develop` — set in Step 1) and **GitHub's "default branch" repo setting** (a UX pointer for the landing page, `git clone` target, and PR-base UI default). They differ. See [Branching & Releases → GitHub default branch setting](https://github.com/amcheste/engineering-handbook/blob/develop/docs/workflows/branching-and-releases.md#github-default-branch-setting).
+
+The rule:
+- **No releases yet** → set GitHub default to `develop`. Nothing's shipped, so the integration state is the only meaningful state.
+- **One or more releases exist** → leave GitHub default at `main`. External visitors see the shipped product. `/publish-release` will keep it at `main` going forward.
 
 ```bash
-gh api repos/<owner/repo> \
-  --method PATCH \
-  --field default_branch=develop \
-  --jq '.default_branch'
+release_count=$(gh api "repos/<owner/repo>/releases" --jq 'length')
+if [ "$release_count" -eq 0 ]; then
+  gh api repos/<owner/repo> \
+    --method PATCH \
+    --field default_branch=develop \
+    --jq '.default_branch'
+  echo "GitHub default branch set to develop (pre-release)"
+else
+  current=$(gh api repos/<owner/repo> --jq '.default_branch')
+  echo "GitHub default branch kept as $current — repo has $release_count release(s)"
+fi
 ```
 
+The integration trunk doesn't change either way — contributors branch from and PR to `develop` regardless.
+
 ## Step 3 — Set merge policy: disable squash, default to rebase
 
 Squash-merging is destructive when bot-authored PRs are merged by a human:
@@ -192,7 +207,7 @@ Report what was configured (and any gaps that need a follow-up PR):
 
 ```
 ✓ develop branch created (or already existed)
-✓ develop set as default branch
+✓ GitHub default branch: develop (pre-release) OR main (kept — repo has releases)
 ✓ Merge policy: squash disabled, rebase + merge enabled
 ✓ develop protected — require PR + [checks]
 ✓ main protected — require PR + [checks]