@atlashub/smartstack-cli 3.31.0 → 3.32.0

package/templates/skills/business-analyse/references/team-orchestration.md

@@ -3,6 +3,7 @@
 > **Loaded by:** step-02 when multi-module detected (`moduleOrder.length >= 2`)
 > **Purpose:** Delegate module specification to autonomous agents with user review.
 > **Rule:** Single module = NO team. Only create team for 2+ modules.
+> **Execution:** Parallel by dependency layer — all modules in the same layer run simultaneously.
 
 ---
 
@@ -39,9 +40,9 @@ Store team context for the session:
 const teamContext = {
   teamName: actualTeamName, // ← RETURNED name, NOT "ba-{appName}"
   moduleOrder: metadata.workflow.moduleOrder,
-  dependencyLayers: dependencyGraph.layers || null,
-  currentModuleIdx: 0,
+  dependencyLayers: dependencyGraph.layers, // ← from step-02 topological sort
   completedModules: [],
+  completedLayers: [],
   mode: "propose-review"
 };
 ```
@@ -51,33 +52,100 @@ const teamContext = {
 
 ---
 
-## 2. Module Agent Spawn — Sequential by Topological Order
+## 2. Module Agent Spawn — Parallel by Dependency Layer
 
-For each module in `moduleOrder` (respecting dependency layers):
+Process modules **layer by layer**. Within each layer, spawn ALL agents **simultaneously**.
 
-### 2a. Prepare Agent Context
+```
+FOR each layer in dependencyGraph.layers:
+  Execute §2a → §2b → §2c → §2d → §2e → §3 → §4
+```
+
+### 2a. Pre-Spawn Cross-Module Analysis
+
+**ALWAYS executed for layers with 2+ modules.** Analyze the module definitions within this layer to identify cross-module touchpoints BEFORE spawning agents.
+
+```
+IF layer.modules.length >= 2:
+
+  ULTRATHINK: Analyze module definitions for same-layer interactions:
+
+  1. Shared entity names
+     → Do any modules reference the same entity? (e.g., both "Products" and "Inventory"
+       might reference a "Category" entity)
+
+  2. Potential FK overlaps
+     → Do any modules anticipate creating entities that others might reference?
+     → E.g., Products creates "Product" entity, Orders references "Product" via FK
+
+  3. Naming conventions
+     → Will both modules use similar attribute names? (e.g., "Code", "Name", "Status")
+     → Agree on a consistent naming pattern
+
+  4. Shared lookup data
+     → Do any modules reference common reference tables?
+     → E.g., both use a "Status" enum, a "Country" lookup, a "Currency" type
+
+  5. Permission path consistency
+     → Verify permission paths won't collide:
+       {context}.{app}.{module1}.{entity}.{action}
+       {context}.{app}.{module2}.{entity}.{action}
+
+  Build coordinationNotes for EACH module in the layer:
+```
+
+**coordinationNotes template** (injected into each agent's prompt):
+
+```
+## Same-Layer Coordination Notes
+
+You are running IN PARALLEL with: {otherModuleCodes.join(", ")}
+
+### Known Touchpoints
+- {otherModule} will define entity "{EntityName}" — if you need to reference it,
+  use CROSS_MODULE_QUERY to get the exact attribute structure
+- Naming convention: use {convention} for shared concepts (e.g., "Status" enum values)
+- Shared lookups: {list any common reference data both modules might create}
+
+### Your Responsibilities vs Theirs
+- You own: {your entities — list}
+- They own: {their entities — list}
+- Contested/shared: {entities both might create — QUERY before defining}
+
+### Cross-Module FK Convention
+When referencing an entity owned by a same-layer module:
+1. Send CROSS_MODULE_QUERY to team lead asking for the entity's attribute structure
+2. WAIT for the answer before defining your FK field
+3. Use the exact entity name and primary key type from the answer
+```
 
-Before spawning, gather the context the agent needs:
+> **IF layer has only 1 module:** Skip §2a entirely. No coordination notes needed.
+
+### 2b. Prepare Agent Context (per module)
+
+For EACH module in the layer, gather the context the agent needs:
 
 ```
 1. ba-reader.readApplicationContext({feature_id})
    → Extract: appName, featureId, context, language
 
 2. Read module decomposition data from master feature.json:
