Creating Branch

Git Branch Creation Workflow

Execute feature branch creation with intelligent naming, automatic type detection, and sequential numbering.

Usage

This skill is invoked when:

• User runs /create-branch or /git:create-branch command
• User requests to create a new feature branch
• User asks to start a new branch for a task

Two Operation Modes

Mode 1: With Description (Manual)

The command takes a description and automatically detects the commit type.

Format: /create-branch <description>

Examples:

/create-branch add user authentication
→ Creates: feat/001-user-authentication

/create-branch fix login bug
→ Creates: fix/002-login-bug

/create-branch refactor auth service
→ Creates: refactor/003-auth-service

/create-branch remove deprecated code
→ Creates: chore/004-remove-deprecated

/create-branch document api endpoints
→ Creates: docs/005-document-api

Mode 2: Auto-Generate from Changes (No Arguments)

When no arguments provided and no sdlc-develop specs exist, analyze uncommitted changes to generate branch name automatically.

Format: /create-branch (no arguments)

Process: 1. Check for sdlc-develop specs (see Mode 3) 2. If no specs, check for uncommitted changes (both staged and unstaged) 3. If no changes exist, display error and require description 4. If changes exist, analyze to generate description 5. Create branch with auto-generated name

Examples:

# After modifying authentication files
/create-branch
→ Auto-detected from changes: feat/006-authentication-system
→ (based on: login.py, auth_service.ts, user_model.py)

# After fixing payment bug
/create-branch
→ Auto-detected from changes: fix/007-payment-processing
→ (based on: payment.js, checkout.py)

Mode 3: From SDLC-Develop Spec (Arkhe Integration)

When no arguments provided and sdlc-develop specs exist, the skill can create branches linked to existing feature specs.

Detection Flow: 1. Check if .arkhe.yaml exists → read develop.specs_dir (default: arkhe/specs) 2. Scan {specs_dir}/ for existing spec directories 3. If specs found → present selection via AskUserQuestion 4. Use spec directory name for branch name

Example:

# Specs exist: arkhe/specs/01-user-auth/, arkhe/specs/02-dashboard/
/create-branch

# Prompt: "Select a feature spec for this branch"
# Options: 01-user-auth, 02-dashboard, None (auto-generate from changes)

# User selects 01-user-auth
→ Creates: feat/01-user-auth

Commit Type Detection

The workflow automatically detects commit types from keywords in the description:

If no keyword is detected, defaults to feat.

Branch Naming Format

Pattern: {type}/{number}-{keyword1}-{keyword2}

Components:

• type: Auto-detected commit type (feat, fix, refactor, chore, docs)
• number: Auto-incremented 3-digit number (001, 002, 003...)
• keywords: First 2-3 meaningful words from description (lowercase, hyphenated)

Examples:

• Input: "add user authentication system"
• Output: feat/001-user-authentication

• Input: "fix null pointer in login"
• Output: fix/002-null-pointer

Important Notes

• Sequential Numbering: Finds next available number by scanning existing branches
• Keyword Extraction: Filters common words, keeps 2-3 meaningful terms
• Lowercase Convention: All branch names are lowercase with hyphens
• Conventional Commits: Aligns with conventional commit types
• SDLC-Develop Integration: Detects feature specs from .arkhe.yaml

Supporting Documentation

