---
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.

**This step runs INLINE in the main conversation. All AskUserQuestion calls
happen here (NOT in a sub-agent). Only clone/validate are delegated.**

---

## EXECUTION SEQUENCE:

### 1. Detect Environment (delegate to sub-agent)

Spawn `Task(gitflow-init-detect)` (haiku) to detect platform, git state, workspace siblings, provider.
Parse the report to extract: PLATFORM, SHELL_TYPE, DETECTED_URL, DETECTED_NAME, GIT_PROVIDER, SIBLING_COUNT.

### 2. Check Existing Configuration

If `.claude/gitflow/config.json` exists, ask user: Reconfigure / Repair / View / Cancel.
If Cancel or View → EXIT. If Repair → delegate to `Task(gitflow-init-validate)` → EXIT.

### 3. Question: Repository URL

If URL was provided in command args (starts with `https://` or `git@`), use it directly → skip to step 4.

Otherwise, call AskUserQuestion:
- header: "Repository"
- question: "Repository URL? (detected: {DETECTED_URL})"
- options: Use detected URL (Recommended) / Enter GitHub URL / Enter Azure DevOps URL / Local only
- If user selects custom option → ask follow-up for actual URL

Store as `{REPO_URL}`.

### 4. Question: Root Folder

Call AskUserQuestion:
- header: "Location"
- question: "Root folder for this project? (worktrees will be created here)"
- options:
  - "Use parent folder (Recommended)" — "{PARENT_DIR}/ - consistent with {SIBLING_COUNT} sibling project(s)"
  - "Use current folder" — "{CURRENT_DIR}/"
  - "Custom path" — "Specify a different location"
- If user selects "Custom path" → ask follow-up for actual path

Store as `{PROJECT_BASE}`. Normalize for platform (WSL: /mnt/ format, Windows: forward slashes).

### 5. Question: Project Name

Call AskUserQuestion:
- header: "Project"
- question: "Project name? (detected: {DETECTED_NAME})"
- options:
  - "Use detected name (Recommended)" — "{DETECTED_NAME}"
  - "Custom name" — "Specify a different project name"
- If user selects "Custom name" → ask follow-up for actual name

Store as `{PROJECT_NAME}`.

Then normalize into variants: PascalCase.Dot, PascalCase, kebab-case, snake_case, Display Name.
See [references/init-name-normalization.md](../references/init-name-normalization.md).

### 5b. Compute Final Project Path

After collecting both root folder and project name, ensure `{PROJECT_BASE}` points to the project-specific directory:

- If `basename({PROJECT_BASE})` already equals `{PROJECT_NAME}` → keep as-is (existing repo case)
- Otherwise → set `{PROJECT_BASE} = {PROJECT_BASE}/{PROJECT_NAME}` (fresh project case)

> **Example:** Root `D:/01 - projets/` + name `MyApp` → `PROJECT_BASE = D:/01 - projets/MyApp/`
> **Example:** Root `D:/01 - projets/MyApp/` + name `MyApp` → stays `D:/01 - projets/MyApp/` (no double nesting)

### 6. Question: Worktree Mode

Call AskUserQuestion:
- header: "Worktrees"
- question: "How should worktrees be organized?"
- options:
  - "Organized (Recommended)" — "Numbered folders: 01-Main/, 02-Develop/, features/, releases/, hotfixes/"
  - "Simple" — "Plain folders: main/, develop/, features/, releases/, hotfixes/"
  - "Disabled" — "No worktrees, use git checkout (not recommended)"

Store as `{WORKTREE_MODE}` ("organized", "simple", or "disabled").

### 7. Confirm all values

Display a summary to the user before proceeding:
```
Ready to initialize:
  URL:      {REPO_URL}
  Folder:   {PROJECT_BASE}
  Name:     {PROJECT_NAME}
  Mode:     {WORKTREE_MODE}
```

### 8. Create Directory Structure (delegate to sub-agent)

**Skip if `{WORKTREE_MODE}` is "disabled".**

Spawn `Task(gitflow-init-clone)` (sonnet) with the user-confirmed values:
- REPO_URL, PROJECT_BASE, PROJECT_NAME, WORKTREE_MODE, PLATFORM

See [references/init-structure-creation.md](../references/init-structure-creation.md) for details.

### 9. Detect Version + Create Configuration

Detect version (csproj > package.json > tags > fallback `0.0.0`).
Write `.claude/gitflow/config.json` in develop worktree.
See [references/init-config-template.md](../references/init-config-template.md) for template.
Store paths as `D:/path/to/folder` format.

### 10. Post-Init Validation (delegate to sub-agent)

Spawn `Task(gitflow-init-validate)` (haiku) to verify structure.
Checks: .bare/HEAD, worktree branches, directories, config file.

### 10b. SmartStack Project Initialization (conditional)

**Skip if `--smartstack` flag was NOT provided.**

After git structure is ready, initialize the SmartStack project in the develop worktree:

1. Navigate to the develop worktree: `{DEVELOP_WORKTREE_PATH}`
2. Run `smartstack init {PROJECT_NAME} --here`
   - `--here` flag initializes in the current directory (no subdirectory creation)
   - This creates: .NET solution, frontend project, .smartstack/config.json
3. Run `smartstack install --local`
   - Deploys skills, agents, hooks to `.claude/` in the project
4. If init fails, display error but do NOT fail the entire gitflow init
   - The git structure is still valid and usable

### 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 SMARTSTACK_INIT}
║  SmartStack: Initialized (backend + frontend)  ✅                ║
╠══════════════════════════════════════════════════════════════════╣
{endif}
{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
- [ ] Worktree mode confirmed by user (organized / simple / disabled)
- [ ] .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:

- ✅ AskUserQuestion called for root folder, project name, AND worktree mode
- ✅ 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
