---
name: step-init
description: Initialize GitFlow configuration and branches
next_step: null
---

# Step: INIT - Initialize GitFlow

## YOUR TASK:

Set up GitFlow configuration with bare repository, worktrees, and branches.

**ULTRA THINK before creating configuration.**

---

## MANDATORY QUESTIONS

**⛔ ALWAYS ask these 3 questions, even if values can be auto-detected.**
**⛔ ALWAYS detect workspace context (step 2) to show sibling projects.**

| Question | Variable | Auto-detect from |
|----------|----------|------------------|
| Repository URL | `{REPO_URL}` | `git remote get-url origin` |
| Root folder | `{ROOT_FOLDER}` | Parent of current directory |
| Project name | `{PROJECT_NAME}` | Repo name from URL or folder |

**Multi-project principle:** Each repository has its OWN independent GitFlow config. Step 2 scans for sibling projects to provide context, not to share configuration.

**⛔ FOLLOW-UP RULE:** When a user selects a "Custom..." option (custom name, custom path, custom URL), that selection is just a CHOICE, not the actual value. You MUST immediately ask a follow-up question to capture the actual value. Never proceed with a blank or default value.

---

## EXECUTION SEQUENCE:

### 1. Detect Environment (for defaults only)

See [references/init-environment-detection.md](../references/init-environment-detection.md) for:
- Platform detection (WSL/Windows/macOS/Linux)
- Git provider detection
- Auto-detect defaults (URL, folder, project name)

### 2. Detect Workspace (multi-project context)

See [references/init-workspace-detection.md](../references/init-workspace-detection.md) for:
- Sibling project scanning
- Workspace context display
- Per-repository GitFlow principle

### 3-7. MANDATORY User Questions

See [references/init-questions.md](../references/init-questions.md) for all 5 mandatory questions in order:
1. Handle existing configuration (if already initialized)
2. Repository URL with provider detection
3. Root folder for project structure
4. Project name confirmation
5. Worktree mode (organized/simple/disabled)

### 6b. Normalize Project Name (INTELLIGENT)

**⛔ ALWAYS normalize, even if user chose the detected name.**

See [references/init-name-normalization.md](../references/init-name-normalization.md) for the full 5-step process:
1. Parse input into words (split on separators + camelCase)
2. Language detection and spell check (ask user if typos found)
3. Generate all name variants (PascalCase.Dot, PascalCase, kebab-case, snake_case)
4. Ask user to choose PRIMARY format
5. Store all derived names in `PROJECT_VARIANTS`


### 8. Create Directory Structure

See [references/init-structure-creation.md](../references/init-structure-creation.md) for:
- Path normalization for WSL
- Complete directory structure creation with absolute paths
- Bare repository setup
- Worktree creation (organized and simple modes)
- GitFlow config directory creation

### 9. Create Configuration

**Write `.claude/gitflow/config.json` in develop worktree.**

See [references/init-config-template.md](../references/init-config-template.md) for:
- Full config.json v2.1.0 template (platform, workspace, repository, git, worktrees, versioning, efcore, workflow, language)
- Path storage convention (`normalize_path_for_storage()` format)

**⛔ IMPORTANT:** Store paths using Windows-style format (`D:/path/to/folder`). The `read_gitflow_config()` in `_shared.md` translates to platform format at read time.

### 10. Detect Version

See [references/init-version-detection.md](../references/init-version-detection.md) for:
- Version detection with priority (csproj, package.json, tags, etc.)
- Platform-agnostic path handling

### 10b. Post-Init Validation

**⛔ MANDATORY: Verify the structure was created correctly.**

See [references/init-config-template.md](../references/init-config-template.md) — Section "Post-Init Validation" for the full bash validation script.

Checks: .bare/HEAD, worktree branches (main/develop), features/releases/hotfixes dirs, .claude/gitflow/ dir.

### 11. Summary

```
╔══════════════════════════════════════════════════════════════════╗
║                    GITFLOW INITIALIZED                            ║
╠══════════════════════════════════════════════════════════════════╣
║  Project:    {PROJECT_NAME}                                       ║
║  Root:       {ROOT_FOLDER}                                        ║
║  Remote:     {REPO_URL}                                           ║
║  Provider:   {GIT_PROVIDER}                                       ║
║  Platform:   {GF_PLATFORM} ({GF_SHELL})                           ║
║  Version:    {VERSION}                                            ║
║  Config:     v2.1.0                                               ║
╠══════════════════════════════════════════════════════════════════╣
║  Structure:                                                        ║
║  ├── .bare/           (git bare repository)                       ║
║  ├── 01-Main/         (main branch)         ✅                    ║
║  ├── 02-Develop/      (develop branch)      ✅                    ║
║  ├── features/        (feature worktrees)   ✅                    ║
║  ├── releases/        (release worktrees)   ✅                    ║
║  └── hotfixes/        (hotfix worktrees)    ✅                    ║
╠══════════════════════════════════════════════════════════════════╣
║  Validation: {ERRORS == 0 ? "ALL CHECKS PASSED" : "errors"}      ║
╠══════════════════════════════════════════════════════════════════╣
{if SIBLING_PROJECTS not empty}
║  Workspace: {WORKSPACE_DIR}                                       ║
║  GitFlow projects: {#SIBLING_PROJECTS + 1} (including this one)   ║
╠══════════════════════════════════════════════════════════════════╣
{endif}
║  Config: 02-Develop/.claude/gitflow/config.json                   ║
╠══════════════════════════════════════════════════════════════════╣
║  NEXT: cd 02-Develop && /gitflow -f <feature-name>                ║
╚══════════════════════════════════════════════════════════════════╝
```

---

## VALIDATION CHECKLIST:

Before completing init, verify:

- [ ] Repository URL confirmed by user
- [ ] Root folder confirmed by user
- [ ] Project name confirmed by user
- [ ] .bare/ directory exists
- [ ] 01-Main/ worktree exists and is on main branch
- [ ] 02-Develop/ worktree exists and is on develop branch
- [ ] features/, releases/, hotfixes/ directories exist
- [ ] .claude/gitflow/config.json created in develop worktree

---

## ERROR HANDLING:

| Error | Solution |
|-------|----------|
| Clone fails | Check URL, network, credentials |
| Worktree exists | Skip or offer to recreate |
| Permission denied | Check folder permissions |
| Branch missing | Create from default branch |

---

## SUCCESS CRITERIA:

- ✅ All 3 mandatory questions asked
- ✅ Complete folder structure created
- ✅ Both main and develop worktrees functional
- ✅ Configuration file created
- ✅ User can navigate to 02-Develop and start working

## NEXT STEP:

Init is standalone. User should `cd 02-Develop` then run `/gitflow -f <feature-name>`.

---

## WORKSPACE MODE (`--workspace`)

When called with `init --workspace`, batch-initialize all repos in a workspace.

See [references/init-config-template.md](../references/init-config-template.md) — Section "Workspace Mode" for the full execution sequence:
1. Ask workspace directory
2. Detect or ask for repos
3. Create `.smartstack-workspace.json`
4. Loop Steps 1-10b per repo with workspace defaults
5. Display global summary