• [WORKFLOW.md](WORKFLOW.md) - Detailed step-by-step process with bash scripts
• [EXAMPLES.md](EXAMPLES.md) - Real-world examples for all branch types
• [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions

Git Branch Creation: Examples

This document provides real-world examples of branch creation with the creating-branch skill.

---

Example 1: Feature Branch (New Functionality)

Scenario

Adding a new user authentication system to the application.

Command

/create-branch add user authentication system

Execution

Step 1: Parse Description

Input: "add user authentication system"

Step 2: Detect Type

Keyword found: "add"
Type detected: feat

Step 3: Extract Keywords

Remove stopwords: "add"
Meaningful words: ["user", "authentication", "system"]
Selected: "user", "authentication" (first 2)
Keywords: user-authentication

Step 4: Find Next Number

Existing branches: feat/001-profile, feat/002-dashboard
Max number: 002
Next number: 003

Step 5: Create Branch

Branch name: feat/003-user-authentication
Command: git checkout -b feat/003-user-authentication

Output

✅ Branch created: feat/003-user-authentication

Typical Usage

# Create branch
/create-branch add user authentication system

# Make changes
vim src/auth/authenticator.js

# Commit
git add .
git commit -m "feat: implement user authentication"

# Push
git push -u origin feat/003-user-authentication

---

Example 2: Bug Fix Branch

Scenario

Fixing a null pointer exception in the login service.

Command

/create-branch fix null pointer in login service

Execution

Step 1: Parse

Input: "fix null pointer in login service"

Step 2: Detect Type

Keyword found: "fix"
Type detected: fix

Step 3: Extract Keywords

Remove stopwords: "fix", "in"
Meaningful words: ["null", "pointer", "login", "service"]
Selected: "null", "pointer" (first 2)
Keywords: null-pointer

Step 4: Find Next Number

Existing branches: feat/003-user-authentication
Max number: 003
Next number: 004

Step 5: Create Branch

Branch name: fix/004-null-pointer
Command: git checkout -b fix/004-null-pointer

Output

✅ Branch created: fix/004-null-pointer

---

Example 3: Refactoring Branch

Scenario

Refactoring the authentication service to improve code quality.

Command

/create-branch refactor authentication service

Execution

Detection:

Keyword: "refactor"
Type: refactor
Keywords: authentication-service
Number: 005

Result:

Branch: refactor/005-authentication-service

Output

✅ Branch created: refactor/005-authentication-service

---

Example 4: Documentation Branch

Scenario

Adding documentation for API endpoints.

Command

/create-branch document api endpoints

Execution

Detection:

Keyword: "document"
Type: docs
Keywords: api-endpoints
Number: 006

Result:

Branch: docs/006-api-endpoints

Output

✅ Branch created: docs/006-api-endpoints

---

Example 5: Chore Branch

Scenario

Removing deprecated code from the codebase.

Command

/create-branch remove deprecated code

Execution

Detection:

Keyword: "remove"
Type: chore
Keywords: deprecated-code
Number: 007

Result:

Branch: chore/007-deprecated-code

Output

✅ Branch created: chore/007-deprecated-code

---

Example 6: Default to Feature Type

Scenario

No explicit type keyword in description.

Command

/create-branch dashboard improvements

Execution

Detection:

No keyword found
Default type: feat
Keywords: dashboard-improvements
Number: 008

Result:

Branch: feat/008-dashboard-improvements

Output

✅ Branch created: feat/008-dashboard-improvements

---

Example 7: Long Description (Keyword Limiting)

Scenario

Very detailed description with many words.

Command

/create-branch add comprehensive user authentication system with OAuth2 and JWT tokens

Execution

Detection:

Keyword: "add"
Type: feat
Meaningful words: ["comprehensive", "user", "authentication", "system", "with", "OAuth2", "and", "JWT", "tokens"]
Selected: "user", "authentication" (first 2 meaningful words, skipping "comprehensive")
Keywords: user-authentication
Number: 009

Result:

Branch: feat/009-user-authentication

Output

✅ Branch created: feat/009-user-authentication

Note: The script automatically limits to 2-3 keywords to keep branch names short and readable.

---

Example 8: Multiple Type Keywords

Scenario

Description contains multiple type keywords.

Command

/create-branch fix and improve login validation

Execution

Detection:

Keywords found: "fix" (first), "improve" (second)
Type: fix (first keyword takes priority)
Meaningful words: ["and", "improve", "login", "validation"]
Remove: "and", "improve" (stopwords + type keyword)
Selected: "login", "validation"
Keywords: login-validation
Number: 010

Result:

Branch: fix/010-login-validation

Output

✅ Branch created: fix/010-login-validation

Note: First detected type keyword determines branch type.

---

Example 9: From SDLC-Develop Spec

Scenario

Creating a branch linked to an existing feature spec from /develop.

Prerequisites

# Existing specs from /develop workflow
ls arkhe/specs/
# 01-user-auth/  02-dashboard/

# .arkhe.yaml exists with specs_dir configured
cat .arkhe.yaml
# develop:
#   specs_dir: arkhe/specs

Command

/create-branch  # No arguments

Execution

Step 1: Detect Specs

Found .arkhe.yaml with specs_dir: arkhe/specs
Specs found: 01-user-auth, 02-dashboard

Step 1b: Spec Selection

AskUserQuestion:
"Select a feature spec for this branch"
Options:
- 01-user-auth
- 02-dashboard
- None (auto-generate from changes)

User Selection: 01-user-auth

Step 6: Generate Branch Name

Type: feat (default)
Spec name: 01-user-auth
Branch: feat/01-user-auth

Output

✅ Branch created: feat/01-user-auth
   Linked to spec: arkhe/specs/01-user-auth/

Typical Usage

# Start with a spec
/develop add user authentication
# ... Phase 0-2 completes, spec saved ...

# Later, create branch from spec
/create-branch
# Select: 01-user-auth
→ feat/01-user-auth

---

Example 10: Sequential Numbering Across Types

Scenario

Multiple branches of different types.

Commands

/create-branch add user profile
→ feat/001-user-profile

/create-branch fix login bug
→ fix/002-login-bug

/create-branch add dashboard
→ feat/003-dashboard

/create-branch refactor auth
→ refactor/004-auth

Result

All branches share sequential numbering:
- feat/001-user-profile
- fix/002-login-bug
- feat/003-dashboard
- refactor/004-auth

Note: Numbers are global across all branch types, not per-type.

---

Example 11: Type Detection Keywords

Complete Keyword Reference

feat (Feature):

/create-branch add notification system
→ feat/001-notification-system

/create-branch create admin dashboard
→ feat/002-admin-dashboard

/create-branch implement search functionality
→ feat/003-search-functionality

/create-branch new reporting feature
→ feat/004-reporting-feature

/create-branch update user interface
→ feat/005-user-interface

/create-branch improve performance
→ feat/006-performance

fix (Bug Fix):

/create-branch fix crash on startup
→ fix/007-crash-startup

/create-branch bug in payment processing
→ fix/008-payment-processing

/create-branch resolve memory leak
→ fix/009-memory-leak

/create-branch correct validation logic
→ fix/010-validation-logic

/create-branch repair broken link
→ fix/011-broken-link

refactor (Code Refactoring):

/create-branch refactor database layer
→ refactor/012-database-layer

/create-branch rename user model
→ refactor/013-user-model

/create-branch reorganize component structure
→ refactor/014-component-structure

chore (Maintenance):

/create-branch remove old migrations
→ chore/015-old-migrations

/create-branch delete unused files
→ chore/016-unused-files

/create-branch clean up dependencies
→ chore/017-dependencies

/create-branch cleanup test fixtures
→ chore/018-test-fixtures

docs (Documentation):

/create-branch docs for setup process
→ docs/019-setup-process

/create-branch document deployment guide
→ docs/020-deployment-guide

/create-branch documentation for api
→ docs/021-api

---

Example 12: SDLC-Develop with No Specs

Scenario

Running /create-branch without arguments when .arkhe.yaml exists but no specs directory.

Prerequisites

# .arkhe.yaml exists
cat .arkhe.yaml
# develop:
#   specs_dir: arkhe/specs

# But no specs exist yet
ls arkhe/specs/
# (empty or directory doesn't exist)

Command

/create-branch  # No arguments

Execution

Step 1: Detect Specs

Found .arkhe.yaml with specs_dir: arkhe/specs
No specs found - falling back to auto-generate mode

Step 2: Auto-generate from changes

• Proceeds with normal change detection
• Or prompts for description if no uncommitted changes

Output (with uncommitted changes)

ℹ️  Auto-detected description: update authentication flow
ℹ️  Based on changes in: src/auth/login.js, src/auth/session.js
✅ Branch created: feat/001-authentication-flow

Output (without changes)

❌ Error: No uncommitted changes detected.

To create a branch, either:
1. Make some changes first, then run /create-branch
2. Provide a description: /create-branch <description>

---

Example 13: Edge Cases

Empty or Very Short Descriptions

One Word:

/create-branch authentication
→ feat/001-authentication  # Default type: feat

Two Words:

/create-branch fix login
→ fix/002-login

Generic Terms:

/create-branch update things
→ feat/003-update-things  # Keeps "update" as keyword since no other meaningful words

Special Characters

With Punctuation:

/create-branch add user's profile page
→ feat/004-user-profile  # Removes apostrophes and special chars

With Numbers:

/create-branch add OAuth2 authentication
→ feat/005-oauth-authentication  # Numbers in words are handled

---

Example 14: Real-World Project Workflow

Scenario: Building a Blog Platform

Phase 1: Core Features

/create-branch add post model
→ feat/001-post-model

/create-branch add user authentication
→ feat/002-user-authentication

/create-branch add comment system
→ feat/003-comment-system

Phase 2: Bug Fixes

/create-branch fix post save error
→ fix/004-post-save

/create-branch fix comment validation
→ fix/005-comment-validation

Phase 3: Improvements

/create-branch refactor post repository
→ refactor/006-post-repository

/create-branch improve comment performance
→ feat/007-comment-performance

Phase 4: Documentation

/create-branch document api endpoints
→ docs/008-api-endpoints

Result: Clean, sequential branch history across entire project lifecycle.

---

Common Patterns

REST API Development

/create-branch add user endpoints
→ feat/001-user-endpoints

/create-branch add post endpoints
→ feat/002-post-endpoints

/create-branch fix authentication middleware
→ fix/003-authentication-middleware

/create-branch document rest api
→ docs/004-rest-api

Frontend Development

/create-branch add login component
→ feat/001-login-component

/create-branch add dashboard layout
→ feat/002-dashboard-layout

/create-branch fix responsive design
→ fix/003-responsive-design

/create-branch refactor component structure
→ refactor/004-component-structure

Database Work

/create-branch add user migration
→ feat/001-user-migration

/create-branch fix foreign key constraint
→ fix/002-foreign-key

/create-branch refactor database schema
→ refactor/003-database-schema

---

Tips for Effective Branch Names

✅ Good Practices

1. Use action verbs:

• /create-branch add payment integration ✅
• /create-branch payment integration ⚠️ (works but less clear)

2. Be specific:

• /create-branch fix null pointer in auth ✅
• /create-branch fix bug ❌ (too vague)

3. Use conventional keywords:

• /create-branch add user auth ✅ (detected as feat)
• /create-branch implement user auth ✅ (detected as feat)
• /create-branch user auth ⚠️ (defaults to feat)

4. Keep descriptions concise:

• The script uses first 2-3 meaningful words
• Longer descriptions are automatically shortened

❌ Avoid

1. Too vague:

• /create-branch work on feature ❌
• /create-branch updates ❌

2. Too long (will be shortened anyway):

• /create-branch add comprehensive user authentication system with OAuth2 JWT tokens and refresh token support
• Result: feat/001-user-authentication (only first 2 meaningful words kept)

3. Non-descriptive:

• /create-branch temp ❌
• /create-branch test ❌

---

Summary

The creating-branch skill automatically:

• ✅ Detects branch type from natural language
• ✅ Extracts meaningful keywords
• ✅ Generates short, readable names
• ✅ Maintains sequential numbering
• ✅ Creates consistent branch names
• ✅ Integrates with SDLC-develop specs for linked branch creation

Result: Professional, discoverable branch names that align with conventional commits.

---

Last Updated: 2025-10-27

Git Branch Creation: Troubleshooting

This document provides solutions to common issues when using the creating-branch skill.

---

Common Issues

Issue 1: Branch Already Exists

Symptom:

fatal: A branch named 'feat/003-user-auth' already exists.

Cause:

• A branch with the same name already exists (locally or remotely)
• Attempting to recreate a previously deleted branch with the same number

Solutions:

Solution A: Use Different Description

# Instead of:
/create-branch add user authentication

# Try:
/create-branch add user auth system
→ feat/003-user-auth-system (different keywords)

Solution B: Delete Existing Branch

# Delete local branch
git branch -d feat/003-user-auth

# Or force delete
git branch -D feat/003-user-auth

# Delete remote branch (if exists)
git push origin --delete feat/003-user-auth

# Then recreate
/create-branch add user authentication

Solution C: Let Sequential Numbering Handle It The script will automatically find the next available number:

# Existing: feat/003-user-auth
# New command: /create-branch add user authentication
# Result: feat/004-user-authentication (incremented number)

---

Issue 2: Invalid Characters in Branch Name

Symptom:

fatal: 'feat/003-user@auth' is not a valid branch name.

Cause:

• Description contains special characters that are not allowed in git branch names
• Characters like @, #, ~, ^, :, \, *, ?, [, ]

Solution:

The script automatically sanitizes branch names, but if you encounter this error:

Remove special characters from description:

# Instead of:
/create-branch add user@domain authentication

# Use:
/create-branch add user domain authentication
→ feat/003-user-domain

Avoid punctuation:

# Instead of:
/create-branch fix: login error!

# Use:
/create-branch fix login error
→ fix/003-login-error

---

Issue 3: Script Not Found or Permission Denied

Symptom:

bash: /create-branch: No such file or directory

or

bash: /create-branch: Permission denied

Causes & Solutions:

Cause A: Wrong Working Directory

Solution: Run from project root

# Check current directory
pwd

# Navigate to project root
cd /path/to/arkhe-claude-plugins

# Then run
/create-branch "add user auth"

Cause B: Script Not Executable

Solution: Make script executable

chmod +x /create-branch
chmod +x git/skills/creating-branch/shared utilities

Cause C: File Doesn't Exist

Solution: Verify installation

# Check if skill files exist
ls -la plugins/git/skills/creating-branch/

# Expected output:
# SKILL.md  WORKFLOW.md  EXAMPLES.md  TROUBLESHOOTING.md

If files are missing, reinstall the git plugin:

/plugin uninstall git@arkhe-claude-plugins
/plugin install git@arkhe-claude-plugins

---

Issue 4: Type Detection Not Working

Symptom: Branch is created as feat/ instead of expected type (e.g., fix/).

Cause:

• Type keyword not recognized
• Keyword appears later in description
• Typo in type keyword

Solutions:

Solution A: Use Recognized Keywords

Supported keywords by type:

• feat: add, create, implement, new, update, improve
• fix: fix, bug, resolve, correct, repair
• refactor: refactor, rename, reorganize
• chore: remove, delete, clean, cleanup
• docs: docs, document, documentation

# Instead of:
/create-branch solve the login issue
→ feat/001-solve-login  # "solve" not recognized

# Use:
/create-branch fix the login issue
→ fix/001-login-issue  # "fix" recognized

Solution B: Put Type Keyword First

The script checks keywords in order:

# Good:
/create-branch fix login validation error
→ fix/001-login-validation

# Less reliable:
/create-branch login validation error fix
→ feat/001-login-validation  # "fix" found too late, defaults to feat

Solution C: Accept Default Type

If no keyword is found, feat is used as default:

/create-branch user authentication
→ feat/001-user-authentication

This is acceptable for most feature work.

---

Issue 5: Sequential Numbering Skips Numbers

Symptom: Expected feat/003- but got feat/005-.

Cause:

• Branches were deleted but their numbers were the highest
• Mixed local and remote branches
• Manual branch creation with higher numbers

Explanation:

This is expected behavior. The script finds the highest number across all existing branches and increments:

# Existing branches:
feat/001-user-auth
feat/002-dashboard
fix/004-login-bug  # Note: 003 was deleted

# New branch:
/create-branch add payment
→ feat/005-payment  # Next after 004, not 003

Solutions:

Solution A: Accept the Gap (Recommended)

Gaps in numbering are acceptable and don't cause issues:

• Sequential order is maintained (005 > 004)
• Each branch has unique identifier
• History is preserved

Solution B: Manually Create with Specific Number

If you need a specific number:

git checkout -b feat/003-payment

Note: This bypasses the automatic numbering system.

Solution C: Reset Numbering (Not Recommended)

Only if absolutely necessary and no remote branches exist:

# Delete all local branches
git branch | grep -v "main\|master" | xargs git branch -D

# Start fresh
/create-branch add first feature
→ feat/001-first-feature

Warning: This destroys branch history.

---

Issue 6: Keywords Too Generic

Symptom: Branch names are not descriptive enough.

Example:

/create-branch add new feature
→ feat/001-new-feature  # Too generic

Cause: Description uses generic terms without specifics.

Solutions:

Be Specific:

# Instead of:
/create-branch add new feature
→ feat/001-new-feature

# Use:
/create-branch add user authentication
→ feat/001-user-authentication

Include Context:

# Instead of:
/create-branch fix bug
→ fix/002-bug

# Use:
/create-branch fix login validation bug
→ fix/002-login-validation

Use Domain Terms:

# Instead of:
/create-branch update the system
→ feat/003-update-system

# Use:
/create-branch update payment gateway
→ feat/003-payment-gateway

---

Issue 7: Branch Name Too Long

Symptom: Expected longer branch name, but got shortened version.

Example:

/create-branch add comprehensive user authentication system with OAuth2 and JWT
→ feat/001-user-authentication  # Expected more keywords

Cause: The script intentionally limits branch names to 2-3 meaningful keywords for readability.

Explanation:

This is expected behavior for good git practices:

• Short branch names are easier to read
• Terminal commands are more manageable
• Tab completion works better
• PR titles remain concise

Solutions:

Solution A: Accept Short Name (Recommended)

Short names are better for git workflows:

feat/001-user-authentication  # Clear and concise

Use commit messages and PR descriptions for details:

git commit -m "feat: implement comprehensive OAuth2 and JWT authentication"

Solution B: Manual Branch Creation

If you absolutely need a longer name:

git checkout -b feat/001-user-authentication-oauth2-jwt

Warning: This bypasses the naming convention.

---

Issue 8: Specs Not Detected

Symptom: Branch creation doesn't offer spec selection even though specs exist.

Causes & Solutions:

Cause A: Missing .arkhe.yaml

Solution: Create configuration or run /develop first

# Check for config
cat .arkhe.yaml

# If missing, create manually
echo "develop:
  specs_dir: arkhe/specs" > .arkhe.yaml

Cause B: Empty specs directory

Solution: Run /develop to create a spec first

/develop add user authentication --plan-only
# Creates arkhe/specs/01-user-auth/

# Now /create-branch will detect it
/create-branch

Cause C: Custom specs_dir not matching

Solution: Verify specs_dir in .arkhe.yaml matches actual location

# Check config
grep specs_dir .arkhe.yaml

# Verify directory exists
ls -la arkhe/specs/  # or your custom path

Cause D: Spec directories have no subdirectories

Solution: Ensure specs are proper directories

# Specs must be directories, not files
ls -la arkhe/specs/
# Should show:
# drwxr-xr-x  01-user-auth/
# drwxr-xr-x  02-dashboard/

---

Issue 9: Wrong Git Repository

Symptom:

fatal: not a git repository (or any of the parent directories): .git

Cause: Not running from within a git repository.

Solutions:

Solution A: Navigate to Git Repository

# Check if in git repo
git status

# If not, navigate to your project
cd /path/to/your/project

# Verify
git status

Solution B: Initialize Git Repository

If this is a new project:

# Initialize repository
git init

# Add remote (if needed)
git remote add origin <url>

# Then create branch
/create-branch add initial feature

---

Issue 10: Script Fails Silently

Symptom: No error message, but branch is not created.

Causes & Solutions:

Cause A: Shell Not Supporting Script

Solution: Use bash explicitly

bash /create-branch "add user auth"

Cause B: Missing Dependencies

Solution: Verify git is installed

# Check git installation
git --version

# If not installed (macOS):
xcode-select --install

# If not installed (Linux):
sudo apt-get install git  # Debian/Ubuntu
sudo yum install git       # RHEL/CentOS

Cause C: Script Syntax Error

Solution: Check script integrity

# Verify script syntax
bash -n /create-branch

# If errors appear, reinstall plugin
/plugin uninstall git@arkhe-claude-plugins
/plugin install git@arkhe-claude-plugins

---

Issue 11: Branch Created but Not Checked Out

Symptom: Branch is created but you're still on the previous branch.

Cause: Script execution was interrupted or failed after branch creation.

Solutions:

Solution A: Manually Checkout

# List branches
git branch

# Checkout the new branch
git checkout feat/003-user-authentication

Solution B: Verify Current Branch

# Check current branch
git branch --show-current

# Or
git status

Solution C: Recreate with Checkout

# Delete the branch
git branch -d feat/003-user-authentication

# Recreate
/create-branch add user authentication

---

Issue 12: Conflict with Remote Branch

Symptom:

fatal: A branch named 'feat/003-user-auth' already exists on remote.

Cause: Branch with same name exists on remote repository.

Solutions:

Solution A: Fetch and Check

# Fetch remote branches
git fetch origin

# List remote branches
git branch -r

# If branch exists remotely, checkout instead
git checkout feat/003-user-auth

Solution B: Use Different Description

# Create with different keywords
/create-branch add user authentication system
→ feat/004-user-authentication-system

Solution C: Delete Remote Branch (If You Own It)

# Delete remote branch
git push origin --delete feat/003-user-auth

# Recreate locally
/create-branch add user authentication

---

Quick Reference

Error Messages

Verification Commands

# Check current branch
git branch --show-current

# List all branches
git branch -a

# Check skill files
ls -la plugins/git/skills/creating-branch/

# Verify git repository
git status

# Check for SDLC-develop specs
cat .arkhe.yaml
ls -la arkhe/specs/

Debugging

Enable Verbose Output:

# Run script directly with bash -x for debugging
bash -x /create-branch "add user auth"

Check Script Execution:

# Verify script runs
bash /create-branch --help

---

Getting Help

If issues persist:

1. Verify Installation:

   /plugin list
   # Ensure git@arkhe-claude-plugins is installed

2. Reinstall Plugin:

   /plugin uninstall git@arkhe-claude-plugins
   /plugin install git@arkhe-claude-plugins

3. Check Git Status:

   git status
   git branch -a

---

Prevention Tips

1. Use Clear Descriptions: Specific, descriptive branch names prevent confusion 2. Check Existing Branches: Run git branch before creating new branches 3. Keep Branch Names Short: Let the script handle keyword extraction 4. Use Conventional Keywords: Stick to recognized type keywords 5. Delete Merged Branches: Clean up after merging to prevent clutter 6. Fetch Regularly: Stay synced with remote branches

---

Last Updated: 2025-10-27

Git Branch Creation: Detailed Workflow

This document provides a detailed step-by-step breakdown of the branch creation process.

Overview

The branch creation process follows 6 main steps:

1. Determine Mode - Check for description, specs, or auto-generate 1b. Spec Selection - (Mode 3 only) Present available specs for selection 2. Parse Description - Extract user's task description 3. Detect Commit Type - Identify branch type from keywords 4. Extract Keywords - Filter meaningful words from description 5. Find Next Number - Auto-increment sequential number 6. Create Branch - Generate name and create git branch

---

Step 1: Determine Operation Mode

Check arguments and environment to determine mode:

# Check for arguments
if [ -n "$DESCRIPTION" ]; then
    MODE="manual"
    # Proceed to Step 2 (parse description)
else
    # Check for sdlc-develop integration
    if [ -f ".arkhe.yaml" ]; then
        SPECS_DIR=$(grep 'specs_dir:' .arkhe.yaml | awk '{print $2}')
        SPECS_DIR=${SPECS_DIR:-arkhe/specs}

        # Find existing spec directories
        SPECS=$(find "$SPECS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort)

        if [ -n "$SPECS" ]; then
            MODE="spec-select"
            # Proceed to Step 1b (spec selection)
        else
            MODE="auto-generate"
            # Proceed to auto-generate from changes
        fi
    else
        MODE="auto-generate"
        # Proceed to auto-generate from changes
    fi
fi

---

Step 1b: Spec Selection (Mode 3 Only)

Present available specs for selection:

Use AskUserQuestion with options:

• Each spec directory as an option (e.g., "01-user-auth", "02-dashboard")
• "None - auto-generate from changes" as final option

If user selects a spec:

• Extract spec name (e.g., "01-user-auth")
• Detect type from spec name or default to "feat"
• Skip to Step 5 (branch name is {type}/{spec-name})

If user selects "None":

• Set MODE="auto-generate"
• Proceed to auto-generate from changes

---

Step 2: Parse Description

Extract and normalize the user's task description.

Input: Raw description from user command

/create-branch add user authentication system

Process: 1. Remove command prefix (/create-branch) 2. Trim whitespace 3. Convert to lowercase 4. Store as working description

Output: "add user authentication system"

---

Step 3: Detect Commit Type

Analyze description keywords to determine branch type.

Detection Logic:

The script scans for specific keywords in the description:

Algorithm: 1. Split description into words 2. Check each word against keyword lists 3. Return first matching type 4. Default to feat if no match

Examples:

• "add user auth" → feat (keyword: "add")
• "fix login bug" → fix (keyword: "fix")
• "refactor auth service" → refactor (keyword: "refactor")
• "remove old code" → chore (keyword: "remove")
• "document api" → docs (keyword: "document")

Output: Commit type string (e.g., feat)

---

Step 4: Extract Keywords

Filter meaningful words from description for branch name.

Filtering Process:

Remove common words (stopwords):

• Articles: the, a, an
• Prepositions: for, to, in, on, at, by, with, from
• Conjunctions: and, or, but
• Pronouns: this, that, these, those
• Commit type keywords: add, fix, create, etc.

Extract meaningful words: 1. Split description into words 2. Remove stopwords 3. Keep first 2-3 meaningful words 4. Convert to lowercase 5. Replace spaces with hyphens

Examples:

Input: "add user authentication system"

• Remove: "add" (commit type keyword)
• Keep: "user", "authentication", "system"
• Limit: "user", "authentication" (first 2 words)
• Output: user-authentication

Input: "fix null pointer exception in login service"

• Remove: "fix", "in" (stopwords)
• Keep: "null", "pointer", "exception", "login", "service"
• Limit: "null", "pointer" (first 2 words)
• Output: null-pointer

Input: "refactor the authentication service module"

• Remove: "refactor", "the" (stopwords)
• Keep: "authentication", "service", "module"
• Limit: "authentication", "service" (first 2 words)
• Output: authentication-service

Output: Hyphenated keyword string

---

Step 5: Find Next Number

Determine the next sequential branch number.

Process:

1. Scan existing branches:

   git branch --list

2. Extract numbers from branches matching pattern:

   feat/001-user-auth
   feat/002-dashboard
   fix/003-login-bug

Extract: [001, 002, 003]

3. Find maximum:

   Max = 003

4. Increment:

   Next = 004

5. Format as 3-digit:

   "004"

Edge Cases:

• No existing branches: Start with 001
• Non-sequential numbers: Find max and increment (e.g., 001, 005 → next is 006)
• Different types: Numbers are global across all types

Output: 3-digit number string (e.g., "004")

---

Step 6: Create Branch

Generate branch name and execute git command.

Branch Name Assembly:

{type}/{number}-{keywords}

Example Construction:

• Type: feat
• Number: 004
• Keywords: user-authentication
• Branch: feat/004-user-authentication

Git Operations:

1. Create branch:

   git checkout -b feat/004-user-authentication

2. Verify creation:

   git branch --show-current

Output:

• Success message with branch name
• If spec-select mode: shows linked spec directory
• Current branch confirmation

---

Complete Example

User Command:

/create-branch add user authentication system

Step-by-Step Execution:

1. Determine Mode: Manual (description provided)

2. Parse: "add user authentication system"

3. Detect Type:

• Found keyword: "add"
• Type: feat

4. Extract Keywords:

• Remove: "add"
• Keep: "user", "authentication", "system"
• Limit: "user", "authentication"
• Result: user-authentication

5. Find Number:

• Scan: feat/001-profile, feat/002-dashboard
• Max: 002
• Next: 003
• Result: 003

6. Create Branch:

• Assemble: feat/003-user-authentication
• Execute: git checkout -b feat/003-user-authentication
• Confirm: Branch created successfully

Final Output:

✅ Created branch: feat/003-user-authentication

---

Configuration Options

Environment Variables

BRANCH_PREFIX (optional):

export BRANCH_PREFIX="myteam-"

Adds prefix to all branch names: myteam-feat/001-user-auth

SDLC-Develop Configuration

When .arkhe.yaml exists, the skill reads:

develop:
  specs_dir: arkhe/specs  # Default if not specified

The skill scans this directory for existing spec directories to offer as branch name options.

---

Integration with Git Workflow

Typical Development Flow

1. Start new task:

   /create-branch add payment integration
   → feat/015-payment-integration

2. Make changes and commit:

   git add .
   git commit -m "feat: implement payment gateway"

3. Push to remote:

   git push -u origin feat/015-payment-integration

4. Create pull request (use /create-pr skill)

Branch Naming Consistency

The branch names align with conventional commits:

• Branch: feat/001-user-auth
• Commits: feat: add user authentication
• PR title: feat: user authentication

---

Advanced Use Cases

Custom Branch Types

While the script supports 5 default types, you can manually create branches with custom types:

git checkout -b perf/001-optimize-queries
git checkout -b test/002-add-unit-tests
git checkout -b ci/003-github-actions

Sequential Numbering Across Types

Numbers increment globally, not per-type:

feat/001-user-auth
fix/002-login-bug
feat/003-dashboard
refactor/004-auth-service

This ensures unique identifiers across the entire project.

SDLC-Develop Integration

When .arkhe.yaml exists and contains specs:

arkhe/specs/
├── 01-user-auth/
│   ├── spec.md
│   └── plan.md
├── 02-dashboard/
│   └── spec.md
└── 03-payment/
    ├── spec.md
    └── plan.md

Running /create-branch without arguments will offer spec selection:

Select a feature spec for this branch:
- 01-user-auth
- 02-dashboard
- 03-payment
- None (auto-generate from changes)

Selected spec becomes the branch name: feat/01-user-auth

---

Best Practices

1. Descriptive Names: Use clear, descriptive task descriptions

• ✅ Good: /create-branch add user authentication with OAuth
• ❌ Poor: /create-branch new feature

2. Consistent Keywords: Use conventional commit keywords

• Use "add" or "create" for new features
• Use "fix" for bug fixes
• Use "refactor" for code improvements

3. Keep Names Short: The script automatically limits to 2-3 keywords

• Input: "add comprehensive user authentication system with OAuth2"
• Output: feat/001-user-authentication (first 2 meaningful words)

4. Review Generated Name: Check the generated branch name before committing

• The script shows the branch name before creating it
• Adjust description if needed

5. Use SDLC-Develop Integration: For complex features, use /develop first

• Creates structured specs in arkhe/specs/
• /create-branch will detect and offer spec selection

---

Summary

The branch creation workflow automates: 1. ✅ Type detection from natural language 2. ✅ Keyword extraction with stopword filtering 3. ✅ Sequential numbering across all branches 4. ✅ Short, readable branch names 5. ✅ SDLC-develop spec detection and selection

Result: Consistent, discoverable branch names that align with conventional commits and modern git workflows.

---

Last Updated: 2025-10-27