@atlashub/smartstack-cli 4.31.0 → 4.33.0

package/templates/skills/apex/references/smartstack-layers.md

@@ -277,7 +277,7 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 | Action | Tool |
 |--------|------|
 | API client | MCP `scaffold_api_client` |
-| Routes | MCP `scaffold_routes` (outputFormat: `applicationRoutes`) |
+| Routes | MCP `scaffold_routes` (outputFormat: `componentRegistry`) |
 | Complex pages | /ui-components skill + `smartstack-frontend.md` patterns |
 | Validate routes | MCP `validate_frontend_routes` |
 
@@ -312,6 +312,9 @@ const [loading, setLoading] = useState(true);
 
 ### RULE — Frontend Route Ordering
 
+> **Note (v3.7+):** Route ordering is handled automatically by DynamicRouter.
+> The ordering rules below apply only to legacy Pattern A/B projects.
+
 > **CRITICAL:** React Router matches routes top-to-bottom. Dynamic routes (`:id`, `:id/edit`) placed BEFORE static routes (`dashboard`, `create`) will swallow the static paths — e.g., `/employees/dashboard` matches `:id` with `id="dashboard"` → 404.
 
 **Order (MANDATORY):**
@@ -346,12 +349,15 @@ POST-CHECK C49 detects this anti-pattern and BLOCKS.
 
 ### Section Routes (when module has sections)
 
-If the module defines `{sections}`, generate frontend routes for EACH section as children of the application route.
+> **Note (v3.7+):** With DynamicRouter, section routes are resolved automatically from navigation
+> seed data + PageRegistry. The manual wiring below applies only to legacy Pattern A/B projects.
+
+If the module defines `{sections}`, ensure navigation seed data has ComponentKey matching PageRegistry keys.
+ComponentKey convention: `{app_code}.{module_code}.{section_code}` (dot-separated, lowercase).
+DynamicRouter generates the URL paths from seed data Route field.
 
