---
name: step-start
description: Create new branch with worktree
next_step: null
---

# Step: START - Create Branch

## YOUR TASK:

Create a new feature/release/hotfix branch with optional worktree setup.

**ULTRA THINK about branch naming and base selection.**

---

## INPUT PARSING:

```
{branch_type} = feature | release | hotfix
{branch_name} = normalized name (kebab-case)
{no_worktree} = --no-worktree flag present
```

**From flags:**
- `-f {name}` → branch_type=feature, branch_name={name}
- `-r {name}` → branch_type=release, branch_name={name}
- `-h {name}` → branch_type=hotfix, branch_name={name}

---

## EXECUTION SEQUENCE:

### 1. Load Config and Analyze Context

Load GitFlow config. Display current branch, version, tag, and dirty status.

### 2. Interactive Questions (if no args)

Ask for branch type (feature/release/hotfix) and name if not provided via args. Display suggested next version for releases.

### 3. Normalize and Validate

See [references/start-branch-normalization.md](../references/start-branch-normalization.md) for:
- Branch name normalization (kebab-case)
- Branch existence validation

### 4. Determine Base Branch

| Type | Base | Target |
|------|------|--------|
| feature | develop | develop |
| release | develop | main |
| hotfix | main | main |

### 5. Handle Dirty Working Directory

Offer user to stash, commit, or continue if working directory has changes.

### 5b. EF Core Migration Pre-flight (Release/Hotfix only)

**BLOCKING CHECK: Validate migration naming conventions BEFORE creating the release branch.**

See [references/start-efcore-preflight.md](../references/start-efcore-preflight.md) for the full validation script and user choice handling.

Expected format: `{context}_v{version}_{sequence}_{Description}` (e.g., `core_v2.0.0_001_InitialSchema`)

---

### 6. Create Branch and Worktree

See [references/start-worktree-creation.md](../references/start-worktree-creation.md) for:
- Worktree path selection (organized mode)
- Numbering rules (only 01-Main/02-Develop, no numbered feature/release/hotfix)
- Cross-platform path repair
- Worktree validation
- No-worktree mode fallback

### 6b. Push Branch to Remote (AUTOMATIC)

**ALWAYS push immediately after branch creation:**
```bash
git push -u origin "$FULL_BRANCH"

# CRITICAL: Verify push and update tracking refs
git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
LOCAL_SHA=$(git rev-parse HEAD)
REMOTE_SHA=$(git rev-parse origin/$FULL_BRANCH)
if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
  echo "✅ Branch pushed and verified - origin/$FULL_BRANCH in sync"
else
  echo "⚠️ Push verification failed"
  echo "  Local:  $LOCAL_SHA"
  echo "  Remote: $REMOTE_SHA"
fi
```

### 7. Create Local Environment Config (Backend + Frontend)

See [references/start-local-config.md](../references/start-local-config.md) for the full configuration:
- **Port generation:** Unique ports per branch (API: 5200+, Web: 5300+) based on branch name hash
- **7a. Backend:** `appsettings.Local.json` (DB connection, SmartStack config, Kestrel port)
- **7b. Frontend:** `.env.standalone` + `npm run local` script (Vite mode=standalone, not "local" which conflicts with .env.local in Vite 7+)
- **7c. Backend:** `launchSettings.json` Local profile with unique port
- **7d. Summary:** Display configured DB name, API port, Web port

### 8. Store State

```bash
# Save to state for next steps
{
  "branch_type": "{branch_type}",
  "branch_name": "{FULL_BRANCH}",
  "base_branch": "{BASE_BRANCH}",
  "target_branch": "{TARGET}",
  "worktree_path": "{WORKTREE_PATH}",
  "version_current": "{VERSION}",
  "local_config": {
    "database": "{DB_NAME}",
    "api_port": "{API_PORT}",
    "web_port": "{WEB_PORT}",
    "api_dir": "{API_DIR}",
    "web_dir": "{WEB_DIR}"
  }
}
```

### 9. Summary

```
╔══════════════════════════════════════════════════════════════════╗
║                    {BRANCH_TYPE} CREATED                          ║
╠══════════════════════════════════════════════════════════════════╣
║  Branch:   {FULL_BRANCH}                                          ║
║  Base:     {BASE_BRANCH}                                          ║
║  Target:   {TARGET}                                               ║
║  Worktree: {WORKTREE_PATH}                                        ║
╠══════════════════════════════════════════════════════════════════╣
║  LOCAL ENVIRONMENT:                                               ║
║  Database: {DB_NAME}                                              ║
║  API:      http://localhost:{API_PORT}                            ║
║  Web:      http://localhost:{WEB_PORT}                            ║
╠══════════════════════════════════════════════════════════════════╣
║  NEXT STEPS:                                                      ║
║                                                                    ║
║  1. Go to worktree:                                               ║
║     cd {WORKTREE_PATH}                                            ║
║                                                                    ║
║  2. Start backend (auto-migrates Core + Extensions DB):           ║
║     dotnet run --project src/{Project}.Api --launch-profile Local ║
║                                                                    ║
║  3. Reset admin password:                                         ║
║     ss admin reset                                                ║
║                                                                    ║
║  4. Start frontend (other terminal):                              ║
║     cd web/{project}-web && npm run local                         ║
║                                                                    ║
║  5. Make changes and commit:                                      ║
║     /gitflow commit                                               ║
║                                                                    ║
║  6. Create pull request:                                          ║
║     /gitflow pr                                                   ║
║                                                                    ║
║  7. After PR merged, finalize:                                    ║
║     /gitflow finish                                               ║
╚══════════════════════════════════════════════════════════════════╝
```

---

## ERROR HANDLING:

| Error | Solution |
|-------|----------|
| Branch exists | Offer: rename, checkout, or delete |
| Dirty working directory | Offer: stash, commit, or continue |
| Worktree path exists | Remove orphan or use different path |
| Base branch behind remote | Pull before creating |

---

## SUCCESS CRITERIA:

- Branch created from correct base
- **Branch pushed to remote (AUTOMATIC)**
- Worktree set up (if enabled)
- Backend local config created: `appsettings.Local.json` (if .NET API detected)
- Backend launch profile created: `launchSettings.json` Local profile with unique port (if .NET API detected)
- Frontend local config created: `.env.standalone` + `npm run local` script (if web project detected)
- Ports synchronized between backend and frontend (unique per branch)
- State stored for subsequent steps

## NEXT STEP:

User works on code, then runs `/gitflow commit`.
