---
description: Phase 1 - Initialize GitFlow structure with versioning and EF Core configuration
agent: gitflow-init
model: sonnet
---

# GitFlow Init

**Arguments:** `$ARGUMENTS`

---

## PREMIÈRE CHOSE À FAIRE

Regarde si `$ARGUMENTS` contient une URL (commence par `https://` ou `git@`).

**Si OUI (URL détectée)** → Tu DOIS suivre le workflow ci-dessous. NE SAUTE AUCUNE ÉTAPE.

**Si NON** → Va directement à la section "MODE B ou C" plus bas.

---

## WORKFLOW QUAND URL DÉTECTÉE

Tu as reçu une URL de repository. Avant de créer quoi que ce soit, tu DOIS poser 3 questions à l'utilisateur.

### ÉTAPE 1 : Extraire les informations de l'URL

Extrais le nom suggéré du projet depuis l'URL :
- `https://github.com/org/mon-projet.git` → nom suggéré = "mon-projet"
- `https://dev.azure.com/org/project/_git/repo` → nom suggéré = "repo"

**NE CRÉE AUCUN DOSSIER MAINTENANT.** Tu dois d'abord poser les questions.

---

### ÉTAPE 2 : DEMANDER OÙ CRÉER LE PROJET

**MAINTENANT, utilise le tool AskUserQuestion pour demander à l'utilisateur où créer le projet.**

Pose cette question avec ces options :
- Question : "Où voulez-vous créer ce projet ?"
- Header : "Location"
- Options :
  1. "C:/Dev" - Dossier de développement recommandé
  2. "Répertoire courant" - Créer ici (affiche le chemin actuel)
  3. "Chemin personnalisé" - Entrer un autre chemin

**ATTENDS LA RÉPONSE DE L'UTILISATEUR.**

Si l'utilisateur choisit "Chemin personnalisé", demande-lui de saisir le chemin.

Stocke le résultat dans `TARGET_FOLDER`.

---

### ÉTAPE 3 : DEMANDER LE NOM DU PROJET

**MAINTENANT, utilise le tool AskUserQuestion pour demander le nom du dossier projet.**

Pose cette question avec ces options :
- Question : "Quel nom pour le dossier du projet ? (Suggéré : {nom_extrait_de_url})"
- Header : "Name"
- Options :
  1. "{nom_extrait_de_url}" - Utiliser le nom de l'URL (Recommandé)
  2. "Nom personnalisé" - Entrer un autre nom

**ATTENDS LA RÉPONSE DE L'UTILISATEUR.**

Si l'utilisateur choisit "Nom personnalisé", demande-lui de saisir le nom.

Stocke le résultat dans `PROJECT_NAME`.

---

### ÉTAPE 4 : CONFIRMATION FINALE

**MAINTENANT, utilise le tool AskUserQuestion pour confirmer la création.**

Affiche un récapitulatif et demande confirmation :
- Question : "Créer le projet GitFlow avec ces paramètres ?\n\nProjet : {PROJECT_NAME}\nEmplacement : {TARGET_FOLDER}/\nChemin complet : {TARGET_FOLDER}/{PROJECT_NAME}/\nRepository : {URL}"
- Header : "Confirm"
- Options :
  1. "Oui, créer le projet" - Procéder à la création (Recommandé)
  2. "Modifier" - Revenir en arrière pour changer les paramètres

**ATTENDS LA RÉPONSE DE L'UTILISATEUR.**

Si l'utilisateur choisit "Modifier", retourne à l'ÉTAPE 2.

---

### ÉTAPE 5 : CRÉER LE PROJET (seulement après confirmation)

**SEULEMENT si l'utilisateur a confirmé "Oui, créer le projet" à l'étape 4**, tu peux maintenant :

1. Vérifier que l'URL est accessible
2. Vérifier que le dossier n'existe pas déjà
3. Créer la structure

Le chemin final est : `{TARGET_FOLDER}/{PROJECT_NAME}/`

---

### ÉTAPE 6 : Validation

Vérifie que :
1. L'URL du repository est accessible (test avec `git ls-remote`)
2. Le dossier `{TARGET_FOLDER}/{PROJECT_NAME}` n'existe pas déjà

Si un problème, informe l'utilisateur et arrête.

---

### ÉTAPE 7 : Créer la structure organisée

```bash
# Create project folder with organized structure
mkdir -p "$PROJECT_BASE"
cd "$PROJECT_BASE"

# Clone as bare repository (hidden)
git clone --bare "$REPO_URL" .bare
echo "gitdir: ./.bare" > .git

# Configure bare repo for worktrees
cd .bare
git config core.bare false
git config core.worktree ".."
cd ..

# Create organized worktree structure
mkdir -p features releases hotfixes

# Create permanent worktrees with numbered prefixes
git worktree add "01-Main" main
git worktree add "02-Develop" develop

# Initialize GitFlow config in 02-Develop (working directory)
cd "02-Develop"
mkdir -p .claude/gitflow/{plans,logs,migrations,backup,cache}
```