-> **CRITICAL — Module Segment Required:** Route paths in `applicationRoutes['{app}']` are RELATIVE to the application root.
-> They MUST include the module segment: `{module-kebab}/{section-kebab}`, NOT just `{section-kebab}`.
-> Without the module segment, the route resolves to `/{app}/{section}` instead of `/{app}/{module}/{section}`,
-> causing a mismatch with backend navigation seed data routes → nav links produce 404s.
+Legacy (Pattern A/B): generate frontend routes for EACH section as children of the application route.
+Route paths MUST include the module segment: `{module-kebab}/{section-kebab}`.
 
 ```tsx
 // Routes in applicationRoutes['human-resources'] — RELATIVE paths include module segment

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

@@ -23,103 +23,48 @@ Read `_shared.md` for SmartStack detection patterns and MCP tools reference.
 
 ## 1. Parse Flags
 
-Extract flags from the raw input:
+Extract flags from input: `-a, -x, -s, -e, -r, -pr, -d {path}, --foundation`
 
-```
-Input: "{raw_input}"
-
-Flags to detect: -a, -x, -s, -e, -r, -pr, -d {path}, --foundation
-Remaining text after flag removal = {task_description}
-```
-
-**Defaults:**
-
-```yaml
-auto_mode: false
-examine_mode: false
-save_mode: false
-economy_mode: false
-pr_mode: false
-resume_mode: false
-delegate_mode: false
-delegate_prd_path: null
-foundation_mode: false
-```
-
-**If `-d {path}` detected:** set `delegate_mode = true`, `delegate_prd_path = {path}`, force `auto_mode = true`, `economy_mode = true`.
+| Flag | Sets | Force |
+|------|------|-------|
+| `-a` | auto_mode | — |
+| `-x` | examine_mode | — |
+| `-s` | save_mode | — |
+| `-e` | economy_mode | — |
+| `-r` | resume_mode | — |
+| `-pr` | pr_mode | — |
+| `-d {path}` | delegate_mode, delegate_prd_path | auto_mode, economy_mode |
+| `--foundation` | foundation_mode | auto_mode |
 
-**If `--foundation` detected:** set `foundation_mode = true`, force `auto_mode = true`. Foundation mode generates ONLY entities + EF configs + migration (domain + infrastructure layers). Skip application/api/frontend/tests.
+**Special behaviors:** `-d {path}` enables delegate mode (extract context from PRD). `--foundation` generates ONLY entities + EF configs + migration (domain + infrastructure layers only).
 
 ---
 
 ## 1b. Delegate Mode Fast Path (if -d)
 
-> **When `/ralph-loop` invokes `/apex -d {prd_path}`, all context is extracted from the PRD file.**
-> Skip interactive sections (hierarchy definition, challenge questions).
+When `-d {prd_path}` is used, extract all context from PRD file and skip sections 2, 4, 5:
 
-```
-IF delegate_mode:
-  Read prd.json from {delegate_prd_path}
-
-  Extract context:
-    {app_name}          = prd.project.application       (e.g., "HumanResources")
-    {module_code}       = prd.project.module            (e.g., "EmployeeManagement")
-    {prd_path}          = {delegate_prd_path}
-    {feature_path}      = prd.source.feature_json_path  (if exists)
-
-  Extract sections from infrastructure tasks with _seedDataMeta:
-    Find task where _seedDataMeta.coreSeedData.navigationSections exists
-    {sections} = _seedDataMeta.coreSeedData.navigationSections[]
-    → map to: { code, label, description, route, displayOrder, navigation }
-
-  Extract entities from domain tasks:
-    {entities} = prd.tasks.filter(t => t.category == 'domain').map(t => entity name from t.description)
-
-  Extract code patterns from feature.json (if available):
-    IF {feature_path} exists:
-      Read feature.json → for each entity with codePattern defined:
-        {code_patterns}[] += { entity, strategy, prefix, digits, includeTenantSlug, separator }
-    ELSE:
-      {code_patterns} = []  # will use heuristic fallback in analysis-methods.md
-
-  Extract complexity:
-    {module_complexity} = heuristic from task count:
-      <= 10 tasks → "simple-crud"
-      <= 20 tasks → "crud-rules"
-      <= 30 tasks → "crud-workflow"
-      > 30 tasks  → "complex"
-
-  Set needs:
-    {needs_seed_data}    = prd.tasks.some(t => t.category == 'seedData' || t.category == 'infrastructure')
-    {needs_migration}    = prd.tasks.some(t => t._migrationMeta != null)
-    {has_dependencies}   = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
-    {key_properties}     = [] (extracted during step-01 from feature.json if available)
-
-  SKIP sections 2 (detect application), 4 (hierarchy), 5 (challenge questions)
-  Jump to section 3 (MCP verify) → then section 6 (determine needs, already set) → section 9 (summary)
-```
+**Extract from prd.json:**
+- `{app_name}` = prd.project.application
+- `{module_code}` = prd.project.module
+- `{sections}` = infrastructure tasks → _seedDataMeta.coreSeedData.navigationSections (map to code/label/description/route/displayOrder/navigation)
+- `{entities}` = domain tasks → extract entity names from descriptions
+- `{code_patterns}` = feature.json entity patterns (or [] for heuristic fallback)
+- `{module_complexity}` = heuristic from task count (≤10→"simple-crud", ≤20→"crud-rules", ≤30→"crud-workflow", >30→"complex")
+- `{needs_seed_data}` = any seedData/infrastructure tasks exist
+- `{needs_migration}` = any tasks with _migrationMeta
+- `{has_dependencies}` = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
+
+**Jump to:** section 3 (MCP verify) → section 6 (determine needs) → section 9 (summary)
 
 ---
 
 ## 2. Detect SmartStack Application
 
-Scan the project to identify the SmartStack hierarchy:
-
-```
-1. Glob("*.sln") → confirm .NET project
-2. Glob("docs/business/**/*") → list existing BA artifacts
-3. Glob(".ralph/prd-*.json") → list existing PRDs
-4. Glob("src/pages/**/*.tsx") → confirm frontend exists
-```
+Scan project: Glob("*.sln"), Glob("docs/business/**/*"), Glob(".ralph/prd-*.json"), Glob("src/pages/**/*.tsx")
 
-**From task description, infer:**
-- `{app_name}`: application name
-- `{module_code}`: target module
-- `{sections}`: sections being added/modified
-
-**From existing artifacts:**
-- `{prd_path}`: `.ralph/prd-{module_code}.json` if exists
-- `{feature_path}`: `docs/business/{app}/{module}/business-analyse/*/feature.json` if exists
+**Infer from task description:** {app_name}, {module_code}, {sections}
+**From artifacts:** {prd_path} = `.ralph/prd-{module_code}.json` (if exists), {feature_path} = `docs/business/{app}/{module}/business-analyse/*/feature.json` (if exists)
 
 If hierarchy cannot be inferred → load application question from `references/challenge-questions.md`.
 
@@ -136,200 +81,104 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 ---
 
-## 4. Define Navigation Hierarchy (4 Levels)
-
-> **Reference:** Load `references/challenge-questions.md` for hierarchy rules and challenge questions:
-> - 4-level hierarchy structure (Application → Module → Section → Resource)
-> - Challenge questions (4a: Application, 4b: Module, 4c: Sections, 5a: Entities, 5b: Dependencies, 5c: Code Generation)
-> - Validation rules (sections MUST have at least one entry)
-> - Storage format for each level
-> - Delegate mode skip (if -d)
-
-### 4d. Resources (Optional)
-
-If the task or feature.json mentions specific resources (export, import, bulk actions):
-```
-For each section, check if resources are needed.
-Resources are OPTIONAL — only define if explicitly mentioned or inferred.
-```
+## 4. Define Navigation Hierarchy
 
-### 4e. Hierarchy Summary
+Reference `references/challenge-questions.md` for 4-level structure (Application → Module → Section → Resource), validation rules, and challenge questions 4a-4c.
 
-Display before proceeding:
-
-```
-{app_name} ({app_code}) → {module_code} → [{sections[].code}]
+**Hierarchy Summary:** {app_name} ({app_code}) → {module_code} → [{sections[].code}]
 Routes: /{app-kebab}/{module-kebab}/{section-kebab}
