@atlashub/smartstack-cli 3.38.0 → 3.39.0

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -1,199 +1,199 @@
-# Navigation: Fallback Procedure (When MCP Unavailable)
-
-> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
-> Reference: `templates-seed.md` for code templates.
->
-> **Branch by Project Type:**
-> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
-> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
-
-## F1. Read Existing Configuration Files
-
-**CRITICAL:** Before generating any code, read existing files to determine state:
-
-1. **Find the Navigation Configuration directory:**
-   ```
-   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
-   ```
-
-2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
-   ```
-   Search for: the last call to GenerateGuid(index++)
-   The index variable starts at 1 and increments per translation entry.
-   Your new translations MUST continue from the next index value.
-   ```
-
-3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
-   ```
-   Read the Configuration for the target level (Application, Module, Section).
-   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
-   If yes: Read the corresponding SeedData class to find existing entries.
-   If no: You will need to add HasData() call.
-   ```
-
-4. **Read existing SeedData files** (if they exist):
-   ```
-   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-   Check for existing entity IDs to avoid collisions.
-   ```
-
-## F2. Determine Parent GUID
-
-For non-application levels, find the parent entity GUID:
-
-| Level | Parent | Where to Find Parent GUID |
-|-------|--------|---------------------------|
-| application | (none — top level) | — |
-| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
-| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
-
-Read the parent SeedData class and find the GUID matching `{parent_path}`.
-
-## F3. Generate Navigation Entity GUID
-
-Generate a deterministic GUID for the new navigation entity:
-
-```csharp
-// Use SHA256 hash of the full_path for deterministic generation
-using var sha256 = System.Security.Cryptography.SHA256.Create();
-var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
-var guid = new Guid(hash.Take(16).ToArray());
-```
-
-**Rules:**
-- NEVER use `Guid.NewGuid()`
-- Read existing SeedData GUIDs to verify no collision
-- Store result as `{navigation_guid}`
-
-## F4. Write Navigation Entity Seed
-
-Based on `{level}`, write the seed entry.
-
-**Option A: Project uses SeedData classes (SmartStack.app pattern)**
-
-If `Navigation{Level}SeedData.cs` exists, add the new entity:
-
-```csharp
-// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
-
-// Add static GUID field
-public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
-
-// Add to GetSeedData() return array
-new {
-    Id = {PascalCode}Id,
-    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
-    Code = "{code}",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    Icon = "{icon}",
-    IconType = IconType.Lucide,
-    Route = "/{full_path_with_slashes}",
-    DisplayOrder = {display_order},
-    IsActive = true,
-    CreatedAt = SeedConstants.SeedDate
-}
-```
-
-**FK property by level:**
-
-| Level | FK Property | References |
-|-------|-------------|------------|
-| application | (none — top level) | — |
-| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
-| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
-
-**Option B: Project uses inline HasData**
-
-If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
-
-```csharp
-// In Configure method, add:
-builder.HasData(new {
-    Id = Guid.Parse("{navigation_guid}"),
-    // ... same properties as Option A
-});
-```
-
-## F5. Write Translation Entries
-
-Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
-
-1. Read the file to find the current highest `index` value
-2. Continue from `index + 1`
-3. Use the SAME `GenerateGuid` method already defined in the file:
-
-```csharp
-// In GetSeedData() method, add at the end before return:
-
-// {level}: {code} translations
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
-    LanguageCode = "fr",
-    Label = "{labels.fr}",
-    Description = "{descriptions.fr}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "en",
-    Label = "{labels.en}",
-    Description = "{descriptions.en}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "it",
-    Label = "{labels.it}",
-    Description = "{descriptions.it}",
-    CreatedAt = seedDate
-});
-translations.Add(new {
-    Id = GenerateGuid(index++),
-    EntityType = NavigationEntityType.{Level},
-    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
-    LanguageCode = "de",
-    Label = "{labels.de}",
-    Description = "{descriptions.de}",
-    CreatedAt = seedDate
-});
-```
-
-## F6. Store Result
-
-```
-{navigation_guid} = [generated GUID]
-{seed_method} = "fallback"  // Indicates MCP was not used
-```
-
-## F7. Validation Checklist
-
-Before proceeding, verify:
-- [ ] Deterministic GUID generated (not NewGuid())
-- [ ] 4 languages present (fr, en, it, de)
-- [ ] Translation index continues existing sequence (no gaps, no collisions)
-- [ ] Parent GUID correctly references existing entity
-- [ ] Route path matches `/{app}/{module}` pattern
-- [ ] DisplayOrder is consistent with existing entities
-- [ ] Code is WRITTEN to files, not just displayed
-
-## F8. Present Summary
-
-```markdown
-## Navigation Seeds Generated (Fallback)
-
-**Entity:** {level} - {code}
-**GUID:** {navigation_guid}
-**Path:** {full_path}
-
-### Files Updated
-
-1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
-2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
-```
+# Navigation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
+> Reference: `templates-seed.md` for code templates.
+>
+> **Branch by Project Type:**
+> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
+> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
+
+## F1. Read Existing Configuration Files
+
+**CRITICAL:** Before generating any code, read existing files to determine state:
+
+1. **Find the Navigation Configuration directory:**
+   ```
+   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
+   ```
+
+2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
+   ```
+   Search for: the last call to GenerateGuid(index++)
+   The index variable starts at 1 and increments per translation entry.
+   Your new translations MUST continue from the next index value.
+   ```
+
+3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
+   ```
+   Read the Configuration for the target level (Application, Module, Section, Resource).
+   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
+   If yes: Read the corresponding SeedData class to find existing entries.
+   If no: You will need to add HasData() call.
+   ```
+
+4. **Read existing SeedData files** (if they exist):
+   ```
+   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+   Check for existing entity IDs to avoid collisions.
+   ```
+
+## F2. Determine Parent GUID
+
+For non-application levels, find the parent entity GUID:
+
+| Level | Parent | Where to Find Parent GUID |
+|-------|--------|---------------------------|
+| application | (none — top level) | — |
+| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
+| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
+
+Read the parent SeedData class and find the GUID matching `{parent_path}`.
+
+## F3. Generate Navigation Entity GUID
+
+Generate a deterministic GUID for the new navigation entity:
+
+```csharp
+// Use SHA256 hash of the full_path for deterministic generation
+using var sha256 = System.Security.Cryptography.SHA256.Create();
+var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
+var guid = new Guid(hash.Take(16).ToArray());
+```
+
+**Rules:**
+- NEVER use `Guid.NewGuid()`
+- Read existing SeedData GUIDs to verify no collision
+- Store result as `{navigation_guid}`
+
+## F4. Write Navigation Entity Seed
+
+Based on `{level}`, write the seed entry.
+
+**Option A: Project uses SeedData classes (SmartStack.app pattern)**
+
+If `Navigation{Level}SeedData.cs` exists, add the new entity:
+
+```csharp
+// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+
+// Add static GUID field
+public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
+
+// Add to GetSeedData() return array
+new {
+    Id = {PascalCode}Id,
+    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
+    Code = "{code}",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    Icon = "{icon}",
+    IconType = IconType.Lucide,
+    Route = "/{full_path_with_slashes}",
+    DisplayOrder = {display_order},
+    IsActive = true,
+    CreatedAt = SeedConstants.SeedDate
+}
+```
+
+**FK property by level:**
+
+| Level | FK Property | References |
+|-------|-------------|------------|
+| application | (none — top level) | — |
+| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
+| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
+
+**Option B: Project uses inline HasData**
+
+If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
+
+```csharp
+// In Configure method, add:
+builder.HasData(new {
+    Id = Guid.Parse("{navigation_guid}"),
+    // ... same properties as Option A
+});
+```
+
+## F5. Write Translation Entries
+
+Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
+
+1. Read the file to find the current highest `index` value
+2. Continue from `index + 1`
+3. Use the SAME `GenerateGuid` method already defined in the file:
+
+```csharp
+// In GetSeedData() method, add at the end before return:
+
+// {level}: {code} translations
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
+    LanguageCode = "fr",
+    Label = "{labels.fr}",
+    Description = "{descriptions.fr}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "en",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "it",
+    Label = "{labels.it}",
+    Description = "{descriptions.it}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "de",
+    Label = "{labels.de}",
+    Description = "{descriptions.de}",
+    CreatedAt = seedDate
+});
+```
+
+## F6. Store Result
+
+```
+{navigation_guid} = [generated GUID]
+{seed_method} = "fallback"  // Indicates MCP was not used
+```
+
+## F7. Validation Checklist
+
+Before proceeding, verify:
+- [ ] Deterministic GUID generated (not NewGuid())
+- [ ] 4 languages present (fr, en, it, de)
+- [ ] Translation index continues existing sequence (no gaps, no collisions)
+- [ ] Parent GUID correctly references existing entity
+- [ ] Route path matches `/{app}/{module}` pattern
+- [ ] DisplayOrder is consistent with existing entities
+- [ ] Code is WRITTEN to files, not just displayed
+
+## F8. Present Summary
+
+```markdown
+## Navigation Seeds Generated (Fallback)
+
+**Entity:** {level} - {code}
+**GUID:** {navigation_guid}
+**Path:** {full_path}
+
+### Files Updated
+
+1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
+2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
+```

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

