@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/efcore/steps/shared/step-00-init.md

@@ -16,145 +16,18 @@ Detect EF Core project structure, identify DbContext (Core vs Extensions), and l
 
 ## EXECUTION SEQUENCE:
 
-### 0. Ensure dotnet ef Available (Platform-Aware)
+Load all helper functions from: `references/shared-init-functions.md`
 
-> **CRITICAL:** On Windows (Git Bash, MSYS2), `dotnet ef` may not be on the shell PATH
-> even though it's installed. This step fixes PATH before any EF Core command.
+This includes:
+- `ensure_dotnet_ef()` - Platform-aware dotnet-ef PATH fix
+- `detect_efcore_project()` - Find EF Core project
+- `detect_dbcontext()` - Detect Core vs Extensions
+- `detect_environment()` - Load environment configuration
+- `determine_base_branch()` - Determine GitFlow branch
+- `block_production()` - Prevent production deployments
+- `run_for_contexts()` - Helper for dual context execution
 
-```bash
-ensure_dotnet_ef() {
-  # Quick check: already available?
-  if dotnet ef --version &>/dev/null; then
-    DOTNET_EF_VERSION=$(dotnet ef --version 2>/dev/null)
-    echo "dotnet-ef: $DOTNET_EF_VERSION"
-    return 0
-  fi
-
-  echo "dotnet-ef not on PATH, attempting platform-aware fix..."
-
-  # Try all known .NET global tools locations
-  # - $USERPROFILE/.dotnet/tools  → Windows via Git Bash (USERPROFILE=C:\Users\xxx)
-  # - $HOME/.dotnet/tools         → Linux/macOS or Git Bash fallback
-  # - $LOCALAPPDATA/Microsoft/dotnet/tools → Windows alternate location
-  for TOOLS_DIR in \
-    "$USERPROFILE/.dotnet/tools" \
-    "$HOME/.dotnet/tools" \
-    "$LOCALAPPDATA/Microsoft/dotnet/tools"; do
-    if [ -n "$TOOLS_DIR" ] && [ -d "$TOOLS_DIR" ]; then
-      export PATH="$TOOLS_DIR:$PATH"
-      echo "  PATH += $TOOLS_DIR"
-    fi
-  done
-
-  # Verify after PATH fix
-  if dotnet ef --version &>/dev/null; then
-    DOTNET_EF_VERSION=$(dotnet ef --version 2>/dev/null)
-    echo "dotnet-ef: $DOTNET_EF_VERSION (found after PATH fix)"
-    return 0
-  fi
-
-  echo "ERROR: dotnet-ef not available"
-  echo "Install with: dotnet tool install --global dotnet-ef"
-  echo ""
-  echo "If installed but not found, check:"
-  echo "  Windows: %USERPROFILE%\\.dotnet\\tools must be in PATH"
-  echo "  Linux:   ~/.dotnet/tools must be in PATH"
-  exit 1
-}
-
-ensure_dotnet_ef
-```
-
-**IMPORTANT — WSL pitfall:**
-If the shell resolves `$HOME` to `/home/{user}` (WSL path) instead of `/c/Users/{user}` (Git Bash),
-the .NET SDK may not be found even if `dotnet-ef` is. Use `$USERPROFILE` first on Windows.
-
----
-
-### 1. Detect EF Core Project
-
-```bash
-detect_efcore_project() {
-  # Find project with EF Core reference
-  CSPROJ=$(find . -name "*.csproj" -exec grep -l "Microsoft.EntityFrameworkCore" {} \; | head -1)
-
-  if [ -z "$CSPROJ" ]; then
-    echo "ERROR: No EF Core project found"
-    exit 1
-  fi
-
-  PROJECT_DIR=$(dirname "$CSPROJ")
-  PROJECT_NAME=$(basename "$CSPROJ" .csproj)
-  MIGRATIONS_DIR="$PROJECT_DIR/Persistence/Migrations"
-
-  # Find startup and infrastructure projects
-  STARTUP_PROJECT=$(find . -name "*.Api.csproj" -o -name "*Web.csproj" | head -1)
-  INFRA_PROJECT=$(find . -name "*Infrastructure.csproj" | head -1)
-  [ -z "$INFRA_PROJECT" ] && INFRA_PROJECT="$CSPROJ"
-
-  echo "Project: $PROJECT_NAME"
-  echo "Migrations: $MIGRATIONS_DIR"
-}
-```
-
-### 2. Detect DbContext (Core vs Extensions)
-
-```bash
-detect_dbcontext() {
-  # Priority 1: SmartStack.Domain exists → SmartStack source project (Core only)
-  if find . -type d -name "SmartStack.Domain" | grep -q .; then
-    DBCONTEXT="CoreDbContext"
-    DBCONTEXT_TYPE="core"
-    SCHEMA="core"
-    RUN_BOTH=false
-    echo "DbContext: CoreDbContext (SmartStack.Domain found)"
-    return
-  fi
-
-  # Priority 2: Client project with SmartStack NuGet → BOTH contexts
-  # Detect: csproj files that have a PackageReference to SmartStack (not ProjectReference)
-  # This identifies client projects created via `ss init` that consume SmartStack as NuGet
-  if find . -name "*.csproj" -exec grep -ql "PackageReference.*SmartStack" {} \; 2>/dev/null; then
-    DBCONTEXT="CoreDbContext"
-    DBCONTEXT_TYPE="both"
-    SCHEMA="core"
-    RUN_BOTH=true
-    echo "DbContext: Both (Core from SmartStack NuGet + Extensions local)"
-    echo "  Deploy order: CoreDbContext → ExtensionsDbContext"
-    return
-  fi
-
-  # Priority 3: Scan for DbContext in code
-  CORE_CTX=$(find . -name "*.cs" -exec grep -l "CoreDbContext" {} \; 2>/dev/null | head -1)
-  EXT_CTX=$(find . -name "*.cs" -exec grep -l "ExtensionsDbContext" {} \; 2>/dev/null | head -1)
-
-  if [ -n "$CORE_CTX" ] && [ -n "$EXT_CTX" ]; then
-    DBCONTEXT="CoreDbContext"
-    DBCONTEXT_TYPE="both"
-    SCHEMA="core"
-    RUN_BOTH=true
-    echo "DbContext: Both (CoreDbContext + ExtensionsDbContext found)"
-  elif [ -n "$CORE_CTX" ] && [ -z "$EXT_CTX" ]; then
-    DBCONTEXT="CoreDbContext"
-    DBCONTEXT_TYPE="core"
-    SCHEMA="core"
-    RUN_BOTH=false
-  elif [ -z "$CORE_CTX" ] && [ -n "$EXT_CTX" ]; then
-    DBCONTEXT="ExtensionsDbContext"
-    DBCONTEXT_TYPE="extensions"
-    SCHEMA="extensions"
-    RUN_BOTH=false
-  else
-    # Priority 4: Ask user
-    DBCONTEXT=""
-    DBCONTEXT_TYPE=""
-    SCHEMA=""
-    RUN_BOTH=false
-  fi
-}
-```
-
-### 3. Ask User if DbContext Unknown
+### User Prompt (if DbContext Unknown)
 
 **If `{dbcontext}` is empty after detection:**
 
