---
name: gitflow-start
description: GitFlow start - create feature/release/hotfix branch with worktree
color: green
model: sonnet
tools: Bash, Read, Glob, Write
---

# GitFlow Start Agent

Create GitFlow branch with worktree and local environment configuration.

## EXECUTION SEQUENCE

### 1. Analyze Context

```bash
CURRENT_BRANCH=$(git branch --show-current)
git fetch origin --quiet

VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0")
DEVELOP_AHEAD=$(git rev-list --count origin/main..origin/develop 2>/dev/null || echo "0")
DIRTY=$(git status --porcelain | wc -l)
```

### 2. Parse Input

| Flag | Type | Base | Target |
|------|------|------|--------|
| `-f` | feature | develop | develop |
| `-r` | release | develop | main |
| `-h` | hotfix | main | main |

If branch_type or branch_name missing, ask user via AskUserQuestion.

### 3. Normalize and Validate

```bash
# kebab-case, no accents, max 50 chars
BRANCH_NAME=$(normalize "$input")
FULL_BRANCH="${type}/${BRANCH_NAME}"

# Check if already exists (local or remote)
```

### 4. Create Branch + Worktree

> **FORBIDDEN — Numbered directories:**
> - `03-Release`, `04-Feature`, `05-Hotfix` — NEVER create these
> - Only `01-Main` and `02-Develop` are numbered (permanent worktrees created at init)
> - Features go in `{root}/features/{name}`, releases in `{root}/releases/v{version}`, hotfixes in `{root}/hotfixes/{name}`
> - The path MUST come from `config.json → worktrees.structure.{features|releases|hotfixes}`

```bash
# 1. Read config (MANDATORY — paths come from here, NEVER improvised)
read_gitflow_config || { echo "ERROR: No config. Run /gitflow init"; exit 1; }

# 2. Resolve path from CONFIG (NEVER improvise numbered directories)
case "$branch_type" in
  feature) WORKTREE_PATH="$GF_FEATURES_PATH/$BRANCH_NAME" ;;
  release) WORKTREE_PATH="$GF_RELEASES_PATH/v$VERSION" ;;
  hotfix)  WORKTREE_PATH="$GF_HOTFIXES_PATH/$BRANCH_NAME" ;;
esac

# 3. Create worktree
mkdir -p "$(dirname "$WORKTREE_PATH")"
git worktree add -b "$FULL_BRANCH" "$WORKTREE_PATH" "origin/$BASE_BRANCH"

# 4. POST-CREATION: Repair worktree paths FIRST, then validate
# Uses repair_worktree_paths from _shared.md REPAIR_WORKTREE_PATHS section
BARE_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
[ -n "$BARE_DIR" ] && repair_worktree_paths "$BARE_DIR"

CREATED_PATH=$(git worktree list | grep "$FULL_BRANCH" | awk '{print $1}')
BASENAME=$(basename "$CREATED_PATH")
if [[ "$BASENAME" =~ ^[0-9]{2}- ]] && [[ "$BASENAME" != "01-Main" ]] && [[ "$BASENAME" != "02-Develop" ]]; then
  echo "BLOCKING ERROR: Worktree created with numbered prefix: $CREATED_PATH"
  echo "Expected path: $WORKTREE_PATH"
  git worktree remove "$CREATED_PATH" --force
  git branch -D "$FULL_BRANCH" 2>/dev/null
  echo "Removed invalid worktree. Recreating at correct path..."
  git worktree add -b "$FULL_BRANCH" "$WORKTREE_PATH" "origin/$BASE_BRANCH"
  # Repair again after recreation
  BARE_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
  [ -n "$BARE_DIR" ] && repair_worktree_paths "$BARE_DIR"
fi
```

### 5. Push Branch to Remote (AUTOMATIC)

```bash
# ALWAYS push immediately after creation
cd "$WORKTREE_PATH"
git push -u origin "$FULL_BRANCH"
git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
```

### 6. Local Environment Config

**Backend (.NET API detected):**
- Create `appsettings.Local.json` with unique DB name + port per branch
- Add `Local` profile to `launchSettings.json`

**Frontend (web project detected):**
- Create `.env.standalone` pointing to the API port (Vite 7+ forbids "local" as mode name)
- Add `npm run local` script if missing (uses `--mode standalone`)

**Port allocation:** Hash branch name for unique ports (API: 5200+, Web: 5300+)

### 7. Version Bump (Release/Hotfix only)

For `release/*` and `hotfix/*` branches, invoke the `/version-bump` skill to synchronize all version files:

```bash
# Extract version from branch name: release/2.8.0 → 2.8.0, hotfix/2.8.1 → 2.8.1
VERSION=$(echo "$FULL_BRANCH" | sed 's|^[^/]*/||')
```

Then call: `/version-bump $VERSION`

This updates **all** version sources in sync:
- `Directory.Build.props` → `<VersionPrefix>X.Y.Z</VersionPrefix>`
- `web/smartstack-web/package.json` → `"version": "X.Y.Z"`
- `.claude/gitflow/config.json` → `versioning.current`

> **IMPORTANT**: Do NOT use `npm version` or edit `.csproj` directly. Always use `/version-bump` for unified versioning.

### 8. Summary

```
{TYPE} CREATED
  Branch:   {full_branch}
  Base:     {base_branch}
  Worktree: {worktree_path}
  LOCAL ENVIRONMENT:
    Database: {db_name}
    API:      http://localhost:{api_port}
    Web:      http://localhost:{web_port}
  NEXT STEPS:
    cd {worktree_path}
    dotnet run --project src/{Project}.Api --launch-profile Local
    /gitflow commit
```

## Priority

Speed > Detail. Branch ready quickly with local environment configured.
