@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/gitflow/steps/step-start.md

@@ -1,195 +1,195 @@
----
-name: step-start
-description: Create new branch with worktree
-next_step: null
----
-
-# Step: START - Create Branch
-
-## YOUR TASK:
-
-Create a new feature/release/hotfix branch with optional worktree setup.
-
-**ULTRA THINK about branch naming and base selection.**
-
----
-
-## INPUT PARSING:
-
-```
-{branch_type} = feature | release | hotfix
-{branch_name} = normalized name (kebab-case)
-{no_worktree} = --no-worktree flag present
-```
-
-**From flags:**
-- `-f {name}` → branch_type=feature, branch_name={name}
-- `-r {name}` → branch_type=release, branch_name={name}
-- `-h {name}` → branch_type=hotfix, branch_name={name}
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Load Config and Analyze Context
-
-Load GitFlow config. Display current branch, version, tag, and dirty status.
-
-### 2. Interactive Questions (if no args)
-
-Ask for branch type (feature/release/hotfix) and name if not provided via args. Display suggested next version for releases.
-
-### 3. Normalize and Validate
-
-See [references/start-branch-normalization.md](../references/start-branch-normalization.md) for:
-- Branch name normalization (kebab-case)
-- Branch existence validation
-
-### 4. Determine Base Branch
-
-| Type | Base | Target |
-|------|------|--------|
-| feature | develop | develop |
-| release | develop | main |
-| hotfix | main | main |
-
-### 5. Handle Dirty Working Directory
-
-Offer user to stash, commit, or continue if working directory has changes.
-
-### 5b. EF Core Migration Pre-flight (Release/Hotfix only)
-
-**BLOCKING CHECK: Validate migration naming conventions BEFORE creating the release branch.**
-
-See [references/start-efcore-preflight.md](../references/start-efcore-preflight.md) for the full validation script and user choice handling.
-
-Expected format: `{context}_v{version}_{sequence}_{Description}` (e.g., `core_v2.0.0_001_InitialSchema`)
-
----
-
-### 6. Create Branch and Worktree
-
-See [references/start-worktree-creation.md](../references/start-worktree-creation.md) for:
-- Worktree path selection (organized mode)
-- Numbering rules (only 01-Main/02-Develop, no numbered feature/release/hotfix)
-- Cross-platform path repair
-- Worktree validation
-- No-worktree mode fallback
-
-### 6b. Push Branch to Remote (AUTOMATIC)
-
-**ALWAYS push immediately after branch creation:**
-```bash
-git push -u origin "$FULL_BRANCH"
-
-# CRITICAL: Verify push and update tracking refs
-git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
-LOCAL_SHA=$(git rev-parse HEAD)
-REMOTE_SHA=$(git rev-parse origin/$FULL_BRANCH)
-if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
-  echo "✅ Branch pushed and verified - origin/$FULL_BRANCH in sync"
-else
-  echo "⚠️ Push verification failed"
-  echo "  Local:  $LOCAL_SHA"
-  echo "  Remote: $REMOTE_SHA"
-fi
-```
-
-### 7. Create Local Environment Config (Backend + Frontend)
-
-See [references/start-local-config.md](../references/start-local-config.md) for the full configuration:
-- **Port generation:** Unique ports per branch (API: 5200+, Web: 5300+) based on branch name hash
-- **7a. Backend:** `appsettings.Local.json` (DB connection, SmartStack config, Kestrel port)
-- **7b. Frontend:** `.env.standalone` + `npm run local` script (Vite mode=standalone, not "local" which conflicts with .env.local in Vite 7+)
-- **7c. Backend:** `launchSettings.json` Local profile with unique port
-- **7d. Summary:** Display configured DB name, API port, Web port
-
-### 8. Store State
-
-```bash
-# Save to state for next steps
-{
-  "branch_type": "{branch_type}",
-  "branch_name": "{FULL_BRANCH}",
-  "base_branch": "{BASE_BRANCH}",
-  "target_branch": "{TARGET}",
-  "worktree_path": "{WORKTREE_PATH}",
-  "version_current": "{VERSION}",
-  "local_config": {
-    "database": "{DB_NAME}",
-    "api_port": "{API_PORT}",
-    "web_port": "{WEB_PORT}",
-    "api_dir": "{API_DIR}",
-    "web_dir": "{WEB_DIR}"
-  }
-}
-```
-
-### 9. Summary
-
-```
-╔══════════════════════════════════════════════════════════════════╗
-║                    {BRANCH_TYPE} CREATED                          ║
-╠══════════════════════════════════════════════════════════════════╣
-║  Branch:   {FULL_BRANCH}                                          ║
-║  Base:     {BASE_BRANCH}                                          ║
-║  Target:   {TARGET}                                               ║
-║  Worktree: {WORKTREE_PATH}                                        ║
-╠══════════════════════════════════════════════════════════════════╣
-║  LOCAL ENVIRONMENT:                                               ║
-║  Database: {DB_NAME}                                              ║
-║  API:      http://localhost:{API_PORT}                            ║
-║  Web:      http://localhost:{WEB_PORT}                            ║
-╠══════════════════════════════════════════════════════════════════╣
-║  NEXT STEPS:                                                      ║
-║                                                                    ║
-║  1. Go to worktree:                                               ║
-║     cd {WORKTREE_PATH}                                            ║
-║                                                                    ║
-║  2. Start backend (auto-migrates Core + Extensions DB):           ║
-║     dotnet run --project src/{Project}.Api --launch-profile Local ║
-║                                                                    ║
-║  3. Reset admin password:                                         ║
-║     ss admin reset                                                ║
-║                                                                    ║
-║  4. Start frontend (other terminal):                              ║
-║     cd web/{project}-web && npm run local                         ║
-║                                                                    ║
-║  5. Make changes and commit:                                      ║
-║     /gitflow commit                                               ║
-║                                                                    ║
-║  6. Create pull request:                                          ║
-║     /gitflow pr                                                   ║
-║                                                                    ║
-║  7. After PR merged, finalize:                                    ║
-║     /gitflow finish                                               ║
-╚══════════════════════════════════════════════════════════════════╝
-```
-
----
-
-## ERROR HANDLING:
-
-| Error | Solution |
-|-------|----------|
-| Branch exists | Offer: rename, checkout, or delete |
-| Dirty working directory | Offer: stash, commit, or continue |
-| Worktree path exists | Remove orphan or use different path |
-| Base branch behind remote | Pull before creating |
-
----
-
-## SUCCESS CRITERIA:
-
-- Branch created from correct base
-- **Branch pushed to remote (AUTOMATIC)**
-- Worktree set up (if enabled)
-- Backend local config created: `appsettings.Local.json` (if .NET API detected)
-- Backend launch profile created: `launchSettings.json` Local profile with unique port (if .NET API detected)
-- Frontend local config created: `.env.standalone` + `npm run local` script (if web project detected)
-- Ports synchronized between backend and frontend (unique per branch)
-- State stored for subsequent steps
-
-## NEXT STEP:
-
-User works on code, then runs `/gitflow commit`.
+---
+name: step-start
+description: Create new branch with worktree
+next_step: null
+---
+
+# Step: START - Create Branch
+
+## YOUR TASK:
+
+Create a new feature/release/hotfix branch with optional worktree setup.
+
+**ULTRA THINK about branch naming and base selection.**
+
+---
+
+## INPUT PARSING:
+
+```
+{branch_type} = feature | release | hotfix
+{branch_name} = normalized name (kebab-case)
+{no_worktree} = --no-worktree flag present
+```
+
+**From flags:**
+- `-f {name}` → branch_type=feature, branch_name={name}
+- `-r {name}` → branch_type=release, branch_name={name}
+- `-h {name}` → branch_type=hotfix, branch_name={name}
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Config and Analyze Context
+
+Load GitFlow config. Display current branch, version, tag, and dirty status.
+
+### 2. Interactive Questions (if no args)
+
+Ask for branch type (feature/release/hotfix) and name if not provided via args. Display suggested next version for releases.
+
+### 3. Normalize and Validate
+
+See [references/start-branch-normalization.md](../references/start-branch-normalization.md) for:
+- Branch name normalization (kebab-case)
+- Branch existence validation
+
+### 4. Determine Base Branch
+
+| Type | Base | Target |
+|------|------|--------|
+| feature | develop | develop |
+| release | develop | main |
+| hotfix | main | main |
+
+### 5. Handle Dirty Working Directory
+
+Offer user to stash, commit, or continue if working directory has changes.
+
+### 5b. EF Core Migration Pre-flight (Release/Hotfix only)
+
+**BLOCKING CHECK: Validate migration naming conventions BEFORE creating the release branch.**
+
+See [references/start-efcore-preflight.md](../references/start-efcore-preflight.md) for the full validation script and user choice handling.
+
+Expected format: `{context}_v{version}_{sequence}_{Description}` (e.g., `core_v2.0.0_001_InitialSchema`)
+
+---
+
+### 6. Create Branch and Worktree
+
+See [references/start-worktree-creation.md](../references/start-worktree-creation.md) for:
+- Worktree path selection (organized mode)
+- Numbering rules (only 01-Main/02-Develop, no numbered feature/release/hotfix)
+- Cross-platform path repair
+- Worktree validation
+- No-worktree mode fallback
+
+### 6b. Push Branch to Remote (AUTOMATIC)
+
+**ALWAYS push immediately after branch creation:**
+```bash
+git push -u origin "$FULL_BRANCH"
+
+# CRITICAL: Verify push and update tracking refs
+git fetch origin $FULL_BRANCH:refs/remotes/origin/$FULL_BRANCH --force --quiet
+LOCAL_SHA=$(git rev-parse HEAD)
+REMOTE_SHA=$(git rev-parse origin/$FULL_BRANCH)
+if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
+  echo "✅ Branch pushed and verified - origin/$FULL_BRANCH in sync"
+else
+  echo "⚠️ Push verification failed"
+  echo "  Local:  $LOCAL_SHA"
+  echo "  Remote: $REMOTE_SHA"
+fi
+```
+
+### 7. Create Local Environment Config (Backend + Frontend)
+
+See [references/start-local-config.md](../references/start-local-config.md) for the full configuration:
+- **Port generation:** Unique ports per branch (API: 5200+, Web: 5300+) based on branch name hash
+- **7a. Backend:** `appsettings.Local.json` (DB connection, SmartStack config, Kestrel port)
+- **7b. Frontend:** `.env.standalone` + `npm run local` script (Vite mode=standalone, not "local" which conflicts with .env.local in Vite 7+)
+- **7c. Backend:** `launchSettings.json` Local profile with unique port
+- **7d. Summary:** Display configured DB name, API port, Web port
+
+### 8. Store State
+
+```bash
+# Save to state for next steps
+{
+  "branch_type": "{branch_type}",
+  "branch_name": "{FULL_BRANCH}",
+  "base_branch": "{BASE_BRANCH}",
+  "target_branch": "{TARGET}",
+  "worktree_path": "{WORKTREE_PATH}",
+  "version_current": "{VERSION}",
+  "local_config": {
+    "database": "{DB_NAME}",
+    "api_port": "{API_PORT}",
+    "web_port": "{WEB_PORT}",
+    "api_dir": "{API_DIR}",
+    "web_dir": "{WEB_DIR}"
+  }
+}
+```
+
+### 9. Summary
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║                    {BRANCH_TYPE} CREATED                          ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Branch:   {FULL_BRANCH}                                          ║
+║  Base:     {BASE_BRANCH}                                          ║
+║  Target:   {TARGET}                                               ║
+║  Worktree: {WORKTREE_PATH}                                        ║
+╠══════════════════════════════════════════════════════════════════╣
+║  LOCAL ENVIRONMENT:                                               ║
+║  Database: {DB_NAME}                                              ║
+║  API:      http://localhost:{API_PORT}                            ║
+║  Web:      http://localhost:{WEB_PORT}                            ║
+╠══════════════════════════════════════════════════════════════════╣
+║  NEXT STEPS:                                                      ║
+║                                                                    ║
+║  1. Go to worktree:                                               ║
+║     cd {WORKTREE_PATH}                                            ║
+║                                                                    ║
+║  2. Start backend (auto-migrates Core + Extensions DB):           ║
+║     dotnet run --project src/{Project}.Api --launch-profile Local ║
+║                                                                    ║
+║  3. Reset admin password:                                         ║
+║     ss admin reset                                                ║
+║                                                                    ║
+║  4. Start frontend (other terminal):                              ║
+║     cd web/{project}-web && npm run local                         ║
+║                                                                    ║
+║  5. Make changes and commit:                                      ║
+║     /gitflow commit                                               ║
+║                                                                    ║
+║  6. Create pull request:                                          ║
+║     /gitflow pr                                                   ║
+║                                                                    ║
+║  7. After PR merged, finalize:                                    ║
+║     /gitflow finish                                               ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## ERROR HANDLING:
+
+| Error | Solution |
+|-------|----------|
+| Branch exists | Offer: rename, checkout, or delete |
+| Dirty working directory | Offer: stash, commit, or continue |
+| Worktree path exists | Remove orphan or use different path |
+| Base branch behind remote | Pull before creating |
+
+---
+
+## SUCCESS CRITERIA:
+
+- Branch created from correct base
+- **Branch pushed to remote (AUTOMATIC)**
+- Worktree set up (if enabled)
+- Backend local config created: `appsettings.Local.json` (if .NET API detected)
+- Backend launch profile created: `launchSettings.json` Local profile with unique port (if .NET API detected)
+- Frontend local config created: `.env.standalone` + `npm run local` script (if web project detected)
+- Ports synchronized between backend and frontend (unique per branch)
+- State stored for subsequent steps
+
+## NEXT STEP:
+
+User works on code, then runs `/gitflow commit`.