**Resulting structure:**
```
{target_folder}/{repo_name}/
├── .bare/                    # Hidden bare repository
├── .git                      # gitdir pointer to .bare
├── 01-Main/                  # Permanent worktree (main branch)
│   └── ...
├── 02-Develop/               # Permanent worktree (develop branch) ← WORKING DIR
│   ├── .claude/gitflow/
│   │   ├── config.json
│   │   ├── plans/
│   │   ├── logs/
│   │   └── migrations/
│   └── ...
├── features/                 # Feature worktrees go here
│   └── {feature-name}/
├── releases/                 # Release worktrees go here
│   └── v{version}/
└── hotfixes/                 # Hotfix worktrees go here
    └── {hotfix-name}/
```

### ÉTAPE 7.5 : Détection et Configuration Azure DevOps (Optionnel)

**Détecter si Azure CLI est installé:**

```bash
# Vérifier Azure CLI
AZ_CLI_INSTALLED=$(az --version 2>/dev/null | head -1)

# Vérifier l'extension azure-devops
AZ_DEVOPS_EXT=$(az extension show --name azure-devops 2>/dev/null | grep -o '"name": "azure-devops"')
```

**Si Azure CLI détecté, proposer la configuration:**

```javascript
if (AZ_CLI_INSTALLED) {
  AskUserQuestion({
    questions: [{
      question: "Azure CLI détecté. Voulez-vous configurer l'intégration Azure DevOps ?",
      header: "Azure DevOps",
      options: [
        { label: "Oui", description: "Configurer Azure DevOps pour PR, work items et boards (Recommandé si vous utilisez Azure DevOps)" },
        { label: "Non", description: "Ignorer pour l'instant (peut être configuré plus tard)" },
        { label: "Installer extension", description: "L'extension azure-devops n'est pas installée" }
      ],
      multiSelect: false
    }]
  })
}
```

**Si "Oui" sélectionné, demander les informations:**

```javascript
// Détecter l'organisation depuis le remote URL si Azure DevOps
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
// https://dev.azure.com/myorg/myproject/_git/myrepo → org=myorg, project=myproject

AskUserQuestion({
  questions: [
    {
      question: "Quelle est votre organisation Azure DevOps ?",
      header: "Organisation",
      options: [
        { label: "${DETECTED_ORG}", description: "Détecté depuis l'URL remote (Recommandé)" },
        { label: "Autre", description: "Entrer une autre organisation" }
      ],
      multiSelect: false
    },
    {
      question: "Quel est le nom de votre projet Azure DevOps ?",
      header: "Projet",
      options: [
        { label: "${DETECTED_PROJECT}", description: "Détecté depuis l'URL remote (Recommandé)" },
        { label: "Autre", description: "Entrer un autre projet" }
      ],
      multiSelect: false
    }
  ]
})
```

**Configurer Azure CLI defaults:**

```bash
# Configurer les defaults Azure DevOps
az devops configure --defaults organization="$AZ_ORG" project="$AZ_PROJECT"

# Vérifier la connexion
az devops project show --project "$AZ_PROJECT" > /dev/null 2>&1 || {
  echo "⚠️  Impossible de se connecter à Azure DevOps."
  echo "   Exécutez 'az login' pour vous authentifier."
}
```

**Si Azure CLI non installé, afficher les instructions:**

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  ℹ️  AZURE DEVOPS CLI NON DÉTECTÉ                                             │
├──────────────────────────────────────────────────────────────────────────────┤
│  Pour activer l'intégration Azure DevOps (PR, work items, boards):           │
│                                                                              │
│  1. Installer Azure CLI:                                                     │
│     winget install Microsoft.AzureCLI                                        │
│                                                                              │
│  2. Installer l'extension:                                                   │
│     az extension add --name azure-devops                                     │
│                                                                              │
│  3. Se connecter:                                                            │
│     az login                                                                 │
│                                                                              │
│  4. Reconfigurer GitFlow:                                                    │
│     /gitflow:1-init --migrate                                                │
│                                                                              │
│  Documentation: https://learn.microsoft.com/cli/azure/boards                 │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

### ÉTAPE 8 : Configuration

```json
{
  "version": "1.4.0",
  "initMode": "clone",
  "repository": {
    "name": "{repo_name}",
    "remoteUrl": "{REPO_URL}",
    "defaultBranch": "main"
  },
  "worktrees": {
    "enabled": true,
    "mode": "organized",
    "basePath": "..",
    "bareRepo": "../.bare",
    "permanent": {
      "main": { "path": "../01-Main", "prefix": "01" },
      "develop": { "path": "../02-Develop", "prefix": "02" }
    },
    "structure": {
      "features": "../features/",
      "releases": "../releases/",
      "hotfixes": "../hotfixes/"
    },
    "cleanupOnFinish": true
  }
}
```

### ÉTAPE 9 : Afficher le résumé

