@atlashub/smartstack-cli 3.31.0 → 3.32.0

package/templates/skills/apex/steps/step-08-run-tests.md

@@ -6,7 +6,7 @@ prev_step: steps/step-07-tests.md
 next_step: COMPLETE
 ---
 
-# Step 8: Run Tests (if -t)
+# Step 8: Run Tests
 
 **CRITICAL:** Fix the CODE, not the tests. Tests represent expected behavior.
 100% pass required for Sonar quality gate.
@@ -85,13 +85,22 @@ questions:
 
 ---
 
-## 5. Frontend Typecheck (if applicable)
+## 5. Frontend Tests + Typecheck (if applicable)
 
 ```bash
+# Run frontend tests first
+WEB_DIR=$(find . -name "vitest.config.ts" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | head -1)
+if [ -n "$WEB_DIR" ]; then
+  cd "$WEB_DIR"
+  npm run test
+  cd -
+fi
+
+# Then typecheck
 npm run typecheck
 ```
 
-**MUST PASS.**
+**BOTH MUST PASS.** If frontend tests fail, apply the same fix loop as backend (fix CODE, not tests, max 5 iterations).
 
 ---
 

package/templates/skills/application/references/provider-template.md

@@ -30,49 +30,71 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
     public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
     {
-        // Check idempotence
-        var exists = await context.NavigationApplications
-            .AnyAsync(a => a.Code == "{app_code}", ct);
-        if (exists) return;
-
-        // 1. Retrieve the parent context ("business", "platform", etc.)
-        var parentContext = await context.NavigationContexts
-            .FirstAsync(c => c.Code == "{context_code}", ct);
-
-        // 2. Create the application
-        var app = NavigationApplication.Create(
-            parentContext.Id,
-            "{app_code}",
-            "{app_label_en}",
-            "{app_desc_en}",
-            "{app_icon}",
-            IconType.Lucide,
-            "/{context_code}/{app_code}",
-            {display_order});
-        context.NavigationApplications.Add(app);
-        await ((DbContext)context).SaveChangesAsync(ct);
+        // --- Application (idempotent — reuse if already exists) ---
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry(Guid.Empty);
+        var existingApp = await context.NavigationApplications
+            .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
 
-        // 3. Create modules
-        // Use GUIDs and data from {Module}NavigationSeedData.cs
-        foreach (var moduleData in GetModuleSeedEntries(app.Id))
+        NavigationApplication app;
+        if (existingApp != null)
+        {
+            app = existingApp; // Reuse existing for module seeding below
+        }
+        else
         {
-            var module = NavigationModule.Create(
-                moduleData.ApplicationId,
-                moduleData.Code,
-                moduleData.Label,
-                moduleData.Description,
-                moduleData.Icon,
-                IconType.Lucide,
-                moduleData.Route,
-                moduleData.DisplayOrder);
-            context.NavigationModules.Add(module);
+            var parentContext = await context.NavigationContexts
+                .FirstAsync(c => c.Code == "{context_code}", ct);
+
+            appEntry = NavigationApplicationSeedData.GetApplicationEntry(parentContext.Id);
+            app = NavigationApplication.Create(
+                appEntry.ContextId, appEntry.Code, appEntry.Label,
+                appEntry.Description, appEntry.Icon, appEntry.IconType,
+                appEntry.Route, appEntry.DisplayOrder);
+            context.NavigationApplications.Add(app);
+            await ((DbContext)context).SaveChangesAsync(ct);
+
+            // Application translations (only when creating new application)
+            foreach (var t in NavigationApplicationSeedData.GetTranslationEntries())
+            {
+                context.NavigationTranslations.Add(
+                    NavigationTranslation.Create(t.EntityType, t.EntityId, t.LanguageCode, t.Label, t.Description));
+            }
+            await ((DbContext)context).SaveChangesAsync(ct);
         }
+
+        // --- Modules (idempotent per-module) ---
+        // var mod1Exists = await context.NavigationModules.AnyAsync(
+        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
+        // if (!mod1Exists) { context.NavigationModules.Add(NavigationModule.Create(...)); }
+        // Repeat per module...
         await ((DbContext)context).SaveChangesAsync(ct);
 
-        // 4. Create translations (4 languages per entity)
-        // Use data from {Module}NavigationTranslationSeedData.cs
-        // ...
+        // Resolve module entities
+        // var mod1Entity = await context.NavigationModules.FirstAsync(
+        //     m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
+
+        // --- Module translations (IDEMPOTENT — check before inserting) ---
+        // CRITICAL: nav_Translations has unique index IX_nav_Translations_EntityType_EntityId_LanguageCode
+        // Always guard with AnyAsync to prevent duplicate key errors on re-runs.
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == {Module}NavigationSeedData.{Module}ModuleId
+        //          && t.EntityType == NavigationEntityType.Module, ct))
+        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries()) { ... } }
         await ((DbContext)context).SaveChangesAsync(ct);
+
+        // --- Sections (idempotent per-section) ---
+        // Check each section before inserting: AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ...)
+
+        // --- Section translations (IDEMPOTENT — same guard pattern as module translations) ---
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == secEntry.Id && t.EntityType == NavigationEntityType.Section, ct))
+
+        // --- Resources (idempotent — use ACTUAL section IDs from DB) ---
+        // CRITICAL: NavigationSection.Create() generates its own ID. Deterministic seed GUIDs
+        // do NOT match actual SectionId in DB → FK_nav_Resources_nav_Sections_SectionId violation.
+        // MUST query actual section: var actualSection = await context.NavigationSections
+        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
+        // Then use actualSection.Id (NOT secEntry.Id) for NavigationResource.Create() and AnyAsync
     }
 
     public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
@@ -150,8 +172,9 @@ services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
 ## Critical Rules
 
 1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
-2. **Idempotence**: Each Seed method checks existence before inserting
-3. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
+2. **Idempotence**: Each Seed method checks existence before inserting. **Translations require explicit `AnyAsync` guard** — unique index `IX_nav_Translations_EntityType_EntityId_LanguageCode` causes crashes on duplicate inserts
+3. **Translation guard pattern**: `if (!await context.NavigationTranslations.AnyAsync(t => t.EntityId == {id} && t.EntityType == ..., ct))` — MANDATORY before every translation batch insert
+4. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
 4. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
 5. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
 6. **Resolve FK by Code**: Parent modules and roles are found by `Code`, not hardcoded GUID

package/templates/skills/application/templates-backend.md

@@ -55,7 +55,7 @@ namespace SmartStack.Application.Common.Interfaces;
 
 public interface I$MODULE_PASCALService
 {
-    Task<PagedResult<$ENTITY_PASCALDto>> GetAllAsync(
+    Task<PaginatedResult<$ENTITY_PASCALDto>> GetAllAsync(
         $ENTITY_PASCALQueryParameters parameters,
         CancellationToken cancellationToken = default);
 
@@ -115,7 +115,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
         _logger = logger;
     }
 
-    public async Task<PagedResult<$ENTITY_PASCALDto>> GetAllAsync(
+    public async Task<PaginatedResult<$ENTITY_PASCALDto>> GetAllAsync(
         $ENTITY_PASCALQueryParameters parameters,
         CancellationToken cancellationToken = default)
     {
@@ -159,7 +159,7 @@ public class $MODULE_PASCALService : I$MODULE_PASCALService
             })
             .ToListAsync(cancellationToken);
 
-        return new PagedResult<$ENTITY_PASCALDto>
+        return new PaginatedResult<$ENTITY_PASCALDto>
         {
             Items = items,
             TotalCount = totalCount,

package/templates/skills/application/templates-frontend.md

@@ -100,7 +100,7 @@ interface $ENTITY_PASCALDto {
   updatedAt: string | null;
 }
 
-interface PagedResult {
+interface PaginatedResult {
   items: $ENTITY_PASCALDto[];
   totalCount: number;
   page: number;
@@ -135,15 +135,15 @@ export function $MODULE_PASCALListView({
     setViewMode,
   } = use$MODULE_PASCALPreferences();
 
-  const [data, setData] = useState<PagedResult | null>(null);
+  const [data, setData] = useState<PaginatedResult | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [page, setPage] = useState(1);
-  const [searchTerm, setSearchTerm] = useState('');
+  const [search, setSearchTerm] = useState('');
 
   useEffect(() => {
     loadData();
-  }, [page, pageSize, sortColumn, sortDirection, searchTerm]);
+  }, [page, pageSize, sortColumn, sortDirection, search]);
 
   const loadData = async () => {
     try {
@@ -154,9 +154,9 @@ export function $MODULE_PASCALListView({
         pageSize: pageSize.toString(),
         sortColumn,
         sortDirection,
-        ...(searchTerm && { searchTerm }),
+        ...(search && { search }),
       });
-      const result = await api.get<PagedResult>(`/api/$module?${params}`);
+      const result = await api.get<PaginatedResult>(`/api/$module?${params}`);
       setData(result);
     } catch (err) {
       setError(t('common:errors.loadFailed'));
@@ -222,7 +222,7 @@ export function $MODULE_PASCALListView({
           <input
             type="text"
             placeholder={t('common:search.placeholder')}
-            value={searchTerm}
+            value={search}
             onChange={(e) => setSearchTerm(e.target.value)}
             className="w-full pl-10 pr-4 py-2 bg-[var(--bg-primary)] border border-[var(--border-color)] text-sm focus:outline-none focus:border-[var(--color-accent-500)]"
             style={{ borderRadius: 'var(--radius-input)' }}
@@ -456,27 +456,27 @@ export interface Update$ENTITY_PASCALRequest {
   description?: string;
 }
 
-export interface PagedResult<T> {
+export interface PaginatedResult<T> {
   items: T[];
   totalCount: number;
   page: number;
   pageSize: number;
 }
 
-export interface QueryParameters {
+export interface PaginationParams {
   page?: number;
   pageSize?: number;
-  searchTerm?: string;
+  search?: string;
   sortColumn?: string;
   sortDirection?: 'asc' | 'desc';
 }
 
 export const $moduleApi = {
-  getAll: async (params: QueryParameters = {}): Promise<PagedResult<$ENTITY_PASCALDto>> => {
+  getAll: async (params: PaginationParams = {}): Promise<PaginatedResult<$ENTITY_PASCALDto>> => {
     const queryParams = new URLSearchParams();
     if (params.page) queryParams.set('page', params.page.toString());
     if (params.pageSize) queryParams.set('pageSize', params.pageSize.toString());
-    if (params.searchTerm) queryParams.set('searchTerm', params.searchTerm);
+    if (params.search) queryParams.set('search', params.search);
     if (params.sortColumn) queryParams.set('sortColumn', params.sortColumn);
     if (params.sortDirection) queryParams.set('sortDirection', params.sortDirection);
 

package/templates/skills/application/templates-seed.md

@@ -895,13 +895,23 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         // Create modules (idempotent per-module — check each before inserting)
         // var mod1Exists = await context.NavigationModules.AnyAsync(m => m.Code == "{module_code}" && m.ApplicationId == app.Id, ct);
         // if (!mod1Exists) { var mod1 = NavigationModule.Create(...); context.NavigationModules.Add(mod1); }
-        // Create module translations from {Module}NavigationSeedData.GetTranslationEntries()
 
-        // Create sections from {Module}NavigationSeedData.GetSectionEntries(moduleId)
+        // Module translations — IDEMPOTENT (unique index IX_nav_Translations_EntityType_EntityId_LanguageCode)
+        // CRITICAL: Always check before inserting to avoid duplicate key errors on re-runs
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == {Module}NavigationSeedData.{Module}ModuleId && t.EntityType == NavigationEntityType.Module, ct))
+        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries()) { ... } }
+
+        // Sections (idempotent per-section — check each before inserting)
+        // var secExists = await context.NavigationSections.AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ..., ct);
         // Use NavigationSection.Create(moduleId, code, label, description, icon, iconType, route, displayOrder)
-        // Create section translations from {Module}NavigationSeedData.GetSectionTranslationEntries()
 
-        // Create resources from {Module}NavigationSeedData.GetResourceEntries(sectionId)
+        // Section translations — IDEMPOTENT (same guard pattern as module translations)
+        // if (!await context.NavigationTranslations.AnyAsync(
+        //     t => t.EntityId == secEntry.Id && t.EntityType == NavigationEntityType.Section, ct))
+
+        // Resources (idempotent per-resource — check each before inserting)
+        // var resExists = await context.NavigationResources.AnyAsync(r => r.Code == resEntry.Code && r.SectionId == ..., ct);
         // Use NavigationResource.Create(sectionId, code, label, entityType, route, displayOrder)
     }
 

package/templates/skills/business-analyse/SKILL.md

@@ -285,19 +285,22 @@ Load ONLY relevant categories based on feature type:
 | 1 module | Inline (classic, no team) |
 | 2+ modules | Team mode (Propose & Review) |
 
-**Team mode workflow (Propose & Review):**
+**Team mode workflow (Parallel Propose & Review):**
 1. Steps 00-02 execute inline in the main conversation (interactive with user)
 2. After step-02 decomposition: clean up old team data (§1a), then `TeamCreate({ team_name: "ba-{appName}" })` — **CRITICAL: capture the RETURNED team name** (may differ from requested)
-3. For each module: spawn autonomous agent using the **returned** team name, agent proposes complete specification, team lead presents to user for validation
-4. After all modules specified: spawn consolidation agent (steps 04a + 04b), present report for user approval (04c)
-5. After consolidation approved: spawn handoff agent (steps 05a + 05b + 05c)
-6. `TeamDelete()` cleanup
+3. For each dependency layer: pre-analyze cross-module touchpoints, then spawn autonomous agents **IN PARALLEL** (all modules in the same layer run simultaneously). Team lead pre-injects coordination notes into each agent's prompt, handles runtime cross-module queries between agents, then presents cross-module interaction analysis + individual module reviews to user.
+4. Between layers: shutdown all layer agents, rebuild completedModulesSummary, spawn next layer
+5. After all modules specified: spawn consolidation agent (steps 04a + 04b), present report for user approval (04c)
+6. After consolidation approved: spawn handoff agent (steps 05a + 05b + 05c)
+7. `TeamDelete()` cleanup
 
 **Why team mode:**
 - Each module agent gets a **fresh context window** (zero accumulation)
 - The team lead stays lightweight (< 30% context even with 10+ modules)
 - Module agents work **autonomously** (no AskUserQuestion — they PROPOSE, user REVIEWS)
-- Error recovery: if an agent crashes, respawn with same module context from feature.json
+- **Parallel execution**: modules in the same dependency layer run simultaneously (~50-66% wall-clock reduction)
+- **Cross-module coordination**: team lead pre-injects known touchpoints + relays runtime queries between parallel agents
+- Error recovery: if an agent crashes, other agents in the layer continue; crashed module retried independently
 
 **Reference:** `references/team-orchestration.md` (loaded by step-02 after decomposition)
 **Agent prompt template:** `references/agent-module-prompt.md`

package/templates/skills/business-analyse/questionnaire/04-data.md

@@ -13,6 +13,9 @@
 | Q4.2 | For each entity: important attributes? | Per entity |
 | Q4.3 | What relationships exist between entities? | Text schema |
 | Q4.4 | Expected data volume? | Estimation |
+| Q4.4b | For each entity: should the Code be auto-generated or user-provided? | Per entity |
+| Q4.4c | If auto-generated: what strategy? (sequential, daily timestamp, yearly, UUID short) | Per entity |
+| Q4.4d | What prefix represents this entity? (2-6 lowercase letters, e.g., emp, inv) | Per entity |
 
 ## 4.2 Data Rules
 
@@ -34,6 +37,8 @@
 | Unique attribute | `HasIndex().IsUnique()` |
 | 1:N relationship | Navigation property |
 | Sensitive data | Encryption + audit |
+| Code auto-generation | `ICodeGenerator<T>.NextCodeAsync()` with retry — see `apex/references/code-generation.md` |
+| Code pattern config | `analysis.entities[].codePattern` in feature.json |
 
 > **⚠️ RBAC EXCLUSION: The following concepts are handled by the platform's RBAC system
 > and MUST NOT be modeled as entity attributes or separate entities:**
@@ -58,6 +63,9 @@
 | Q4.2 (attributes) | Liste de champs techniques (ID, CreatedDate) | "Les champs techniques (Id, TenantId, audit) sont auto-gérés. Quels sont les attributs MÉTIER ?" |
 | Q4.3 (relationships) | "1:N" without detail | "Un {Parent} peut avoir combien de {Children} max ? Un {Child} peut-il exister sans {Parent} ?" |
 | Q4.4 (volume) | "Beaucoup" | "Ordre de grandeur : dizaines, centaines, milliers, millions ? Croissance par mois ?" |
+| Q4.4b (code pattern) | "User enters the code" or no answer | "Le code doit-il suivre un format spécifique ? (numéro séquentiel, date, combinaison ?)" |
+| Q4.4c (code strategy) | No answer | Propose strategy based on entity type: invoices/orders → timestamp-daily, employees/customers → sequential, references/categories → uuid-short, contracts → year-sequential, tickets → timestamp-minute |
+| Q4.4d (code prefix) | Too long or ambiguous | "Le préfixe est limité à 2-6 lettres minuscules. Exemple : 'emp' pour Employee, 'inv' pour Invoice, 'ctr' pour Contract." |
 | Q4.5 (validations) | Validations basiques seulement | "Y a-t-il des règles inter-champs ? (date fin > date début, montant selon statut)" |
 | Q4.8 (sensitive) | "Non" | "Pas de données personnelles (nom, email, téléphone) ? Pas de données financières ?" |
 

package/templates/skills/business-analyse/references/agent-module-prompt.md

@@ -1,8 +1,9 @@
 # Module Specifier Agent — Prompt Template
 
-> **Used by:** team-orchestration.md § 2b
+> **Used by:** team-orchestration.md § 2c
 > **Purpose:** Self-contained prompt for autonomous module specification agents.
 > **Placeholders:** All `{...}` tokens are replaced at spawn time by the team lead.
+> **New in v3.32:** `{coordinationNotes}` for parallel same-layer execution.
 
 ---
 
@@ -52,12 +53,23 @@ You work WITHOUT user interaction:
 **Dependencies on other modules:** {dependencies}
 **Detail tabs:** {detailTabs}
 
-## Completed Modules Context
+## Completed Modules Context (from previous layers)
 
-These modules are already specified. Reference their entities for FK relationships:
+These modules are already specified (from completed dependency layers).
+Reference their entities for FK relationships:
 
 {completedModulesSummary}
 
+## Same-Layer Coordination (Parallel Execution)
+
+{coordinationNotes}
+
+> **Parallel execution note:** You may be running simultaneously with other module agents
+> in the same dependency layer. The `completedModulesSummary` above covers COMPLETED LAYERS only.
+> For information about modules in your SAME layer, use the CROSS_MODULE_QUERY protocol
+> described in the Communication Protocol section below.
+> If `coordinationNotes` is empty, you are the only module in this layer — no coordination needed.
+
 ## Project Context
 
 - Language: {language}
@@ -204,6 +216,55 @@ SendMessage({
 - {section}: {1-line description of layout}
 ```
 
+### Cross-Module Queries (for same-layer modules)
+
+If you need information about another module being specified in parallel
+(e.g., entity attribute structure for FK references, shared enum values, naming conventions):
+
+```
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "CROSS_MODULE_QUERY:{targetModuleCode}\nQuestion: {your specific question}\nContext: {why you need this information}",
+  summary: "Query about {targetModuleCode}"
+})
+```
+
+Then **WAIT** for the team lead to respond with `CROSS_MODULE_ANSWER` before proceeding.
+Do NOT guess or assume — **always query** when unsure about a same-layer module's design.
+
+**When to use CROSS_MODULE_QUERY:**
+- You need the exact attribute list of an entity owned by another same-layer module
+- You want to verify a naming convention with a parallel module
+- You need to know if a shared concept (e.g., Status enum) is already defined elsewhere
+- You're defining a FK that references an entity from a same-layer module
+
+**When NOT to use CROSS_MODULE_QUERY:**
+- For modules in completed layers → use `completedModulesSummary` (already in your context)
+- For general SmartStack conventions → use ULTRATHINK + step file instructions
+- For your own module's entities → you define them yourself
+
+### Responding to Cross-Module Queries (relay from team lead)
+
+The team lead may relay a question from another same-layer agent:
+
+```
+"CROSS_MODULE_QUERY_RELAY:{requestingModule}\nQuestion: {their question}"
+```
+
+Respond with your current specification data:
+
+```
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "CROSS_MODULE_ANSWER_RELAY:{requestingModule}\nAnswer: {your answer based on your current specification state}",
+  summary: "Answer for {requestingModule}"
+})
+```
+
+Then **continue your work** — don't wait for anything after answering a relay query.
+
 ### After receiving feedback:
 
 If team lead sends "REVISION:{moduleCode}\n{feedback}":
@@ -268,17 +329,35 @@ OBJ-{PREFIX}-{NNN}       → OBJ-TM-001
 
 NEVER use bare IDs (UC-001, BR-VAL-001) — always prefixed.
 
+## MANDATORY SECTIONS (your feature.json MUST contain ALL of these)
+
+> **CRITICAL — Missing any of these sections causes BLOCKING validation errors.**
+
+- `analysis.dataLifecycle` — Even for simple modules. Use standard defaults if no specific GDPR requirements:
+  ```json
+  { "retentionPeriod": "Standard (as per company policy)", "archiveStrategy": "Soft-delete with audit trail", "gdprCompliance": "N/A — no PII or standard audit trail only" }
+  ```
+- `specification.navigation.entries[]` — Module + section entries with labels in **4 languages (fr, en, it, de)**
+- `validation` — completeness/consistency/convention/semantic checks + decision (recording step-03d results)
+
+**i18n RULE:** ALL i18n keys MUST have **4 languages (fr, en, it, de)**. IT/DE can use shorter translations but MUST exist. Missing IT/DE is a common failure — use EN as fallback if unsure.
+
+**Wireframe RULE:** For each data-centric section with a create form, a wireframe `{section}-create` MUST exist. For modifiable entities, a `{section}-edit` wireframe SHOULD also exist. These are action-page wireframes, NOT navigation sections.
+
 ## Quality Checklist (self-verify before PROPOSAL_READY)
 
 - [ ] All entities have attributes with type + required + validation
 - [ ] All FK fields are Guid type with navigation property
 - [ ] All sections have at least 1 resource
-- [ ] All sections have a wireframe
+- [ ] All sections have a wireframe (+ create/edit wireframes for data-centric sections)
 - [ ] seedDataCore has all 7 arrays with content
 - [ ] Permissions follow {context}.{app}.{module}.{entity}.{action} pattern
-- [ ] i18n has all 8 required keys (actions, columns, empty, errors, form, labels, messages, validation)
+- [ ] i18n has all keys in **4 languages (fr, en, it, de)** — not just fr/en
 - [ ] At least 2 actors, 2 use cases, 4 functional requirements
 - [ ] Gherkin scenarios are arrays (not objects)
 - [ ] Messages have `message` field (not `text`)
 - [ ] Validations have `rules[]` arrays (not singular `rule`)
+- [ ] `analysis.dataLifecycle` section present
+- [ ] `specification.navigation.entries[]` non-empty with 4-language labels
+- [ ] `validation` section with decision recorded
 ```

package/templates/skills/business-analyse/references/agent-pooling-best-practices.md

@@ -212,6 +212,57 @@ Spawn agent-consolidate
 
 ---
 
+### Pattern 4: Layer-Based Parallel Spawn (RECOMMENDED for Step 03)
+
+**Scenario:** Step 03 - Specify modules across dependency layers
+
+**Recommended:**
+```
+FOR each layer in dependencyGraph.layers:
+
+  1. Pre-analyze: Identify cross-module touchpoints between modules in this layer
+     → Shared entities, FK overlaps, naming conventions, shared lookups
+     → Build coordinationNotes per module
+
+  2. Spawn ALL layer agents in parallel (1 Task per module, ALL in ONE message)
+     → Each agent receives: module context + completedModulesSummary + coordinationNotes
+
+  3. Handle cross-module queries during execution (team lead relays)
+     → Agent sends CROSS_MODULE_QUERY → team lead routes → answer forwarded
+
+  4. Wait for ALL PROPOSAL_READY from this layer
+
+  5. Display cross-module interaction analysis (bird's-eye view)
+     → Detected interactions, resolved queries, attention points
+
+  6. Review each module individually with user (quality-first)
+     → Approve, revise, or see detail per module
+
+  7. Layer consistency check (FK names, permissions, i18n, seed data IDs)
+     → Auto-fix if inconsistency found
+
+  8. Shutdown ALL layer agents
+
+  9. Rebuild completedModulesSummary for next layer
+
+  10. Proceed to next layer
+```
+
+**Result:**
+- 4 agents for 4 modules (same count as sequential)
+- But wall-clock reduced by ~50-66% for apps with parallel layers
+- Cross-module consistency guaranteed by pre-injection + relay + consistency check
+- Each agent has fresh context (zero accumulation)
+
+**Why this pattern works:**
+- Dependency layers already computed by step-02 topological sort
+- Modules in the same layer have NO direct dependencies (by definition)
+- Pre-injection prevents most cross-module issues before they happen
+- Runtime relay catches unexpected edge cases
+- Consistency check catches anything missed by both mechanisms
+
+---
+
 ## Metrics & Monitoring
 
 ### Target Metrics (per BA session)
@@ -282,19 +333,23 @@ Otherwise → inline or reuse.
 ### Step 03: Module Specification (BIGGEST IMPACT)
 
 **Current:** 4-5 agents PER module × 5 modules = 20-25 agents
-**Target:** 1 agent per module (5 total) OR 1 agent for all modules (1 total)
-
-**Changes:**
-- **Option A:** ONE agent for ALL modules (sequential)
-  - Agent loops through modules
-  - Executes 03a → 03b → 03c → 03d internally
-  - Displays progress checkpoints
+**Target:** 1 agent per module, parallel within dependency layers
 
-- **Option B:** ONE agent PER module (if parallel possible)
-  - Max 2-3 modules in parallel
-  - Each agent handles 1 module end-to-end
+**Implementation (team mode with parallel layers):**
+- ONE agent PER module, each executing 03a → 03b → 03c → 03d autonomously
+- Modules in the same dependency layer spawn **simultaneously** (parallel)
+- Modules in different layers spawn **sequentially** (dependency order)
+- Team lead pre-injects cross-module coordination notes before spawning
+- Runtime cross-module queries relayed by team lead between parallel agents
+- Layer consistency check after all modules in a layer are approved
 
-**Recommended:** Option A (sequential) for most cases, Option B only if modules truly independent
+**Example (4 modules, 3 layers):**
+```
+Layer 0: [Customers, Products] → 2 agents in parallel
+Layer 1: [Orders]              → 1 agent (after layer 0 complete)
+Layer 2: [Invoices]            → 1 agent (after layer 1 complete)
+Total: 4 agents, but wall-clock = 3 layers (not 4 sequential)
+```
 
 ---
 
@@ -433,17 +488,19 @@ Session: Business-analyse for HumanResources application
 - Cache efficiency: 50-60% read (optimal)
 ```
 
-### After Optimization — Team Mode (Target, RECOMMENDED)
+### After Optimization — Team Mode with Parallel Layers (Target, RECOMMENDED)
 
 ```
-Session: Business-analyse for HumanResources application (4 modules)
+Session: Business-analyse for HumanResources application (4 modules, 3 layers)
 - Team lead context: <50% (never exhausted)
-- Module agents: 4 (1 per module, each ~40-60% context)
+- Module agents: 4 (1 per module, parallel within layers, each ~40-60% context)
 - Consolidation agent: 1 (~30-40% context)
 - Handoff agent: 1 (~40-50% context)
 - Total agents: 6
 - Context exhaustion: ZERO (each agent has fresh context window)
 - User interaction: Propose & Review (user validates complete proposals)
+- Wall-clock: ~50% reduction vs sequential (layer 0 runs 2 modules in parallel)
+- Cross-module quality: pre-injection + relay + consistency check
 ```
 
 ### Success Metrics
@@ -452,8 +509,10 @@ Session: Business-analyse for HumanResources application (4 modules)
 - ✅ Ultra-short agents eliminated
 - ✅ JSONL complexity reduced by 68-81%
 - ✅ **Context exhaustion eliminated** (team mode)
-- ✅ Token usage reduced by 15-20% (agent pooling) or distributed across agents (team mode)
-- ✅ Same output quality (no regressions)
+- ✅ Token usage distributed across parallel agents (team mode)
+- ✅ **Wall-clock time reduced by ~50-66%** (parallel layer execution)
+- ✅ **Cross-module consistency guaranteed** (pre-injection + relay + consistency check)
+- ✅ Same or better output quality (cross-module coordination improves integration)
 
 ---
 
@@ -472,6 +531,10 @@ Session: Business-analyse for HumanResources application (4 modules)
 
 - Reuse agents for sequential operations
 - Spawn 1 agent per logical phase (not per sub-step)
+- Spawn ALL same-layer agents in parallel (one message, multiple Task calls)
+- Pre-inject coordination notes for parallel agents
+- Handle cross-module queries via relay protocol
+- Run layer consistency check after parallel approvals
 - Do summaries/formatting inline
 - Pre-load context at phase start
 - Display progress checkpoints
@@ -482,12 +545,13 @@ Session: Business-analyse for HumanResources application (4 modules)
 - Spawn agents for trivial tasks (<20 lines output)
 - Spawn new agent for each step transition
 - Spawn agents for sequential dependencies
+- Spawn agents from different dependency layers in parallel
 - Re-read same files multiple times
 - Create summary-only agents
-- Spawn more than 7 agents per BA session
+- Spawn more than N+2 agents per BA session (N modules + consolidation + handoff)
 
 ---
 
-**Last Updated:** 2026-02-08
-**Version:** 1.0
+**Last Updated:** 2026-02-15
+**Version:** 2.0 (parallel layer execution)
 **Author:** SmartStack CLI Team