@atlashub/smartstack-cli 3.43.0 → 3.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.43.0",
+  "version": "3.45.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/efcore/conflicts.md

@@ -28,14 +28,34 @@ fi
 3. **Display** results in standard format
 4. **Block** if HIGH or CRITICAL conflict
 
+## Base Branch Determination
+
+**BEFORE calling MCP, determine the correct base branch:**
+
+```bash
+# Determine base branch based on current branch type:
+#   feature/*  → compareBranch: "develop"
+#   release/*  → compareBranch: "main"
+#   hotfix/*   → compareBranch: "main"
+#   develop    → compareBranch: "main"
+CURRENT_BRANCH=$(git branch --show-current)
+case "$CURRENT_BRANCH" in
+  feature/*)  COMPARE_BRANCH="develop" ;;
+  release/*)  COMPARE_BRANCH="main" ;;
+  hotfix/*)   COMPARE_BRANCH="main" ;;
+  develop)    COMPARE_BRANCH="main" ;;
+  *)          COMPARE_BRANCH="develop" ;;
+esac
+```
+
 ## MCP Integration
 
-**Primary method:** Use MCP tool for analysis
+**Primary method:** Use MCP tool for analysis with the **correct base branch**
 
 ```
 CALL mcp__smartstack__check_migrations WITH:
   - branch: {current_branch}
-  - compareBranch: "develop"
+  - compareBranch: {COMPARE_BRANCH}
 ```
 
 **Response structure:**

package/templates/agents/efcore/migration.md

@@ -180,6 +180,17 @@ After rebase on develop:
 3. Report the error with dotnet output
 4. Suggest corrective action
 
