@atlashub/smartstack-cli 3.46.0 → 3.47.0

package/package.json

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

package/templates/skills/apex/SKILL.md

@@ -64,6 +64,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{module_complexity}` | string | "simple-crud", "crud-rules", "crud-workflow", "complex" |
 | `{has_dependencies}` | string | "none", "references", "unknown" |
 | `{key_properties}` | string[] | Key business properties mentioned by user |
+| `{code_patterns}` | object[] | Per-entity code generation config [{entity, strategy, prefix, digits, includeTenantSlug, separator}] |
 | `{prd_path}` | string? | `.ralph/prd-{module}.json` if exists |
 | `{feature_path}` | string? | `docs/business/.../feature.json` if exists |
 | `{needs_seed_data}` | boolean | Seed data creation required |

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

@@ -38,26 +38,37 @@ For each entity found (or to be created), determine the `tenantMode`:
 
 ## Code Pattern Detection
 
-For each entity found (or to be created), identify code generation needs:
+For each entity found (or to be created), identify code generation needs using the following **priority order**:
 
 ```
-IF feature.json exists AND entity has codePattern:
-  → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
-  → Record in analysis: entity has auto-generated code
-
-ELSE IF feature.json exists BUT entity has NO codePattern:
-  → Record: entity needs codePattern decision in step-02
-  → Apply heuristic default based on entity name:
-    Invoice/Order/Receipt → timestamp-daily
-    Ticket/Incident → timestamp-minute
-    Contract/Policy → year-sequential
-    Reference/Category → uuid-short
-    Employee/Customer/Project → sequential
-
-ELSE (no feature.json):
-  → Propose codePattern during step-02 planning based on task description
+PRIORITY 1 — User choice from challenge questions (step-00):
+  IF {code_patterns} is set (from step-00 section 5c):
+    → Use {code_patterns} for each entity
+    → This is the user's explicit choice — always takes precedence
+
+PRIORITY 2 — feature.json (from /business-analyse):
+  IF feature.json exists AND entity has codePattern:
+    → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
+    → Record in analysis: entity has auto-generated code
+
+PRIORITY 3 — Heuristic fallback (delegate mode ONLY):
+  IF delegate_mode AND no code pattern from Priority 1 or 2:
+    → Apply heuristic default based on entity name:
+      Invoice/Order/Receipt/PurchaseOrder → timestamp-daily
+      Ticket/Incident/SupportRequest → timestamp-minute
+      Contract/Policy/Agreement → year-sequential
+      Category/Status/Type (reference data) → uuid-short
+      Employee/Customer/Project → sequential
+    → WARNING: heuristic applied — PRD was incomplete
+
+FALLBACK — Manual (safest default):
+  IF none of the above apply:
+    → strategy: "manual" (Code field in CreateDto, user-provided)
+    → No auto-generation, no ICodeGenerator injection
 ```
 
+**IMPORTANT:** In interactive mode (no `-d` flag), heuristics are NEVER applied silently. The user is always asked via challenge questions (step-00 section 5c). Heuristics only serve as fallback in delegate mode when the PRD is incomplete.
+
 **Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
 
 **Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.

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

@@ -158,6 +158,149 @@ questions:
 
 ---
 
+## 5c. Code Generation Strategy
+
+> **Purpose:** When `/apex` is used directly (without `/business-analyse`), the user is never asked about entity code generation strategy. This section fills that gap with a rapid, consolidated question.
+
+### Skip Conditions
+
+```
+IF delegate_mode (-d flag):
+  → SKIP (ralph-loop / PRD already defines code patterns)
+
+IF feature.json exists AND ALL entities have codePattern defined:
+  → SKIP (BA already collected code patterns)
+  → Extract {code_patterns} from feature.json for each entity
+
+IF foundation_mode (--foundation):
+  → SKIP (foundation generates entities but code strategy comes from PRD)
+```
+
+### Code Pattern Heuristic — `suggestCodePattern(entityName)`
+
+Suggests a recommended strategy + prefix based on entity name:
+
+```
+FUNCTION suggestCodePattern(entityName):
+  prefix = KNOWN_PREFIXES[entityName] ?? entityName[0:3].toLowerCase()
+  strategy = KNOWN_STRATEGIES[entityName] ?? "sequential"
+  digits = 5  # default (covers 99,999 records per tenant)
+  RETURN { strategy, prefix, digits, includeTenantSlug: true, separator: "-" }
+
+KNOWN_PREFIXES:
+  Employee → "emp", Invoice → "inv", Contract → "ctr",
+  Order → "ord", Ticket → "tkt", Project → "prj",
+  Customer → "cus", Product → "prd", Expense → "exp",
+  Leave → "lev", Department → "dep", Document → "doc"
+
+KNOWN_STRATEGIES:
+  Invoice, Order, Receipt, PurchaseOrder → "timestamp-daily"
+  Ticket, Incident, SupportRequest → "timestamp-minute"
+  Contract, Policy, Agreement → "year-sequential"
+  Category, Status, Type (reference data) → "uuid-short"
+  DEFAULT → "sequential"
+```
+
+### Question — Single Entity (1 entity)
+
+When `{entities}.length == 1`:
+
+```yaml
+# Compute suggestion first
+suggestion = suggestCodePattern({entities}[0])
+example = "{suggestion.prefix}-{tenantSlug}-00001"  # or appropriate format per strategy
+
+questions:
+  - header: "Code"
+    question: "How should the code for '{entities[0]}' be generated?"
+    options:
+      - label: "Auto-generate: {suggestion.strategy} with prefix '{suggestion.prefix}' (Recommended)"
+        description: "Example: {example} — auto-generated, excluded from CreateDto"
+      - label: "Auto-generate with custom settings"
+        description: "Choose strategy, prefix, and separator yourself"
+      - label: "Manual (user-provided)"
+        description: "Code field included in CreateDto — user enters the code manually"
+    multiSelect: false
+```
+
+**Follow-up if "custom settings":**
+```yaml
+questions:
+  - header: "Strategy"
+    question: "Which code generation strategy for '{entities[0]}'?"
+    options:
+      - label: "sequential"
+        description: "Simple incrementing counter: {prefix}-{tenant}-00001, 00002, ..."
+      - label: "timestamp-daily"
+        description: "Date-based: {prefix}-{tenant}-20260222-001"
+      - label: "year-sequential"
+        description: "Year prefix: {prefix}-{tenant}-2026-00001"
+      - label: "uuid-short"
+        description: "Short unique ID: {prefix}-{tenant}-a1b2c3"
+    multiSelect: false
+  - header: "Prefix"
+    question: "What prefix for the code? (2-6 lowercase letters)"
+    options:
+      - label: "{suggestion.prefix} (Recommended)"
+        description: "Auto-suggested from entity name"
+      - label: "Custom"
+        description: "Enter your own prefix in 'Other'"
+    multiSelect: false
+```
+
+### Question — Multiple Entities (2+ entities)
+
+When `{entities}.length >= 2`:
+
+```
+Compute suggestions for ALL entities:
+  recommendations = {entities}.map(e => { entity: e, ...suggestCodePattern(e) })
+
+Display table:
+  | Entity | Strategy | Prefix | Example |
+  |--------|----------|--------|---------|
+  | Employee | sequential | emp | emp-{tenant}-00001 |
+  | Contract | year-sequential | ctr | ctr-{tenant}-2026-00001 |
+```
+
+```yaml
+questions:
+  - header: "Code"
+    question: "How should entity codes be generated? (see recommendations above)"
+    options:
+      - label: "Accept all recommendations (Recommended)"
+        description: "Use the suggested strategy and prefix for each entity"
+      - label: "All manual (user-provided)"
+        description: "No auto-generation — Code field in CreateDto for all entities"
+      - label: "Customize per entity"
+        description: "Choose strategy individually for each entity"
+    multiSelect: false
+```
+
+**If "Customize per entity":**
+→ Loop through each entity and ask the single-entity question (section above).
+
+### Storage Format
+
+```yaml
+{code_patterns}:
+  - entity: "Employee"
+    strategy: "sequential"
+    prefix: "emp"
+    digits: 5
+    includeTenantSlug: true
+    separator: "-"
+  - entity: "Contract"
+    strategy: "year-sequential"
+    prefix: "ctr"
+    digits: 5
+    includeTenantSlug: true
+    separator: "-"
+  # strategy: "manual" → no auto-generation for this entity
+```
+
+---
+
 ## Delegate Mode Skip (if -d flag)
 
 When `/ralph-loop` invokes `/apex -d {prd_path}`, ALL hierarchy is extracted from the PRD file: