Branch Create

Path Resolution (avoid missing-skill errors)

• Always open this skill using the absolute path from the active session skills list (for example <agent-skills-root>/branch/SKILL.md).
• Do not use guessed repo-relative skill paths unless the session explicitly lists that exact path.
• If you see a missing-skill error from a stale path, re-open from the active session skills list and continue.

Workflow

1. Confirm the issue target (for example #123, 123, or an issue URL). If missing, ask the user for it.
2. Identify the branch type.

- Prefer issue labels if available. - Suggested defaults: feature, bugfix, chore, docs, refactor, test, release. - If ambiguous, ask the user to choose.

1. Identify scope.

- Use issue metadata if available (component, area, or team). - If unavailable, ask for a short scope token.

1. Build the short description from the issue title.

- Lowercase. - Remove stop words and punctuation. - Replace whitespace with hyphens. - Keep concise (recommended <= 5 words). - Limit final slug length to keep the branch name manageable.

1. Form branch name as type/scope-short-description.

- Examples: - bugfix/api-auth-token-refresh - feature/dashboard-lien-card - chore/ci-fix-cache-busting

1. Verify the repository can branch from main.

- Confirm the repo has an origin remote. - Confirm origin/main exists. - If switching to main would require leaving a dirty worktree, stop and ask the user instead of stashing or resetting anything.

1. Sync local main from origin/main before branching:

- git fetch origin main - If local main exists: git switch main - If local main does not exist: git switch -c main --track origin/main - git pull --ff-only origin main

1. Create branch locally from updated main:

- git switch -c "<branch-name>"

1. Set issue start-work state in GitHub before coding (execution mode).

- Add in-progress label: - gh issue edit <issue> --add-label "agent/in-progress" - Remove conflicting status labels when present: - gh issue edit <issue> --remove-label "agent/resolved" || true - gh issue edit <issue> --remove-label "agent/blocking" || true - gh issue edit <issue> --remove-label "Blocked" || true - Post a start comment that includes branch name: - gh issue comment <issue> --body "Status: in progress. Branch: <branch-name>. Owner mode: Agent/Hybrid/Human." - If your repo uses a project board status field, also move the item to In progress.

1. Report the branch name and current status with:

- git status -sb

Hard rules

• Create a local branch only (do not push unless explicitly requested).
• Always branch from an updated local main that matches origin/main.
• For issue-driven execution, do not start implementation until the issue is marked agent/in-progress (or user explicitly says not to mutate GitHub).
• Never stash, reset, or rebase just to make the branch creation succeed.
• Do not run branch resets/rebases/cherrypicks unless explicitly instructed.
• If the repository has no main branch, stop and ask the user for the correct base branch.
• If origin/main is missing, stop and ask the user for the correct remote base branch.

Optional issue metadata enrichment (when gh is available)

• Try gh issue view <issue> --json number,title,labels when possible.
• Use labels to infer type.
• Use the title to derive a short description.
• If metadata is unavailable, continue with user-provided values.

Optional issue creation (when user asks to create one first)

• If the user asks you to open an issue before branching, avoid inline --body "..." for multiline Markdown.
• Use a temp file with gh issue create --body-file to prevent shell quoting/backtick interpolation bugs:

- BODYFILE=$(mktemp) - cat > "$BODYFILE" <<'EOF' ... EOF - gh issue create --title "<title>" --body-file "$BODYFILE" - rm -f "$BODYFILE"