BuilderIO/agent-native / .agents/skills/new-branch
new-branch
VerifiedName and create a task branch from fresh origin/main, and rotate a task-owned worktree to a new branch after its PR merges. Use when asked for a fresh branch, when /ship needs a branch for detached work, and after a merge.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
SKILL.md
View on GitHub---
name: new-branch
description: >-
Name and create a task branch from fresh origin/main, and rotate a
task-owned worktree to a new branch after its PR merges. Use when asked for
a fresh branch, when /ship needs a branch for detached work, and after a
merge.
user-invocable: true
scope: dev
metadata:
internal: true
---
# New Branch
Creating or switching branches never needs permission, but a branch is for
new work, not for the next change of a flow already on a branch. A whole demo
flow or batch of rows is one branch and one PR with one commit per change, so
mid-flow work goes on the existing branch, and a new branch starts only after
that flow's PR merges. In a checkout other
sessions are using, branch in a new worktree instead of switching that
checkout's branch under them. Platform-assigned Builder.io and Fusion branches
stay where they are. Never move a branch that another worktree has checked out
(`git worktree list --porcelain`), and never stash, reset, or force anything.
## Name
`<login>/changes-N`, for example `octocat/changes-545`.
```bash
login=$(gh api user --jq .login)
git fetch origin --quiet || { echo "fetch failed: not branching from a stale origin/main" >&2; exit 1; }
last=$(git for-each-ref --format='%(refname:short)' refs/heads refs/remotes/origin \
| sed -nE "s#^(origin/)?$login/changes-([0-9]{2,6})\$#\2#p" | sort -n | tail -1)
branch="$login/changes-$(( ${last:-49} + 1 ))"
```
Only your own prefixed branches count, and six digits at most, which skips
legacy and timestamp-named branches.
## Create
Look at what would come along first:
```bash
git status --short --untracked-files=all
git log --oneline origin/main..HEAD
```
Then pick the base. The `git switch` commands below are for a checkout only
this task uses; in a checkout other sessions are using, create the branch in a
new worktree instead (`git worktree add -b "$branch" <path> <base>`).
- **Nothing in the log, or every commit is from a PR that already merged**
(squash merges leave the source commits off `main`'s history; check with
`gh pr view <number> --json state`): `git switch -c "$branch" origin/main`.
- **Commits that aren't merged anywhere yet, all from this task:**
`git switch -c "$branch"` to keep them at HEAD.
- **A mix of merged and newer commits, or commits or dirty paths from another
task:** don't switch. Leave the checkout where it is and report what you
found.
Never branch from a local `main`, which can be stale. If the branch is for an
existing PR update, base it on that PR's freshly fetched live head instead of
`origin/main` (see `babysit-pr` for the push target). Don't push the new branch
until it has changes to ship.
## After a merge
Rotate only when the flow's PR merged, the tree is clean, and nothing is
unpushed.
```bash
git fetch origin --quiet || { echo "fetch failed: keeping this branch" >&2; exit 1; }
git merge-base --is-ancestor <mergeCommit.oid> origin/main
git status --porcelain --untracked-files=all -- ':/' ':(top,exclude)learnings.md' ':(top,exclude)bridge/**' ':(top,exclude)data/**'
git log --oneline <ship_merge_head_oid>..HEAD
```
- `mergeCommit.oid` comes from `gh pr view <number> --json mergeCommit`. If it
isn't in `origin/main` yet, wait a few seconds and fetch again.
- `ship_merge_head_oid` is the head `/ship` saved before merging. The `git log`
must print nothing, which means no commits landed after the merged head.
Also confirm the PR's final head is the one that merged:
`gh pr view <number> --json headRefOid --jq .headRefOid` must print
`ship_merge_head_oid`. This works even when the source branch was deleted
or lives on a fork. If the command fails, keep the branch.
- `git cat-file -e "<ship_merge_head_oid>^{commit}"` and
`git merge-base --is-ancestor <ship_merge_head_oid> HEAD` must both succeed
first, which proves this checkout holds the merged head. If
the saved OID is missing or invalid, an empty `git log` proves nothing, so
keep the branch.
- If any of these commands fails, or anything is dirty or unpushed, keep the
branch and list what you found.
When it's all clear, compute `$branch` as above and run
`git switch -c "$branch" origin/main`. Always use `origin/main` here, never the
HEAD-keeping branch from "Create": a squash merge leaves the source commits
off `main`'s history, so HEAD would carry already-merged work. In a shared
checkout, don't rotate; leave its branch as it is.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |