@atlashub/smartstack-cli 3.36.0 → 3.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/dist/index.js +16 -24
  2. package/dist/index.js.map +1 -1
  3. package/dist/mcp-entry.mjs +201 -256
  4. package/dist/mcp-entry.mjs.map +1 -1
  5. package/package.json +3 -2
  6. package/scripts/extract-api-endpoints.ts +325 -0
  7. package/scripts/extract-business-rules.ts +440 -0
  8. package/scripts/generate-doc-with-mock-ui.ts +804 -0
  9. package/scripts/health-check.sh +168 -0
  10. package/scripts/postinstall.js +18 -0
  11. package/templates/agents/ba-reader.md +9 -9
  12. package/templates/agents/ba-writer.md +12 -15
  13. package/templates/agents/code-reviewer.md +1 -1
  14. package/templates/agents/docs-context-reader.md +1 -1
  15. package/templates/agents/gitflow/merge.md +0 -4
  16. package/templates/agents/gitflow/pr.md +0 -4
  17. package/templates/agents/gitflow/start.md +30 -5
  18. package/templates/mcp-scaffolding/frontend/nav-routes.ts.hbs +20 -20
  19. package/templates/mcp-scaffolding/frontend/routes.tsx.hbs +16 -24
  20. package/templates/mcp-scaffolding/migrations/seed-roles.cs.hbs +2 -2
  21. package/templates/skills/_resources/mcp-validate-documentation-spec.md +3 -3
  22. package/templates/skills/_shared.md +15 -17
  23. package/templates/skills/ai-prompt/SKILL.md +1 -1
  24. package/templates/skills/ai-prompt/steps/step-00-init.md +47 -0
  25. package/templates/skills/apex/SKILL.md +3 -4
  26. package/templates/skills/apex/_shared.md +10 -20
  27. package/templates/skills/apex/references/analysis-methods.md +141 -0
  28. package/templates/skills/apex/references/challenge-questions.md +1 -21
  29. package/templates/skills/apex/references/core-seed-data.md +35 -57
  30. package/templates/skills/apex/references/examine-build-validation.md +87 -0
  31. package/templates/skills/apex/references/execution-frontend-gates.md +177 -0
  32. package/templates/skills/apex/references/execution-frontend-patterns.md +105 -0
  33. package/templates/skills/apex/references/execution-layer1-rules.md +96 -0
  34. package/templates/skills/apex/references/initialization-challenge-flow.md +110 -0
  35. package/templates/skills/apex/references/planning-layer-mapping.md +151 -0
  36. package/templates/skills/apex/references/post-checks.md +145 -40
  37. package/templates/skills/apex/references/smartstack-api.md +35 -51
  38. package/templates/skills/apex/references/smartstack-frontend.md +17 -17
  39. package/templates/skills/apex/references/smartstack-layers.md +38 -62
  40. package/templates/skills/apex/steps/step-00-init.md +14 -26
  41. package/templates/skills/apex/steps/step-01-analyze.md +10 -143
  42. package/templates/skills/apex/steps/step-02-plan.md +10 -92
  43. package/templates/skills/apex/steps/step-03-execute.md +47 -249
  44. package/templates/skills/apex/steps/step-04-examine.md +14 -78
  45. package/templates/skills/apex/steps/step-05-deep-review.md +2 -2
  46. package/templates/skills/apex/steps/step-08-run-tests.md +2 -0
  47. package/templates/skills/application/SKILL.md +6 -7
  48. package/templates/skills/application/references/backend-controller-hierarchy.md +16 -16
  49. package/templates/skills/application/references/backend-seeding-and-dto-output.md +83 -0
  50. package/templates/skills/application/references/backend-table-prefix-mapping.md +79 -0
  51. package/templates/skills/application/references/backend-verification.md +1 -1
  52. package/templates/skills/application/references/frontend-i18n-and-output.md +67 -0
  53. package/templates/skills/application/references/frontend-route-naming.md +117 -0
  54. package/templates/skills/application/references/frontend-route-wiring-app-tsx.md +107 -0
  55. package/templates/skills/application/references/frontend-verification.md +12 -12
  56. package/templates/skills/application/references/init-parameter-detection.md +120 -0
  57. package/templates/skills/application/references/migration-checklist-troubleshooting.md +100 -0
  58. package/templates/skills/application/references/nav-fallback-procedure.md +5 -6
  59. package/templates/skills/application/references/provider-template.md +2 -6
  60. package/templates/skills/application/references/roles-client-project-handling.md +55 -0
  61. package/templates/skills/application/references/roles-fallback-procedure.md +149 -0
  62. package/templates/skills/application/references/test-coverage-requirements.md +213 -0
  63. package/templates/skills/application/references/test-frontend.md +3 -3
  64. package/templates/skills/application/steps/step-00-init.md +11 -141
  65. package/templates/skills/application/steps/step-01-navigation.md +3 -3
  66. package/templates/skills/application/steps/step-02-permissions.md +4 -4
  67. package/templates/skills/application/steps/step-03-roles.md +18 -175
  68. package/templates/skills/application/steps/step-03b-provider.md +1 -2
  69. package/templates/skills/application/steps/step-04-backend.md +19 -110
  70. package/templates/skills/application/steps/step-05-frontend.md +17 -143
  71. package/templates/skills/application/steps/step-06-migration.md +12 -60
  72. package/templates/skills/application/steps/step-07-tests.md +9 -76
  73. package/templates/skills/application/templates-backend.md +29 -27
  74. package/templates/skills/application/templates-frontend.md +48 -48
  75. package/templates/skills/application/templates-seed.md +57 -131
  76. package/templates/skills/business-analyse/SKILL.md +27 -30
  77. package/templates/skills/business-analyse/_architecture.md +6 -6
  78. package/templates/skills/business-analyse/_shared.md +60 -88
  79. package/templates/skills/business-analyse/questionnaire/04-data.md +3 -3
  80. package/templates/skills/business-analyse/questionnaire/06-security.md +1 -1
  81. package/templates/skills/business-analyse/questionnaire/13-cross-module.md +1 -1
  82. package/templates/skills/business-analyse/react/application-viewer.md +12 -12
  83. package/templates/skills/business-analyse/react/components.md +8 -12
  84. package/templates/skills/business-analyse/react/schema.md +11 -11
  85. package/templates/skills/business-analyse/references/agent-module-prompt.md +2 -3
  86. package/templates/skills/business-analyse/references/analysis-semantic-checks.md +190 -0
  87. package/templates/skills/business-analyse/references/cache-warming-strategy.md +2 -2
  88. package/templates/skills/business-analyse/references/cadrage-challenge-patterns.md +41 -0
  89. package/templates/skills/business-analyse/references/cadrage-coverage-matrix.md +74 -0
  90. package/templates/skills/business-analyse/references/cadrage-shared-modules.md +69 -0
  91. package/templates/skills/business-analyse/references/cadrage-structure-cards.md +1 -1
  92. package/templates/skills/business-analyse/references/compilation-structure-cards.md +297 -0
  93. package/templates/skills/business-analyse/references/consolidation-structural-checks.md +2 -2
  94. package/templates/skills/business-analyse/references/deploy-modes.md +5 -5
  95. package/templates/skills/business-analyse/references/detection-strategies.md +7 -7
  96. package/templates/skills/business-analyse/references/handoff-file-templates.md +14 -22
  97. package/templates/skills/business-analyse/references/handoff-mappings.md +4 -4
  98. package/templates/skills/business-analyse/references/handoff-seeddata-generation.md +312 -0
  99. package/templates/skills/business-analyse/references/init-schema-deployment.md +3 -3
  100. package/templates/skills/business-analyse/references/naming-conventions.md +22 -24
  101. package/templates/skills/business-analyse/references/prd-generation.md +2 -2
  102. package/templates/skills/business-analyse/references/review-data-mapping.md +2 -2
  103. package/templates/skills/business-analyse/references/robustness-checks.md +1 -1
  104. package/templates/skills/business-analyse/references/spec-auto-inference.md +3 -3
  105. package/templates/skills/business-analyse/references/team-orchestration.md +49 -6
  106. package/templates/skills/business-analyse/references/ui-dashboard-spec.md +1 -1
  107. package/templates/skills/business-analyse/references/ui-resource-cards.md +18 -18
  108. package/templates/skills/business-analyse/references/validate-incremental-html.md +2 -2
  109. package/templates/skills/business-analyse/references/validation-checklist.md +2 -2
  110. package/templates/skills/business-analyse/schemas/application-schema.json +4 -5
  111. package/templates/skills/business-analyse/schemas/project-schema.json +1 -6
  112. package/templates/skills/business-analyse/schemas/sections/metadata-schema.json +2 -3
  113. package/templates/skills/business-analyse/schemas/sections/specification-schema.json +4 -4
  114. package/templates/skills/business-analyse/steps/step-00-init.md +8 -17
  115. package/templates/skills/business-analyse/steps/step-01-cadrage.md +35 -198
  116. package/templates/skills/business-analyse/steps/step-01b-applications.md +16 -20
  117. package/templates/skills/business-analyse/steps/step-02-decomposition.md +1 -1
  118. package/templates/skills/business-analyse/steps/step-03a1-setup.md +4 -4
  119. package/templates/skills/business-analyse/steps/step-03a2-analysis.md +1 -1
  120. package/templates/skills/business-analyse/steps/step-03b-ui.md +4 -4
  121. package/templates/skills/business-analyse/steps/step-03c-compile.md +66 -140
  122. package/templates/skills/business-analyse/steps/step-03d-validate.md +2 -2
  123. package/templates/skills/business-analyse/steps/step-04a-collect.md +2 -2
  124. package/templates/skills/business-analyse/steps/step-04b-analyze.md +42 -160
  125. package/templates/skills/business-analyse/steps/step-04c-decide.md +1 -1
  126. package/templates/skills/business-analyse/steps/step-05a-handoff.md +74 -104
  127. package/templates/skills/business-analyse/steps/step-05b-deploy.md +13 -11
  128. package/templates/skills/business-analyse/steps/step-06-review.md +3 -3
  129. package/templates/skills/business-analyse/templates/tpl-frd.md +13 -13
  130. package/templates/skills/business-analyse/templates/tpl-handoff.md +12 -12
  131. package/templates/skills/business-analyse/templates-frd.md +25 -25
  132. package/templates/skills/business-analyse/templates-react.md +15 -21
  133. package/templates/skills/controller/SKILL.md +1 -1
  134. package/templates/skills/controller/postman-templates.md +1 -1
  135. package/templates/skills/controller/references/controller-code-templates.md +2 -2
  136. package/templates/skills/controller/references/mcp-scaffold-workflow.md +209 -0
  137. package/templates/skills/controller/references/permission-sync-templates.md +13 -16
  138. package/templates/skills/controller/steps/step-00-init.md +11 -11
  139. package/templates/skills/controller/steps/step-03-generate.md +64 -103
  140. package/templates/skills/controller/templates.md +67 -71
  141. package/templates/skills/debug/SKILL.md +13 -218
  142. package/templates/skills/debug/steps/step-00-init.md +57 -0
  143. package/templates/skills/debug/steps/step-01-analyze.md +219 -0
  144. package/templates/skills/debug/steps/step-02-resolve.md +85 -0
  145. package/templates/skills/documentation/SKILL.md +49 -345
  146. package/templates/skills/documentation/data-schema.md +11 -8
  147. package/templates/skills/documentation/steps/step-00-init.md +70 -0
  148. package/templates/skills/documentation/steps/step-01-scan.md +113 -0
  149. package/templates/skills/documentation/steps/step-02-generate.md +231 -0
  150. package/templates/skills/documentation/steps/step-03-validate.md +238 -0
  151. package/templates/skills/documentation/templates.md +480 -322
  152. package/templates/skills/efcore/references/both-contexts.md +32 -0
  153. package/templates/skills/efcore/references/database-operations.md +67 -0
  154. package/templates/skills/efcore/references/destructive-operations.md +38 -0
  155. package/templates/skills/efcore/references/reset-operations.md +81 -0
  156. package/templates/skills/efcore/references/seed-methods.md +86 -0
  157. package/templates/skills/efcore/references/shared-init-functions.md +250 -0
  158. package/templates/skills/efcore/references/sql-objects-injection.md +61 -0
  159. package/templates/skills/efcore/references/troubleshooting.md +81 -0
  160. package/templates/skills/efcore/steps/db/step-deploy.md +1 -32
  161. package/templates/skills/efcore/steps/db/step-reset.md +7 -103
  162. package/templates/skills/efcore/steps/db/step-seed.md +10 -132
  163. package/templates/skills/efcore/steps/db/step-status.md +5 -44
  164. package/templates/skills/efcore/steps/migration/step-03-validate.md +8 -62
  165. package/templates/skills/efcore/steps/rebase-snapshot/step-03-create.md +1 -57
  166. package/templates/skills/efcore/steps/shared/step-00-init.md +11 -254
  167. package/templates/skills/efcore/steps/squash/step-03-create.md +1 -58
  168. package/templates/skills/feature-full/SKILL.md +1 -1
  169. package/templates/skills/feature-full/steps/step-00-init.md +57 -0
  170. package/templates/skills/feature-full/steps/step-01-implementation.md +1 -1
  171. package/templates/skills/gitflow/SKILL.md +1 -1
  172. package/templates/skills/gitflow/_shared.md +23 -0
  173. package/templates/skills/gitflow/references/commit-message-generation.md +58 -0
  174. package/templates/skills/gitflow/references/commit-migration-validation.md +49 -0
  175. package/templates/skills/gitflow/references/finish-cleanup.md +51 -0
  176. package/templates/skills/gitflow/references/finish-version-bumping.md +45 -0
  177. package/templates/skills/gitflow/references/init-environment-detection.md +41 -0
  178. package/templates/skills/gitflow/references/init-questions.md +185 -0
  179. package/templates/skills/gitflow/references/init-structure-creation.md +71 -0
  180. package/templates/skills/gitflow/references/init-version-detection.md +21 -0
  181. package/templates/skills/gitflow/references/init-workspace-detection.md +43 -0
  182. package/templates/skills/gitflow/references/merge-ci-status.md +36 -0
  183. package/templates/skills/gitflow/references/merge-execution.md +62 -0
  184. package/templates/skills/gitflow/references/merge-pr-context.md +76 -0
  185. package/templates/skills/gitflow/references/pr-build-checks.md +60 -0
  186. package/templates/skills/gitflow/references/pr-generation.md +58 -0
  187. package/templates/skills/gitflow/references/start-branch-normalization.md +28 -0
  188. package/templates/skills/gitflow/references/start-worktree-creation.md +50 -0
  189. package/templates/skills/gitflow/references/sync-push-verify.md +44 -0
  190. package/templates/skills/gitflow/references/sync-rebase-conflicts.md +38 -0
  191. package/templates/skills/gitflow/steps/step-commit.md +12 -91
  192. package/templates/skills/gitflow/steps/step-finish.md +15 -159
  193. package/templates/skills/gitflow/steps/step-init.md +24 -326
  194. package/templates/skills/gitflow/steps/step-merge.md +17 -176
  195. package/templates/skills/gitflow/steps/step-pr.md +10 -116
  196. package/templates/skills/gitflow/steps/step-start.md +16 -109
  197. package/templates/skills/gitflow/steps/step-sync.md +6 -69
  198. package/templates/skills/ralph-loop/SKILL.md +6 -0
  199. package/templates/skills/ralph-loop/references/category-completeness.md +185 -0
  200. package/templates/skills/ralph-loop/references/compact-loop.md +1 -1
  201. package/templates/skills/ralph-loop/references/init-resume-recovery.md +127 -0
  202. package/templates/skills/ralph-loop/references/module-transition.md +151 -0
  203. package/templates/skills/ralph-loop/references/multi-module-queue.md +171 -0
  204. package/templates/skills/ralph-loop/references/parallel-execution.md +246 -0
  205. package/templates/skills/ralph-loop/references/task-transform-legacy.md +6 -9
  206. package/templates/skills/ralph-loop/references/team-orchestration.md +45 -3
  207. package/templates/skills/ralph-loop/steps/step-00-init.md +36 -109
  208. package/templates/skills/ralph-loop/steps/step-01-task.md +15 -163
  209. package/templates/skills/ralph-loop/steps/step-02-execute.md +8 -154
  210. package/templates/skills/ralph-loop/steps/step-04-check.md +21 -73
  211. package/templates/skills/review-code/references/owasp-api-top10.md +5 -5
  212. package/templates/skills/review-code/references/smartstack-conventions.md +11 -11
  213. package/templates/skills/validate-feature/references/api-smoke-tests.md +140 -0
  214. package/templates/skills/validate-feature/references/db-validation-checks.md +180 -0
  215. package/templates/skills/validate-feature/steps/step-01-compile.md +5 -2
  216. package/templates/skills/validate-feature/steps/step-04-api-smoke.md +34 -145
  217. package/templates/skills/validate-feature/steps/step-05-db-validation.md +74 -260
  218. package/templates/skills/workflow/SKILL.md +1 -1
  219. package/templates/skills/workflow/steps/step-00-init.md +57 -0