-```
 
----
+**Resources:** OPTIONAL — only define if explicitly mentioned or inferred from task/feature.json (export, import, bulk actions).
 
-## 5. Challenge the Need
+### 4f. Naming Derivation Rules (DETERMINISTIC)
 
-> **Objective:** Even without a formal Business Analysis (`/business-analyse`), the need MUST be challenged to avoid obvious gaps. This is a rapid scope validation — 3-4 targeted questions to ensure the developer has thought through the fundamentals.
+All naming variants are derived from {app_name}, {module_code}, {sections}. Do NOT invent names.
 
-### 5a. Entity Scope & Relationships
+| Source | Derivation | Example |
+|--------|-----------|---------|
+| {app_name} | kebab: lowercase, hyphen-separated | `human-resources` |
+| {app_name} | PascalCase | `HumanResources` |
+| {module_code} | already kebab | `employee-management` |
+| {module_code} | PascalCase: remove hyphens, capitalize | `EmployeeManagement` |
+| {sections[].code} | already kebab | `employees` |
+| {sections[].code} | PascalCase | `Employees` |
+| NavRoute | `{app_name_kebab}.{module_code}.{section_code}` (dots) | `human-resources.employee-management.employees` |
+| API route | resolved dynamically by [NavRoute] from DB | N/A |
+| Permission | `{app_name_kebab}.{module_code}.{section_code}.{action}` | `human-resources.employee-management.employees.read` |
 
-Load and execute entity questions from `references/challenge-questions.md` section 5a.
+Call `mcp__smartstack__validate_conventions` after computing derivations. Fix any errors BEFORE step-01.
 
-### 5b. Dependencies & Key Properties
-
-Load and execute dependency questions from `references/challenge-questions.md` section 5b.
-
-### 5c. Code Generation Strategy
+---
 
-Load and execute code generation questions from `references/challenge-questions.md` section 5c.
+## 5. Challenge the Need
 
-**Skip if:**
-- `delegate_mode` is true (PRD defines code patterns)
-- `foundation_mode` is true (code strategy comes later)
-- `feature.json` exists AND all entities in `{entities}` have `codePattern` defined
+Rapid scope validation — load and execute questions from `references/challenge-questions.md`:
+- **5a:** Entity scope & relationships
+- **5b:** Dependencies & key properties
+- **5c:** Code generation strategy
 
-**If feature.json covers SOME but not all entities:**
-→ Only ask for entities without `codePattern` in feature.json
-→ Merge feature.json patterns + user answers into `{code_patterns}`
+**Skip 5c if:**
+- `delegate_mode = true` (PRD defines patterns)
+- `foundation_mode = true` (code strategy later)
+- `feature.json` exists AND all entities have `codePattern` defined
 
-### 5d. Store Responses
+**If feature.json covers SOME entities:** Only ask for entities without `codePattern`, merge responses.
 
-```yaml
-{entities}: string[]            # Main entities to manage
-{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 (from 5c or feature.json)
+**Store responses:**
 ```
-
-These values are propagated to:
-- **step-01 (Analyze):** Guide code exploration focus + code pattern detection (uses `{code_patterns}` as Priority 1)
-- **step-02 (Plan):** Inform layer mapping (e.g., workflow → needs /workflow skill)
-- **step-03 (Execute):** Entity scaffolding with correct properties, relationships, and code generation strategy
+{entities}, {module_complexity}, {has_dependencies}, {key_properties}, {code_patterns}
+```
+Propagated to: step-01 (code focus), step-02 (layer mapping), step-03 (scaffolding)
 
 ---
 
 ## 5e. Scope Complexity Guard
 
-> **Root cause (test-apex-007):** `/apex` was invoked with 3 applications and 7 entities.
-> The model's context window saturated, causing: incomplete migrations, lost conventions,
-> missing pages, unregistered i18n, forgotten DI registrations.
->
-> `/apex` is designed for **incremental** development (1 module at a time).
-> Multi-module projects should use `/ralph-loop` which calls `/apex -d` per module.
-
-### Scope Detection
+**Design:** `/apex` handles 1 module at a time. Use `/ralph-loop` for multi-module projects.
 
+**Calculate:**
 ```
-entity_count = {entities}.length
-section_count = {sections}.length
-app_count = number of DISTINCT applications detected in {task_description}
-           (heuristics: "application X et application Y", "module X, module Y, module Z"
-            with different app names, "3 apps", etc.)
-
 scope_score = entity_count + (section_count * 0.5) + (app_count * 3)
 ```
 
-### Guard Rules
-
-```
-IF delegate_mode (-d flag):
-  → SKIP guard (ralph-loop already handles scope per module)
-
-ELSE IF app_count > 1:
-  → Warning: "Multiple applications detected ({app_count} apps, {entity_count} entities).
-     /apex handles 1 module at a time. For multi-module projects, use:
-     - /ralph-loop (automated: reads PRD, generates all modules sequentially)
-     - Multiple /apex calls (manual: one /apex per module)
-
-     To proceed, split your request:
-       /apex -e add HR employee management
-       /apex -e add CRM client management
-       /apex -e add Project management"
-
-ELSE IF entity_count > 6:
-  → BLOCKING: "Too many entities ({entity_count}) for a single /apex invocation.
-     Context window saturation causes: incomplete migrations, lost conventions,
-     missing pages, unregistered i18n, forgotten DI registrations.
-     Maximum: 6 entities without delegate mode (-d).
-
-     Solutions:
-       /ralph-loop (automated multi-module orchestration)
-       /apex -d {prd_path} (delegate mode, called per module by ralph-loop)
-       Split manually: /apex add {first 3-4 entities} → then /apex add {remaining}"
-  → STOP execution
-
-ELSE IF scope_score > 8:
-  → WARNING: "Large scope detected ({entity_count} entities, {section_count} sections).
-     /apex works best with ≤ 4 entities per invocation.
-     Consider splitting into smaller iterations."
-
-  AskUserQuestion:
-    header: "Scope"
-    question: "Le périmètre est large ({entity_count} entités). Réduire le scope ou continuer ?"
-    options:
-      - label: "Continue anyway"
-        description: "Proceed with full scope (higher risk of omissions)"
-      - label: "Split into iterations"
-        description: "Focus on the first module/app, then run /apex again for the rest"
-      - label: "Use /ralph-loop"
-        description: "Switch to /ralph-loop for automated multi-module orchestration"
-
-  IF "Split" → ask user which module to focus on first, update {entities}/{sections}
-  IF "/ralph-loop" → display command to run, STOP execution
-
-ELSE:
-  → PASS (scope is manageable)
-```
-
-### Recommended Scope per /apex Invocation
+**Rules:**
+- `delegate_mode (-d)` → SKIP guard (ralph-loop handles scope per module)
+- `app_count > 1` → Warning: use `/ralph-loop` or split requests
+- `entity_count > 6` → BLOCKING: max 6 entities. Solutions: `/ralph-loop`, `/apex -d`, or split manually
+- `scope_score > 8` → WARNING: ask user to split or use `/ralph-loop`
 
+**Recommended Scope:**
 | Metric | Safe | Warning | Blocking |
 |--------|------|---------|----------|
-| Applications | 1 | 1 (large) | >1 |
+| Applications | 1 | 1 | >1 |
 | Entities | 1-4 | 5-6 | >6 without -d |
 | Sections | 1-3 | 4-5 | >5 without -d |
-| Sub-resources | 0-2 | 3-4 | >4 without -d |
 
 ---
 
 ## 6. Determine Needs
 
 ```
-needs_seed_data   = {sections}.length > 0 OR task mentions navigation/permissions/roles/seed
-needs_migration   = {entities}.length > 0 OR task mentions entity/field/table/column/migration
-needs_workflow    = {module_complexity} == "crud-workflow" OR task mentions workflow/email/approval
-needs_notification = {module_complexity} in ["crud-workflow","complex"] OR task mentions notification/alert
+needs_seed_data = {sections}.length > 0 OR mentions navigation/permissions/roles/seed
+needs_migration = {entities}.length > 0 OR mentions entity/field/table/column/migration
+needs_workflow = {module_complexity} == "crud-workflow" OR mentions workflow/email/approval
+needs_notification = {module_complexity} in ["crud-workflow","complex"] OR mentions notification/alert
 ```
 
 ---
 
 ## 7. Resume Mode (if -r)
 
-```
-IF resume_mode:
-  Read .claude/output/apex/ → find latest task directory (by timestamp)
-
-  IF state.json exists:
-    → Read state.json for precise layer-level resume:
-      completed_layers, completed_entities, files_created, build_gates, commits
-    → Resume step-03 at NEXT uncompleted layer (skip completed layers entirely)
-    → Re-derive remaining state variables from existing files + git log
-
-  ELSE IF 00-context.md exists:
-    → Restore state from 00-context.md (step-00 output only)
-    → Re-derive post-step-00 state from git history + existing files
-
-  ELSE:
-    → Full re-derive from git history + existing files (slowest path)
-```
+Read latest task directory in `.claude/output/apex/`:
+- **If state.json exists:** resume step-03 at next uncompleted layer (skip completed)
+- **Else if 00-context.md exists:** restore step-00 state, re-derive post-step-00 from git + files
+- **Else:** full re-derive from git history + files
 
 ---
 
 ## 8. Save Mode Setup (if -s)
 
-```
-IF save_mode:
-  Generate task_id → create .claude/output/apex/{task_id}/ → write 00-context.md
-  (timestamp, state variables, flags, hierarchy, challenge responses)
-```
+Generate task_id → create `.claude/output/apex/{task_id}/` → write `00-context.md` with timestamp, state, flags, hierarchy, responses
 
 ---
 
@@ -340,14 +189,8 @@ APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
 Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
-Code: {code_patterns summary — e.g., "Employee:sequential(emp), Contract:year-seq(ctr)" or "all manual" or "none"}
-PRD: {prd_path||none} | Feature: {feature_path||none} | Flags: {active_flags}
-MCP: {available|degraded} | Needs: migration/seed/workflow/notification = {yes|no}
+Code: {code_patterns summary} | PRD: {prd_path||none} | Feature: {feature_path||none}
+Flags: {active_flags} | MCP: {available|degraded} | Needs: {migration/seed/workflow/notification}
 NEXT STEP: step-01-analyze
 ```
 
----
-
-## NEXT STEP
-
-Load `steps/step-01-analyze.md`