+## SQL in Migrations (STRICT RULE)
+
+**FORBIDDEN:** Raw SQL inline in migrations (e.g., `migrationBuilder.Sql("CREATE FUNCTION ...")`)
+
+**ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
+
+- All SQL objects (functions, views, procedures, TVFs) MUST be `.sql` files in `Persistence/SqlObjects/`
+- Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` in the `Up()` method
+- If `Persistence/SqlObjects/*.sql` files exist, inject the call automatically after migration creation
+- **Never** write raw SQL directly inside migration `Up()` or `Down()` methods
+
 ## Important Notes
 
 - **Core migrations** go to `CoreDbContextModelSnapshot.cs`

package/templates/agents/efcore/rebase-snapshot.md

@@ -21,6 +21,13 @@ if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi micr
 fi
 ```
 
+## SQL in Migrations (STRICT RULE)
+
+**FORBIDDEN:** Raw SQL inline in migrations (e.g., `migrationBuilder.Sql("CREATE FUNCTION ...")`)
+
+**ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
+Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` — never inline SQL.
+
 ## Workflow
 
 1. **Backup** all migrations

package/templates/agents/efcore/scan.md

@@ -29,15 +29,37 @@ fi
 4. **Analyze** conflict risks
 5. **Recommend** optimal merge order
 
+## Base Branch Determination
+
+**BEFORE calling MCP, determine the correct base branch for each worktree:**
+
+```bash
+# For each branch, determine its base:
+#   feature/*  → compareBranch: "develop"
+#   release/*  → compareBranch: "main"
+#   hotfix/*   → compareBranch: "main"
+#   develop    → compareBranch: "main"
+determine_compare_branch() {
+  case "$1" in
+    feature/*)  echo "develop" ;;
+    release/*)  echo "main" ;;
+    hotfix/*)   echo "main" ;;
+    develop)    echo "main" ;;
+    *)          echo "develop" ;;
+  esac
+}
+```
+
 ## MCP Integration
 
-**Primary method:** Loop through branches and call MCP
+**Primary method:** Loop through branches and call MCP with the **correct base branch**
 
 ```
 FOR each branch in active_worktrees:
+  COMPARE_BRANCH = determine_compare_branch(branch)
   CALL mcp__smartstack__check_migrations WITH:
     - branch: {branch}
-    - compareBranch: "develop"
+    - compareBranch: {COMPARE_BRANCH}
   STORE result
 ```
 

package/templates/agents/efcore/squash.md

@@ -21,6 +21,13 @@ if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi micr
 fi
 ```
 
+## SQL in Migrations (STRICT RULE)
+
+**FORBIDDEN:** Raw SQL inline in migrations (e.g., `migrationBuilder.Sql("CREATE FUNCTION ...")`)
+
+**ONLY** SQL objects defined in `src/{Project}.Infrastructure/Persistence/SqlObjects/` are authorized.
+Migrations reference these via `SqlObjectHelper.ApplyAll(migrationBuilder)` — never inline SQL.
+
 ## Core Principle
 
 ```

package/templates/agents/gitflow/init.md

@@ -15,10 +15,10 @@ You initialize a GitFlow project by orchestrating 3 specialized sub-agents.
 ```
 gitflow-init (you - orchestrator)
   ├── Task(gitflow-init-detect)   → Environment report
-  ├── AskUserQuestion             → User confirms URL, path, name
-  ├── Task(gitflow-init-clone)    → Create structure
+  ├── AskUserQuestion             → User confirms URL, path, name, worktree mode
+  ├── Task(gitflow-init-clone)    → Create structure (skip if disabled)
   ├── Write config.json           → v2.1.0 with platform & workspace
-  └── Task(gitflow-init-validate) → Verify & repair
+  └── Task(gitflow-init-validate) → Verify & repair (skip if disabled)
 ```
 
 ---
@@ -55,10 +55,24 @@ fi
 ```
 
 - **View**: Display config in formatted table and EXIT
-- **Reconfigure**: Continue with full init workflow
+- **Reconfigure**: Load existing values as defaults, then continue with full init workflow (see below)
 - **Repair**: Delegate directly to `Task(gitflow-init-validate)` then EXIT
 - **Cancel**: EXIT immediately
 
+### Loading Existing Config as Defaults (Reconfigure mode)
+
+When the user chooses "Reconfigure", parse the existing `config.json` to pre-populate defaults:
+
+```bash
+# Extract current values from existing config
+EXISTING_URL=$(cat .claude/gitflow/config.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('repository',{}).get('remoteUrl',''))" 2>/dev/null)
+EXISTING_NAME=$(cat .claude/gitflow/config.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('repository',{}).get('name',''))" 2>/dev/null)
+EXISTING_ROOT=$(cat .claude/gitflow/config.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('repository',{}).get('rootFolder',''))" 2>/dev/null)
+EXISTING_MODE=$(cat .claude/gitflow/config.json | python3 -c "import sys,json; print(json.load(sys.stdin).get('worktrees',{}).get('mode','organized'))" 2>/dev/null)
+```
+
+These values will be shown as "(Current)" recommended options in each question below.
+
 ---
 
 ## STEP 1: DETECT ENVIRONMENT
@@ -81,7 +95,9 @@ Parse the report to extract:
 
 ---
 
-## STEP 2: ASK USER (3 MANDATORY QUESTIONS)
+## STEP 2: ASK USER (4 MANDATORY QUESTIONS)
+
+> **Reconfigure mode:** When `EXISTING_GITFLOW=true` and user chose "Reconfigure", show existing values as "(Current)" recommended options in each question. This avoids forcing the user to re-enter everything.
 
 ### 2a. Repository URL
 
@@ -89,6 +105,7 @@ Parse the report to extract:
 
 Otherwise ask:
 
+**Fresh init (no existing config):**
 ```json
 {
   "questions": [{
@@ -105,12 +122,30 @@ Otherwise ask:
 }
 ```
 
+**Reconfigure mode (existing config):**
+```json
+{
+  "questions": [{
+    "question": "Repository URL? (current: {EXISTING_URL})",
+    "header": "Repository",
+    "options": [
+      {"label": "Keep current (Recommended)", "description": "{EXISTING_URL}"},
+      {"label": "Enter GitHub URL", "description": "https://github.com/org/repo.git"},
+      {"label": "Enter Azure DevOps URL", "description": "https://dev.azure.com/org/project/_git/repo"},
+      {"label": "Local only (no remote)", "description": "Initialize without remote"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
 **If user selects a custom option, ask follow-up for the actual URL.**
 
 ### 2b. Root Folder
 
 **CRITICAL for WSL: Normalize the path for the current platform.**
 
+**Fresh init:**
 ```json
 {
   "questions": [{
@@ -126,6 +161,22 @@ Otherwise ask:
 }
 ```
 
+**Reconfigure mode:**
+```json
+{
+  "questions": [{
+    "question": "Root folder? (current: {EXISTING_ROOT})",
+    "header": "Location",
+    "options": [
+      {"label": "Keep current (Recommended)", "description": "{EXISTING_ROOT}"},
+      {"label": "Use parent folder", "description": "{PARENT_DIR}/"},
+      {"label": "Custom path", "description": "Specify a different location"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
 **After getting the path, normalize it:**
 ```bash
 # On WSL: translate Windows paths to /mnt/ format
@@ -135,6 +186,7 @@ Otherwise ask:
 
 ### 2c. Project Name
 
+**Fresh init:**
 ```json
 {
   "questions": [{
@@ -149,12 +201,66 @@ Otherwise ask:
 }
 ```
 
+**Reconfigure mode:**
+```json
+{
+  "questions": [{
+    "question": "Project name? (current: {EXISTING_NAME})",
+    "header": "Project",
+    "options": [
+      {"label": "Keep current (Recommended)", "description": "{EXISTING_NAME}"},
+      {"label": "Custom name", "description": "Specify a different project name"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
 Normalize name into variants (PascalCase.Dot, PascalCase, kebab-case, snake_case, Display Name).
 
+### 2d. Worktree Mode
+
+**Fresh init:**
+```json
+{
+  "questions": [{
+    "question": "How should worktrees be organized?",
+    "header": "Worktrees",
+    "options": [
+      {"label": "Organized (Recommended)", "description": "01-Main, 02-Develop, features/, releases/, hotfixes/"},
+      {"label": "Simple", "description": "main/, develop/, features/, releases/, hotfixes/"},
+      {"label": "Disabled", "description": "No worktrees, use git checkout (not recommended)"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+**Reconfigure mode:**
+```json
+{
+  "questions": [{
+    "question": "How should worktrees be organized? (current: {EXISTING_MODE})",
+    "header": "Worktrees",
+    "options": [
+      {"label": "Keep current: {EXISTING_MODE} (Recommended)", "description": "No change to worktree structure"},
+      {"label": "Organized", "description": "01-Main, 02-Develop, features/, releases/, hotfixes/"},
+      {"label": "Simple", "description": "main/, develop/, features/, releases/, hotfixes/"},
+      {"label": "Disabled", "description": "No worktrees, use git checkout (not recommended)"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+Store the result as `{WORKTREE_MODE}` ("organized", "simple", or "disabled").
+
 ---
 
 ## STEP 3: CLONE AND CREATE STRUCTURE
 
+**Skip this step if `{WORKTREE_MODE}` is "disabled".**
+
 Delegate to `gitflow-init-clone` sub-agent:
 
 ```
@@ -164,7 +270,7 @@ Task(gitflow-init-clone):
     - REPO_URL: {REPO_URL}
     - PROJECT_BASE: {PROJECT_BASE}  (already platform-normalized absolute path)
     - PROJECT_NAME: {PROJECT_NAME}
-    - WORKTREE_MODE: organized
+    - WORKTREE_MODE: {WORKTREE_MODE}
     - PLATFORM: {PLATFORM}
   subagent_type: gitflow-init-clone
   model: sonnet
@@ -178,9 +284,19 @@ Check the result. If FAIL, report to user and suggest manual intervention.
 
 Write `.claude/gitflow/config.json` in develop worktree using the Write tool.
 
-**Path:** `{PROJECT_BASE}/02-Develop/.claude/gitflow/config.json`
+**Path (depends on worktree mode):**
+- Organized: `{PROJECT_BASE}/02-Develop/.claude/gitflow/config.json`
+- Simple: `{PROJECT_BASE}/develop/.claude/gitflow/config.json`
+- Disabled: `{PROJECT_BASE}/.claude/gitflow/config.json`
 
 **Content (v2.1.0):**
+
+Compute directory names based on `{WORKTREE_MODE}`:
+```
+MAIN_DIR    = organized → "01-Main"  | simple → "main"  | disabled → "."
+DEVELOP_DIR = organized → "02-Develop" | simple → "develop" | disabled → "."
+```
+
 ```json
 {
   "version": "2.1.0",
@@ -212,11 +328,11 @@ Write `.claude/gitflow/config.json` in develop worktree using the Write tool.
     "prefixes": { "feature": "feature/", "release": "release/", "hotfix": "hotfix/" }
   },
   "worktrees": {
-    "enabled": true,
-    "mode": "organized",
+    "enabled": "{WORKTREE_MODE != 'disabled'}",
+    "mode": "{WORKTREE_MODE}",
     "structure": {
-      "main": "{normalize_path_for_storage(PROJECT_BASE)}/01-Main",
-      "develop": "{normalize_path_for_storage(PROJECT_BASE)}/02-Develop",
+      "main": "{normalize_path_for_storage(PROJECT_BASE)}/{MAIN_DIR}",
+      "develop": "{normalize_path_for_storage(PROJECT_BASE)}/{DEVELOP_DIR}",
       "features": "{normalize_path_for_storage(PROJECT_BASE)}/features",
       "releases": "{normalize_path_for_storage(PROJECT_BASE)}/releases",
       "hotfixes": "{normalize_path_for_storage(PROJECT_BASE)}/hotfixes"
@@ -248,6 +364,8 @@ Write `.claude/gitflow/config.json` in develop worktree using the Write tool.
 
 ## STEP 5: VALIDATE
 
+**Skip this step if `{WORKTREE_MODE}` is "disabled".**
+
 Delegate to `gitflow-init-validate` sub-agent:
 
 ```
@@ -255,7 +373,7 @@ Task(gitflow-init-validate):
   prompt: |
     Validate GitFlow installation:
     - PROJECT_BASE: {PROJECT_BASE}
-    - WORKTREE_MODE: organized
+    - WORKTREE_MODE: {WORKTREE_MODE}
     - REPO_URL: {REPO_URL}
     - PLATFORM: {PLATFORM}
   subagent_type: gitflow-init-validate
@@ -276,6 +394,9 @@ If `{HAS_WORKSPACE}=false` and `{SIBLING_COUNT} > 0`, suggest creating a workspa
 
 ## STEP 7: SUMMARY
 
+**Adapt structure display based on `{WORKTREE_MODE}`:**
+
+**Organized mode:**
 ```
 ================================================================================
                     GITFLOW INITIALIZED
@@ -287,6 +408,7 @@ PROJECT
   URL:        {REPO_URL}
   Provider:   {GIT_PROVIDER}
   Platform:   {PLATFORM} ({SHELL_TYPE})
+  Mode:       organized
 
 STRUCTURE
   01-Main/     → main branch       ✓
@@ -309,6 +431,67 @@ NEXT STEPS
 ================================================================================
 ```
 
+**Simple mode:**
+```
+================================================================================
+                    GITFLOW INITIALIZED
+================================================================================
+
+PROJECT
+  Name:       {PROJECT_NAME}
+  Location:   {PROJECT_BASE}/
+  URL:        {REPO_URL}
+  Provider:   {GIT_PROVIDER}
+  Platform:   {PLATFORM} ({SHELL_TYPE})
+  Mode:       simple
+
+STRUCTURE
+  main/        → main branch       ✓
+  develop/     → develop branch    ✓
+  features/    → feature worktrees ✓
+  releases/    → release worktrees ✓
+  hotfixes/    → hotfix worktrees  ✓
+
+CONFIG
+  Version:    2.1.0
+  Path:       develop/.claude/gitflow/config.json
+
+VALIDATION
+  {validation_summary}
+
+NEXT STEPS
+  cd "{PROJECT_BASE}/develop"
+  /gitflow -f <feature-name>
+
+================================================================================
+```
+
+**Disabled mode:**
+```
+================================================================================
+                    GITFLOW INITIALIZED (no worktrees)
+================================================================================
+
+PROJECT
+  Name:       {PROJECT_NAME}
+  Location:   {PROJECT_BASE}/
+  URL:        {REPO_URL}
+  Provider:   {GIT_PROVIDER}
+  Platform:   {PLATFORM} ({SHELL_TYPE})
+  Mode:       disabled (git checkout)
+
+CONFIG
+  Version:    2.1.0
+  Path:       .claude/gitflow/config.json
+
+NEXT STEPS
+  cd "{PROJECT_BASE}"
+  git checkout develop
+  /gitflow -f <feature-name>
+
+================================================================================
+```
+
 ---
 
 ## WORKSPACE MODE (`--workspace`)

package/templates/skills/apex/SKILL.md

@@ -87,7 +87,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
 | 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
 | 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
-| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 50 POST-CHECKs, acceptance criteria |
+| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 44 POST-CHECKs, acceptance criteria |
 | 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
 | 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
 | 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP |
@@ -103,7 +103,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | **A** — Analyze | 01 | Yes | Explore existing code |
 | **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
 | **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
-| **X** — eXamine | 04 | Yes | 50 POST-CHECKs, MCP validation, build, acceptance criteria |
+| **X** — eXamine | 04 | Yes | 3 MCP tools + 50 POST-CHECKs (6 security + 44 convention), build, acceptance criteria |
 | *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
 | *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
 | *Tests* | 07-08 | **Yes** | Scaffold and run tests |
@@ -112,13 +112,18 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 <reference_files>
 **Loaded conditionally by steps that need them:**
 
-| File | Purpose | Loaded by |
-|------|---------|-----------|
-| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01, step-03 |
-| `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
-| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (delegate mode + seedData tasks) |
-| `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 |
-| `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
+| File | Purpose | Loaded by | Stays in context for |
+|------|---------|-----------|---------------------|
+| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01 | step-03 (do NOT re-read) |
+| `references/smartstack-layers.md` | Layer rules, skill/MCP mapping, planning templates, delegate fast path | step-02 | step-03 (do NOT re-read) |
+| `references/smartstack-frontend.md` | Frontend patterns, EntityLookup, i18n, compliance gates (sections 1-9) | step-03 | step-04 |
+| `references/challenge-questions.md` | Hierarchy rules, challenge questions, delegate mode skip | step-00 | — |
+| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (delegate mode + seedData tasks) | — |
+| `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 | — |
+| `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 (if NOT economy_mode) | — |
+| `references/post-checks.md` | 6 security + 44 convention bash checks (MCP tools run first) | step-04 | — |
+
+**Context propagation rule:** Files loaded in step N remain in conversation context for step N+1. Steps mark "do NOT re-read" to avoid duplicate reads.
 </reference_files>
 
 <execution_rules>

package/templates/skills/apex/_shared.md

@@ -60,6 +60,9 @@ Write back to {delegate_prd_path}
 
 ### Permission Path Format
 
+> **NOTE:** Permission paths use the navigation hierarchy as base (2+ segments).
+> Controller `[NavRoute]` attributes use the same segments: minimum 2 (`app.module`) for module-level, 3 (`app.module.section`) for section-level.
+
 | Level | Permission format | Segments |
 |-------|------------------|----------|
 | Module | `{app}.{module}.{action}` | 2+1 segments |

package/templates/skills/apex/references/analysis-methods.md

@@ -15,7 +15,7 @@ For each entity found (or to be created), identify FK relationships:
 1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>`)
 2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
 
-See `references/execution-frontend-patterns.md` for EntityLookup patterns.
+See `references/smartstack-frontend.md` section 6 for EntityLookup patterns.
 
 ---
 

package/templates/skills/apex/references/challenge-questions.md

@@ -2,6 +2,19 @@
 
 > **Referenced by:** step-00-init.md
 > Question templates for context detection, hierarchy validation, and need challenging.
+> Previously split across `challenge-questions.md` and `initialization-challenge-flow.md` — now consolidated here.
+
+---
+
+## 4-Level Navigation Hierarchy (BLOCKING RULE)
+
+SmartStack uses a **4-level navigation hierarchy:**
+- **Level 1: Application** — e.g., "HumanResources", "ProjectManagement"
+- **Level 2: Module** — e.g., "Employees", "Timesheet"
+- **Level 3: Section** — e.g., "List", "Dashboard", "Approval"
+- **Level 4: Resource** — e.g., "Export", "Settings" (optional)
+
+**BLOCKING RULE:** Every module MUST have at least one section. A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
 
 ---
 
@@ -142,4 +155,12 @@ questions:
       - label: "I have specific requirements"
         description: "Describe your fields in 'Other'"
     multiSelect: false
+
+---
+
+## Delegate Mode Skip (if -d flag)
+
+When `/ralph-loop` invokes `/apex -d {prd_path}`, ALL hierarchy is extracted from the PRD file:
+- Skip sections 4a-5b (no interactive questions)
+- Jump directly to MCP verify section
 ```