@@ -3,10 +3,10 @@ name: application
3
3
  description: |
4
4
  Creates SmartStack full-stack applications/modules.
5
5
  Use this skill when:
6
- - User asks to create an application, module, or context
6
+ - User asks to create an application or module
7
7
  - User mentions "new module", "new application", "add a feature"
8
8
  - User wants to extend navigation with new entries
9
- Scope: Context → Application → Module → Section (all levels)
9
+ Scope: Application → Module → Section (all levels)
10
10
  ---
11
11
 
12
12
  # Skill Application SmartStack
@@ -59,8 +59,8 @@ This skill uses progressive step loading. Each step calls MCP tools for generati
59
59
  |---------|---------|
60
60
  | Explicit request | "Create a module to manage products" |
61
61
  | New feature | "We need to add order management" |
62
- | Navigation extension | "Add a CRM application in business" |
63
- | Keywords | "new module", "new application", "add a context" |
62
+ | Navigation extension | "Add a CRM application" |
63
+ | Keywords | "new module", "new application" |
64
64
 
65
65
  ## FLOW ARCHITECTURE
66
66
 
@@ -76,13 +76,12 @@ WEB (React) → API (.NET) → Application → Infrastructure → Database
76
76
 
77
77
  | Hint | → Level |
78
78
  |------|---------|
