@atlashub/smartstack-cli 3.37.0 → 3.39.0

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

@@ -1,6 +1,6 @@
 ---
 name: step-00-init
-description: Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge the need
+description: Parse flags, detect application, verify MCP, define hierarchy (4 levels), challenge the need
 model: sonnet
 next_step: steps/step-01-analyze.md
 ---
@@ -62,7 +62,6 @@ IF delegate_mode:
   Read prd.json from {delegate_prd_path}
 
   Extract context:
-    {context_code}      = prd.project.context          (e.g., "business")
     {app_name}          = prd.project.application       (e.g., "HumanResources")
     {module_code}       = prd.project.module            (e.g., "EmployeeManagement")
     {prd_path}          = {delegate_prd_path}
@@ -89,13 +88,13 @@ IF delegate_mode:
     {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 context), 4 (hierarchy), 5 (challenge questions)
+  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)
 ```
 
 ---
 
-## 2. Detect SmartStack Context
+## 2. Detect SmartStack Application
 
 Scan the project to identify the SmartStack hierarchy:
 
@@ -107,7 +106,6 @@ Scan the project to identify the SmartStack hierarchy:
 ```
 
 **From task description, infer:**
-- `{context_code}`: business (default), platform, personal
 - `{app_name}`: application name
 - `{module_code}`: target module
 - `{sections}`: sections being added/modified
@@ -116,7 +114,7 @@ Scan the project to identify the SmartStack hierarchy:
 - `{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 context detection question from `references/challenge-questions.md`.
+If hierarchy cannot be inferred → load application question from `references/challenge-questions.md`.
 
 ---
 
@@ -131,24 +129,14 @@ IF failure → warn user, continue in degraded mode (manual tools only)
 
 ---
 
-## 4. Define Navigation Hierarchy (5 Levels)
+## 4. Define Navigation Hierarchy (4 Levels)
 
-> **BLOCKING RULE:** SmartStack uses a 5-level navigation hierarchy:
-> **Context → Application → Module → Section → Resource**
->
-> **Every module MUST have at least one section.** A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
-
-### 4a. Validate Application Level
-
-Load and execute application question from `references/challenge-questions.md` section 4a.
-
-### 4b. Validate Module Level
-
-Load and execute module question from `references/challenge-questions.md` section 4b.
-
-### 4c. Define Sections (MANDATORY — at least one)
-
-Load and execute section questions from `references/challenge-questions.md` section 4c (includes validation and storage format).
+> **Reference:** Load `references/initialization-challenge-flow.md` for detailed challenge flow:
+> - 4-level hierarchy structure (Application → Module → Section → Resource)
+> - Challenge questions (4a: Application, 4b: Module, 4c: Sections)
+> - Validation rules (sections MUST have at least one entry)
+> - Storage format for each level
+> - Delegate mode skip (if -d)
 
 ### 4d. Resources (Optional)
 
@@ -163,8 +151,8 @@ Resources are OPTIONAL — only define if explicitly mentioned or inferred.
 Display before proceeding:
 
 ```
-{context_code} → {app_name} ({app_code}) → {module_code} → [{sections[].code}]
-Routes: /{context_code}/{app-kebab}/{module-kebab}/{section-kebab}
+{app_name} ({app_code}) → {module_code} → [{sections[].code}]
+Routes: /{app-kebab}/{module-kebab}/{section-kebab}
 ```
 
 ---
@@ -305,7 +293,7 @@ IF save_mode:
 ```
 APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
-Context: {context_code} → {app_name} → {module_code} → {sections[].code}
+Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
 PRD: {prd_path||none} | Feature: {feature_path||none} | Flags: {active_flags}
 MCP: {available|degraded} | Needs: migration/seed/workflow/notification = {yes|no}

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

@@ -141,149 +141,16 @@ Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedCons
 
 ---
 