```
================================================================================
                    GITFLOW INITIALIZED (Clone Mode)
================================================================================

REPOSITORY
  Name:   {repo_name}
  Remote: {REPO_URL}

STRUCTURE CREATED
  {PROJECT_BASE}/
  ├── 01-Main/        ← main branch
  ├── 02-Develop/     ← develop branch (current directory)
  ├── features/       ← feature worktrees
  ├── releases/       ← release worktrees
  └── hotfixes/       ← hotfix worktrees

WORKING DIRECTORY
  {PROJECT_BASE}/02-Develop

NEXT STEPS
  1. cd "{PROJECT_BASE}/02-Develop"
  2. code .   (or your preferred IDE)
  3. /gitflow:10-start feature {name}

================================================================================
```

---

## MODE C: Interactive (No Repo Detected)

**Trigger:** Current directory is NOT a git repository AND no URL provided in arguments

This mode guides the user through setting up a new GitFlow project interactively.

**Critical Flow Order:**
```
C.1 Target Directory (WHERE?) → C.2 Repository URL → C.3 Project Name (WHAT?) → C.4 Confirmation → C.5 Execute
```

### C.1 Ask for Target Directory (FIRST - Critical)

**IMPORTANT:** Ask WHERE to create the project BEFORE asking for repository details.

```javascript
AskUserQuestion({
  questions: [{
    question: "Where do you want to create your GitFlow project?",
    header: "Location",
    options: [
      { label: "Current directory", description: `Create in: ${process.cwd()} (Recommended)` },
      { label: "C:/Dev", description: "Common development folder (Windows)" },
      { label: "~/projects", description: "Common development folder (Unix)" },
      { label: "Custom path", description: "Enter a different location" }
    ],
    multiSelect: false
  }]
})
```

**If "Custom path" selected:**
```
Enter the target parent folder (project will be created inside):
> Example: C:/Projects or /home/user/dev
```

**Validate path exists:**
```bash
# Expand ~ if present
TARGET_PATH="${TARGET_PATH/#\~/$HOME}"

# Check directory exists
if [ ! -d "$TARGET_PATH" ]; then
  echo "WARNING: Directory does not exist: $TARGET_PATH"
  # Ask: Create it? or Choose different path?
  AskUserQuestion({
    questions: [{
      question: "Directory '$TARGET_PATH' does not exist. Create it?",
      header: "Create Dir",
      options: [
        { label: "Yes, create it", description: "Create the directory and continue (Recommended)" },
        { label: "Choose different path", description: "Enter another location" }
      ],
      multiSelect: false
    }]
  })
fi

# Check write permissions
if [ ! -w "$TARGET_PATH" ]; then
  echo "ERROR: No write permission to: $TARGET_PATH"
  # Ask again
fi
```

### C.2 Ask for Repository URL

```javascript
AskUserQuestion({
  questions: [{
    question: "What repository do you want to clone?",
    header: "Repository",
    options: [
      { label: "GitHub", description: "https://github.com/org/repo.git" },
      { label: "GitLab", description: "https://gitlab.com/org/repo.git" },
      { label: "Azure DevOps", description: "https://dev.azure.com/org/project/_git/repo" },
      { label: "Other", description: "Any git remote URL (SSH or HTTPS)" }
    ],
    multiSelect: false
  }]
})
```

**Then prompt for the actual URL:**
```
Enter the repository URL:
> Example: https://github.com/organization/my-project.git
```

**Validate URL is accessible:**
```bash
git ls-remote "$REPO_URL" HEAD > /dev/null 2>&1 || {
  echo "ERROR: Cannot access repository: $REPO_URL"
  echo "Please verify:"
  echo "  - URL is correct"
  echo "  - You have access permissions"
  echo "  - Network connectivity"
  # Ask again
}
```

### C.3 Ask for Project Name (EXPLICIT - Critical)

**IMPORTANT:** This is a CRITICAL step. Ask EXPLICITLY for the project name, don't just confirm.

Extract suggestion from URL:
```bash
# Extract repo name from various URL formats
# https://github.com/org/my-project.git → my-project
# git@github.com:org/my-project.git → my-project
# https://dev.azure.com/org/project/_git/repo → repo

SUGGESTED_NAME=$(basename "$REPO_URL" .git)
```

**Ask user EXPLICITLY for project name:**

```javascript
AskUserQuestion({
  questions: [{
    question: "What should we name this project folder?",
    header: "Project Name",  // Critical: explicit header
    options: [
      { label: "${SUGGESTED_NAME}", description: `Use repository name: "${SUGGESTED_NAME}" (Recommended)` },
      { label: "Custom name", description: "Enter a different folder name" }
    ],
    multiSelect: false
  }]
})
```

**If "Custom name" selected:**
```
Enter the project folder name:
>
```

**Strict validation:**
```bash
# 1. Not empty
if [ -z "$PROJECT_NAME" ]; then
  echo "ERROR: Project name cannot be empty"
  # Ask again
fi

# 2. Valid characters only
if [[ ! "$PROJECT_NAME" =~ ^[a-zA-Z0-9._-]+$ ]]; then
  echo "ERROR: Invalid characters in project name"
  echo "Allowed: letters, numbers, dots (.), underscores (_), hyphens (-)"
  echo "Not allowed: spaces, special characters"
  # Ask again
fi

# 3. Doesn't already exist in target location
FULL_PROJECT_PATH="$TARGET_PATH/$PROJECT_NAME"
if [ -d "$FULL_PROJECT_PATH" ]; then
  echo "ERROR: Folder already exists: $FULL_PROJECT_PATH"
  # Ask for different name
fi

# 4. Reasonable length
if [ ${#PROJECT_NAME} -gt 100 ]; then
  echo "ERROR: Project name too long (max 100 characters)"
  # Ask again
fi
```