-   → modules[currentModuleIdx]: code, name, description, featureType, entities,
-     anticipatedSections, dependencies, detailTabs
+   → modules[moduleCode]: code, name, description, featureType, entities,
+     anticipatedSections, dependencies, detailTabs, estimatedComplexity, priority
 
 3. ba-reader.getCompletedModulesSummary({feature_id})
-   → Compact summary of already-specified modules (max 100 lines)
+   → Compact summary of already-specified modules from COMPLETED LAYERS (max 100 lines)
    → Includes: entity names, FK relationships, permission paths, shared types
 ```
 
-### 2b. Spawn Agent
+### 2c. Spawn ALL Layer Agents Simultaneously
+
+**For layers with 1 module** — single spawn (same as standard):
 
 ```javascript
 Task({
   subagent_type: "general-purpose",
-  team_name: teamContext.teamName, // ← ACTUAL name from TeamCreate result
+  team_name: teamContext.teamName,
   name: "mod-{moduleCode}",
   model: "opus",
   mode: "bypassPermissions",
@@ -91,7 +159,10 @@ Task({
     anticipatedSections: module.anticipatedSections,
     dependencies: module.dependencies,
     detailTabs: module.detailTabs,
+    estimatedComplexity: module.estimatedComplexity,
+    priority: module.priority,
     completedModulesSummary,
+    coordinationNotes: "",  // empty for single-module layer
     language: metadata.language,
     docsDir: "docs/business/{appName}/{moduleCode}/business-analyse/v{version}/"
   }),
@@ -99,75 +170,220 @@ Task({
 });
 ```
 
-**BUILD_PROMPT**: Read `references/agent-module-prompt.md`, replace all `{placeholders}` with actual values, and pass as the `prompt` parameter.
+**For layers with 2+ modules** — spawn ALL in a **single message** (parallel):
 
-### 2c. Sequential Constraint
+```javascript
+// CRITICAL: All Task() calls MUST be in ONE message for parallel execution.
+// Do NOT await between them — they MUST be sent together.
 
-- Spawn ONE module agent at a time
-- Wait for MODULE_COMPLETE before spawning the next
-- Reason: later modules may reference entities/FKs from earlier modules
-- **Future optimization**: modules in the same dependency layer with no cross-refs COULD run in parallel
+// Agent 1:
+Task({
+  subagent_type: "general-purpose",
+  team_name: teamContext.teamName,
+  name: "mod-{moduleCode1}",
+  model: "opus",
+  mode: "bypassPermissions",
+  prompt: BUILD_PROMPT(references/agent-module-prompt.md, {
+    ...moduleContext1,
+    coordinationNotes: coordinationNotesForModule1,  // ← NEW
+  }),
+  description: "Specify {moduleCode1}"
+});
 
-### 2d. After Spawning — Wait for Agent Message
+// Agent 2 (IN SAME MESSAGE):
+Task({
+  subagent_type: "general-purpose",
+  team_name: teamContext.teamName,
+  name: "mod-{moduleCode2}",
+  model: "opus",
+  mode: "bypassPermissions",
+  prompt: BUILD_PROMPT(references/agent-module-prompt.md, {
+    ...moduleContext2,
+    coordinationNotes: coordinationNotesForModule2,  // ← NEW
+  }),
+  description: "Specify {moduleCode2}"
+});
+
+// ... repeat for all modules in this layer
+```
+
+**BUILD_PROMPT**: Read `references/agent-module-prompt.md`, replace all `{placeholders}` with actual values (including the new `{coordinationNotes}`), and pass as the `prompt` parameter.
+
+### 2d. Track Layer State
+
+After spawning, initialize layer tracking:
+
+```javascript
+const layerState = {
+  layerIndex: L,
+  modules: layer.modules,                        // ["Customers", "Products"]
+  pendingProposals: [...layer.modules],           // agents not yet PROPOSAL_READY
+  receivedProposals: {},                          // { moduleCode: proposalSummary }
+  approvedModules: [],                            // modules approved by user
+  crossModuleQueries: [],                         // log of queries handled
+};
+```
+
+### 2e. Wait for Layer Completion — Message Handling Loop
 
-After calling `Task()` to spawn the module agent, the team lead **MUST WAIT** for the agent to send a message.
+After spawning all agents in the layer, the team lead enters a **message handling loop**.
 Messages from teammates are delivered automatically — do NOT poll or re-spawn.
 
-The agent will send `PROPOSAL_READY:{moduleCode}` when its specification is complete.
-This may take several minutes. The team lead does nothing until the message arrives.
+```
+WHILE layerState.pendingProposals.length > 0:
+
+  Wait for next message from any agent in this layer.
+
+  CASE message matches "PROPOSAL_READY:{moduleCode}":
+    → Remove moduleCode from pendingProposals
+    → Store proposal in receivedProposals[moduleCode]
+    → Display: "✓ Module {moduleCode} proposal received ({received}/{total})"
+    → IF pendingProposals is now empty:
+        → All agents in this layer have proposed
+        → Proceed to §3 (Layer Review)
+
+  CASE message matches "CROSS_MODULE_QUERY:{targetModule}":
+    → Handle per §2-bis (Cross-Module Coordination Protocol)
+
+  CASE message matches "CROSS_MODULE_ANSWER_RELAY:{requestingModule}":
+    → Forward to requesting agent per §2-bis
+
+  CASE message matches "ERROR:{moduleCode}:{description}":
+    → Handle per §8 (Error Recovery)
+    → Remove from pendingProposals if module is skipped
+    → IF pendingProposals is now empty → proceed to §3
+```
+
+> **This loop may take several minutes** as agents work autonomously.
+> The team lead does nothing except handle cross-module queries during this time.
 
 ---
 
-## 3. Propose & Review Protocol
+## 2-bis. Cross-Module Coordination Protocol (Runtime Relay)
+
+When an agent sends `CROSS_MODULE_QUERY:{targetModule}`, the team lead routes the query based on the target module's state:
 
-### 3a. Team Lead Receives PROPOSAL_READY
+### Case 1: Target is in a COMPLETED layer
 
-The module agent sends this message when specification is complete:
+The target module's specification is already written to feature.json.
 
 ```
-PROPOSAL_READY:{moduleCode}
+→ Read target module's entities/attributes from completedModulesSummary
+→ Send answer directly to requesting agent:
 
-## Module: {moduleCode} — Specification Summary
+SendMessage({
+  type: "message",
+  recipient: "mod-{requestingModule}",
+  content: "CROSS_MODULE_ANSWER:{requestingModule}\nAnswer: {entity structure from completed module data}",
+  summary: "Answer from completed {targetModule}"
+})
+```
 
-### Entities ({count})
-| Entity | Attributes | Relationships |
-|--------|-----------|---------------|
-| ... | ... | ... |
+### Case 2: Target is in CURRENT layer AND has sent PROPOSAL_READY
 
-### Sections ({count})
-| Section | Description | Resources |
-|---------|-------------|-----------|
-| ... | ... | ... |
+The target agent has finished its proposal — we have its specification data.
 
-### Use Cases ({count})
-- UC-{PREFIX}-001: {title}
-- UC-{PREFIX}-002: {title}
-- ...
+```
+→ Extract relevant entity/attribute info from receivedProposals[targetModule]
+→ Send answer directly to requesting agent:
 
-### Business Rules ({count})
-- BR-{CAT}-{PREFIX}-001: {title}
-- ...
+SendMessage({
+  type: "message",
+  recipient: "mod-{requestingModule}",
+  content: "CROSS_MODULE_ANSWER:{requestingModule}\nAnswer: {entity structure from proposal data}",
+  summary: "Answer from {targetModule} proposal"
+})
+```
 
-### Permissions ({count})
-- {context}.{app}.{module}.{action}
-- ...
+### Case 3: Target is in CURRENT layer AND still working (no PROPOSAL_READY yet)
 
-### Seed Data
-- Modules: {count} | Sections: {count} | Resources: {count}
-- Translations: {count} | Permissions: {count} | Role mappings: {count}
+The target agent is still specifying — relay the question.
 
-### Wireframes
-- {section}: {1-line description}
-- ...
 ```
+→ Forward question to target agent:
+
+SendMessage({
+  type: "message",
+  recipient: "mod-{targetModule}",
+  content: "CROSS_MODULE_QUERY_RELAY:{requestingModule}\nQuestion: {original question}",
+  summary: "Relay query from {requestingModule}"
+})
 
-### 3b. Present to User and Handle Response
+→ Wait for target agent to respond with CROSS_MODULE_ANSWER_RELAY
+→ Forward answer to requesting agent:
+
+SendMessage({
+  type: "message",
+  recipient: "mod-{requestingModule}",
+  content: "CROSS_MODULE_ANSWER:{requestingModule}\nAnswer: {answer from target agent}",
+  summary: "Answer from {targetModule}"
+})
+```
+
+### Case 4: Circular query (A asks about B, B asks about A simultaneously)
+
+Both agents are blocked waiting for each other. The team lead MUST resolve this autonomously.
+
+```
+→ ULTRATHINK: Based on SmartStack conventions and module descriptions,
+  make a consistent design decision for BOTH modules.
+→ Send CROSS_MODULE_ANSWER to BOTH agents with compatible entity structures.
+→ Log resolution in layerState.crossModuleQueries[] for later review.
+```
+
+> **Every cross-module query is logged** in `layerState.crossModuleQueries[]` for display during §3 review.
+
+---
+
+## 3. Layer Review — Quality-First Protocol
+
+When ALL agents in a layer have sent PROPOSAL_READY, the team lead presents the results to the user.
+
+### 3a. Cross-Module Interaction Analysis (layers with 2+ modules)
+
+**ALWAYS displayed FIRST** for multi-module layers. This gives the user a bird's-eye view of how modules in this layer interact.
+
+```
+═══════════════════════════════════════════════════════════
+  Layer {L} — {N} modules terminés — Analyse croisée
+═══════════════════════════════════════════════════════════
+
+### Interactions cross-module détectées
+
+| Module A | Module B | Type | Détail |
+|----------|----------|------|--------|
+| {mod1} | {mod2} | FK | {mod1}.{entity}.{field} → {mod2}.{entity} |
+| {mod1} | {mod2} | Concept partagé | Les deux définissent "{concept}" |
+| {mod1} | {mod2} | Lookup | {mod1} référence {mod2}.{entity} comme donnée de ref |
+
+### Requêtes cross-module résolues pendant la spécification ({count})
+{FOR each query in layerState.crossModuleQueries:}
+  - {requestingModule} → {targetModule}: {question summary} → {answer summary}
+
+### Points d'attention
+- {naming inconsistencies detected between module proposals}
+- {potential permission path conflicts}
+- {shared entity definition differences}
+
+─────────────────────────────────────────────────────────
+```
+
+> **For single-module layers:** Skip §3a entirely — no cross-module analysis needed.
+
+### 3b. Individual Module Review (ALWAYS — for quality)
+
+Review each module's proposal individually. For multi-module layers, the user has already seen the cross-module context from §3a.
+
+```
+FOR each module in layer (respecting topologicalOrder within layer):
+```
 
 **Step 1:** Format and display the proposal:
 
 ```
 ═══════════════════════════════════════════════════════════
-  Proposition pour le module {moduleCode} ({idx+1}/{total})
+  Proposition pour le module {moduleCode}
+  (Layer {L} — module {idx+1}/{layerTotal} — global {globalIdx+1}/{totalModules})
 ═══════════════════════════════════════════════════════════
 
 {structured summary from agent — displayed as-is}
@@ -178,11 +394,11 @@ PROPOSAL_READY:{moduleCode}
 **Step 2:** Ask the user via AskUserQuestion:
 
 ```
-Validez-vous cette specification ?
+Validez-vous cette spécification ?
 Options:
   1. "Valider" → approve as-is
   2. "Modifier" → provide feedback for revision
-  3. "Voir detail" → team lead reads module feature.json and displays full content
+  3. "Voir détail" → team lead reads module feature.json and displays full content
 ```
 
 **Step 3 — IMMEDIATELY after AskUserQuestion returns, handle the response:**
@@ -197,7 +413,9 @@ SendMessage({
 })
 ```
 → CRITICAL: You MUST send this message. Do NOT skip this step.
-→ Then WAIT for the agent to send `MODULE_COMPLETE:{moduleCode}` (see §4).
+→ Then WAIT for the agent to send `MODULE_COMPLETE:{moduleCode}`.
+→ Add moduleCode to `layerState.approvedModules`.
+→ Continue to next module in this layer.
 
 **IF user selected "Modifier" (revision):**
 → Ask user for specific feedback via AskUserQuestion
@@ -210,9 +428,10 @@ SendMessage({
   summary: "{moduleCode} revision requested"
 })
 ```
-→ Then WAIT for the agent to send a new `PROPOSAL_READY` → go back to Step 1.
+→ Then WAIT for the agent to send a new `PROPOSAL_READY` → re-display this module's proposal.
+→ Other modules in the layer are NOT blocked — their proposals remain in receivedProposals.
 
-**IF user selected "Voir detail":**
+**IF user selected "Voir détail":**
 → Read module feature.json via ba-reader.readSection({feature_id, section})
 → Display relevant sections in detail
 → Go back to Step 2 (re-ask the validation question)
@@ -221,58 +440,120 @@ SendMessage({
 
 - Max **3 revision cycles** per module
 - After 3 rejections: team lead asks user if they want to switch to **inline interactive mode** for this module
-  - If yes: team lead loads step-03a1-setup.md and executes interactively (classic mode)
+  - If yes: shutdown agent, team lead loads step-03a1-setup.md and executes interactively
   - If no: mark module as "needs-review" and continue to next module
 
+### 3d. Layer Consistency Check (layers with 2+ modules)
+
+After ALL modules in a layer are approved, perform a final cross-module consistency verification:
+
+```
+IF layer.modules.length >= 2 AND all modules approved:
+
+  ULTRATHINK: Verify cross-module consistency:
+
+  1. FK references: Do FK field names match actual entity names across modules?
+     → e.g., if Products.CategoryId references Categories.Category, names must match
+
+  2. Permission paths: Are paths consistent and non-colliding?
+     → business.{app}.{module1}.{entity}.read vs business.{app}.{module2}.{entity}.read
+
+  3. i18n keys: Do keys follow consistent patterns? No collisions?
+     → {module1}.labels.name vs {module2}.labels.name (OK — namespaced)
+
+  4. Seed data IDs: Are deterministic GUIDs unique across modules?
+     → Check DeterministicGuid inputs don't collide
+
+  5. Entity attribute types: Are shared concepts typed consistently?
+     → If both modules define "Status", is it the same enum type?
+
+  IF inconsistency found:
+    Display warning with specific issue:
+    "⚠ Incohérence détectée entre {mod1} et {mod2}: {description}"
+
+    AskUserQuestion:
+      question: "Corriger automatiquement cette incohérence ?"
+      options:
+        1. "Corriger" → send REVISION to affected agent(s) with fix instructions
+        2. "Ignorer" → proceed (will be caught in consolidation)
+
+    IF "Corriger":
+      → Send REVISION:{moduleCode}\n{auto-fix instructions} to affected agent
+      → Wait for new PROPOSAL_READY
+      → Re-approve (no full re-review needed — only the fix)
+
+  IF no inconsistency found:
+    Display: "✓ Cohérence cross-module vérifiée pour le layer {L}"
+```
+
 ---
 
-## 4. Module Completion & Agent Shutdown
+## 4. Layer Completion & Agent Shutdown
 
-When the team lead receives `MODULE_COMPLETE:{moduleCode}` from the agent, execute these steps **IN ORDER**:
+After ALL modules in a layer are approved AND consistency check passed:
 
-### 4a. Update Tracking
+### 4a. Shutdown ALL Layer Agents (MANDATORY — do NOT skip)
+
+**IMMEDIATELY** after layer is fully approved, send shutdown_request to ALL agents in this layer:
 
 ```javascript
-teamContext.completedModules.push(moduleCode);
-teamContext.currentModuleIdx++;
+// Send shutdown to ALL layer agents
+FOR each moduleCode in layer.modules:
+  SendMessage({
+    type: "shutdown_request",
+    recipient: "mod-{moduleCode}",
+    content: "Layer complete, shutting down"
+  })
+```
+
+Wait for ALL agents to confirm shutdown (`shutdown_response approve: true`).
+
+> **WARNING:** If you skip this step, agents will remain running indefinitely.
+> Agents CANNOT self-terminate — they NEED shutdown_request from you.
 
-ba-writer.advanceModuleLoop({feature_id});
-ba-writer.updateModuleStatus({feature_id, moduleCode, status: "specified"});
+### 4b. Update Layer Tracking
 
-Display: "✓ Module {moduleCode} specified ({completedModules.length}/{moduleOrder.length})"
+```javascript
+FOR each moduleCode in layer.modules:
+  teamContext.completedModules.push(moduleCode);
+  ba-writer.updateModuleStatus({feature_id, moduleCode, status: "specified"});
+
+teamContext.completedLayers.push(layerState.layerIndex);
+
+Display:
+"═══ Layer {L} complete — {layer.modules.length} modules specified ═══"
+"═══ Progress: {completedModules.length}/{moduleOrder.length} modules ═══"
 ```
 
-### 4b. Shutdown Agent (MANDATORY — do NOT skip)
+### 4c. Build Updated Context for Next Layer
 
-**IMMEDIATELY** after receiving MODULE_COMPLETE, send shutdown_request to terminate the agent:
+Before spawning the next layer's agents, rebuild the `completedModulesSummary`:
 
 ```
-SendMessage({
-  type: "shutdown_request",
-  recipient: "mod-{moduleCode}",
-  content: "Module complete, shutting down"
-})
+ba-reader.getCompletedModulesSummary({feature_id})
+→ Now includes ALL modules from completed layers
+→ This summary is injected into next layer's agent prompts
+→ Agents in the next layer will have full context of everything specified so far
 ```
 
-The agent will respond with `shutdown_response approve: true` and terminate.
-**Wait for the agent to confirm shutdown** before spawning the next agent.
-
-> **WARNING:** If you skip this step, the agent will remain running indefinitely.
-> The agent CANNOT self-terminate — it NEEDS this shutdown_request from you.
+### 4d. Next Layer or Consolidation
 
-### 4c. Next Module or Consolidation
+```
+IF more layers remain in dependencyGraph.layers:
+  → Go back to §2 for the next layer
 
-If more modules remain → spawn next module agent (go to §2).
-If all modules complete → proceed to §5 (Consolidation).
+IF all layers complete (all modules specified):
+  → Proceed to §5 (Consolidation)
+```
 
 ---
 
 ## 5. Consolidation Phase
 
-After ALL modules are specified:
+After ALL modules are specified (all layers complete):
 
 ```
-Display: "═══ All modules specified — Starting consolidation ═══"
+Display: "═══ All {moduleOrder.length} modules specified — Starting consolidation ═══"
 ```
 
 ### 5a. Spawn Consolidation Agent
@@ -295,6 +576,7 @@ Execute cross-module consolidation (steps 04a + 04b):
 ## Context
 - Feature ID: {featureId}
 - Modules: {moduleOrder.join(", ")}
+- Dependency layers: {JSON.stringify(dependencyGraph.layers)}
 - All modules have status "specified"
 
 ## Output
@@ -328,7 +610,7 @@ When CONSOLIDATION_READY received:
 
 AskUserQuestion: "Approuvez-vous la consolidation ?"
 - "Approuver" → send APPROVED to agent → agent writes consolidation to master feature.json
-- "Reviser" → send feedback → agent adjusts
+- "Réviser" → send feedback → agent adjusts
 
 After approval → shutdown consolidation agent → proceed to §6.
 
@@ -393,7 +675,7 @@ After handoff complete:
 
 ```javascript
 // Safety net: shutdown ALL remaining agents (module agents + consolidation + handoff)
-// Module agents should already be shut down in §4b, but this catches any missed ones.
+// Module agents should already be shut down in §4a, but this catches any missed ones.
 const allAgents = [
   ...teamContext.moduleOrder.map(m => `mod-${m}`),
   "consolidation",
@@ -422,28 +704,32 @@ Display: "═══ Business-analyse complete — Team cleaned up ═══"
 
 ## 8. Error Recovery
 
-### Agent Crash
+### Agent Crash in Parallel Layer
 
-If an agent stops responding or sends ERROR:
+If an agent stops responding or sends ERROR while other agents in the same layer are still working:
 
 ```javascript
-// 1. Check module status in feature.json
+// 1. Do NOT disrupt other agents in the layer — they continue working
+// 2. Check module status in feature.json
 const moduleStatus = ba-reader.getModuleStatus({feature_id});
 
-// 2. If module has partial data (status = "in-progress"):
-//    → Spawn new agent for same module
+// 3. If module has partial data (status = "in-progress"):
+//    → Spawn new agent for same module (joins existing layer)
 //    → New agent detects partial state and continues
 //    → Include in prompt: "Resume specification — partial data exists in feature.json"
 
-// 3. Track retry count
+// 4. Track retry count per module
 if (retryCount[moduleCode] >= 3) {
   Display: "Agent failed 3 times for module {moduleCode}."
   AskUserQuestion: "Fallback to inline interactive mode for this module?"
-  // If yes: load step-03a1-setup.md inline
+  // If yes: remove from pendingProposals, will handle inline after layer completes
   // If no: skip module, mark as "needs-review"
 }
 ```
 
+> **Key difference from sequential mode:** Other agents in the layer keep running.
+> The crashed module is retried independently without blocking the layer.
+
 ### Context Exhaustion on Team Lead
 
 The team lead should stay under 30% context usage. If approaching limits:
@@ -459,9 +745,13 @@ If the entire session crashes:
 1. User restarts `/business-analyse`
 2. Step-00 detects existing feature.json with `status: "decomposed"` or partial modules
 3. Reads `metadata.workflow.completedModules` to know which modules are done
-4. **Cleans up old team/task data** (§1a cleanup step) before creating new team
-5. Creates new team (§1b — captures actual team name), spawns agent for next incomplete module
-6. Continues normally
+4. Determines which layer to resume from:
+   - Find the first layer where not all modules are in `completedModules`
+   - Modules already completed in that layer are skipped
+5. **Cleans up old team/task data** (§1a cleanup step) before creating new team
+6. Creates new team (§1b — captures actual team name)
+7. Spawns agents ONLY for incomplete modules in the current layer
+8. Continues normally (parallel within layer, sequential between layers)
 
 ---
 
@@ -471,25 +761,68 @@ If the entire session crashes:
 |-----------|--------|
 | 1 module | NO team, classic inline execution |
 | 2+ modules | Team mode (Propose & Review) |
-| Modules in same dependency layer, no cross-refs | Sequential (future: parallel) |
-| Modules with dependencies | Strict topological order |
-| Agent error | Respawn with same module context (max 3 retries) |
+| Modules in same dependency layer | Spawn ALL in parallel (single message) |
+| Modules in different layers | Sequential — complete layer N before spawning layer N+1 |
+| Layer with 1 module | Standard single-agent propose-review |
+| Layer with 2+ modules | Pre-inject coordination notes + parallel spawn + batch review |
+| Cross-module query (completed layer) | Answer from completedModulesSummary |
+| Cross-module query (same layer, proposed) | Answer from receivedProposals |
+| Cross-module query (same layer, working) | Relay to target agent |
+| Circular cross-query (A↔B) | Team lead resolves autonomously |
+| Agent error in parallel layer | Other agents continue; retry crashed module |
 | User rejects 3 times | Offer fallback to inline interactive |
+| Layer consistency check fails | Auto-fix via targeted REVISION |
 | Context > 50% on team lead | Minimize presentation, suggest auto-approve |
-| Session crash | Resume from feature.json workflow state |
+| Session crash | Resume from feature.json + completedModules state |
+
+---
+
+## Message Protocol Summary
+
+### Standard Messages (unchanged)
+
+| Message | Direction | Purpose |
+|---------|-----------|---------|
+| `PROPOSAL_READY:{moduleCode}\n{summary}` | agent → lead | Specification complete |
+| `APPROVED:{moduleCode}` | lead → agent | User approved |
+| `REVISION:{moduleCode}\n{feedback}` | lead → agent | User wants changes |
+| `MODULE_COMPLETE:{moduleCode}` | agent → lead | After approval confirmed |
+| `CONSOLIDATION_READY:{appName}\n{report}` | agent → lead | Consolidation done |
+| `HANDOFF_READY:{appName}\n{report}` | agent → lead | Handoff done |
+| `ERROR:{moduleCode}:{description}` | agent → lead | Blocking error |
+| `shutdown_request` / `shutdown_response` | lead ↔ agent | Termination |
+
+### Cross-Module Messages (NEW — for parallel execution)
+
+| Message | Direction | Purpose |
+|---------|-----------|---------|
+| `CROSS_MODULE_QUERY:{targetModule}\nQuestion:{q}\nContext:{ctx}` | agent → lead | Ask about same-layer module |
+| `CROSS_MODULE_ANSWER:{requestingModule}\nAnswer:{a}` | lead → agent | Response to query |
+| `CROSS_MODULE_QUERY_RELAY:{requestingModule}\nQuestion:{q}` | lead → target agent | Relay query to working agent |
+| `CROSS_MODULE_ANSWER_RELAY:{requestingModule}\nAnswer:{a}` | target agent → lead | Response to relayed query |
 
 ---
 
 ## Token Budget Estimates
 
-| Phase | Agent | Estimated Context % | Duration |
-|-------|-------|-------------------|----------|
-| Init + Cadrage + Decomposition | Team lead (inline) | 20-30% | 5-10 min |
-| Module specification (per module) | mod-{code} agent | 40-60% | 3-5 min |
-| Propose & Review (per module) | Team lead relay | +2-5% per module | 1-2 min |
-| Consolidation | consolidation agent | 30-40% | 2-3 min |
-| Handoff | handoff agent | 40-50% | 3-5 min |
-| **Total team lead** | — | **30-50%** | — |
-| **Total per module agent** | — | **40-60%** | — |
-
-**Key insight:** Team lead never exceeds 50% even with 10+ modules, because module specifications happen in separate contexts.
+| Phase | Agent | Est. Context % | Notes |
+|-------|-------|---------------|-------|
+| Init + Cadrage + Decomposition | Team lead (inline) | 20-30% | Sequential, interactive |
+| Pre-spawn analysis (per layer) | Team lead | +1-3% per layer | Cross-module touchpoint detection |
+| Module specification (per module) | mod-{code} agent | 40-60% | Parallel within layer, fresh context |
+| Cross-module relay (per query) | Team lead | +1-2% per query | Lightweight relay |
+| Layer review (per layer) | Team lead | +3-5% per layer | Proposals + consistency check |
+| Consolidation | consolidation agent | 30-40% | Cross-module validation |
+| Handoff | handoff agent | 40-50% | Artifact generation |
+| **Total team lead** | — | **30-50%** | Same budget, more throughput |
+| **Total per module agent** | — | **40-60%** | Independent contexts |
+
+**Key insight:** Team lead never exceeds 50% even with 10+ modules, because:
+- Module specifications happen in separate parallel contexts
+- Cross-module relay is lightweight (forward message, not re-analyze)
+- Layer reviews are incremental (only current layer proposals)
+
+**Wall-clock time improvement:**
+- Layer with 3 independent modules: 1x (parallel) vs 3x (sequential) = **66% reduction**
+- Typical 4-module app (2 layers of 2): ~50% wall-clock reduction
+- Full benefit: apps with many independent foundation modules (layer 0)