79
- | "context", "workspace" | Context |
80
79
  | "application", "app" | Application |
81
80
  | "module", "feature" | Module |
82
81
  | "section", "tab" | Section |
83
82
 
84
83
  ### 2. Parameter Extraction
85
- `$LEVEL`, `$PARENT` (platform/business/personal), `$CODE` (kebab-case), `$LABEL_EN`, `$ICON` (Lucide)
84
+ `$LEVEL`, `$CODE` (kebab-case), `$LABEL_EN`, `$ICON` (Lucide)
86
85
 
87
86
  ### 3. Full-Stack Generation
88
87
  ```
@@ -232,7 +231,7 @@ await _workflowService.TriggerAsync("{entity}.created", new Dictionary<string, o
232
231
  - [templates-seed.md](templates-seed.md) - Seed data patterns reference
233
232
 
234
233
  <success_criteria>
235
- - Navigation entries created with correct hierarchy (Context/Application/Module)
234
+ - Navigation entries created with correct hierarchy (Application/Module)
236
235
  - Permissions generated via MCP with 2-file pattern (constants + seed)
237
236
  - Roles assigned with appropriate permission sets
238
237
  - Backend layers follow SmartStack conventions (validated by MCP)
@@ -6,32 +6,32 @@
6
6
 
7
7
  ## Controller File Location
8
8
 
9
- Controllers are organized by **context short name** and **application** (matching SmartStack.app pattern):
9
+ Controllers are organized by **application** (matching SmartStack.app pattern):
10
10
 
11
11
  ```