### C.4 Final Confirmation with Full Path

**Display complete summary before creating:**

```javascript
AskUserQuestion({
  questions: [{
    question: `Create GitFlow project with these settings?\n
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Project Name:  ${PROJECT_NAME}
  Location:      ${TARGET_PATH}/
  Full Path:     ${FULL_PROJECT_PATH}/
  Repository:    ${REPO_URL}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Structure to be created:
  ${PROJECT_NAME}/
  ├── .bare/           (hidden bare repository)
  ├── 01-Main/         (main branch)
  ├── 02-Develop/      (develop branch) ← Working directory
  ├── features/
  ├── releases/
  └── hotfixes/`,
    header: "Confirm",
    options: [
      { label: "Yes, create project", description: "Create structure and clone repository (Recommended)" },
      { label: "Change settings", description: "Go back and modify name, location, or repository" }
    ],
    multiSelect: false
  }]
})
```

**If "Change settings" selected:**
- Return to C.1 and let user modify any setting

### C.5 Create Structure and Clone

Once all inputs are confirmed, execute the same steps as MODE A:

```bash
# Final path is already set from C.3 validation
# FULL_PROJECT_PATH="$TARGET_PATH/$PROJECT_NAME"

# Create project folder with organized structure
mkdir -p "$FULL_PROJECT_PATH"
cd "$FULL_PROJECT_PATH"

# Clone as bare repository (hidden)
git clone --bare "$REPO_URL" .bare
echo "gitdir: ./.bare" > .git

# Configure bare repo for worktrees
cd .bare
git config core.bare false
git config core.worktree ".."
cd ..

# Create organized worktree structure
mkdir -p features releases hotfixes

# Create permanent worktrees with numbered prefixes
git worktree add "01-Main" main
git worktree add "02-Develop" develop 2>/dev/null || {
  # If develop doesn't exist, create it from main
  git worktree add "02-Develop" -b develop main
}

# Initialize GitFlow config in 02-Develop (working directory)
cd "02-Develop"
mkdir -p .claude/gitflow/{plans,logs,migrations,backup,cache}
```

### C.6 Generate Config and Display Summary

Generate the same config as MODE A (see A.4) and display:

```
================================================================================
                    GITFLOW INITIALIZED (Interactive Mode)
================================================================================

REPOSITORY
  Name:   ${PROJECT_NAME}
  Remote: ${REPO_URL}

STRUCTURE CREATED
  ${FULL_PROJECT_PATH}/
  ├── .bare/          ← Bare repository (hidden)
  ├── .git            ← Pointer to .bare
  ├── 01-Main/        ← main branch (read-only reference)
  ├── 02-Develop/     ← develop branch (WORKING DIRECTORY)
  ├── features/       ← Feature worktrees will go here
  ├── releases/       ← Release worktrees will go here
  └── hotfixes/       ← Hotfix worktrees will go here

WORKING DIRECTORY
  ${FULL_PROJECT_PATH}/02-Develop

NEXT STEPS
  1. Open the project:
     cd "${FULL_PROJECT_PATH}/02-Develop"
     code .

  2. Start a new feature:
     /gitflow:10-start feature my-feature

================================================================================
```

---

## MODE B: Existing Repository (Default)

**Trigger:** Currently inside a git repository without URL argument

### 0. Check existing structure

**IMPORTANT:** Before analyzing, check if GitFlow is already initialized.

Check for existing structure at [.claude/gitflow/config.json](.claude/gitflow/config.json).

**If structure exists, analyze differences:**

| Check | Expected | Current | Status |
|-------|----------|---------|--------|
| Config version | 1.2.0 | {existing} | {OK/OUTDATED} |
| Worktrees enabled | true | {value} | {OK/MISSING} |
| EF Core config | crossBranch section | {exists?} | {OK/MISSING} |
| Folders | [plans/](.claude/gitflow/plans/), [logs/](.claude/gitflow/logs/), [migrations/](.claude/gitflow/migrations/) | {exists?} | {OK/INCOMPLETE} |

**If differences detected, ask user:**

```javascript
AskUserQuestion({
  questions: [{
    question: "Existing GitFlow structure detected (v{existing_version}). What do you want to do?",
    header: "Init",
    options: [
      { label: "Migrate", description: "Update to v1.2.0 - preserve existing config (Recommended)" },
      { label: "Reset", description: "Delete and recreate from scratch (loses config)" },
      { label: "Skip", description: "Keep current structure unchanged" }
    ],
    multiSelect: false
  }]
})
```

