@atlashub/smartstack-cli 4.39.0 → 4.41.0

package/package.json

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

package/templates/skills/apex/SKILL.md

@@ -147,6 +147,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 <execution_rules>
 
+- **ULTRA THINK at each step transition** — Deep reasoning about scope, existing code, and whether elements need to be CREATED or MODIFIED before acting. This is critical when updating an existing module (adding sections/resources to existing seed data, permissions, roles).
 - **Load one step at a time** - Progressive loading to manage context
 - **ORCHESTRATE, never generate** - All SmartStack code via skills (/controller, /application, etc.) or MCP tools
 - **MCP-first** - Use MCP scaffold/validate tools before manual approaches

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

@@ -90,6 +90,30 @@ Cross-reference with step-00 challenge responses:
 - Each section: NavigationSectionSeedData, frontend route → exists/missing
 - If dependencies: verify FK target entities and their `?search=` support
 
+### Seed Data Completeness Criteria (CRITICAL)
+
+> **A seed file EXISTS does NOT mean it's COMPLETE.** When adding sections/resources to an existing module, seed files are the most commonly missed update.
+
+For seed data files, apply these SPECIFIC completeness criteria:
+
+| File | COMPLETE if | INCOMPLETE if |
+|------|-------------|---------------|
+| NavigationModuleSeedData.cs | Contains entries for ALL {sections} from step-00 scope | Missing GetSectionEntries/GetResourceEntries for ANY new section |
+| Permissions.cs | Has constants for ALL {sections} (Read/Create/Update/Delete/Wildcard per section) | Missing permission constants for ANY new section |
+| PermissionsSeedData.cs | Has HasData() entries for ALL permissions in Permissions.cs | Missing HasData() for ANY new permission |
+| RolesSeedData.cs | Has role-permission mappings for ALL permissions | Missing mappings for ANY new permission |
+| {App}SeedDataProvider.cs | Calls seed methods that cover ALL modules/sections | Missing calls for new module/section seed data |
+
+**Decision matrix:**
+
+```
+Seed file NOT found                              → "create"
+Seed file found + covers ALL target sections     → "skip"
+Seed file found + MISSING some target sections   → "modify"  ← THIS IS THE COMMON MISS
+```
+
+> **ULTRA THINK:** When the task says "add absence management to HR module" and NavigationModuleSeedData.cs already has entries for "employees" section — the file EXISTS but is INCOMPLETE (missing "absences" section). Action = "modify", NOT "skip".
+
 ---
 
 ## Scope Re-Check (after exploration)

package/templates/skills/apex/steps/step-00-init.md

@@ -7,6 +7,8 @@ next_step: steps/step-01-analyze.md
 
 # Step 0: Initialize
 
+**ULTRA THINK about whether this is a NEW module (create from scratch) or an UPDATE to an existing module (add sections/resources/entities to existing code). This distinction drives every downstream decision — especially seed data, permissions, and roles.**
+
 **Before anything else**, display the version banner:
 
 ```

package/templates/skills/apex/steps/step-01-analyze.md

@@ -8,6 +8,8 @@ next_step: steps/step-02-plan.md
 
 # Step 1: Analyze
 
+**ULTRA THINK about existing code structure. Pay special attention to seed data files — they may exist but be INCOMPLETE (missing sections, permissions, or roles for the new scope). An existing file does NOT mean it's complete.**
+
 **Goal:** Understand what EXISTS in the codebase. Pure exploration, NO planning.
 
 ## LOAD CONDITIONALLY
@@ -135,7 +137,9 @@ Agent(subagent_type='Explore', model='sonnet',
 
 ---
 
-## 3. Seed Data Inventory
+## 3. Seed Data Inventory (CONTENT-AWARE)
+
+> **CRITICAL:** Finding that a seed file EXISTS is not enough. You must READ it and compare its content against the target scope to determine if it needs MODIFICATION.
 
 ```
 Glob("**/Seeding/Data/{module_code}/*SeedData.cs")
@@ -144,6 +148,42 @@ Glob("**/Seeding/*SeedDataProvider.cs")
 
 Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedConstants, IClientSeedDataProvider (+ DI registration).
 
+### 3b. Seed Data Content Analysis (if files exist)
+
+For each existing seed file, READ IT and extract what's already covered:
+
+```
+NavigationModuleSeedData.cs:
+  → Extract existing section codes (from GetSectionEntries or similar methods)
+  → Extract existing resource codes (from GetResourceEntries or similar methods)
+  → Compare against {sections} from step-00
+  → Mark MISSING sections/resources → these need "modify" action
+
+Permissions.cs:
+  → Extract existing permission constants (Read, Create, Update, Delete per section)
+  → Compare against {sections} from step-00
+  → Mark sections WITHOUT permissions → these need "modify" action
+
+PermissionsSeedData.cs:
+  → Extract existing permission paths from HasData() entries
+  → Mark missing paths → "modify"
+
+RolesSeedData.cs:
+  → Extract existing role-permission mappings
+  → Mark missing mappings for new sections → "modify"
+
+{App}SeedDataProvider.cs:
+  → Check which seed methods are called (SeedNavigationAsync, SeedPermissionsAsync, etc.)
+  → Check if new module/section seed classes are referenced → "modify" if missing
+```
+
+**Result:** For each seed file, set action to:
+- `"skip"` — file exists AND covers ALL target sections/entities
+- `"modify"` — file exists BUT is MISSING entries for new sections/entities
+- `"create"` — file does not exist
+
+> **Common mistake:** Marking seed files as "skip" just because the file exists. A `NavigationModuleSeedData.cs` that covers sections A and B MUST be marked "modify" if the task adds section C.
+
 ---
 
 ## 4-7. Analysis Methods & Validation

package/templates/skills/apex/steps/step-02-plan.md

@@ -8,6 +8,8 @@ next_step: steps/step-03-execute.md
 
 # Step 2: Plan
 
+**ULTRA THINK about the execution strategy. For each file: is it CREATE (new) or MODIFY (exists but needs additions for new sections/entities)? Seed data files are frequently marked "skip" by mistake when they should be "modify" — verify this explicitly.**
+
 **Goal:** Create a precise, file-by-file plan. Each file mapped to a SKILL or MCP tool.
 
 ## LOAD CONDITIONALLY

package/templates/skills/apex/steps/step-03-execute.md

@@ -8,6 +8,8 @@ next_step: steps/step-04-examine.md
 
 # Step 3: Execute — Orchestrator
 
+**ULTRA THINK about the full execution context. Before dispatching layers, verify: are we creating a NEW module or UPDATING an existing one? This is critical for Layer 1 (seed data) — existing seed files must be MODIFIED, not recreated or skipped.**
+
 /apex ORCHESTRATES. It does not write SmartStack code directly.
 All code goes through skills (/controller, /application, /ui-components, /efcore) or MCP tools.
 

package/templates/skills/apex/steps/step-03a-layer0-domain.md

@@ -5,6 +5,8 @@ model: opus
 parent_step: steps/step-03-execute.md
 ---
 
+**ULTRA THINK about domain entities: which are NEW (create) vs which EXIST (modify/extend)?**
+
 ## Layer 0 — Domain + Infrastructure (sequential, agent principal)
 
 ### Task Progress

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -5,6 +5,8 @@ model: opus
 parent_step: steps/step-03-execute.md
 ---
 
+**ULTRA THINK about seed data completeness: is this a NEW module (create all seed files from scratch) or an UPDATE to an existing module (modify existing seed files to add new sections/resources/permissions)? Read existing files BEFORE deciding what to generate.**
+
 ## Layer 1 — Seed Data (DEDICATED LAYER — sequential, agent principal)
 
 ### Task Progress