12
12
  Api/Controllers/
13
- ├── Admin/ platform.administration
14
- │ ├── {Application}/ Application sub-folder (e.g., AI/, Communications/, Tenants/)
13
+ ├── Administration/ ← administration.*
14
+ │ ├── {Module}/ Module sub-folder (e.g., AI/, Communications/, Tenants/)
15
15
  │ │ └── {EntityName}Controller.cs
16
- │ └── {EntityName}Controller.cs ← Direct controllers (no application sub-folder)
17
- ├── Business/ business.*
16
+ │ └── {EntityName}Controller.cs ← Direct controllers (no module sub-folder)
17
+ ├── Support/ support.*
18
18
  │ └── {EntityName}Controller.cs
19
- ├── Support/ platform.support
19
+ ├── {ApplicationPascal}/ Other applications (e.g., Sales/, HumanResources/)
20
20
  │ └── {EntityName}Controller.cs
21
- ├── User/ personal.*
21
+ ├── MySpace/ myspace.*
22
22
  │ └── {EntityName}Controller.cs
23
23
  └── {SharedControllers}.cs ← Root-level (Auth, Config, Navigation, etc.)
24
24
  ```
25
25
 
26
- ## Context-to-Folder Mapping
26
+ ## Application-to-Folder Mapping
27
27
 
28
- | NavRoute Context | Controller Folder | Example |
28
+ | NavRoute Application | Controller Folder | Example |
29
29
  |-----------------|-------------------|---------|
30
- | `platform.administration` | `Admin` | `Controllers/Admin/TenantsController.cs` |
31
- | `platform.administration.{app}` | `Admin/{App}` | `Controllers/Admin/AI/AiPromptsController.cs` |
32
- | `platform.support` | `Support` | `Controllers/Support/TicketsController.cs` |
33
- | `business.*` | `Business` | `Controllers/Business/MyTicketsController.cs` |
34
- | `personal.*` | `User` | `Controllers/User/PreferencesController.cs` |
30
+ | `administration` | `Administration` | `Controllers/Administration/TenantsController.cs` |
31
+ | `administration.{module}` | `Administration/{Module}` | `Controllers/Administration/AI/AiPromptsController.cs` |
32
+ | `support` | `Support` | `Controllers/Support/TicketsController.cs` |
33
+ | `{application}` | `{ApplicationPascal}` | `Controllers/Sales/ProductsController.cs` |
34
+ | `myspace` | `MySpace` | `Controllers/MySpace/PreferencesController.cs` |
35
35
 
36
36
  ## Controller Attributes
37
37
 
@@ -44,7 +44,7 @@ The generated controller uses NavRoute attribute:
44
44
  public class {EntityName}Controller : ControllerBase
45
45
  {
46
46
  [HttpGet]
47
- [RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
47
+ [RequirePermission(Permissions.{Application}.{Module}.Read)]
48
48
  public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }
49
49
 
50
50
  // ... other CRUD methods
@@ -55,4 +55,4 @@ This ensures:
55
55
  - API route is derived from navigation path
56
56
  - Permissions use the constants from Permissions.cs
57
57
  - Frontend can discover API path from NavRoute registry
58
- - Controller file is in the correct context/application folder
58
+ - Controller file is in the correct application folder
@@ -0,0 +1,83 @@
1
+ # Backend Generation: Entity Seeding & Output Formatting
2
+
3
+ > Referenced from `steps/step-04-backend.md` — Optional seeding and MCP response handling.
4
+
5
+ ---
6
+
7
+ ## Entity Seeding (Optional)
8
+
9
+ Ask the user if they want to seed initial data for the entity:
10
+
11
+ ```yaml
12
+ questions:
13
+ - header: "Seed Data"
14
+ question: "Would you like to generate initial seed data for {EntityName}?"
15
+ options:
16
+ - label: "Yes - Generate SeedData provider"
17
+ description: "Creates {EntityName}SeedData.cs + registers in DevDataSeeder (same pattern as core)"
18
+ - label: "No - Skip seeding"
19
+ description: "Entity starts empty (can add seed data later)"
20
+ multiSelect: false
21
+ ```
22
+
23
+ **If user selects YES:**
24
+
25
+ See [references/backend-entity-seeding.md](../references/backend-entity-seeding.md) for the full seeding pattern:
26
+ 1. **SeedData file** (`{EntityName}SeedData.cs`) — static class with deterministic GUIDs, 3-5 samples
27
+ 2. **DevDataSeeder update** — add `Seed{EntityName}sAsync()` method with idempotent check
28
+
29
+ **If user selects NO:**
30
+
31
+ Skip this section and proceed to storing entity info.
32
+
33
+ ```markdown
34
+ > Skipping entity seed data. You can generate it later using the SeedData provider pattern
35
+ > documented in templates-seed.md.
36
+ ```
37
+
38
+ ---
39
+
40
+ ## Presenting Output to User
41
+
42
+ Display generated backend code organized by layer:
43
+
44
+ ### Domain Layer
45
+ - `Domain/{Application}/{Module}/{EntityName}.cs`
46
+
47
+ ### Infrastructure Layer
48
+ - `Persistence/Configurations/{Application}/{Module}/{EntityName}Configuration.cs`
49
+ - `Services/{Application}/{Module}/{EntityName}Service.cs`
50
+
51
+ ### Application Layer
52
+ - `Common/Interfaces/I{EntityName}Service.cs`
53
+ - `{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs`
54
+ - `{Application}/{Module}/DTOs/Create{EntityName}Dto.cs`
55
+ - `{Application}/{Module}/DTOs/Update{EntityName}Dto.cs`
56
+
57
+ ### API Layer
58
+ - `Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs`
59
+ - NavRoute: `{full_path}`
60
+ - Endpoints:
61
+ - GET /api/{code} - List all
62
+ - GET /api/{code}/{id} - Get by ID
63
+ - POST /api/{code} - Create
64
+ - PUT /api/{code}/{id} - Update
65
+ - DELETE /api/{code}/{id} - Delete
66
+
67
+ ### Next Steps
68
+ 1. Add DbSet to ICoreDbContext: `public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();`
69
+ 2. Register service in DI: `services.AddScoped<I{EntityName}Service, {EntityName}Service>();`
70
+ 3. Run: `dotnet ef migrations add core_vX.X.X_XXX_Add{EntityName}`
71
+
72
+ ---
73
+
74
+ ## Entity Info Storage
75
+
76
+ Store for use in frontend generation:
77
+
78
+ ```
79
+ {entity_name} = "{EntityName}"
80
+ {entity_code} = "{code}"
81
+ {api_route} = "/api/{code}"
82
+ {has_seed_data} = true/false // Whether SeedData provider was generated
83
+ ```
@@ -0,0 +1,79 @@
1
+ # Backend: Table Prefix & Controller Folder Mapping
2
+
3
+ > Referenced from `steps/step-04-backend.md` — Deriving table prefixes and controller organization.
4
+
5
+ ---
6
+
7
+ ## Table Prefix Priority
8
+
9
+ 1. **If a `feature.json` exists** with `metadata.tablePrefix` → use that prefix (e.g., `rh_`, `fi_`)
10
+ 2. **Otherwise**, derive from navigation context using the fallback table below
11
+
12
+ ---
13
+
14
+ ## Fallback Table (when no feature.json tablePrefix)
15
+
16
+ | Application | Table Prefix | Controller Folder | Example |
17
+ |---------|--------|-------------------|---------|
18
+ | `administration.*` | `auth_` or `cfg_` | `Administration` | Table: `auth_Tenants`, Controller: `Controllers/Administration/TenantsController.cs` |
19
+ | `support.*` | `support_` | `Support` | Table: `support_Tickets`, Controller: `Controllers/Support/TicketsController.cs` |
20
+ | `*` (business apps) | `ref_` or domain-specific | `{ApplicationPascal}` | Table: `ref_Products`, Controller: `Controllers/Sales/ProductsController.cs` |
21
+ | `myspace.*` | `usr_` | `MySpace` | Table: `usr_Preferences`, Controller: `Controllers/MySpace/PreferencesController.cs` |
22
+
23
+ ---
24
+
25
+ ## Feature.json Table Prefix Detection
26
+
27
+ ```
28
+ Search for feature.json in:
29
+ - docs/business/{application}/business-analyse/*/feature.json
30
+ - Read metadata.tablePrefix if exists
31
+ ```
32
+
33
+ **Example from feature.json:**
34
+
35
+ ```json
36
+ {
37
+ "metadata": {
38
+ "tablePrefix": "rh_",
39
+ "schema": "core"
40
+ },
41
+ "analysis": { ... }
42
+ }
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Implementation
48
+
49
+ ```csharp
50
+ // Check for feature.json tablePrefix
51
+ Search for feature.json in:
52
+ - docs/business/{application}/business-analyse/*/feature.json
53
+ - Read metadata.tablePrefix if exists
54
+
55
+ IF metadata.tablePrefix exists:
56
+ {prefix} = metadata.tablePrefix # e.g., "rh_"
57
+ ELSE:
58
+ {prefix} = derived from context table above
59
+ ```
60
+
61
+ Store: `{controller_folder}` = the Controller Folder from the table above.
62
+
63
+ ---
64
+
65
+ ## Usage in MCP Call
66
+
67
+ When calling `mcp__smartstack__scaffold_extension`:
68
+
69
+ ```
70
+ Tool: mcp__smartstack__scaffold_extension
71
+ Args:
72
+ type: "feature"
73
+ name: "{entityName}"
74
+ options:
75
+ navRoute: "{full_path}"
76
+ tablePrefix: "{prefix}" ← Derived prefix
77
+ schema: "core"
78
+ ...
79
+ ```
@@ -30,7 +30,7 @@ services.AddScoped<I{EntityName}Service, {EntityName}Service>();
30
30
 
31
31
  ## Check 4: RequirePermission Attributes (BLOCKING)
32
32
 
33
- Each HTTP action MUST have `[RequirePermission(Permissions.{Context}.{Application}.{Module}.{Action})]`.
33
+ Each HTTP action MUST have `[RequirePermission(Permissions.{Application}.{Module}.{Action})]`.
34
34
 
35
35
  ## Check 5: Entity Configuration (BLOCKING)
36
36
 
@@ -0,0 +1,67 @@
1
+ # Frontend: i18n Structure & Output Formatting
2
+
3
+ > Referenced from `steps/step-05-frontend.md` — i18n files and output presentation.
4
+
5
+ ---
6
+
7
+ ## i18n Structure
8
+
9
+ All i18n files must follow this structure:
10
+
11
+ ```
12
+ locales/
13
+ ├── fr/
14
+ │ └── {entityCode}.json
15
+ ├── en/
16
+ │ └── {entityCode}.json
17
+ ├── it/
18
+ │ └── {entityCode}.json
19
+ └── de/
20
+ └── {entityCode}.json
21
+ ```
22
+
23
+ **Note:** i18n files are auto-generated by `type: "page"` scaffold. Verify the 4 language files were created and customize the `title`/`subtitle` with proper labels.
24
+
25
+ If customization needed:
26
+ - `i18n/locales/fr/{entityCode}.json` → set `"title": "{labels.fr}"`
27
+ - `i18n/locales/en/{entityCode}.json` → set `"title": "{labels.en}"`
28
+ - `i18n/locales/it/{entityCode}.json` → set `"title": "{labels.it}"`
29
+ - `i18n/locales/de/{entityCode}.json` → set `"title": "{labels.de}"`
30
+
31
+ ---
32
+
33
+ ## Presenting Output to User
34
+
35
+ Display generated frontend code organized by category:
36
+
37
+ ### Pages
38
+ - `pages/{application}/{module}/{EntityName}Page.tsx`
39
+ - `pages/{application}/{module}/{EntityName}ListView.tsx`
40
+
41
+ ### Components
42
+ - `components/{application}/{module}/{EntityName}.tsx`
43
+ - `hooks/use{EntityName}.ts`
44
+
45
+ ### API Client
46
+ - `services/api/{entityCode}Api.ts`
47
+ - `types/{entityName}.types.ts`
48
+
49
+ ### Routes
50
+ - Updated `navRoutes.generated.ts`
51
+ - Generated `clientRoutes.generated.tsx`
52
+ - Wired routes in `App.tsx` (standard + tenant blocks)
53
+
54
+ ### i18n
55
+ - `locales/fr/{entityCode}.json`
56
+ - `locales/en/{entityCode}.json`
57
+ - `locales/it/{entityCode}.json`
58
+ - `locales/de/{entityCode}.json`
59
+
60
+ ### Route Configuration Example
61
+ ```tsx
62
+ // In routes.tsx - NESTED routes (not flat!)
63
+ <Route path="{application_kebab}">
64
+ <Route index element={<Navigate to="{module_kebab}" replace />} />
65
+ <Route path="{module_kebab}" element={<{EntityName}Page />} />
66
+ </Route>
67
+ ```
@@ -0,0 +1,117 @@
1
+ # Frontend: Route Naming & Kebab-Case Requirements
2
+
3
+ > Referenced from `steps/step-05-frontend.md` — Route path conventions and naming rules.
4
+
5
+ ---
6
+
7
+ ## Route Naming Rule (BLOCKING)
8
+
9
+ All route paths MUST use **kebab-case** to match navigation seed data exactly.
10
+
11
+ **Transformation:** `PascalCase` → `kebab-case`
12
+
13
+ Examples:
14
+ - `HumanResources` → `human-resources`
15
+ - `Employees` → `employees`
16
+ - `TimeManagement` → `time-management`
17
+ - `OrderItems` → `order-items`
18
+
19
+ ---
20
+
21
+ ## Forbidden Patterns
22
+
23
+ | Pattern | Issue |
24
+ |---------|-------|
25
+ | `humanresources` | Concatenated words without hyphens |
26
+ | `timemanagement` | Missing hyphens in multi-word names |
27
+ | `mymodule` | Ambiguous (is this "my-module" or literal "mymodule"?) |
28
+
29
+ ---
30
+
31
+ ## Required Patterns
32
+
33
+ | Pattern | Correct Usage |
34
+ |---------|---------------|
35
+ | `human-resources` | Multi-word segment with proper hyphens |
36
+ | `time-management` | Proper kebab-case |
37
+ | `employees` | Single-word segments stay lowercase |
38
+ | `products` | Single-word segments stay lowercase |
39
+
40
+ ---
41
+
42
+ ## Verification
43
+
44
+ Route paths MUST match the navigation seed data routes (which use `ToKebabCase()`).
45
+
46
+ **Example verification:**
47
+
48
+ Navigation seed data:
49
+ ```csharp
50
+ Route = "/human-resources/time-management" // From ToKebabCase()
51
+ ```
52
+
53
+ App.tsx routes must use:
54
+ ```tsx
55
+ const applicationRoutes: ApplicationRouteExtensions = {
56
+ 'human-resources': [ // ← kebab-case
57
+ { path: 'time-management', element: <TimeManagementPage /> }, // ← kebab-case
58
+ ],
59
+ };
60
+ ```
61
+
62
+ ---
63
+
64
+ ## Kebab-Case Conversion Rules
65
+
66
+ | Input | Output | Rule |
67
+ |-------|--------|------|
68
+ | `ProductCode` | `product-code` | Insert `-` before uppercase letters |
69
+ | `Product` | `product` | Lowercase single words |
70
+ | `IDs` | `ids` | Lowercase acronyms |
71
+ | `HTTPSConnection` | `https-connection` | Insert `-` before each uppercase cluster transition |
72
+ | `CamelCaseExample` | `camel-case-example` | Insert `-` at each camelCase boundary |
73
+
74
+ ---
75
+
76
+ ## Implementation Pattern
77
+
78
+ When generating routes, apply kebab-case to all multi-word segments:
79
+
80
+ ```tsx
81
+ // CORRECT
82
+ <Route path="/human-resources" element={<HRLayout />}>
83
+ <Route path="employees" element={<EmployeesPage />} />
84
+ <Route path="time-management" element={<TimeManagementPage />} />
85
+ </Route>
86
+
87
+ // FORBIDDEN
88
+ <Route path="/humanresources" element={<HRLayout />} />
89
+ <Route path="/HR" element={<HRLayout />} />
90
+ <Route path="/human_resources" element={<HRLayout />} />
91
+ ```
92
+
93
+ ---
94
+
95
+ ## Cross-Reference with Navigation Seeds
96
+
97
+ Before finalizing route paths, verify they match navigation seeds:
98
+
99
+ **Step 1:** Extract application code from `{full_path}` (e.g., `human-resources.time-management` → app: `human-resources`)
100
+
101
+ **Step 2:** Check existing navigation seeds:
102
+ ```bash
103
+ Glob: **/Seeding/Data/Navigation/NavigationApplicationSeedData.cs
104
+ Search for: Route = "/{application_kebab}"
105
+ ```
106
+
107
+ **Step 3:** Ensure App.tsx routes use the exact same kebab-case format.
108
+
109
+ ---
110
+
111
+ ## Validation Checklist
112
+
113
+ - [ ] All multi-word segments use hyphens (kebab-case)
114
+ - [ ] Single-word segments are lowercase
115
+ - [ ] Route paths match navigation seed data routes
116
+ - [ ] No uppercase letters in route paths
117
+ - [ ] No underscores (`_`) or camelCase in paths
@@ -0,0 +1,107 @@
1
+ # Frontend: Route Wiring in App.tsx
2
+
3
+ > Referenced from `steps/step-05-frontend.md` — Detailed route wiring patterns and verification.
4
+
5
+ ---
6
+
7
+ ## Step 4: Wire Routes to App.tsx (BLOCKING)
8
+
9
+ **CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
10
+
11
+ After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
12
+
13
+ ---
14
+
15
+ ## Step 4a: Import Page Components
16
+
17
+ At the top of App.tsx:
18
+
19
+ ```tsx
20
+ import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
21
+ // Or lazy-loaded:
22
+ const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{EntityName}Page'));
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Step 4b: Detect App.tsx Routing Pattern
28
+
29
+ Read App.tsx and detect which pattern is used:
30
+
31
+ ### Pattern A: applicationRoutes Object
32
+
33
+ **If App.tsx contains:** `applicationRoutes: ApplicationRouteExtensions`
34
+
35
+ → Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)
36
+
37
+ ```tsx
38
+ const applicationRoutes: ApplicationRouteExtensions = {
39
+ 'human-resources': [
40
+ // existing routes...
41
+ { path: '{module_kebab}', element: <{EntityName}ListPage /> },
42
+ { path: '{module_kebab}/new', element: <Create{EntityName}Page /> },
43
+ { path: '{module_kebab}/:id', element: <{EntityName}DetailPage /> },
44
+ { path: '{module_kebab}/:id/edit', element: <Create{EntityName}Page /> },
45
+ ],
46
+ };
47
+ ```
48
+
49
+ Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
50
+
51
+ ### Pattern B: JSX Routes
52
+
53
+ **If App.tsx contains:** `<Route path="/{application}" element={<{Layout} />}>`
54
+
55
+ → Insert `<Route>` children inside the Layout wrapper:
56
+
57
+ ```tsx
58
+ <Route path="/human-resources" element={<BusinessLayout />}>
59
+ {/* ... existing routes ... */}
60
+ <Route path="{module_kebab}" element={<{EntityName}Page />} />
61
+ </Route>
62
+ ```
63
+
64
+ **ALSO add the same routes inside the tenant-prefixed block:**
65
+
66
+ Find `<Route path="/t/:slug">` and add the **same route entries** there.
67
+
68
+ ---
69
+
70
+ ## Step 4c: Application-to-Layout Mapping
71
+
72
+ | Application prefix | Layout Component | Route path |
73
+ |---------|------------------|------------|
74
+ | `administration.*` | `AdminLayout` | `/administration` |
75
+ | `*` (business apps) | `BusinessLayout` | `/{application}` |
76
+ | `myspace.*` | `UserLayout` | `/myspace` |
77
+
78
+ ---
79
+
80
+ ## Step 4d: Verify Wiring
81
+
82
+ ```
83
+ Tool: mcp__smartstack__validate_frontend_routes
84
+ Args:
85
+ scope: "routes"
86
+ ```
87
+
88
+ If `appWiring.issues` is not empty, fix the wiring before proceeding.
89
+
90
+ ---
91
+
92
+ ## Forbidden Patterns (BOTH patterns)
93
+
94
+ - Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
95
+ - Adding routes OUTSIDE the Layout wrapper (shell will not render)
96
+ - Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
97
+
98
+ ---
99
+
100
+ ## Verification Checklist
101
+
102
+ - [ ] Routes are inside Layout wrapper (BusinessLayout, AdminLayout, UserLayout)
103
+ - [ ] Routes use NESTED structure (not flat)
104
+ - [ ] Application kebab-case matches navigation seed data
105
+ - [ ] Both standard and tenant-prefixed blocks have routes (if using Pattern B)
106
+ - [ ] Page components are imported at top of App.tsx
107
+ - [ ] `mcp__smartstack__validate_frontend_routes` returns no issues
@@ -9,13 +9,13 @@
9
9
  **CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