@@ -1,130 +1,130 @@
----
-name: step-00-init
-description: Initialize application/module creation - parse parameters and validate context
-next_step: steps/step-01-navigation.md
----
-
-# Step 0: Initialization
-
-## MANDATORY EXECUTION RULES
-
-- NEVER skip parameter validation
-- ALWAYS detect the navigation level from user request
-- ALWAYS validate MCP availability before proceeding
-- YOU ARE AN INITIALIZER, not an executor
-- FORBIDDEN to call MCP tools until init is complete
-
-## YOUR TASK
-
-Initialize the application/module creation by parsing parameters, detecting level, and validating the SmartStack context.
-
----
-
-## EXECUTION SEQUENCE
-
-### 1-4. Parameter Detection & Project Analysis
-
-See [references/init-parameter-detection.md](../references/init-parameter-detection.md) for:
-- Navigation level detection (application/module/section)
-- Parameter extraction (code, labels, icon, displayOrder)
-- Project type & seeding strategy detection
-- Feature.json context enrichment (optional)
-- MCP prerequisite validation (BLOCKING)
-
-### 5. Build Full Path
-
-```
-{full_path} = {parentPath}.{code}  (if parentPath exists)
-{full_path} = {code}               (if application level)
-
-Example:
-  level: module
-  parentPath: sales
-  code: products
-  → full_path: sales.products
-```
-
-### 6. Infer Descriptions (if not provided)
-
-```yaml
-descriptions:
-  fr: "Gestion de {labels.fr}"
-  en: "{labels.en} management"
-  it: "Gestione di {labels.it}"
-  de: "Verwaltung von {labels.de}"
-```
-
-### 7. Show Summary
-
-```
-## Application Skill: {level} - {code}
-
-| Parameter | Value |
-|-----------|-------|
-| Level | {level} |
-| Code | {code} |
-| Full Path | {full_path} |
-| Parent | {parentPath} |
-| Icon | {icon} |
-| Display Order | {displayOrder} |
-| Project Type | {project_type} |
-| Seeding Strategy | {seeding_strategy} |
-| Feature.json | {has_feature_context ? feature_json_path : "Not found (standard generation)"} |
-
-### Labels
-| Language | Label |
-|----------|-------|
-| FR | {labels.fr} |
-| EN | {labels.en} |
-| IT | {labels.it} |
-| DE | {labels.de} |
-
-→ Proceeding to navigation generation...
-```
-
----
-
-## STATE VARIABLES TO PERSIST
-
-| Variable | Description |
-|----------|-------------|
-| `{level}` | application, module, or section |
-| `{code}` | kebab-case identifier |
-| `{full_path}` | Complete navigation path |
-| `{parent_path}` | Parent path (null for context) |
-| `{labels}` | Object with fr, en, it, de |
-| `{descriptions}` | Object with fr, en, it, de |
-| `{icon}` | Lucide icon name |
-| `{display_order}` | Numeric display order |
-| `{mcp_available}` | Boolean - MCP connectivity status |
-| `{project_type}` | "core" or "client" (from .smartstack/config.json) |
-| `{db_context}` | "core" or "extensions" (from .smartstack/config.json) |
-| `{seeding_strategy}` | "hasdata" (core) or "provider" (client) |
-| `{feature_json_path}` | Path to feature.json (null if not found) |
-| `{has_feature_context}` | Boolean - whether BA context is available |
-| `{feature_data}` | Parsed feature.json object (null if not found) |
-
----
-
-## SUCCESS METRICS
-
-- Level correctly detected
-- All required parameters extracted
-- MCP availability verified
-- Project type and seeding strategy detected
-- Feature.json detected if available (enrichment context loaded)
-- Full path computed correctly
-- Summary displayed
-- Proceeded to step-01-navigation.md
-
-## FAILURE MODES
-
-- Missing required parameters (ask user)
-- Invalid level detection (clarify with user)
-- MCP not available (STOP - display install instructions)
-
----
-
-## NEXT STEP
-
-After showing initialization summary, proceed to `./step-01-navigation.md`
+---
+name: step-00-init
+description: Initialize application/module creation - parse parameters and validate context
+next_step: steps/step-01-navigation.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES
+
+- NEVER skip parameter validation
+- ALWAYS detect the navigation level from user request
+- ALWAYS validate MCP availability before proceeding
+- YOU ARE AN INITIALIZER, not an executor
+- FORBIDDEN to call MCP tools until init is complete
+
+## YOUR TASK
+
+Initialize the application/module creation by parsing parameters, detecting level, and validating the SmartStack context.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1-4. Parameter Detection & Project Analysis
+
+See [references/init-parameter-detection.md](../references/init-parameter-detection.md) for:
+- Navigation level detection (application/module/section/resource)
+- Parameter extraction (code, labels, icon, displayOrder)
+- Project type & seeding strategy detection
+- Feature.json context enrichment (optional)
+- MCP prerequisite validation (BLOCKING)
+
+### 5. Build Full Path
+
+```
+{full_path} = {parentPath}.{code}  (if parentPath exists)
+{full_path} = {code}               (if application level)
+
+Example:
+  level: module
+  parentPath: sales
+  code: products
+  → full_path: sales.products
+```
+
+### 6. Infer Descriptions (if not provided)
+
+```yaml
+descriptions:
+  fr: "Gestion de {labels.fr}"
+  en: "{labels.en} management"
+  it: "Gestione di {labels.it}"
+  de: "Verwaltung von {labels.de}"
+```
+
+### 7. Show Summary
+
+```
+## Application Skill: {level} - {code}
+
+| Parameter | Value |
+|-----------|-------|
+| Level | {level} |
+| Code | {code} |
+| Full Path | {full_path} |
+| Parent | {parentPath} |
+| Icon | {icon} |
+| Display Order | {displayOrder} |
+| Project Type | {project_type} |
+| Seeding Strategy | {seeding_strategy} |
+| Feature.json | {has_feature_context ? feature_json_path : "Not found (standard generation)"} |
+
+### Labels
+| Language | Label |
+|----------|-------|
+| FR | {labels.fr} |
+| EN | {labels.en} |
+| IT | {labels.it} |
+| DE | {labels.de} |
+
+→ Proceeding to navigation generation...
+```
+
+---
+
+## STATE VARIABLES TO PERSIST
+
+| Variable | Description |
+|----------|-------------|
+| `{level}` | application, module, section, or resource |
+| `{code}` | kebab-case identifier |
+| `{full_path}` | Complete navigation path |
+| `{parent_path}` | Parent path (null for context) |
+| `{labels}` | Object with fr, en, it, de |
+| `{descriptions}` | Object with fr, en, it, de |
+| `{icon}` | Lucide icon name |
+| `{display_order}` | Numeric display order |
+| `{mcp_available}` | Boolean - MCP connectivity status |
+| `{project_type}` | "core" or "client" (from .smartstack/config.json) |
+| `{db_context}` | "core" or "extensions" (from .smartstack/config.json) |
+| `{seeding_strategy}` | "hasdata" (core) or "provider" (client) |
+| `{feature_json_path}` | Path to feature.json (null if not found) |
+| `{has_feature_context}` | Boolean - whether BA context is available |
+| `{feature_data}` | Parsed feature.json object (null if not found) |
+
+---
+
+## SUCCESS METRICS
+
+- Level correctly detected
+- All required parameters extracted
+- MCP availability verified
+- Project type and seeding strategy detected
+- Feature.json detected if available (enrichment context loaded)
+- Full path computed correctly
+- Summary displayed
+- Proceeded to step-01-navigation.md
+
+## FAILURE MODES
+
+- Missing required parameters (ask user)
+- Invalid level detection (clarify with user)
+- MCP not available (STOP - display install instructions)
+
+---
+
+## NEXT STEP
+
+After showing initialization summary, proceed to `./step-01-navigation.md`