-## 4. FK Field Detection
-
-For each entity found (or to be created), identify FK relationships:
-- Properties ending in "Id" with matching navigation property
-- Record: `{ entity, fkProperty, targetEntity, isRequired }`
-
-**Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>` — even with API-loaded options)
-2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
-
----
-
-## 4a. Tenant Mode Decision
-
-For each entity found (or to be created), determine the `tenantMode`:
-
-- **`strict`** (default) — Data belongs to a specific tenant. Examples: Employee, Order, Invoice, CustomerInteraction
-- **`optional`** — Data can be shared across tenants OR tenant-specific. Examples: Department, Currency, JobTitle, Language
-- **`scoped`** — Data has explicit visibility scope controlled by workflow/feature rules. Examples: Settings, Workflow, EmailTemplate, ApprovalConfig
-- **`none`** — Platform-wide data (never tenant-filtered). Examples: Navigation, Permission, User, SystemConfiguration
-
-**Why:** Tenant mode drives EF query filters, seed data generation, and API access control. Must be decided before planning.
-
-**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
-
----
-
-## 4b. Code Pattern Detection
-
-For each entity found (or to be created), identify code generation needs:
-
-```
-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
-```
-
-**Why:** Code generation strategy drives CreateDto structure (Code field removed when auto-generated), service injection (ICodeGenerator<T>), and DI registration. Must be decided before planning.
-
-**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
-
----
-
-## 5. Gap Analysis
-
-Compare what EXISTS vs what the TASK REQUIRES:
-
-```
-For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
-```
-
-Cross-reference with step-00 challenge responses:
-- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
-- Each section: NavigationSectionSeedData, frontend route → exists/missing
-- If dependencies: verify FK target entities and their `?search=` support
-
----
-
-## 5b. Scope Re-Check (after exploration)
-
-> **Re-validate scope after code exploration reveals the true entity count.**
-> Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
-
-```
-IF NOT delegate_mode:
-  actual_entities = count of entities marked "create" in gap analysis
-  actual_sections = count of sections marked "create"
-
-  IF actual_entities > 6:
-    WARNING: "Code exploration reveals {actual_entities} entities to create.
-     This exceeds the recommended maximum (4) for a single /apex invocation.
-     Risk: incomplete migrations, lost conventions, missing pages.
-     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
-
-    AskUserQuestion: (same options as step-00 section 5d)
-```
-
----
-
-## 6. Analysis Validation (User Checkpoint)
-
-> **Objective:** Present findings and validate scope with the user BEFORE planning.
-
-### 6a. Present Findings
-
-```
-ANALYSIS FINDINGS
-═══════════════════════════════════════════════════════════════
-
-Entities expected / found / to create: {summary}
-Sections expected / found / to create: {summary}
-FK Relationships: {fkFields summary}
-Dependencies: {cross-module refs or "none"}
-Complexity: {module_complexity}
-```
-
-### 6b. Validate with User (if NOT auto_mode)
-
-```yaml
-questions:
-  - header: "Scope"
-    question: "Based on the analysis above, is the scope accurate?"
-    options:
-      - label: "Scope is correct (Recommended)"
-        description: "Proceed to planning with the identified elements"
-      - label: "Add elements"
-        description: "I need to add entities, properties, or sections"
-      - label: "Reduce scope"
-        description: "Remove some elements — smaller first iteration"
-      - label: "Change approach"
-        description: "The analysis reveals issues — let's adjust"
-    multiSelect: false
-```
-
-If "Add elements": update `{entities}`, `{sections}`, `{key_properties}`, re-run gap analysis.
-If "Reduce scope": update variables accordingly.
-If "Change approach": discuss with user, potentially restart from step-00.
-
----
-
-## 7. Analysis Summary
-
-```
-**APEX SmartStack - Analysis Complete**
-Navigation: {context_code} → {app_name} → {module_code} → {sections[].code}
-Entities: {entity_name → create | modify | skip}
-Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
-Required: create / modify / skip lists
-Profile: complexity, dependencies, FK fields, workflow, notifications
-ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
-```
+## 4-7. Analysis Methods & Validation
+
+> **Reference:** Load `references/analysis-methods.md` for detailed analysis procedures:
+> - FK field detection (frontend EntityLookup + backend search support)
+> - Tenant mode decision (strict/optional/scoped/none)
+> - Code pattern detection (auto-generated strategies)
+> - Gap analysis (exists/missing/modify classification)
+> - Scope re-check (entity count validation)
+> - Analysis validation checkpoint (user confirmation)
+> - Analysis summary output format
 
 ---
 

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

@@ -52,98 +52,16 @@ IF delegate_mode:
 
 ---
 
-## 1. Map Changes to Layers
-
-For each element identified in step-01 (create or modify), assign to a SmartStack layer:
-
-| Layer | Category | Order |
-|-------|----------|-------|
-| 0 | Domain (entities, enums, exceptions) | Sequential |
-| 0 | Infrastructure - EF Configs | Sequential |
-| 0 | Infrastructure - Migration (BLOCKING) | Sequential |
-| 1 | Application (services, DTOs, validators) | Parallel |
-| 1 | API (controllers) | Parallel |
-| 1 | Infrastructure - Seed Data | Parallel |
-| 2 | Frontend (pages, components) | Parallel |
-| 2 | I18n (translations) | Parallel |
-| 3 | Tests | Sequential |
-
-**Entity Definition Template:** Each entity in the plan MUST include:
-```
-Entity: {EntityName}
-  - tenantMode: strict | optional | scoped | none
-  - codePattern: auto-generated strategy (if applicable)
-  - fkFields: [{field, targetEntity}] (if applicable)
-  - acceptance criteria: [AC1, AC2, ...]
-```
-
-The `tenantMode` decision (from step-01, section 4a) drives EF query filters, seed data approach, and API authorization. See `smartstack-layers.md` for tenant mode seed data strategies.
-
----
-
-## 2. Assign Skill/MCP per File
-
-For EACH file in the plan, specify HOW it will be created/modified:
-
-```markdown
-### Layer 0 — Domain + Infrastructure (sequential)
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 1 | Domain/Entities/.../MyEntity.cs | create | MCP scaffold_extension |
-| 2 | Infrastructure/.../MyEntityConfiguration.cs | create | MCP scaffold_extension |
-| 3 | Migration | create | MCP suggest_migration + dotnet ef |
-
-### Layer 1 — Application + API (parallel)
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 4 | Application/Services/.../MyService.cs | create | MCP scaffold_extension |
-| 5 | Application/DTOs/.../MyDto.cs | create | MCP scaffold_extension |
-| 6 | Api/Controllers/.../MyController.cs | create | /controller skill |
-| 7 | Seeding/Data/NavigationApplicationSeedData.cs | create | ref smartstack-layers.md (once per app) |
-| 7b | Seeding/Data/ApplicationRolesSeedData.cs | create | ref smartstack-layers.md (once per app) |
-| 7c | Infrastructure/Services/CodeGeneration/ | create | ref code-generation.md (ICodeGenerator<T> + DI, per entity with codePattern != manual) |
-| 8 | Seeding/Data/.../NavigationModuleSeedData.cs | create | ref smartstack-layers.md |
-| 8b | Application/Authorization/Permissions.cs | create | MCP generate_permissions → static constants |
-| 9 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
-| 10 | Seeding/Data/.../RolesSeedData.cs | create | ref smartstack-layers.md |
-
-### Layer 2 — Frontend + I18n (parallel)
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 11 | src/pages/{Ctx}/{App}/{Mod}/ListPage.tsx | create | /ui-components skill |
-| 11b | src/pages/{Ctx}/{App}/{Mod}/CreatePage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
-| 11c | src/pages/{Ctx}/{App}/{Mod}/EditPage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
-| 11d | src/pages/{Ctx}/{App}/{Mod}/{Section}Page.tsx | create | /ui-components skill (per section in `{sections}`) |
-| 11e | src/pages/{Ctx}/{App}/{Mod}/{Section}DetailPage.tsx | create | /ui-components skill (per section in `{sections}`) |
-| 12 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
-| 13 | src/routes/{module}.tsx | create | MCP scaffold_routes |
-| 14 | src/i18n/locales/{lang}/{module}.json | create | ref smartstack-frontend.md (4 languages: fr, en, it, de) |
-
-**FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6). The corresponding backend GetAll endpoints (Layer 1) MUST support `?search=` parameter.
-
-### Layer 2b — Documentation (after frontend pages exist)
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 14b | src/pages/docs/business/{app}/{module}/doc-data.ts | create | /documentation skill |
-| 14c | src/pages/docs/business/{app}/{module}/index.tsx | create | /documentation skill |
-
-### Layer 3 — Tests (sequential)
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 15 | tests/.../MyEntityTests.cs | create | MCP scaffold_tests |
-| 16 | tests/.../MyServiceTests.cs | create | MCP scaffold_tests |
-```
-
----
-
-## 3. Identify Parallelization (Agent Teams)
-
-If NOT economy_mode AND Layer 1 has both backend and frontend work:
+## 1-3. Layer Mapping, Skill Assignment, Parallelization
+
+> **Reference:** Load `references/planning-layer-mapping.md` for detailed planning procedures:
+> - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
+> - Entity definition template (tenantMode, codePattern, fkFields, ACs)
+> - Skill/MCP assignment table (per file, per layer)
+> - Layer 0/1/2b/3 file lists with tools
+> - FK field guidance (EntityLookup + backend ?search= parameter)
+> - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
+> - Delegate mode fast path (PRD task mapping to layers)
 
 ```
 Layer 0: SEQUENTIAL (agent principal)