10
10
 
11
11
  ```tsx
12
- // CORRECT - Inside BusinessLayout (shell renders: header + AvatarMenu + sidebar)
13
- <Route path="/business" element={<BusinessLayout />}>
14
- <Route path="sales/products" element={<ProductsPage />} />
12
+ // CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
13
+ <Route path="/sales" element={<SalesLayout />}>
14
+ <Route path="products" element={<ProductsPage />} />
15
15
  </Route>
16
16
 
17
17
  // FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
18
- <Route path="/business/sales/products" element={<ProductsPage />} />
18
+ <Route path="/sales/products" element={<ProductsPage />} />
19
19
  ```
20
20
 
21
21
  ### Rule 2: Use nested routes (not flat)
@@ -24,8 +24,8 @@
24
24
 
25
25
  ```tsx
26
26
  // CORRECT - Nested routes inside layout
27
- <Route path="/business" element={<BusinessLayout />}>
28
- <Route path="sales">
27
+ <Route path="/sales" element={<SalesLayout />}>
28
+ <Route path="products">
29
29
  <Route index element={<Navigate to="products" replace />} />
30
30
  <Route path="products" element={<ProductsPage />} />
31
31
  <Route path="orders" element={<OrdersPage />} />
@@ -33,8 +33,8 @@
33
33
  </Route>
34
34
 
35
35
  // FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
36
- <Route path="/business/sales" element={<Navigate to="products" />} />
37
- <Route path="/business/sales/products" element={<ProductsPage />} />
36
+ <Route path="/sales/products" element={<Navigate to="products" />} />
37
+ <Route path="/sales/products" element={<ProductsPage />} />
38
38
  ```