@@ -15,7 +17,33 @@ TaskUpdate(taskId: progress_tracker_id,
 
 > This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
 
-### Application-Level Seed Data (ONCE per application)
+---
+
+### Mode Detection: CREATE vs UPDATE
+
+> **CRITICAL — Run this BEFORE generating any seed data.**
+
+```
+Glob("**/Seeding/Data/{module_code}/*SeedData.cs") → existing_seed_files
+Glob("**/Seeding/Data/NavigationApplicationSeedData.cs") → app_seed_exists
+Glob("**/Seeding/*SeedDataProvider.cs") → provider_exists
+
+IF existing_seed_files is EMPTY:
+  SEED_MODE = "CREATE"
+  → Generate ALL seed data from scratch (full templates below)
+
+IF existing_seed_files is NOT EMPTY:
+  SEED_MODE = "UPDATE"
+  → Read EACH existing file
+  → Compare content against {sections} and {entities} from step-00
+  → ADD only what's MISSING — do NOT recreate or duplicate existing entries
+```
+
+---
+
+### CREATE Mode — Application-Level Seed Data (ONCE per application)
+
+> Skip if `app_seed_exists` (files already present from previous APEX run).
 
 ```
 1. NavigationApplicationSeedData.cs
@@ -27,7 +55,13 @@ TaskUpdate(taskId: progress_tracker_id,
    → References NavigationApplicationSeedData.ApplicationId
 ```
 
-### Per-Module Seed Data
+---
+
+### Per-Module Seed Data (CREATE or UPDATE)
+
+#### If SEED_MODE = "CREATE"
+
+Generate all files from scratch using `references/core-seed-data.md` templates:
 
 ```
 3. NavigationModuleSeedData.cs
@@ -51,7 +85,51 @@ TaskUpdate(taskId: progress_tracker_id,
    → Look up roles by Code at runtime
 ```
 
-### Infrastructure Provider (ONCE per application)
+#### If SEED_MODE = "UPDATE"
+
+> **Read each existing file FIRST, then surgically add only what's missing.**
+
+```
+3. NavigationModuleSeedData.cs — READ EXISTING FILE
+   → Extract existing section codes (look for GetSectionEntries or section GUID definitions)
+   → Extract existing resource codes
+   → For each section in {sections} NOT already present:
+     - Add new section entry in GetSectionEntries() with new Guid.NewGuid()
+     - Add section translations (4 languages) in GetSectionTranslationEntries()
+     - Add route entry: /{app-kebab}/{module-kebab}/{new-section-kebab}
+   → For each resource in {resources} NOT already present:
+     - Add resource entry in GetResourceEntries()
+     - Add resource translations
+   → PRESERVE all existing entries unchanged
+
+4. Permissions.cs — READ EXISTING FILE
+   → Extract existing permission constants
+   → For each NEW section:
+     - Add section-level constants: Wildcard, Read, Create, Update, Delete
+     - Path format: {app}.{module}.{new-section}.{action}
+   → MCP generate_permissions for validation (compare output vs file)
+   → PRESERVE all existing constants unchanged
+
+5. PermissionsSeedData.cs — READ EXISTING FILE
+   → Extract existing HasData() permission entries
+   → Add HasData() entries for each NEW permission from step 4
+   → PRESERVE all existing entries unchanged
+
+6. RolesSeedData.cs — READ EXISTING FILE
+   → Extract existing role-permission mappings
+   → For each NEW permission:
+     - Admin → wildcard or all new permissions
+     - Manager → Read + Create + Update for new section
+     - Contributor → Read + Create for new section
+     - Viewer → Read for new section
+   → PRESERVE all existing mappings unchanged
+```
+
+---
+
+### Infrastructure Provider (CREATE or UPDATE)
+
+#### If SEED_MODE = "CREATE"
 
 ```
 7. {App}SeedDataProvider.cs
@@ -63,8 +141,38 @@ TaskUpdate(taskId: progress_tracker_id,
    → DI: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()
 ```
 
+#### If SEED_MODE = "UPDATE"
+
+```
+7. {App}SeedDataProvider.cs — READ EXISTING FILE
+   → Verify SeedNavigationAsync() calls the module's NavigationModuleSeedData
+   → If new sections were added: verify they are seeded (new section entries are part of existing methods)
+   → Verify SeedPermissionsAsync() covers new PermissionsSeedData entries
+   → Verify SeedRolePermissionsAsync() covers new RolesSeedData entries
+   → Add any missing calls or registrations
+   → PRESERVE all existing logic unchanged
+```
+
 <!-- TODO A4: Replace direct seed generation with MCP scaffold_seed_data when B1 is ready. This will eliminate the need for references/core-seed-data.md (1464 lines). -->
 
+---
+
+### Post-Layer 1 Verification Checklist
+
+> **Before the build gate, verify ALL new scope elements are covered:**
+
+```
+For each section in {sections} from step-00:
+  ✓ NavigationModuleSeedData has section entry + translations (4 langs)
+  ✓ NavigationModuleSeedData has route: /{app}/{module}/{section}
+  ✓ Permissions.cs has constants for this section (Read/Create/Update/Delete/Wildcard)
+  ✓ PermissionsSeedData has HasData() for each permission
+  ✓ RolesSeedData maps all 4 roles to section permissions
+  ✓ {App}SeedDataProvider references all seed data classes
+
+IF any check fails → fix BEFORE build gate
+```
+
 ### Post-Layer 1 Build Gate
 
 ```bash

package/templates/skills/apex/steps/step-03c-layer2-backend.md

@@ -5,6 +5,8 @@ model: opus
 parent_step: steps/step-03-execute.md
 ---
 
+**ULTRA THINK about backend services: which services/controllers are NEW vs which need MODIFICATION for new entities/endpoints?**
+
 ## Layer 2 — Backend (Services + Controllers)
 
 ### Task Progress

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -5,6 +5,8 @@ model: opus
 parent_step: steps/step-03-execute.md
 ---
 
+**ULTRA THINK about frontend completeness: new pages, routes, i18n keys, AND permissions/navigation alignment with Layer 1 seed data.**
+
 # Layer 3 — Frontend (Pages + I18n + Documentation)
 
 ### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)

package/templates/skills/apex/steps/step-03e-layer4-devdata.md

@@ -5,6 +5,8 @@ model: opus
 parent_step: steps/step-03-execute.md
 ---
 
+**ULTRA THINK about dev data coverage: all NEW entities need realistic test data.**
+
 ## Layer 4 — DevData (optional)
 
 ### Task Progress

package/templates/skills/apex/steps/step-04-examine.md

@@ -8,6 +8,8 @@ next_step: steps/step-05-deep-review.md
 
 # Step 4: eXamine
 
+**ULTRA THINK about completeness. Did ALL new sections/entities get their navigation entries, permissions, and roles? Cross-check the scope from step-00 against what was actually generated in Layer 1.**
+
 > **This is the X in APEX.** Mandatory automated examination of all generated code.
 
 **Goal:** Verify everything works. MCP conventions, build, seed data, acceptance criteria.
@@ -92,6 +94,8 @@ If migration fails (SQLite-only syntax, type mismatches, missing FK targets), fi
 
 ## 6. Seed Data Completeness Check (if needs_seed_data)
 
+> **CRITICAL — Cross-check against {sections} from step-00.** Every section in scope MUST have navigation, permissions, and roles. This is the most common miss when UPDATING an existing module.
+
 | File | Checks |
 |------|--------|
 | NavigationApplicationSeedData | 4 lang translations |
@@ -105,6 +109,20 @@ If migration fails (SQLite-only syntax, type mismatches, missing FK targets), fi
 | IClientSeedDataProvider | 4 Seed methods, idempotent, SaveChanges per group |
 | DI Registration | `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()` |
 
+### 6a. Section Coverage Matrix (MANDATORY for updates)
+
+```
+For EACH section in {sections} from step-00:
+  Read NavigationModuleSeedData.cs → has section entry?       YES / NO
+  Read NavigationModuleSeedData.cs → has translations (4)?    YES / NO
+  Read NavigationModuleSeedData.cs → has route?               YES / NO
+  Read Permissions.cs → has section permissions?              YES / NO
+  Read PermissionsSeedData.cs → has HasData() entries?        YES / NO
+  Read RolesSeedData.cs → has role-permission mappings?       YES / NO
+
+IF ANY cell = NO → BLOCKING — return to step-03b to fix
+```
+
 ---
 
 ## 6b. POST-CHECKs

package/templates/skills/dev-start/SKILL.md

@@ -278,7 +278,9 @@ If `--frontend-only`: skip backend checks.
 
 ## Step 5: Launch backend
 
-If NOT already running and NOT `--frontend-only`:
+Track whether the backend was just launched: `BACKEND_JUST_LAUNCHED=true/false`. This is used in Step 7 for cache invalidation.
+
+If NOT already running and NOT `--frontend-only` (set `BACKEND_JUST_LAUNCHED=true`):
 
 ```bash
 # cd into the API directory first
@@ -313,8 +315,10 @@ Use `Bash(run_in_background=true)` so it runs in background.
 
 ## Step 7: Handle admin password
 
-1. If `.claude/dev-session.json` exists and contains a password and `--reset` NOT specified -> reuse stored credentials
-2. If `--reset` OR no stored password:
+**Cache invalidation rule:** If the backend was just launched in Step 5 (i.e., it was NOT already running), the cache is STALE because `MigrateAsync()` + `HasData()` may have re-seeded the admin user with the default password hash, overwriting any previously set password. In this case, ALWAYS run a fresh admin reset regardless of `dev-session.json`.
+
+1. If `.claude/dev-session.json` exists and contains a password AND `--reset` NOT specified AND the backend was already running (NOT launched in Step 5) -> reuse stored credentials
+2. If `--reset` OR no stored password OR backend was just launched in Step 5:
    a. If backend was just launched, wait for it to be UP first.
       Run the full wait in a **single bash command** to avoid multiple tool calls:
       ```bash
@@ -335,9 +339,9 @@ Use `Bash(run_in_background=true)` so it runs in background.
       If `/scalar` does not respond after 30s, warn the user and attempt the reset anyway.
    b. Run admin reset using the connection string extracted from appsettings (Step 3):
       ```bash
-      smartstack admin reset --connection "{CONN_STR}" --force --json
+      smartstack admin reset --connection '{CONN_STR}' --force --json
       ```
-      **IMPORTANT:** Always pass `--connection` with the full connection string. Without it, the CLI shows an interactive environment picker that blocks execution.
+      **IMPORTANT:** Always pass `--connection` with the full connection string (single-quoted to avoid shell expansion). Without it, the CLI shows an interactive environment picker that blocks execution.
    c. Parse JSON output to extract email and password
    d. Write `.claude/dev-session.json`:
       ```json
@@ -380,7 +384,7 @@ Use `Bash(run_in_background=true)` so it runs in background.
 1. **NEVER debug or fix code** - This skill ONLY starts processes. If the backend or frontend fails to start, display the error and STOP. Do NOT attempt to: clean/restore/rebuild, upgrade packages, inspect DLLs, clear NuGet cache, read .csproj files, or any other diagnostic/repair action. The user will fix the issue themselves.
 2. **Fail-fast on crash** - After launching backend in background, wait 5s then check TaskOutput. If the process already exited or shows errors, report and STOP immediately.
 3. **Backend must be READY before admin reset** - First poll the port (netstat), then poll the `/scalar` endpoint (HTTP 200/302) to confirm the API is fully initialized. Kestrel binds the port before the app finishes starting, so port-only checks are insufficient.
-4. **Admin reset requires --connection** - Always pass `--connection "{CONN_STR}"` to avoid the interactive environment picker.
+4. **Admin reset requires --connection** - Always pass `--connection '{CONN_STR}'` (single-quoted to avoid shell expansion) to avoid the interactive environment picker.
 5. **Read config files in parallel** - When reading appsettings, .env, and launchSettings, use multiple Read calls in a single message.
 6. **Cross-worktree support** - Detect the correct API directory regardless of which worktree we're in.
 7. **No MCP required** - This skill only uses bash commands and the `smartstack` CLI.