**Migration actions (if "Migrate" selected):**
1. Backup existing config to [.claude/gitflow/backup/](.claude/gitflow/backup/)
2. Add missing config sections (worktrees, efcore.crossBranch, etc.)
3. Create missing folders
4. Update version to 1.2.0
5. Preserve user customizations (branch names, versioning source, etc.)

**Reset actions (if "Reset" selected):**
1. Backup entire [.claude/gitflow/](.claude/gitflow/) to `.claude/gitflow.bak_<timestamp>/`
2. Delete [.claude/gitflow/](.claude/gitflow/)
3. Continue with fresh initialization

**Skip actions:**
1. Display current config summary
2. Exit without changes

---

### 1. Analysis

Analyze the repository and detect:

**Git:**
- Check if it's a Git repo
- List existing branches (main/master, develop)
- Get remote origin URL

**Version (.NET - priority order):**
1. `*.csproj` → `<Version>` tag
2. `Directory.Build.props` → `<Version>` tag
3. `AssemblyInfo.cs` → `[AssemblyVersion]` attribute
4. `VERSION` file → raw content
5. Last git tag → format `vX.Y.Z`
6. None → suggest `0.1.0` with `VERSION` file

**EF Core:**
- Detect if EF Core is referenced in csproj files
- List existing DbContexts

### 2. Generate the plan file

Create plan file in [.claude/gitflow/plans/](.claude/gitflow/plans/) named `init_<YYYYMMDD>.md` containing:

````markdown
# GitFlow Initialization Plan

> Read this file then execute:

```
/gitflow:1-init --exec
```

## Repository
| Info | Value |
|------|-------|
| Name | {repo_name} |
| Remote | {url_or_local} |

## Version
| Source | File | Version |
|--------|------|---------|
| {type} | {path} | {version} |

## Planned Actions
- [ ] Branches: main ({create|exists}), develop ({create|exists})
- [ ] Structure: .claude/gitflow/{config.json, plans/, logs/, migrations/}
- [ ] CLAUDE.md: Repository section
- [ ] EF Core: {active|inactive} - Contexts: {list}

## Configuration
- Versioning: SemVer
- Tag prefix: v
- Auto-increment: feature→minor, hotfix→patch, release→manual

## Modify?
Edit this file before executing.

## Execute

```
/gitflow:1-init --exec
```
````

### 3. Display message

````
Plan generated: .claude/gitflow/plans/init_<DATE>.md

1. Read the file
2. Modify if necessary
3. Execute:

```
/gitflow:1-init --exec
```
````

---

## --exec mode: Execute the plan

### Prerequisites
- Init plan exists in [.claude/gitflow/plans/](.claude/gitflow/plans/)

### Actions
1. **Branches**: Create main and develop if absent, checkout develop
2. **Structure**: Create [.claude/gitflow/](.claude/gitflow/) with subdirectories:
   - [plans/](.claude/gitflow/plans/) - Integration plans
   - [logs/](.claude/gitflow/logs/) - Operation history
   - [migrations/](.claude/gitflow/migrations/) - EF Core snapshots
3. **Worktrees** (if `--with-worktrees`): Create worktrees structure (see below)
4. **Config**: Create [config.json](.claude/gitflow/config.json) with plan configuration
5. **CLAUDE.md**: Add Repository section if branches existed
6. **VERSION**: Create file if no source detected
7. **Commit** (ask): `chore(gitflow): initialization v{VERSION}`

### Creating Worktrees (v1.3)

If `--with-worktrees` is specified (default: true), ask user for structure preference:

```javascript
AskUserQuestion({
  questions: [{
    question: "Choose worktree organization style",
    header: "Structure",
    options: [
      { label: "Organized (Recommended)", description: "01-Main/, 02-Develop/, features/, releases/, hotfixes/ in parent folder" },
      { label: "Adjacent", description: "../worktrees/ folder next to repo (legacy mode)" },
      { label: "Skip worktrees", description: "No worktree structure, use branch switching" }
    ],
    multiSelect: false
  }]
})
```

#### Option 1: Organized Structure (Recommended)

```bash
# Move current repo to subfolder with numbered prefix
CURRENT_DIR=$(pwd)
PARENT_DIR=$(dirname "$CURRENT_DIR")
REPO_NAME=$(basename "$CURRENT_DIR")

# Create organized structure in parent
cd "$PARENT_DIR"
mkdir -p "${REPO_NAME}-gitflow"
mv "$REPO_NAME" "${REPO_NAME}-gitflow/.bare-temp"

cd "${REPO_NAME}-gitflow"

# Convert to bare repo structure
git clone --bare ".bare-temp" .bare
rm -rf .bare-temp
echo "gitdir: ./.bare" > .git

# Configure bare repo
cd .bare
git config core.bare false
git config core.worktree ".."
cd ..

# Create worktree structure
mkdir -p features releases hotfixes
git worktree add "01-Main" main
git worktree add "02-Develop" develop

# Move to 02-Develop as working directory
cd "02-Develop"
```

