Skip to content

BuilderIO/agent-native / .agents/skills/new-branch

new-branch

Verified

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.

FileKindSize
SKILL.mdskill md4.3 KB
---
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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall