@atlashub/smartstack-cli 3.28.0 → 3.30.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 (44) hide show
  1. package/dist/index.js +6 -7
  2. package/dist/index.js.map +1 -1
  3. package/package.json +2 -3
  4. package/templates/project/api.ts.template +4 -2
  5. package/templates/project/appsettings.json.template +1 -1
  6. package/templates/skills/apex/_shared.md +13 -0
  7. package/templates/skills/apex/references/post-checks.md +228 -6
  8. package/templates/skills/apex/references/smartstack-api.md +67 -17
  9. package/templates/skills/apex/references/smartstack-frontend.md +41 -1
  10. package/templates/skills/apex/references/smartstack-layers.md +40 -10
  11. package/templates/skills/apex/steps/step-02-plan.md +16 -11
  12. package/templates/skills/apex/steps/step-03-execute.md +6 -0
  13. package/templates/skills/apex/steps/step-04-examine.md +4 -2
  14. package/templates/skills/application/references/frontend-verification.md +26 -1
  15. package/templates/skills/application/steps/step-03-roles.md +1 -1
  16. package/templates/skills/application/steps/step-05-frontend.md +24 -8
  17. package/templates/skills/application/templates-frontend.md +41 -22
  18. package/templates/skills/application/templates-seed.md +53 -16
  19. package/templates/skills/business-analyse/SKILL.md +4 -2
  20. package/templates/skills/business-analyse/_shared.md +17 -4
  21. package/templates/skills/business-analyse/react/schema.md +1 -1
  22. package/templates/skills/business-analyse/references/agent-module-prompt.md +40 -11
  23. package/templates/skills/business-analyse/references/consolidation-structural-checks.md +4 -3
  24. package/templates/skills/business-analyse/references/deploy-modes.md +1 -1
  25. package/templates/skills/business-analyse/references/handoff-file-templates.md +4 -4
  26. package/templates/skills/business-analyse/references/robustness-checks.md +12 -9
  27. package/templates/skills/business-analyse/references/spec-auto-inference.md +3 -3
  28. package/templates/skills/business-analyse/references/team-orchestration.md +57 -23
  29. package/templates/skills/business-analyse/references/ui-resource-cards.md +3 -3
  30. package/templates/skills/business-analyse/references/validation-checklist.md +21 -3
  31. package/templates/skills/business-analyse/schemas/sections/specification-schema.json +33 -5
  32. package/templates/skills/business-analyse/steps/step-03a2-analysis.md +12 -0
  33. package/templates/skills/business-analyse/steps/step-03b-ui.md +14 -2
  34. package/templates/skills/business-analyse/steps/step-03c-compile.md +17 -9
  35. package/templates/skills/business-analyse/steps/step-03d-validate.md +42 -2
  36. package/templates/skills/business-analyse/steps/step-04b-analyze.md +5 -3
  37. package/templates/skills/business-analyse/steps/step-05a-handoff.md +23 -15
  38. package/templates/skills/business-analyse/templates/tpl-handoff.md +10 -8
  39. package/templates/skills/business-analyse/templates/tpl-progress.md +7 -6
  40. package/templates/skills/ralph-loop/references/category-rules.md +50 -6
  41. package/templates/skills/ralph-loop/references/compact-loop.md +16 -1
  42. package/templates/skills/ralph-loop/references/core-seed-data.md +158 -38
  43. package/templates/skills/ralph-loop/references/task-transform-legacy.md +3 -3
  44. package/templates/skills/ralph-loop/steps/step-02-execute.md +109 -1
@@ -24,12 +24,17 @@ Your mission: specify module "{moduleCode}" completely and autonomously.
24
24
  ## Mode: PROPOSE & REVIEW (Autonomous)
25
25
 
26
26
  You work WITHOUT user interaction:
27
- - Do NOT use AskUserQuestion — you make all decisions autonomously
27
+ - **ABSOLUTE PROHIBITION: NEVER use AskUserQuestion**not in ANY step (03a1, 03a2, 03b, 03c, 03d)
28
+ - The step files you load contain AskUserQuestion calls — these are for INLINE MODE ONLY
29
+ - When you see `AskUserQuestion` in a step file → replace with ULTRATHINK autonomous decision
30
+ - When you see `Ask via AskUserQuestion` → decide autonomously based on context
31
+ - When you see validation options (Auto-corriger, Réviser, etc.) → auto-correct silently
28
32
  - Use ULTRATHINK to reason about every design choice
29
33
  - Base decisions on the context below + SmartStack conventions
30
34
  - Write the specification to feature.json via ba-writer operations
31
35
  - Send a structured proposal summary to the team lead when done
32
36
  - Wait for approval or revision feedback
37
+ - In step-03d: SKIP section 12 (Loop Decision) entirely → go to section 12-bis (Agent Mode)
33
38
 
34
39
  ## Module Context
35
40
 
@@ -132,17 +137,19 @@ Execute ALL compilation sections:
132
137
  - Functional Requirements
133
138
  - Permission matrix (CRUD per entity + module admin)
134
139
  - Navigation seed data (7 arrays — CRITICAL)
135
- - i18n keys (4 languages: fr, en, nl, de)
140
+ - i18n keys (4 languages: fr, en, it, de)
136
141
  - API endpoints summary
137
142
 
138
- **CRITICAL for seed data — 7 mandatory arrays:**
139
- 1. navigationModules (1 entry)
140
- 2. navigationSections (1 per section)
141
- 3. navigationResources (1+ per section)
142
- 4. navigationTranslations (4 languages × all entries)
143
- 5. permissions (CRUD per entity)
144
- 6. rolePermissions (admin=all, manager=most, contributor=create+read+update, viewer=read)
145
- 7. permissionConstants (C# constant names)
143
+ **CRITICAL for seed data — 9 mandatory arrays:**
144
+ 1. navigationApplications (1 entry — application-level, created ONCE per app)
145
+ 2. applicationRoles (4 entries — admin, manager, contributor, viewer)
146
+ 3. navigationModules (1 entry per module)
147
+ 4. navigationSections (1 per section)
148
+ 5. navigationResources (1+ per section)
149
+ 6. navigationTranslations (4 languages × all entries)
150
+ 7. permissions (wildcard + CRUD per module — {path, action, description} format)
151
+ 8. rolePermissions (admin=wildcard, manager=CRU, contributor=CR, viewer=R)
152
+ 9. permissionConstants (C# constant names)
146
153
 
147
154
  ### Step 5: Validate & Propose (step-03d-validate.md)
148
155
  Load: `templates/skills/business-analyse/steps/step-03d-validate.md`
@@ -221,7 +228,29 @@ SendMessage({
221
228
  summary: "{moduleCode} module complete"
222
229
  })
223
230
 
224
- Then STOP do not proceed to next module. The team lead handles ordering.
231
+ Then WAIT for the team lead to send you a `shutdown_request`.
232
+ Do NOT proceed to next module — the team lead handles module ordering.
233
+
234
+ ### Shutdown handling (MANDATORY):
235
+
236
+ When you receive a message with `type: "shutdown_request"` from the team lead:
237
+ → Extract the `requestId` from the JSON message
238
+ → IMMEDIATELY respond with:
239
+
240
+ ```
241
+ SendMessage({
242
+ type: "shutdown_response",
243
+ request_id: "{requestId from the shutdown_request}",
244
+ approve: true
245
+ })
246
+ ```
247
+
248
+ This terminates your process. Do NOT output any text after sending `shutdown_response`.
249
+
250
+ **IMPORTANT:** Do NOT confuse APPROVED with shutdown. The sequence is:
251
+ 1. Team lead sends `APPROVED:{moduleCode}` → you update status + send `MODULE_COMPLETE`
252
+ 2. Team lead sends `shutdown_request` → you respond with `shutdown_response approve: true` → you terminate
253
+ These are TWO separate steps. Never try to self-terminate or call `shutdown_response` without a `shutdown_request`.
225
254
 
226
255
  ## ID Naming Convention
227
256
 
@@ -23,7 +23,7 @@
23
23
  | `specification.seedDataBusiness` | YES | Must define reference/lookup seed data for testing (types, categories, statuses) |
24
24
  | `specification.gherkinScenarios` | YES | Must be `{feature, scenarios[]}` (NOT flat array) |
25
25
  | `specification.navigation` | YES | Must have entries[] |
26
- | `specification.i18nKeys[]` | YES | Must have >=1 key with fr, en, nl, de |
26
+ | `specification.i18nKeys[]` | YES | Must have >=1 key with fr, en, it, de |
27
27
  | `validation` | YES | Must have completenessChecks, consistencyChecks, semanticChecks, decision |
28
28
 
29
29
  ## B. Field Name Conformity
@@ -46,7 +46,8 @@
46
46
  | BR | `BR-(VAL\|CALC\|WF\|SEC\|DATA)-{PREFIX}-\d{3}` | BR-VAL-RM-001 |
47
47
  | UC | `UC-{PREFIX}-\d{3}` | UC-RM-001 |
48
48
  | FR | `FR-{PREFIX}-\d{3}` | FR-RM-001 |
49
- | Permissions | `business.{app}.{module}.{resource}.{action}` | business.freebike.repairs.create |
49
+ | Permissions (module) | `business.{app}.{module}.{action}` | business.freebike.repairs.create |
50
+ | Permissions (section) | `business.{app}.{module}.{section}.{action}` | business.freebike.repairs.dashboard.read |
50
51
 
51
52
  ## D. Cross-Module ID Uniqueness
52
53
 
@@ -71,7 +72,7 @@ FOR each region: IF missing position or components[] -> ERROR
71
72
 
72
73
  ```
73
74
  FOR each navigationModules[].code:
74
- FOR each language in [fr, en, nl, de]:
75
+ FOR each language in [fr, en, it, de]:
75
76
  IF NOT EXISTS navigationTranslations[] with moduleCode AND language -> ERROR
76
77
  ```
77
78
 
@@ -37,7 +37,7 @@ Focused handoff for changes:
37
37
  |-------|-----------|
38
38
  | All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
39
39
  | prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
40
- | progress.txt incomplete | Ensure all 5 CORE SeedData entries are present per module. Check topological order. |
40
+ | progress.txt incomplete | Ensure all CORE SeedData entries are present: 2 app-level (NavigationApplication + ApplicationRoles) + per module (NavigationModule + NavigationSections + Permissions + Roles). Check topological order. |
41
41
  | BA manifest not found | Create docs/business/index.json if missing. Use schema provided in section 3. |
42
42
  | Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.json metadata exactly. |
43
43
  | ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
@@ -90,16 +90,16 @@ From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.
90
90
 
91
91
  ## 4.6 SeedData Files
92
92
 
93
- **OBLIGATORY: 6 CORE (1 app-level + 5 per module) + business per module:**
93
+ **OBLIGATORY: 2 app-level CORE + per module CORE (NavigationModule + NavigationSections + Permissions + Roles) + business per module:**
94
94
 
95
95
  ```json
96
96
  "seedData": [
97
97
  { "path": "src/Infrastructure/Persistence/Seeding/Data/NavigationApplicationSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationApplications", "module": "shared", "description": "Application-level navigation seed data. Created ONCE per application (FIRST). Provides ApplicationId for modules and roles." },
98
+ { "path": "src/Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.rolePermissions", "module": "shared", "description": "Application-scoped role definitions (admin, manager, contributor, viewer). Created ONCE per application. Provides role entries for SeedRolesAsync()." },
98
99
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationModuleSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationModules", "module": "{moduleCode}" },
100
+ { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationSectionSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.navigationSections", "module": "{moduleCode}", "description": "MANDATORY when sections defined. Seeds section-level navigation entries (list, dashboard, etc.) with full absolute routes." },
99
101
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/PermissionsSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.permissions", "module": "{moduleCode}" },
100
- { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.roles", "module": "{moduleCode}" },
101
- { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/TenantSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.tenants", "module": "{moduleCode}" },
102
- { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/UserSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.users", "module": "{moduleCode}" },
102
+ { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs", "type": "SeedData", "category": "core", "source": "specification.seedDataCore.rolePermissions", "module": "{moduleCode}" },
103
103
  { "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs", "type": "SeedData", "category": "business", "source": "specification.seedDataBusiness.{module}", "module": "{moduleCode}" }
104
104
  ]
105
105
  ```
@@ -17,7 +17,7 @@ This document consolidates all robustness checks implemented across the business
17
17
 
18
18
  Ensures each module has ALL required components before being marked as "specified". Prevents incomplete modules from reaching step-04 consolidation.
19
19
 
20
- ### Checks (30 total)
20
+ ### Checks (31 total)
21
21
 
22
22
  #### SECTION 1: Data Model (3 checks)
23
23
 
@@ -50,38 +50,41 @@ Ensures each module has ALL required components before being marked as "specifie
50
50
  | # | Check | Minimum | Blocking | Rationale |
51
51
  |---|-------|---------|----------|-----------|
52
52
  | 4.1 | Permissions count | ≥5 | YES | CRUD (4) + 1 business action minimum |
53
- | 4.2 | Permission format | `business.{app}.{module}.{resource}.{action}` | YES | Wrong format breaks RBAC system |
53
+ | 4.2 | Permission format | Module: `business.{app}.{module}.{action}` or Section: `business.{app}.{module}.{section}.{action}` | YES | Wrong format breaks RBAC system |
54
54
  | 4.3 | Role permissions | All roles have ≥1 permission | YES | Roles without permissions are useless |
55
55
 
56
- #### SECTION 5: UI & Navigation (3 checks)
56
+ #### SECTION 5: UI & Navigation (4 checks)
57
57
 
58
58
  | # | Check | Minimum | Blocking | Rationale |
59
59
  |---|-------|---------|----------|-----------|
60
60
  | 5.1 | Sections count | ≥2 | YES | Modules need list + form minimum |
61
61
  | 5.2 | Wireframes count | 1 per section | YES | EVERY section MUST have wireframe |
62
62
  | 5.3 | Navigation entries | ≥1 | YES | Module must be accessible in menu |
63
+ | 5.4 | Navigation route patterns | No `/list` or `/detail/:id` suffixes | YES | list route = module route (index), detail route = module + /:id. FORBIDDEN: `/module/list`, `/module/detail/:id` |
63
64
 
64
65
  #### SECTION 6: I18N & Messages (3 checks)
65
66
 
66
67
  | # | Check | Minimum | Blocking | Rationale |
67
68
  |---|-------|---------|----------|-----------|
68
69
  | 6.1 | i18n keys count | ≥42 | YES | Entities, fields, messages, validation, navigation |
69
- | 6.2 | i18n languages | All keys have 4 languages (fr/en/nl/de) | YES | Missing translations break multi-language |
70
+ | 6.2 | i18n languages | All keys have 4 languages (fr/en/it/de) | YES | Missing translations break multi-language |
70
71
  | 6.3 | Messages count | ≥4 | YES | 1 success, 1 error, 1 warning, 1 info minimum |
71
72
 
72
73
  #### SECTION 7: Seed Data (2 checks)
73
74
 
74
75
  | # | Check | Minimum | Blocking | Rationale |
75
76
  |---|-------|---------|----------|-----------|
76
- | 7.1 | CORE seed data sections | All 5 sections present | YES | Missing CORE data breaks deployment |
77
+ | 7.1 | CORE seed data sections | All 7 sections present | YES | Missing CORE data breaks deployment |
77
78
  | 7.2 | Business seed data | Template defined | NO (WARNING) | Helps with testing |
78
79
 
79
80
  **CORE sections required:**
80
81
  1. `navigationModules`
81
- 2. `navigationTranslations`
82
- 3. `permissions`
83
- 4. `rolePermissions`
84
- 5. `permissionConstants`
82
+ 2. `navigationSections`
83
+ 3. `navigationResources`
84
+ 4. `navigationTranslations`
85
+ 5. `permissions`
86
+ 6. `rolePermissions`
87
+ 7. `permissionConstants`
85
88
 
86
89
  #### SECTION 8: API Endpoints (2 checks)
87
90
 
@@ -90,15 +90,15 @@ IF entity has lifeCycles:
90
90
  ### Detail section auto-generation
91
91
 
92
92
  When auto-generating the detail section, create:
93
- - `specification.sections[]` entry with `code: "detail"`, `navigation: "hidden"`, route `/business/{app}/{module}/detail/:id`
93
+ - `specification.sections[]` entry with `code: "detail"`, `navigation: "hidden"`, route `/business/{app}/{module}/:id`
94
94
  - `specification.uiWireframes[]` entry with `section: "detail"` and ASCII mockup showing all tabs
95
95
  - Resources: `{module}-detail-header` (DetailHeader), `{module}-detail-tabs` (TabPanel), `{module}-info-card` (DetailCard), one `{module}-{relation}-grid` per relation tab, `{module}-history` (Timeline if auditable)
96
96
 
97
97
  ### Detail page navigation wiring
98
98
 
99
99
  The detail page is NOT a sidebar entry. Navigation is handled by:
100
- - **From list**: row click action `navigate:detail` → `/business/{app}/{module}/detail/{id}`
101
- - **Back button**: detail header → `/business/{app}/{module}/list`
100
+ - **From list**: row click action `navigate:detail` → `/business/{app}/{module}/{id}`
101
+ - **Back button**: detail header → `/business/{app}/{module}`
102
102
  - **Route registration**: route MUST be registered in frontend routing with `:id` parameter
103
103
 
104
104
  ## Status/Lifecycle Enhancement
@@ -85,13 +85,21 @@ Task({
85
85
  - Reason: later modules may reference entities/FKs from earlier modules
86
86
  - **Future optimization**: modules in the same dependency layer with no cross-refs COULD run in parallel
87
87
 
88
+ ### 2d. After Spawning — Wait for Agent Message
89
+
90
+ After calling `Task()` to spawn the module agent, the team lead **MUST WAIT** for the agent to send a message.
91
+ Messages from teammates are delivered automatically — do NOT poll or re-spawn.
92
+
93
+ The agent will send `PROPOSAL_READY:{moduleCode}` when its specification is complete.
94
+ This may take several minutes. The team lead does nothing until the message arrives.
95
+
88
96
  ---
89
97
 
90
98
  ## 3. Propose & Review Protocol
91
99
 
92
100
  ### 3a. Team Lead Receives PROPOSAL_READY
93
101
 
94
- After the agent finishes specifying a module, it sends:
102
+ The module agent sends this message when specification is complete:
95
103
 
96
104
  ```
97
105
  PROPOSAL_READY:{moduleCode}
@@ -130,9 +138,9 @@ PROPOSAL_READY:{moduleCode}
130
138
  - ...
131
139
  ```
132
140
 
133
- ### 3b. Team Lead Presents to User
141
+ ### 3b. Present to User and Handle Response
134
142
 
135
- Format the proposal for user review:
143
+ **Step 1:** Format and display the proposal:
136
144
 
137
145
  ```
138
146
  ═══════════════════════════════════════════════════════════
@@ -144,7 +152,7 @@ Format the proposal for user review:
144
152
  ─────────────────────────────────────────────────────────
145
153
  ```
146
154
 
147
- Then ask user via AskUserQuestion:
155
+ **Step 2:** Ask the user via AskUserQuestion:
148
156
 
149
157
  ```
150
158
  Validez-vous cette specification ?
@@ -154,9 +162,9 @@ Options:
154
162
  3. "Voir detail" → team lead reads module feature.json and displays full content
155
163
  ```
156
164
 
157
- ### 3c. Approval Flow
165
+ **Step 3 IMMEDIATELY after AskUserQuestion returns, handle the response:**
158
166
 
159
- **If user approves:**
167
+ **IF user selected "Valider" (approve):**
160
168
  ```
161
169
  SendMessage({
162
170
  type: "message",
@@ -165,9 +173,12 @@ SendMessage({
165
173
  summary: "{moduleCode} approved by user"
166
174
  })
167
175
  ```
168
- Agent writes final status, sends MODULE_COMPLETE, and shuts down.
176
+ CRITICAL: You MUST send this message. Do NOT skip this step.
177
+ → Then WAIT for the agent to send `MODULE_COMPLETE:{moduleCode}` (see §4).
169
178
 
170
- **If user requests modifications:**
179
+ **IF user selected "Modifier" (revision):**
180
+ → Ask user for specific feedback via AskUserQuestion
181
+ → Then send:
171
182
  ```
172
183
  SendMessage({
173
184
  type: "message",
@@ -176,14 +187,14 @@ SendMessage({
176
187
  summary: "{moduleCode} revision requested"
177
188
  })
178
189
  ```
179
- Agent applies changes, re-validates, sends new PROPOSAL_READY.
190
+ Then WAIT for the agent to send a new `PROPOSAL_READY` → go back to Step 1.
180
191
 
181
- **If user wants to see detail:**
182
- Team lead reads module feature.json via ba-reader.readSection({feature_id, section})
183
- Displays relevant sections in detail
184
- Re-asks validation question
192
+ **IF user selected "Voir detail":**
193
+ Read module feature.json via ba-reader.readSection({feature_id, section})
194
+ Display relevant sections in detail
195
+ Go back to Step 2 (re-ask the validation question)
185
196
 
186
- ### 3d. Revision Limits
197
+ ### 3c. Revision Limits
187
198
 
188
199
  - Max **3 revision cycles** per module
189
200
  - After 3 rejections: team lead asks user if they want to switch to **inline interactive mode** for this module
@@ -192,30 +203,42 @@ SendMessage({
192
203
 
193
204
  ---
194
205
 
195
- ## 4. Module Completion & Advancement
206
+ ## 4. Module Completion & Agent Shutdown
207
+
208
+ When the team lead receives `MODULE_COMPLETE:{moduleCode}` from the agent, execute these steps **IN ORDER**:
196
209
 
197
- When agent sends MODULE_COMPLETE:
210
+ ### 4a. Update Tracking
198
211
 
199
212
  ```javascript
200
- // Update tracking
201
213
  teamContext.completedModules.push(moduleCode);
202
214
  teamContext.currentModuleIdx++;
203
215
 
204
- // Update master feature.json
205
216
  ba-writer.advanceModuleLoop({feature_id});
206
217
  ba-writer.updateModuleStatus({feature_id, moduleCode, status: "specified"});
207
218
 
208
- // Display progress
209
219
  Display: "✓ Module {moduleCode} specified ({completedModules.length}/{moduleOrder.length})"
220
+ ```
221
+
222
+ ### 4b. Shutdown Agent (MANDATORY — do NOT skip)
223
+
224
+ **IMMEDIATELY** after receiving MODULE_COMPLETE, send shutdown_request to terminate the agent:
210
225
 
211
- // Shutdown agent
226
+ ```
212
227
  SendMessage({
213
228
  type: "shutdown_request",
214
229
  recipient: "mod-{moduleCode}",
215
230
  content: "Module complete, shutting down"
216
- });
231
+ })
217
232
  ```
218
233
 
234
+ The agent will respond with `shutdown_response approve: true` and terminate.
235
+ **Wait for the agent to confirm shutdown** before spawning the next agent.
236
+
237
+ > **WARNING:** If you skip this step, the agent will remain running indefinitely.
238
+ > The agent CANNOT self-terminate — it NEEDS this shutdown_request from you.
239
+
240
+ ### 4c. Next Module or Consolidation
241
+
219
242
  If more modules remain → spawn next module agent (go to §2).
220
243
  If all modules complete → proceed to §5 (Consolidation).
221
244
 
@@ -346,13 +369,21 @@ Display final status to user. If quality gate PASS → ready for /ralph-loop.
346
369
  After handoff complete:
347
370
 
348
371
  ```javascript
349
- // Shutdown any remaining agents
350
- for (const agentName of ["consolidation", "handoff"]) {
372
+ // Safety net: shutdown ALL remaining agents (module agents + consolidation + handoff)
373
+ // Module agents should already be shut down in §4b, but this catches any missed ones.
374
+ const allAgents = [
375
+ ...teamContext.moduleOrder.map(m => `mod-${m}`),
376
+ "consolidation",
377
+ "handoff"
378
+ ];
379
+
380
+ for (const agentName of allAgents) {
351
381
  SendMessage({
352
382
  type: "shutdown_request",
353
383
  recipient: agentName,
354
384
  content: "Workflow complete"
355
385
  });
386
+ // Ignore errors for already-terminated agents
356
387
  }
357
388
 
358
389
  // Delete team
@@ -361,6 +392,9 @@ TeamDelete();
361
392
  Display: "═══ Business-analyse complete — Team cleaned up ═══"
362
393
  ```
363
394
 
395
+ > **Note:** Sending shutdown_request to an already-terminated agent is harmless.
396
+ > This safety net ensures no orphan agents remain running.
397
+
364
398
  ---
365
399
 
366
400
  ## 8. Error Recovery
@@ -8,7 +8,7 @@
8
8
  {
9
9
  "code": "list",
10
10
  "labels": { "fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste" },
11
- "route": "/business/{app}/{module}/list",
11
+ "route": "/business/{app}/{module}",
12
12
  "icon": "list",
13
13
  "permission": "business.{app}.{module}.read",
14
14
  "wireframe": "{module}-list",
@@ -81,7 +81,7 @@
81
81
  {
82
82
  "code": "detail",
83
83
  "labels": { "fr": "Détail", "en": "Detail", "it": "Dettaglio", "de": "Detail" },
84
- "route": "/business/{app}/{module}/detail/:id",
84
+ "route": "/business/{app}/{module}/:id",
85
85
  "icon": "file-text",
86
86
  "permission": "business.{app}.{module}.read",
87
87
  "wireframe": "{module}-detail",
@@ -238,7 +238,7 @@ A wireframe without `componentMapping` or `layout` will FAIL validation in step
238
238
  "type": "page",
239
239
  "regions": [
240
240
  { "id": "header", "position": "top", "components": [
241
- { "type": "BackButton", "target": "/business/{app}/{module}/list" },
241
+ { "type": "BackButton", "target": "/business/{app}/{module}" },
242
242
  { "type": "DetailHeader", "resourceRef": "{module}-detail-header" },
243
243
  { "type": "StatusBadge", "resourceRef": "{module}-status" }
244
244
  ]},
@@ -115,10 +115,10 @@ const checklist = {
115
115
  },
116
116
 
117
117
  permissionFormat: {
118
- check: "All permissions use full format: business.{app}.{module}.{resource}.{action}",
118
+ check: "All permissions use correct format: module-level business.{app}.{module}.{action} or section-level business.{app}.{module}.{section}.{action}",
119
119
  status: validatePermissionFormat() ? "PASS" : "FAIL",
120
120
  blocking: true,
121
- details: "Wrong format breaks RBAC system"
121
+ details: "Wrong format breaks RBAC system. Module-level = 4 segments, section-level = 5 segments."
122
122
  },
123
123
 
124
124
  rolePermissions: {
@@ -168,6 +168,24 @@ const checklist = {
168
168
  details: "Module must be accessible in menu"
169
169
  },
170
170
 
171
+ navigationRoutePatterns: {
172
+ check: "Navigation routes do NOT contain CRUD suffixes (/list, /detail/:id)",
173
+ status: (() => {
174
+ const allRoutes = [
175
+ ...(specification.seedDataCore?.navigationSections || []).map(s => s.route),
176
+ ...(specification.sections || []).map(s => s.route),
177
+ ...(specification.navigation?.entries || []).map(e => e.route)
178
+ ].filter(Boolean);
179
+ const forbidden = allRoutes.filter(r => r.match(/\/list$/) || r.match(/\/detail\/:id$/));
180
+ return forbidden.length === 0 ? "PASS" : "FAIL";
181
+ })(),
182
+ blocking: true,
183
+ details: "FORBIDDEN: /module/list (use /module), /module/detail/:id (use /module/:id). " +
184
+ "list route = module route (React Router index route). " +
185
+ "detail route = module route + /:id (React Router :id child). " +
186
+ "Other sections (dashboard, approve) add /{section} normally."
187
+ },
188
+
171
189
  // SECTION 6: I18N & MESSAGES (BLOCKING)
172
190
  i18nKeys: {
173
191
  minimum: 42, // Realistic minimum for a module
@@ -178,7 +196,7 @@ const checklist = {
178
196
  },
179
197
 
180
198
  i18nLanguages: {
181
- check: "All i18n keys have 4 languages (fr, en, nl, de)",
199
+ check: "All i18n keys have 4 languages (fr, en, it, de)",
182
200
  status: validateI18nCompleteness() ? "PASS" : "FAIL",
183
201
  blocking: true,
184
202
  details: "Missing translations break multi-language support"
@@ -26,7 +26,7 @@
26
26
  "id": { "type": "string", "pattern": "^UC-[A-Z]{2,4}-\\d{3}$", "description": "Module-prefixed UC ID (e.g., UC-RM-001)" },
27
27
  "name": { "type": "string" },
28
28
  "primaryActor": { "type": "string" },
29
- "permission": { "type": "string", "description": "business.{app}.{module}.{action}" },
29
+ "permission": { "type": "string", "description": "Module-level: business.{app}.{module}.{action} or section-level: business.{app}.{module}.{section}.{action}" },
30
30
  "preconditions": { "type": "array", "items": { "type": "string" } },
31
31
  "postconditions": { "type": "array", "items": { "type": "string" } },
32
32
  "mainScenario": { "type": "array", "items": { "type": "string" } },
@@ -82,7 +82,7 @@
82
82
  "type": "object",
83
83
  "required": ["path", "action"],
84
84
  "properties": {
85
- "path": { "type": "string", "description": "business.{app}.{module}.{action}" },
85
+ "path": { "type": "string", "description": "Module-level: business.{app}.{module}.{action} or section-level: business.{app}.{module}.{section}.{action}" },
86
86
  "action": { "type": "string", "enum": ["read", "create", "update", "delete", "export", "import", "admin", "*"] },
87
87
  "description": { "type": "string" }
88
88
  }
@@ -382,8 +382,36 @@
382
382
  },
383
383
  "seedDataCore": {
384
384
  "type": "object",
385
- "description": "7 mandatory SmartStack core SeedData definitions (modules, sections, resources, translations, permissions, rolePermissions, permissionConstants)",
385
+ "description": "9 mandatory SmartStack core SeedData definitions (navigationApplications, applicationRoles, modules, sections, resources, translations, permissions, rolePermissions, permissionConstants)",
386
386
  "properties": {
387
+ "navigationApplications": {
388
+ "type": "array",
389
+ "description": "Level 2 (Application) navigation entry for core.nav_Applications table. Created ONCE per application (FIRST). Provides ApplicationId for modules and roles.",
390
+ "items": {
391
+ "type": "object",
392
+ "required": ["code", "label", "icon", "route"],
393
+ "properties": {
394
+ "code": { "type": "string", "description": "Application code (PascalCase, e.g., HumanResources)" },
395
+ "label": { "type": "string", "description": "Application label in default language" },
396
+ "icon": { "type": "string", "description": "Lucide icon name" },
397
+ "route": { "type": "string", "description": "Full route path (e.g., /business/human-resources)" },
398
+ "sort": { "type": "integer", "description": "Display order" }
399
+ }
400
+ }
401
+ },
402
+ "applicationRoles": {
403
+ "type": "array",
404
+ "description": "Application-scoped role definitions (admin, manager, contributor, viewer). Created ONCE per application. Used by SeedRolesAsync() in IClientSeedDataProvider.",
405
+ "items": {
406
+ "type": "object",
407
+ "required": ["code", "name", "permissions"],
408
+ "properties": {
409
+ "code": { "type": "string", "description": "Role code (e.g., admin, manager, contributor, viewer)" },
410
+ "name": { "type": "string", "description": "Human-readable role name" },
411
+ "permissions": { "type": "string", "description": "Permission level: wildcard(*), CRU, CR, R" }
412
+ }
413
+ }
414
+ },
387
415
  "navigationModules": {
388
416
  "type": "array",
389
417
  "items": {
@@ -406,7 +434,7 @@
406
434
  "type": "object",
407
435
  "required": ["code", "label", "icon", "route", "parentCode", "permission"],
408
436
  "properties": {
409
- "code": { "type": "string", "description": "Section code (list, detail, create, dashboard)" },
437
+ "code": { "type": "string", "description": "Section code (list, detail, dashboard, approve, import, etc.)" },
410
438
  "label": { "type": "string", "description": "Section label in default language (fr)" },
411
439
  "icon": { "type": "string", "description": "Lucide icon name" },
412
440
  "route": { "type": "string", "description": "Full route path" },
@@ -486,7 +514,7 @@
486
514
  "type": "object",
487
515
  "required": ["code", "labels", "route", "permission", "wireframe", "useCases", "resources"],
488
516
  "properties": {
489
- "code": { "type": "string", "description": "Section code (kebab-case: list, detail, create, dashboard)" },
517
+ "code": { "type": "string", "description": "Section code (kebab-case: list, detail, dashboard, approve, import, etc.)" },
490
518
  "labels": {
491
519
  "type": "object",
492
520
  "properties": {
@@ -17,6 +17,18 @@ next_step: steps/step-03b-ui.md
17
17
  - **ID NAMING RULE:** All IDs MUST include module prefix (BR-{CAT}-{PREFIX}-{NNN}, OBJ-{PREFIX}-{NNN}, etc.)
18
18
  - **SCHEMA CONFORMITY RULE:** ALL data MUST fit within feature-schema.json structure
19
19
 
20
+ ## MODE DETECTION (inherited from step-03a1)
21
+
22
+ > **CRITICAL: Re-check your execution mode before proceeding.**
23
+
24
+ **IF you are running as a TEAM AGENT** (your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient):
25
+ → **NEVER** use `AskUserQuestion` — replace ALL user interactions with ULTRATHINK autonomous decisions
26
+ → You are in autonomous mode — make all choices based on decomposition data + SmartStack conventions
27
+ → Do NOT present options to the user — you PROPOSE to the team lead via SendMessage, not to the user
28
+
29
+ **IF you are running in the MAIN CONVERSATION** (classic inline mode):
30
+ → Normal interactive mode — use `AskUserQuestion` as documented below
31
+
20
32
  ## YOUR TASK
21
33
 
22
34
  Define the module's analysis section: objectives, entities (with attributes and relationships), business rules, process flow, and data lifecycle.
@@ -14,6 +14,18 @@ next_step: steps/step-03c-compile.md
14
14
  - ALWAYS use ULTRATHINK mode
15
15
  - This step is EXECUTED ONCE PER MODULE, after step-03a1-setup.md and step-03a2-analysis.md
16
16
  - **WIREFRAME RULE:** Every section MUST have a wireframe in `specification.uiWireframes[]`. No section without a validated mockup.
17
+
18
+ ## MODE DETECTION (inherited from step-03a1)
19
+
20
+ > **CRITICAL: Re-check your execution mode before proceeding.**
21
+
22
+ **IF you are running as a TEAM AGENT** (your prompt contains `PROPOSE & REVIEW` or `team-lead` as recipient):
23
+ → **NEVER** use `AskUserQuestion` — replace ALL wireframe validations with ULTRATHINK self-review
24
+ → Generate wireframes autonomously, self-validate them, move on
25
+ → Do NOT ask the user to validate mockups — the team lead handles review after PROPOSAL_READY
26
+
27
+ **IF you are running in the MAIN CONVERSATION** (classic inline mode):
28
+ → Normal interactive mode — display wireframes then ask for validation via `AskUserQuestion`
17
29
  - **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
18
30
  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
19
31
  The prefix is derived from the module code initials (2-4 chars):
@@ -243,7 +255,7 @@ A wireframe without `componentMapping` or `layout` will FAIL validation in step
243
255
 
244
256
  Adaptation rules for the detail mockup:
245
257
  - **Header**: entity code + name + status badge (if lifeCycles) + action buttons (edit, delete)
246
- - **Back button**: navigates to `/business/{app}/{module}/list`
258
+ - **Back button**: navigates to `/business/{app}/{module}`
247
259
  - **Tabs**: one per identified tab (Info + relations + history)
248
260
  - **Info tab content**: all entity attributes as label:value pairs (read-only by default)
249
261
  - **Edit button**: toggles the Info tab into SmartForm edit mode
@@ -261,7 +273,7 @@ Transition buttons are contextual: only show actions allowed from the current st
261
273
  5. **Store** in `specification.uiWireframes[]` with `section: "detail"`.
262
274
  See [references/ui-resource-cards.md](../references/ui-resource-cards.md) "Detail Page Wireframe" for exact JSON format.
263
275
 
264
- 6. **Create the detail section** in `specification.sections[]` with `navigation: "hidden"` and route `/business/{app}/{module}/detail/:id`.
276
+ 6. **Create the detail section** in `specification.sections[]` with `navigation: "hidden"` and route `/business/{app}/{module}/:id`.
265
277
  See [references/ui-resource-cards.md](../references/ui-resource-cards.md) "Detail Page section" for exact JSON format.
266
278
 
267
279
  ### 3b-bis. Wireframe-to-Component Mapping