**Resulting structure (Organized):**
```
parent/
└── {repo-name}-gitflow/         # Project folder
    ├── .bare/                   # Bare repository
    ├── .git                     # gitdir pointer
    ├── 01-Main/                 # Permanent worktree (main)
    │   └── ...
    ├── 02-Develop/              # Permanent worktree (develop) ← WORKING DIR
    │   ├── .claude/gitflow/
    │   └── ...
    ├── features/                # Feature worktrees
    │   └── {feature-name}/
    ├── releases/                # Release worktrees
    │   └── v{version}/
    └── hotfixes/                # Hotfix worktrees
        └── {hotfix-name}/
```

#### Option 2: Adjacent Structure (Legacy)

```bash
# Base path (relative to main repo)
WORKTREE_BASE="../worktrees"

# Create directories
mkdir -p "$WORKTREE_BASE/features"
mkdir -p "$WORKTREE_BASE/releases"
mkdir -p "$WORKTREE_BASE/hotfixes"

# Create permanent worktrees for main and develop
git worktree add "$WORKTREE_BASE/main" main
git worktree add "$WORKTREE_BASE/develop" develop
```

**Resulting structure (Adjacent/Legacy):**
```
parent/
├── atlashub-project/          # Main repo (stays as-is)
│   ├── .claude/gitflow/
│   └── ...
└── worktrees/                 # Adjacent folder
    ├── main/                  # Permanent worktree
    ├── develop/               # Permanent worktree
    ├── features/              # Features in progress
    │   └── {feature-name}/
    ├── releases/              # Releases in progress
    │   └── v{version}/
    └── hotfixes/              # Hotfixes in progress
        └── {hotfix-name}/
```

### Config.json structure

#### Organized Mode (v1.3)
```json
{
  "version": "1.4.0",
  "initMode": "organized",
  "repository": { "name": "", "defaultBranch": "main", "remoteUrl": "" },
  "versioning": { "strategy": "semver", "current": "0.1.0", "source": "auto", "sourceFile": "", "tagPrefix": "v", "autoIncrement": { "feature": "minor", "hotfix": "patch", "release": "manual" } },
  "git": { "branches": { "main": "main", "develop": "develop", "feature": "feature/", "release": "release/", "hotfix": "hotfix/" }, "mergeStrategy": "--no-ff", "protectedBranches": ["main", "develop"] },
  "worktrees": {
    "enabled": true,
    "mode": "organized",
    "basePath": "..",
    "bareRepo": "../.bare",
    "permanent": {
      "main": { "path": "../01-Main", "prefix": "01" },
      "develop": { "path": "../02-Develop", "prefix": "02" }
    },
    "structure": {
      "features": "../features/",
      "releases": "../releases/",
      "hotfixes": "../hotfixes/"
    },
    "cleanupOnFinish": true
  },
  "database": {
    "enabled": true,
    "server": "localhost",
    "authType": "windows",
    "username": "",
    "password": "",
    "namePrefix": "",
    "autoCreateLocalConfig": true
  },
  "azureDevOps": {
    "enabled": false,
    "organization": "",
    "project": "",
    "defaultReviewers": [],
    "workItemTypes": {
      "feature": "User Story",
      "hotfix": "Bug",
      "release": "Epic"
    },
    "linkWorkItems": true,
    "autoTransitionWorkItems": true
  },
  "efcore": {
    "enabled": false, "contexts": [], "generateScript": false, "scriptOutputPath": "",
    "crossBranch": { "enabled": true, "scanOnMigrationCreate": true, "blockOnConflict": true, "cacheExpiry": "1h" }
  },
  "workflow": { "requireConfirmation": true, "createCheckpoints": true, "commitConventions": "conventional", "push": { "afterCommit": "worktree", "afterFinish": "always" } }
}
```

### Azure DevOps Configuration (NEW in v1.4)

La section `azureDevOps` configure l'integration avec Azure DevOps CLI pour les PR, work items et boards:

| Parametre | Description | Defaut |
|-----------|-------------|--------|
| `enabled` | Activer l'integration Azure DevOps | `false` |
| `organization` | URL de l'organisation (ex: `https://dev.azure.com/myorg`) | - |
| `project` | Nom du projet Azure DevOps | - |
| `defaultReviewers` | Liste des reviewers par defaut pour les PR | `[]` |
| `workItemTypes.feature` | Type de work item pour les features | `User Story` |
| `workItemTypes.hotfix` | Type de work item pour les hotfixes | `Bug` |
| `workItemTypes.release` | Type de work item pour les releases | `Epic` |
| `linkWorkItems` | Lier automatiquement les PR aux work items | `true` |
| `autoTransitionWorkItems` | Transitionner automatiquement les work items au merge | `true` |

**Commandes disponibles avec Azure DevOps:**

| Action | Commande |
|--------|----------|
| Creer PR avec work item | `az repos pr create --work-items 123` |
| Completer PR (merge) | `az repos pr update --id 42 --status completed` |
| Creer work item | `az boards work-item create --type "User Story" --title "..."` |
| Lier commit a work item | Message commit avec `#123` |

**Installation Azure CLI:**

```bash
# 1. Installer Azure CLI
winget install Microsoft.AzureCLI

# 2. Ajouter l'extension Azure DevOps (auto-install au premier usage)
az extension add --name azure-devops

# 3. Se connecter
az login

# 4. Configurer les defaults (fait automatiquement par /gitflow:1-init)
az devops configure --defaults organization=https://dev.azure.com/VOTRE_ORG project=VOTRE_PROJET
```

---

### Database Configuration (NEW in v1.3)

La section `database` configure la creation automatique de `appsettings.Local.json` lors du `/gitflow:10-start`:

| Parametre | Description | Defaut |
|-----------|-------------|--------|
| `enabled` | Activer la creation automatique | `true` |
| `server` | Serveur SQL Server | `localhost` |
| `authType` | Type d'authentification (`windows` ou `sql`) | `windows` |
| `username` | Utilisateur SQL (si authType=sql) | - |
| `password` | Mot de passe SQL (si authType=sql) | - |
| `namePrefix` | Prefixe des noms de DB (vide = nom du projet) | - |
| `autoCreateLocalConfig` | Creer appsettings.Local.json automatiquement | `true` |

**Convention de nommage des bases de donnees:**

| Type branche | Pattern | Exemple |
|--------------|---------|---------|
| develop | `{prefix}_Dev` | `SmartStack_Dev` |
| feature/* | `{prefix}_feat_{name}` | `SmartStack_feat_user_auth` |
| hotfix/* | `{prefix}_fix_{name}` | `SmartStack_fix_login_bug` |
| release/* | `{prefix}_rel_{version}` | `SmartStack_rel_1_3_0` |

**Avantages:**
- Isolation complete entre worktrees
- Pas de conflits de base de donnees
- Chaque developpeur peut travailler sur plusieurs features simultanement
- Fichier `appsettings.Local.json` ignore par git (credentials securises)

#### Adjacent/Legacy Mode (v1.2 compatible)
```json
{
  "version": "1.4.0",
  "initMode": "adjacent",
  "repository": { "name": "", "defaultBranch": "main", "remoteUrl": "" },
  "versioning": { "strategy": "semver", "current": "0.1.0", "source": "auto", "sourceFile": "", "tagPrefix": "v", "autoIncrement": { "feature": "minor", "hotfix": "patch", "release": "manual" } },
  "git": { "branches": { "main": "main", "develop": "develop", "feature": "feature/", "release": "release/", "hotfix": "hotfix/" }, "mergeStrategy": "--no-ff", "protectedBranches": ["main", "develop"] },
  "worktrees": {
    "enabled": true,
    "mode": "adjacent",
    "basePath": "../worktrees",
    "permanent": { "main": true, "develop": true },
    "structure": { "features": "features/", "releases": "releases/", "hotfixes": "hotfixes/" },
    "cleanupOnFinish": true
  },
  "azureDevOps": {
    "enabled": false,
    "organization": "",
    "project": "",
    "defaultReviewers": [],
    "workItemTypes": { "feature": "User Story", "hotfix": "Bug", "release": "Epic" },
    "linkWorkItems": true,
    "autoTransitionWorkItems": true
  },
  "efcore": {
    "enabled": false, "contexts": [], "generateScript": false, "scriptOutputPath": "",
    "crossBranch": { "enabled": true, "scanOnMigrationCreate": true, "blockOnConflict": true, "cacheExpiry": "1h" }
  },
  "workflow": { "requireConfirmation": true, "createCheckpoints": true, "commitConventions": "conventional", "push": { "afterCommit": "worktree", "afterFinish": "always" } }
}
```

### Archive plan
Rename to `init_<DATE>_DONE_<TIMESTAMP>.md`

---

## Modes

### Clone Mode (New in v1.3)

| Command | Action |
|---------|--------|
| `/gitflow:1-init {url}` | Clone repo to current directory with organized structure |
| `/gitflow:1-init {url} {folder}` | Clone repo to target folder with organized structure |
| `/gitflow:1-init {url} {folder} --yes` | Clone and initialize without prompts |

**Examples:**
```bash
/gitflow:1-init https://github.com/org/repo.git
/gitflow:1-init https://github.com/org/repo.git c:/dev
/gitflow:1-init git@github.com:org/repo.git c:/dev --yes
```

### Interactive Mode (New in v1.3)

**Trigger:** Run `/gitflow:1-init` from a directory that is NOT a git repository

| Step | Action |
|------|--------|
| 1 | Detect no git repo → **ask for target directory (WHERE?)** |
| 2 | Ask for repository URL |
| 3 | Validate URL is accessible |
| 4 | **Ask EXPLICITLY for project name (WHAT?)** |
| 5 | Final confirmation with full path |
| 6 | Create organized structure and clone |

**Flow:**
```
User runs: /gitflow:1-init

→ "Where do you want to create your GitFlow project?"
  [Current directory] [C:/Dev] [~/projects] [Custom path]

→ "What repository do you want to clone?"
  [GitHub] [GitLab] [Azure DevOps] [Other]

→ "Enter the repository URL:"
  > https://github.com/myorg/my-awesome-project.git

→ "What should we name this project folder?"
  [my-awesome-project (Recommended)] [Custom name]

→ "Create GitFlow project with these settings?
    Project Name: my-awesome-project
    Location:     C:/Dev/
    Full Path:    C:/Dev/my-awesome-project/
    Repository:   https://github.com/myorg/my-awesome-project.git"
  [Yes, create project (Recommended)] [Change settings]

→ Creates structure and clones...
→ Opens in 02-Develop
```

### Existing Repo Mode

| Command | Action |
|---------|--------|
| `/gitflow:1-init` | Generate plan (asks if structure exists, asks for structure style) |
| `/gitflow:1-init --exec` | Execute existing plan |
| `/gitflow:1-init --yes` | Generate + execute without intermediate file |
| `/gitflow:1-init --migrate` | Force migration of existing structure to v1.4.0 |
| `/gitflow:1-init --reset` | Force reset (backup + recreate from scratch) |
| `/gitflow:1-init --organized` | Force organized structure (01-Main, 02-Develop) |
| `/gitflow:1-init --adjacent` | Force adjacent/legacy structure (../worktrees) |
| `/gitflow:1-init --no-worktrees` | Generate plan without worktrees |
| `/gitflow:1-init --with-azure-devops` | Configure Azure DevOps integration during init |
| `/gitflow:1-init --skip-azure-devops` | Skip Azure DevOps detection/configuration |

---

## Migration Details

### v1.3 → v1.4 (Azure DevOps Integration)

When migrating to v1.4, these changes are available:

#### New Config Fields

```json
{
  "version": "1.4.0",
  "azureDevOps": {
    "enabled": false,                    // NEW - Enable Azure DevOps CLI integration
    "organization": "",                  // NEW - Azure DevOps organization URL
    "project": "",                       // NEW - Azure DevOps project name
    "defaultReviewers": [],              // NEW - Default PR reviewers
    "workItemTypes": {                   // NEW - Work item type mapping
      "feature": "User Story",
      "hotfix": "Bug",
      "release": "Epic"
    },
    "linkWorkItems": true,               // NEW - Auto-link PR to work items
    "autoTransitionWorkItems": true      // NEW - Auto-transition work items on merge
  }
}
```

#### Migration Options

```javascript
AskUserQuestion({
  questions: [{
    question: "v1.3 config detected. Azure DevOps integration is now available. Configure it?",
    header: "Azure DevOps",
    options: [
      { label: "Yes, configure", description: "Set up Azure DevOps CLI integration (Recommended if using Azure DevOps)" },
      { label: "Skip for now", description: "Just update version to v1.4.0, configure later" }
    ],
    multiSelect: false
  }]
})
```

---

### v1.2 → v1.3 (Organized Structure)

When migrating to v1.3, these changes are available:

#### New Config Fields

```json
{
  "version": "1.4.0",
  "initMode": "organized",      // NEW - "organized" | "adjacent" | "clone" | "interactive"
  "worktrees": {
    "mode": "organized",        // NEW - matches initMode
    "bareRepo": "../.bare",     // NEW - path to bare repo (organized mode)
    "permanent": {
      "main": { "path": "../01-Main", "prefix": "01" },     // CHANGED - object with path/prefix
      "develop": { "path": "../02-Develop", "prefix": "02" } // CHANGED
    }
  }
}
```

#### Migration Options

```javascript
AskUserQuestion({
  questions: [{
    question: "v1.2 config detected. How would you like to upgrade?",
    header: "Migrate",
    options: [
      { label: "Keep adjacent", description: "Stay with ../worktrees structure (just update version)" },
      { label: "Convert to organized", description: "Restructure to 01-Main/, 02-Develop/, etc. (Recommended)" },
      { label: "Skip", description: "Keep v1.2 config unchanged" }
    ],
    multiSelect: false
  }]
})
```

#### Convert to Organized (if selected)

1. Backup current worktrees
2. Create new organized structure
3. Move worktree contents to new locations
4. Update config with new paths
5. Clean up old structure

---

### v1.0 → v1.2 (Legacy)

When migrating from v1.0/v1.1 to v1.2:

#### Config additions

```json
{
  "version": "1.2.0",
  "worktrees": {
    "enabled": true,
    "basePath": "../worktrees",
    "permanent": { "main": true, "develop": true },
    "structure": { "features": "features/", "releases": "releases/", "hotfixes": "hotfixes/" },
    "cleanupOnFinish": true
  },
  "efcore": {
    "crossBranch": {
      "enabled": true,
      "scanOnMigrationCreate": true,
      "blockOnConflict": true,
      "cacheExpiry": "1h"
    }
  },
  "workflow": {
    "push": {
      "afterCommit": "worktree",
      "afterFinish": "always"
    }
  }
}
```

#### Structure additions

```
.claude/gitflow/
├── backup/                    # NEW - for migration backups
├── cache/                     # NEW - for cross-branch scan cache
└── (existing folders preserved)
```

### Preserved during all migrations

- `versioning.source` and `versioning.sourceFile`
- `repository.*` settings
- `git.branches.*` custom branch names
- `efcore.contexts` list
- All existing plans and logs