39
39
 
40
40
  ## Post-Generation Verification (MANDATORY)
@@ -74,9 +74,9 @@ Verify exactly **4 language files** exist with identical key structures:
74
74
  ### 5. Route Check (BLOCKING)
75
75
 
76
76
  Verify routes are:
77
- - **INSIDE** the Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
77
+ - **INSIDE** the Layout wrapper (e.g. `SalesLayout`, `AdminLayout`, or `UserLayout`)
78
78
  - **NESTED** (not flat)
79
- - Following path convention: `/{context}/{application_kebab}/{module_kebab}` (kebab-case)
79
+ - Following path convention: `/{application_kebab}/{module_kebab}` (kebab-case)
80
80
 
81
81
  ### 5b. Route Wiring Check (BLOCKING)
82
82
 
@@ -110,7 +110,7 @@ Scan App.tsx route paths for non-kebab-case segments:
110
110
 
111
111
  **Verification steps:**
112
112
 
113
- 1. Extract all route path strings from App.tsx (both `contextRoutes` and `<Route path="...">`)
113
+ 1. Extract all route path strings from App.tsx (both `applicationRoutes` and `<Route path="...">`)
114
114
  2. For each multi-word path segment, verify it uses hyphens (kebab-case)
115
115
  3. Cross-reference route paths with navigation seed data routes to ensure exact match
116
116
  4. Single-word segments are fine as-is (e.g., `employees`, `products`)
@@ -150,7 +150,7 @@ Common issues: missing imports, wrong interface names, incorrect prop types, mis
150
150
  IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
151
151
 
152
152
  **Focus only on errors in files generated by this step:**
153
- - `pages/{context}/{application}/{module}/*.tsx`
153
+ - `pages/{application}/{module}/*.tsx`
154
154
  - `services/api/{entityCode}Api.ts`
155
155
  - `types/{entityName}.types.ts`
156
156
  - `hooks/use{EntityName}*.ts`