@@ -188,123 +61,7 @@ if (answer === "CoreDbContext") {
 }
 ```
 
-### 4. Detect Environment
-
-```bash
-detect_environment() {
-  API_DIR=$(find . -type d -name "*.Api" | head -1)
-  [ -z "$API_DIR" ] && API_DIR="src/SmartStack.Api"
-
-  # Priority: --env flag > appsettings.Local.json > error
-  if [ -n "$ENV_FLAG" ]; then
-    CONFIG_FILE="$API_DIR/appsettings.${ENV_FLAG}.json"
-  elif [ -f "$API_DIR/appsettings.Local.json" ]; then
-    CONFIG_FILE="$API_DIR/appsettings.Local.json"
-    SELECTED_ENV="Local"
-  else
-    echo "ERROR: No appsettings.Local.json found"
-    echo "Create one or use --env flag"
-    exit 1
-  fi
-
-  echo "Environment: $SELECTED_ENV"
-  echo "Config: $CONFIG_FILE"
-}
-```
-
-### 5. Determine Base Branch (for squash/rebase)
-
-```bash
-determine_base_branch() {
-  CURRENT_BRANCH=$(git branch --show-current)
-
-  case "$CURRENT_BRANCH" in
-    feature/*)
-      BASE_BRANCH="develop"
-      BRANCH_TYPE="feature"
-      ;;
-    release/*)
-      BASE_BRANCH="main"
-      BRANCH_TYPE="release"
-      ;;
-    hotfix/*)
-      BASE_BRANCH="main"
-      BRANCH_TYPE="hotfix"
-      ;;
-    develop)
-      BASE_BRANCH="main"
-      BRANCH_TYPE="develop"
-      ;;
-    main|master)
-      echo "ERROR: Cannot run on main/master branch"
-      exit 1
-      ;;
-    *)
-      BASE_BRANCH="develop"
-      BRANCH_TYPE="unknown"
-      ;;
-  esac
-
-  echo "Branch: $CURRENT_BRANCH ($BRANCH_TYPE)"
-  echo "Base: $BASE_BRANCH"
-}
-```
-
-### 6. Block Production
-
-```bash
-block_production() {
-  # Check for production indicators (case-insensitive)
-  if grep -qi '"Production"' "$CONFIG_FILE" 2>/dev/null; then
-    echo "BLOCKED: Production environment detected in $CONFIG_FILE"
-    exit 1
-  fi
-
-  # Case-insensitive database name check
-  DB_LOWER=$(echo "$DATABASE_NAME" | tr '[:upper:]' '[:lower:]')
-  if [[ "$DB_LOWER" == *"prod"* ]] || [[ "$DB_LOWER" == *"production"* ]]; then
-    echo "BLOCKED: Production database detected ($DATABASE_NAME)"
-    exit 1
-  fi
-
-  # Environment name check (case-insensitive)
-  ENV_LOWER=$(echo "$SELECTED_ENV" | tr '[:upper:]' '[:lower:]')
-  if [[ "$ENV_LOWER" == "production" ]] || [[ "$ENV_LOWER" == "prod" ]]; then
-    echo "BLOCKED: Production environment selected ($SELECTED_ENV)"
-    exit 1
-  fi
-}
-```
-
-### 7. Dual Context Helper
-
-```bash
-# Helper for steps that need to run for both contexts when RUN_BOTH=true
-# Usage: run_for_contexts "command_or_function"
-# Executes with CoreDbContext first, then ExtensionsDbContext
-# Maintains deploy order constraint: Core MUST run first
-
-run_for_contexts() {
-  if [ "$RUN_BOTH" = "true" ]; then
-    echo "=== Running for CoreDbContext (core schema) ==="
-    DBCONTEXT="CoreDbContext"
-    DBCONTEXT_TYPE="core"
-    SCHEMA="core"
-    eval "$1"
-
-    echo ""
-    echo "=== Running for ExtensionsDbContext (extensions schema) ==="
-    DBCONTEXT="ExtensionsDbContext"
-    DBCONTEXT_TYPE="extensions"
-    SCHEMA="extensions"
-    eval "$1"
-  else
-    eval "$1"
-  fi
-}
-```
-
-### 8. Display Summary
+### Display Summary
 
 ```
 EF CORE CONTEXT

package/templates/skills/efcore/steps/squash/step-03-create.md

@@ -135,64 +135,7 @@ echo "  Down methods: $DOWN_METHODS"
 
 ### 6. Inject SQL Objects (Functions, Views, SP)
 
-EF Core does NOT generate DDL for TVF, views, and stored procedures.
-SQL source scripts are in `Persistence/SqlObjects/` (Embedded Resources).
-After a squash, they must be re-injected into the consolidated migration.
-
-```bash
-# Check if SqlObjects folder exists with .sql files
-SQL_OBJECTS_DIR="$INFRA_PROJECT_DIR/Persistence/SqlObjects"
-SQL_FILES=$(find "$SQL_OBJECTS_DIR" -name "*.sql" 2>/dev/null | wc -l)
-
-if [ "$SQL_FILES" -gt 0 ]; then
-  echo ""
-  echo "Found $SQL_FILES SQL object(s) in SqlObjects/"
-  echo "Injecting SqlObjectHelper.ApplyAll(migrationBuilder) into migration..."
-
-  # Validate migration file path before sed operations (prevent path injection)
-  if [ ! -f "$MIGRATION_FILE" ]; then
-    echo "ERROR: Migration file not found: $MIGRATION_FILE"
-    exit 1
-  fi
-  if ! echo "$MIGRATION_FILE" | grep -qE '\.cs$'; then
-    echo "ERROR: Invalid migration file path (not .cs): $MIGRATION_FILE"
-    exit 1
-  fi
-
-  # Add using directive if not present
-  if ! grep -q "using SmartStack.Infrastructure.Persistence.SqlObjects;" "$MIGRATION_FILE"; then
-    sed -i '1s/^/using SmartStack.Infrastructure.Persistence.SqlObjects;\n/' "$MIGRATION_FILE"
-  fi
-
-  # Add SqlObjectHelper.ApplyAll at the end of Up() method
-  # Find the closing brace of Up() and insert before it
-  sed -i '/protected override void Up/,/^        }/ {
-    /^        }/ i\
-\            // Apply SQL objects (TVF, Views, SP) from embedded resources\
-\            SqlObjectHelper.ApplyAll(migrationBuilder);
-  }' "$MIGRATION_FILE"
-
-  # Verify injection succeeded (fallback to manual step if sed pattern didn't match)
-  if ! grep -q "SqlObjectHelper.ApplyAll" "$MIGRATION_FILE"; then
-    echo "WARNING: Automatic injection failed (indentation pattern may differ)"
-    echo ""
-    echo "MANUAL STEP REQUIRED: Add these lines inside the Up() method before the closing brace:"
-    echo '    using SmartStack.Infrastructure.Persistence.SqlObjects;'
-    echo '    ...'
-    echo '    SqlObjectHelper.ApplyAll(migrationBuilder);'
-    echo ""
-    echo "File: $MIGRATION_FILE"
-  else
-    echo "  SqlObjectHelper.ApplyAll(migrationBuilder) injected"
-  fi
-  find "$SQL_OBJECTS_DIR" -name "*.sql" -exec basename {} \; | while read f; do
-    echo "  - $f"
-  done
-else
-  echo ""
-  echo "No SQL objects found in SqlObjects/ - skipping injection"
-fi
-```
+Load: `references/sql-objects-injection.md`
 
 ---
 

package/templates/skills/feature-full/SKILL.md

@@ -43,7 +43,7 @@ DOMAIN -> APPLICATION -> INFRASTRUCTURE -> API -> WEB
 
 ## Phases 2-7: Implementation
 
-See [steps/step-01-implementation.md](steps/step-01-implementation.md) for detailed code templates covering:
+Start with [steps/step-00-init.md](steps/step-00-init.md) to analyze requirements and existing patterns, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for detailed code templates covering:
 - Phase 2: Domain (Entity + Factory + Behaviors + Enum)
 - Phase 3: Application (Interface + DTOs + Permissions)
 - Phase 4: Infrastructure (EF Config + Service + DI)

package/templates/skills/feature-full/steps/step-00-init.md

@@ -0,0 +1,57 @@
+# Step 0: Initialization
+
+## YOUR TASK
+Gather requirements and analyze existing code patterns before implementing a complete full-stack feature.
+
+## EXECUTION SEQUENCE
+
+### 1. Identify Feature Scope
+- What is the main entity/aggregate? (e.g., Product, Invoice, Support Ticket)
+- What are the CRUD operations required? (Create, Read, Update, Delete, Archive)
+- What business rules apply? (validations, state transitions, constraints)
+- What user permissions are needed? (who can create/edit/delete/view)
+- What notifications/workflows are required? (emails, webhooks, automation)
+- Does AI play a role? (content generation, analysis, validation)
+
+### 2. Analyze Existing Code Patterns
+- Review `Domain/` for similar entity structures, factories, and behaviors
+- Check `Application/` for existing service interfaces and DTOs
+- Examine `Infrastructure/` for EF Core configurations and patterns
+- Look at `API/Controllers/` for authorization and RequirePermission attributes
+- Study `web/` for similar pages, forms, and i18n implementations
+- Identify reusable components and patterns to follow
+
+### 3. Define Data Model
+- Entity properties and types
+- Enums for status, types, and classifications
+- Relationships (OneToMany, ManyToMany, etc.)
+- Audit requirements (CreatedAt, CreatedBy, ModifiedAt, ModifiedBy)
+- Soft delete or permanent delete?
+
+### 4. Plan Implementation Phases
+- **Phase 2:** Domain entity, factory method, behaviors, enums, IAuditableEntity
+- **Phase 3:** Application service interface, DTOs, permissions (create + assign permissions files)
+- **Phase 4:** Infrastructure (EF Config, concrete service, DI registration, DbSet, migration)
+- **Phase 5:** API controller with Authorize, RequirePermission, ProducesResponseType
+- **Phase 6:** Frontend (API client, custom hook with SignalR, page, form, routing, i18n for 4 languages)
+- **Phase 7:** Integrations (notifications, workflows, AI if applicable)
+
+### 5. Validate Against Architecture Rules
+- Confirm layered architecture is followed (no frontend-to-DB shortcuts)
+- Verify entity factory methods are used (no direct constructors in services)
+- Check permissions split across 2 files (Create/List/Read/Update/Delete vs Assign)
+- Plan SignalR hooks for real-time updates
+- Define ProducesResponseType for all endpoints
+- Plan i18n for English, French, Italian, German
+
+## SUCCESS METRICS
+- Feature scope clearly defined and bounded
+- All required CRUD operations identified
+- Business rules documented
+- Permissions mapped to roles
+- Implementation plan with all 7 phases outlined
+- Existing code patterns understood and will be followed
+- Data model defined with relationships and audit requirements
+
+## NEXT STEP
+Proceed to `./step-01-implementation.md` to execute all phases (Domain, Application, Infrastructure, API, Frontend, Integrations) with code templates and orchestration of child skills.

package/templates/skills/feature-full/steps/step-01-implementation.md

@@ -30,7 +30,7 @@ public record {Entity}Dto(Guid Id, string Name, string Status, DateTime CreatedA
 public record Create{Entity}Request(string Name, string? Description);
 
 // Permissions.cs + PermissionConfiguration.cs (2 files!)
-public const string View = "{context}.{area}.{module}.read";
+public const string View = "{area}.{module}.read";
 ```
 
 ## Phase 4: Infrastructure

package/templates/skills/gitflow/SKILL.md

@@ -6,11 +6,12 @@ disable-model-invocation: true
 ---
 
 ## Current state (auto-injected)
-- Branch: !`git branch --show-current`
-- Status: !`git status --short`
-- Recent commits: !`git log --oneline -5`
-- Worktrees: !`git worktree list 2>/dev/null`
-- Config: !`cat .gitflow/config.json 2>/dev/null || echo "no config found"`
+- Preflight: !`if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi microsoft /proc/version 2>/dev/null; then p=$(sed 's/^gitdir: //' .git | tr -d '\r\n'); d=$(echo "${p:0:1}" | tr A-Z a-z); r="${p:2}"; r="${r//\\//}"; printf 'gitdir: %s\n' "$(realpath -m --relative-to="$(pwd)" "/mnt/$d$r")" > .git && echo "repaired"; else echo "ok"; fi`
+- Branch: !`git branch --show-current 2>/dev/null || echo "UNAVAILABLE"`
+- Status: !`git status --short 2>/dev/null || echo "UNAVAILABLE"`
+- Recent commits: !`git log --oneline -5 2>/dev/null || echo "UNAVAILABLE"`
+- Worktrees: !`git worktree list 2>/dev/null || echo "UNAVAILABLE (run preflight_git_check from _shared.md)"`
+- Config: !`cat .claude/gitflow/config.json 2>/dev/null || echo "no config found"`
 
 <objective>
 Execute GitFlow workflows with automatic versioning, worktree management, and EF Core migration validation. Uses progressive step loading to minimize context and maintain fresh state at each phase.
@@ -316,6 +317,28 @@ Auto mode: {auto_mode}
 
 </task_agents>
 
+<worktree_repair>
+
+**MANDATORY PRE-FLIGHT:** Before routing to any step or agent, run `preflight_git_check` (from `_shared.md` PREFLIGHT_GIT_CHECK section). This ensures git is accessible and repairs cross-platform worktree paths (Windows ↔ WSL).
+
+**When to trigger:** If any auto-injected state shows "UNAVAILABLE", or if the Preflight line shows "repaired".
+
+**Execution:**
+```bash
+# 1. Detect platform
+detect_platform
+
+# 2. Run preflight (repairs .git file + .bare/worktrees/*/gitdir)
+preflight_git_check
+
+# 3. Verify
+git status --short
+```
+
+**This converts all paths to relative format (cross-platform safe).**
+
+</worktree_repair>
+
 <execution_rules>
 
 - **Single step mode**: Read the step file and execute inline

package/templates/skills/gitflow/_shared.md

@@ -143,6 +143,9 @@ Searches in: pwd, develop worktree, then git root.
 
 ```bash
 resolve_gitflow_config_path() {
+  # Ensure git is accessible (cross-platform worktree repair)
+  preflight_git_check 2>/dev/null
+
   # 1. Try current directory
   [ -f ".claude/gitflow/config.json" ] && { echo ".claude/gitflow/config.json"; return 0; }
 
@@ -316,9 +319,36 @@ cleanup_worktree_for_branch() {
 
 ---
 
+## VALIDATE_WORKTREE_PATH
+
+Validates that a worktree path follows config conventions. Only `01-Main` and `02-Develop` may use numbered prefixes. All other worktrees (features, releases, hotfixes) MUST use config paths (`features/{name}`, `releases/v{version}`, `hotfixes/{name}`).
+
+```bash
+validate_worktree_path() {
+  local WORKTREE_PATH="$1"
+  local BASENAME=$(basename "$WORKTREE_PATH")
+
+  # Only 01-Main and 02-Develop may use numbered prefixes
+  if [[ "$BASENAME" =~ ^[0-9]{2}- ]] && [[ "$BASENAME" != "01-Main" ]] && [[ "$BASENAME" != "02-Develop" ]]; then
+    echo "ERROR: Invalid numbered worktree directory: $BASENAME"
+    echo "  Path: $WORKTREE_PATH"
+    echo "  FORBIDDEN: Numbered directories like 03-Release, 04-Feature, 05-Hotfix"
+    echo "  REQUIRED: Use config paths → features/{name}, releases/v{version}, hotfixes/{name}"
+    return 1
+  fi
+  return 0
+}
+```
+
+---
+
 ## REPAIR_WORKTREE_PATHS
 
-Repairs worktree metadata files that contain paths from a different platform (e.g., WSL paths `/mnt/d/...` on Windows, or Windows paths `D:/...` on WSL). Scans `.bare/worktrees/*/gitdir` and the corresponding `{worktree}/.git` files.
+Converts worktree metadata paths to **relative paths** for cross-platform compatibility (Windows + WSL).
+Absolute paths (Windows `D:/...` or POSIX `/mnt/d/...`) break when switching environments.
+Relative paths work everywhere without repair.
+
+Scans `.bare/worktrees/*/gitdir` and the corresponding `{worktree}/.git` files.
 
 ```bash
 repair_worktree_paths() {
@@ -333,24 +363,48 @@ repair_worktree_paths() {
     local gitdir_file="$wt_dir/gitdir"
     [ ! -f "$gitdir_file" ] && continue
 
-    # Fix .bare/worktrees/{name}/gitdir
+    # Read stored path (may be Windows absolute, POSIX absolute, or already relative)
     local stored_path=$(cat "$gitdir_file" | tr -d '\n\r')
-    local fixed_path=$(normalize_path_for_platform "$stored_path")
-    if [ "$stored_path" != "$fixed_path" ]; then
-      echo "$fixed_path" > "$gitdir_file"
-      echo "REPAIRED: $wt_name/gitdir → $fixed_path"
+
+    # Resolve to current platform absolute path for realpath computation
+    local resolved_path="$stored_path"
+    local is_abs=false
+    if [[ "$stored_path" =~ ^[A-Za-z]:[\\/] ]]; then
+      is_abs=true
+      resolved_path=$(normalize_path_for_platform "$stored_path")
+    elif [[ "$stored_path" =~ ^/ ]]; then
+      is_abs=true
+      resolved_path=$(normalize_path_for_platform "$stored_path")
+    fi
+    if [ "$is_abs" = "false" ]; then
+      # Already relative - resolve from gitdir_file location to get absolute
+      resolved_path=$(realpath -m "$wt_dir/$stored_path")
+    fi
+
+    # Get worktree real directory (parent of .git file)
+    local wt_real_dir=$(dirname "$resolved_path")
+    [ ! -d "$wt_real_dir" ] && continue
+
+    # Compute relative path: .bare/worktrees/{name}/ → worktree/.git
+    local bare_wt_abs=$(realpath -m "$wt_dir")
+    local wt_abs=$(realpath -m "$wt_real_dir")
+    local rel_gitdir=$(realpath -m --relative-to="$bare_wt_abs" "$wt_abs/.git")
+
+    if [ "$stored_path" != "$rel_gitdir" ]; then
+      printf '%s\n' "$rel_gitdir" > "$gitdir_file"
+      echo "REPAIRED: $wt_name/gitdir → $rel_gitdir"
       REPAIRED=$((REPAIRED + 1))
     fi
 
-    # Fix the worktree's .git file
-    local wt_real_dir=$(dirname "$fixed_path")
+    # Fix the worktree's .git pseudo-file → relative path to .bare/worktrees/{name}
     if [ -f "$wt_real_dir/.git" ]; then
       local git_content=$(cat "$wt_real_dir/.git" | tr -d '\n\r')
       local git_path="${git_content#gitdir: }"
-      local fixed_git_path=$(normalize_path_for_platform "$git_path")
-      if [ "$git_path" != "$fixed_git_path" ]; then
-        echo "gitdir: $fixed_git_path" > "$wt_real_dir/.git"
-        echo "REPAIRED: $wt_name/.git → $fixed_git_path"
+      local rel_bare=$(realpath -m --relative-to="$wt_abs" "$bare_wt_abs")
+
+      if [ "$git_path" != "$rel_bare" ]; then
+        printf 'gitdir: %s\n' "$rel_bare" > "$wt_real_dir/.git"
+        echo "REPAIRED: $wt_name/.git → $rel_bare"
         REPAIRED=$((REPAIRED + 1))
       fi
     fi
@@ -362,6 +416,49 @@ repair_worktree_paths() {
 
 ---
 
+## PREFLIGHT_GIT_CHECK
+
+Lightweight check to ensure git is accessible in the current worktree. If git fails (cross-platform path issue), locates `.bare` and calls `repair_worktree_paths`. Must be called before any git operation in agents that may run in worktrees created from a different environment (Windows vs WSL).
+
+```bash
+preflight_git_check() {
+  # Quick test: if git works, nothing to do
+  git rev-parse --git-dir >/dev/null 2>&1 && return 0
+
+  echo "Git inaccessible — attempting worktree path repair..."
+
+  # Find .bare directory by walking up
+  local BARE_DIR=""
+  local DIR="$(pwd)"
+  while [ "$DIR" != "/" ]; do
+    [ -d "$DIR/.bare" ] && { BARE_DIR="$DIR/.bare"; break; }
+    DIR=$(dirname "$DIR")
+  done
+
+  if [ -z "$BARE_DIR" ]; then
+    echo "ERROR: No .bare directory found. Not a GitFlow worktree."
+    return 1
+  fi
+
+  # Ensure platform is detected
+  [ -z "$GF_PLATFORM" ] && detect_platform
+
+  # Repair all worktree paths to relative format
+  repair_worktree_paths "$BARE_DIR"
+
+  # Verify repair
+  if git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "Worktree paths repaired successfully."
+    return 0
+  else
+    echo "ERROR: Worktree repair failed. Run /gitflow init to reconfigure."
+    return 1
+  fi
+}
+```
+
+---
+
 ## RESOLVE_WORKSPACE
 
 Resolves the workspace JSON file by walking up the directory tree.

package/templates/skills/gitflow/phases/abort.md

@@ -67,6 +67,10 @@ BRANCH_TYPE=$(echo $CURRENT | cut -d'/' -f1)
 echo "⚠️ This will delete branch $CURRENT and its worktree"
 echo "All uncommitted changes will be LOST"
 
+# Repair cross-platform worktree paths (WSL ↔ Windows)
+detect_platform
+repair_worktree_paths "$(git rev-parse --git-common-dir 2>/dev/null || echo '.bare')"
+
 # Find worktree
 WORKTREE=$(git worktree list | grep "$CURRENT" | awk '{print $1}')
 

package/templates/skills/gitflow/phases/cleanup.md

@@ -38,6 +38,10 @@ CURRENT=$(git rev-parse --abbrev-ref HEAD)
 ```bash
 echo "Scanning worktrees..."
 
+# Repair cross-platform worktree paths (WSL ↔ Windows)
+detect_platform
+repair_worktree_paths "$(git rev-parse --git-common-dir 2>/dev/null || echo '.bare')"
+
 mkdir -p .claude/gitflow/cache
 git worktree list > .claude/gitflow/cache/worktrees.txt