@atlashub/smartstack-cli 3.35.0 → 3.37.0

package/templates/skills/ralph-loop/references/team-orchestration.md

@@ -6,7 +6,295 @@
 
 ---
 
-## 1. Layer Detection
+## Mode Selection
+
+Ralph-loop supports TWO team orchestration modes:
+
+### 1. **Parallel Mode** (`-p` flag) — RECOMMENDED
+
+**Architecture:** Phase 0 (entities sequential by Ralph) + Phase 1-N (teammates parallel)
+
+**Avantages:**
+- ✅ Zero EF Core ModelSnapshot conflicts (entities generated once in Phase 0)
+- ✅ True parallelization on 75-85% of code (services/controllers/frontend/tests)
+- ✅ Teammates have isolated contexts (no saturation)
+- ✅ 2-3x faster than sequential mode
+- ✅ Simple coordination (no dependency graph needed)
+
+**When to use:**
+- 2+ applications OR 5+ modules
+- Complex modules with many entities
+- Need guaranteed conflict-free execution
+
+**Workflow:**
+1. Ralph generates ALL entities + migration (Phase 0)
+2. Ralph spawns teammates (1 per application or module)
+3. Teammates generate services/controllers/frontend/tests in parallel
+4. Ralph collects results + validates
+5. TeamDelete
+
+See section **Parallel Mode Protocol** below.
+
+---
+
+### 2. **Dependency Layer Mode** (no `-p` flag) — LEGACY
+
+**Architecture:** Layer-by-layer execution based on dependency graph
+
+**Avantages:**
+- ✅ Respects module dependencies
+- ✅ Works without `-p` flag (backward compatible)
+
+**Inconvénients:**
+- ⚠️ Requires dependency graph in feature.json
+- ⚠️ EF Core ModelSnapshot conflicts possible if modules touch same entities
+- ⚠️ More complex coordination
+
+**When to use:**
+- Modules have strict dependencies
+- No `-p` flag specified (legacy mode)
+- Single-application projects with <5 modules
+
+See section **Dependency Layer Mode Protocol** below.
+
+---
+
+## Parallel Mode Protocol (if `-p` flag)
+
+### Phase 0: Foundation (Ralph sequential)
+
+Ralph generates ALL entities from ALL modules in ONE pass to avoid ModelSnapshot conflicts.
+
+```javascript
+// 1. Collect all entities
+const allPrds = glob('.ralph/prd-*.json').map(f => readJSON(f));
+const allEntities = [];
+const allModules = [];
+
+for (const prd of allPrds) {
+  const entities = prd.tasks
+    .filter(t => t.category === 'domain')
+    .map(t => extractEntityName(t.description));
+
+  allEntities.push(...entities);
+  allModules.push({
+    code: prd.project.module,
+    application: prd.project.application,
+    entityCount: entities.length
+  });
+}
+
+console.log(`Phase 0: Generating ${allEntities.length} entities from ${allModules.length} modules`);
+
+// 2. Invoke apex in foundation mode
+// /apex --foundation -d .ralph/prd.json
+//
+// Apex will:
+// - Generate ALL entity classes
+// - Generate ALL EF configurations
+// - Register ALL DbSets in DbContext
+// - Create ONE migration with all entities
+// - Skip services/controllers/frontend/tests
+
+// 3. Verify build
+const buildResult = bash('dotnet build');
+if (buildResult.exitCode !== 0) {
+  throw new Error('Phase 0 build failed');
+}
+
+// 4. Commit foundation
+bash(`git add . && git commit -m "chore(foundation): entities for all modules"`);
+
+console.log(`Phase 0 complete. ModelSnapshot contains ${allEntities.length} entities.`);
+```
+
+---
+
+### Phase 1-N: Spawn Teammates (parallel)
+
+Ralph creates a team and spawns teammates (1 per application OR 1 per module if app has >3 modules).
+
+```javascript
+// 1. Determine teammate granularity
+const teammates = [];
+const applicationsMap = {}; // group modules by application
+
+for (const mod of allModules) {
+  if (!applicationsMap[mod.application]) {
+    applicationsMap[mod.application] = [];
+  }
+  applicationsMap[mod.application].push(mod);
+}
+
+for (const [appName, modules] of Object.entries(applicationsMap)) {
+  if (modules.length <= 3) {
+    // 1 teammate per APPLICATION
+    teammates.push({
+      name: `apex-${kebabCase(appName)}`,
+      application: appName,
+      modules: modules.map(m => m.code),
+      scope: 'application'
+    });
+  } else {
+    // Application has >3 modules → 1 teammate per MODULE
+    for (const mod of modules) {
+      teammates.push({
+        name: `apex-${kebabCase(appName)}-${kebabCase(mod.code)}`,
+        application: appName,
+        modules: [mod.code],
+        scope: 'module'
+      });
+    }
+  }
+}
+
+console.log(`Spawning ${teammates.length} teammates:`);
+for (const t of teammates) {
+  console.log(`  - ${t.name} (${t.scope}): ${t.modules.join(', ')}`);
+}
+
+// 2. Create team
+const teamName = `smartstack-${kebabCase(projectName)}`;
+TeamCreate({ team_name: teamName, description: `Parallel dev for ${teammates.length} modules` });
+
+// 3. Spawn teammates in parallel (single message, multiple Task calls)
+for (const teammate of teammates) {
+  const prdFiles = teammate.modules.map(m => `.ralph/prd-${m}.json`);
+
+  Task({
+    subagent_type: "apex",
+    name: teammate.name,
+    team_name: teamName,
+    mode: "bypassPermissions",
+    prompt: `
+You are teammate ${teammate.name}.
+
+## Context
+- Application: ${teammate.application}
+- Modules: ${teammate.modules.join(', ')}
+- PRD files: ${prdFiles.join(', ')}
+
+## Phase 0 Completed (by Ralph)
+ALL entity classes, EF configurations, and migrations are already created.
+The ModelSnapshot is complete and the database schema is ready.
+
+## Your Task
+For each module in your scope, generate:
+- Services (Application layer)
+- Controllers (API layer)
+- Seed data (Navigation + Permissions + RolePermissions + Business data)
+- Frontend (Pages + Routes + i18n for all 4 languages)
+- Tests (Unit + Integration)
+
+## Execution
+For each PRD file:
+  1. INVOKE /apex -d {prdFile}
+     → Apex will see existing entities and skip domain/infrastructure layers
+     → Apex will generate services/controllers/seed/frontend/tests
+     → Apex will run POST-CHECKs and commit per layer
+  2. Verify build passes
+  3. Verify tests pass
+
+## Communication Protocol
+When ALL your modules are complete:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "COMPLETE:${teammate.name}",
+    summary: "${teammate.name} completed ${teammate.modules.join(', ')}"
+  })
+
+If you encounter a BLOCKING error:
+  SendMessage({
+    type: "message",
+    recipient: "team-lead",
+    content: "ERROR:${teammate.name}:{error_summary}",
+    summary: "${teammate.name} blocked"
+  })
+
+## DO NOT
+- Create new entities (already done in Phase 0)
+- Create migrations (ModelSnapshot already complete)
+- Modify existing entities or EF configs
+    `,
+    description: `${teammate.application} - ${teammate.modules.join(', ')}`
+  });
+}
+```
+
+---
+
+### Collect Results
+
+Ralph waits for all teammates to send completion messages.
+
+```javascript
+// Track completion
+const expectedTeammates = teammates.length;
+let completedTeammates = 0;
+let errors = [];
+
+// Messages arrive automatically via SendMessage
+// When a teammate sends "COMPLETE:xxx", increment counter
+// When a teammate sends "ERROR:xxx:yyy", record error
+
+// Wait loop (teammates send messages when done)
+console.log(`Waiting for ${expectedTeammates} teammates to complete...`);
+
+// After all teammates complete (or timeout):
+console.log(`Results:`);
+console.log(`  ✓ Completed: ${completedTeammates}/${expectedTeammates}`);
+console.log(`  ✗ Errors: ${errors.length}`);
+
+for (const error of errors) {
+  console.log(`    - ${error}`);
+}
+```
+
+---
+
+### Validation
+
+After all teammates complete, Ralph runs global validation.
+
+```bash
+# Full solution build
+dotnet build --no-restore
+
+# Full test suite
+dotnet test --no-build
+
+# MCP validation
+mcp__smartstack__validate_conventions checks=["all"]
+```
+
+---
+
+### Cleanup
+
+```javascript
+// Shutdown teammates
+for (const teammate of teammates) {
+  SendMessage({
+    type: "shutdown_request",
+    recipient: teammate.name,
+    content: "All modules complete, shutting down team"
+  });
+}
+
+// Wait for shutdown confirmations, then:
+TeamDelete();
+
+console.log(`Team ${teamName} deleted. All teammates shut down.`);
+```
+
+---
+
+## Dependency Layer Mode Protocol (no `-p` flag — LEGACY)
+
+### 1. Layer Detection
+
+**For dependency layer mode only (legacy, no `-p` flag).**
 
 Read dependency graph from master feature.json:
 
@@ -32,7 +320,7 @@ if (!layers) {
 
 ---
 
-## 2. Team Setup
+### 2. Team Setup (Legacy)
 
 ```javascript
 // Create team
@@ -49,7 +337,9 @@ const teamContext = {
 
 ---
 
-## 3. Teammate Spawn — Per Layer
+### 3. Teammate Spawn — Per Layer (Legacy)
+
+**For dependency layer mode only.**
 
 For each layer, spawn teammates IN PARALLEL (single message, multiple Task calls):
 
@@ -80,7 +370,9 @@ for (const layer of layers) {
 
 ---
 
-## 4. Teammate Prompt Template
+### 4. Teammate Prompt Template (Legacy)
+
+**For dependency layer mode only.**
 
 Each teammate receives a self-contained prompt that delegates to `/apex`:
 
@@ -119,7 +411,9 @@ ${prdFile}
 
 ---
 
-## 5. Team Lead Wait Logic
+### 5. Team Lead Wait Logic (Legacy)
+
+**For dependency layer mode only.**
 
 After spawning a layer, the team lead waits for completion:
 
@@ -144,7 +438,9 @@ let errors = [];
 
 ---
 
-## 6. Cross-Module Verification
+### 6. Cross-Module Verification (Legacy)
+
+**For dependency layer mode only.**
 
 After all layers complete, team lead runs:
 
@@ -161,7 +457,9 @@ mcp__smartstack__validate_conventions checks=["all"]
 
 ---
 
-## 7. Cleanup
+### 7. Cleanup (Legacy)
+
+**For dependency layer mode only.**
 
 After all modules done and report generated:
 
@@ -177,12 +475,31 @@ TeamDelete();
 
 ---
 
+---
+
 ## Decision Matrix
 
-| Condition | Action |
-|-----------|--------|
-| 1 module | NO team, classic compact loop |
-| 2+ modules, no dependency graph | Sequential layers (one at a time) |
-| 2+ modules, with layers | Parallel within each layer |
-| Teammate error | Log, try to continue other modules |
-| All modules done | Cross-module verify → step-05 → TeamDelete |
+| Condition | Mode | Action |
+|-----------|------|--------|
+| 1 module | No team | Classic compact loop (no teams) |
+| 2+ modules, `-p` flag | **Parallel Mode** | Phase 0 (Ralph entities) + spawn teammates per app/module |
+| 2+ modules, no `-p`, with dependency graph | Dependency Layer Mode (legacy) | Parallel within each layer based on dependencies |
+| 2+ modules, no `-p`, no dependency graph | Sequential (legacy) | Sequential layers (one module at a time) |
+| Teammate error (parallel) | Continue | Log error, other teammates continue, report in step-05 |
+| Teammate error (legacy) | Continue | Log, try to continue other modules |
+| All modules done (parallel) | Validate + Report | Global build/test → step-05 report → TeamDelete |
+| All modules done (legacy) | Validate + Report | Cross-module verify → step-05 → TeamDelete |
+
+---
+
+## Recommendations
+
+| Scenario | Recommended Mode |
+|----------|------------------|
+| **Multi-app project** (HR + CRM + PM) | **Parallel mode** (`-p`) — 2-3x faster, zero conflicts |
+| **Single-app, 5+ modules** | **Parallel mode** (`-p`) — better scalability |
+| **Single-app, 2-4 modules** | Parallel mode (`-p`) OR sequential (both OK) |
+| **Modules with strict dependencies** | Dependency layer mode (no `-p`) OR sequential |
+| **Single module** | No teams (compact loop) |
+
+**Default recommendation: Use `-p` for 2+ modules.**

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -32,6 +32,7 @@ Defaults:
   completion_promise: null
   verbose_mode: false
   resume_mode: false
+  parallel_mode: false
   current_iteration: 1
 
 Flags:
@@ -39,9 +40,12 @@ Flags:
   -c TEXT / --completion-promise TEXT → {completion_promise} = TEXT
   -v / --verbose                → {verbose_mode} = true
   -r / --resume                 → {resume_mode} = true
+  -p / --parallel               → {parallel_mode} = true
   Remainder → {task_description}
 ```
 
+**If `-p` detected:** set `parallel_mode = true`. Ralph will execute Phase 0 (entities) sequentially, then spawn parallel teammates for services/controllers/frontend/tests. Requires 2+ modules to be effective.
+
 ## 2. Verify MCP (MANDATORY)
 
 ```

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -52,7 +52,168 @@ writeJSON('.ralph/prd.json', prd);
 
 ### 3. Delegate to /apex
 
-#### 3a. Section-Split Mode
+#### 3a. Parallel Mode (if `-p` flag)
+
+**IF `{parallel_mode}` == true:**
+
+##### Phase 0: Foundation (Ralph sequential)
+
+```javascript
+// Collect ALL entities from ALL modules
+const allEntities = [];
+const allModules = [];
+for (const prdFile of glob('.ralph/prd-*.json')) {
+  const modulePrd = readJSON(prdFile);
+  const moduleEntities = modulePrd.tasks
+    .filter(t => t.category === 'domain')
+    .map(t => extractEntityName(t.description));
+  allEntities.push(...moduleEntities);
+  allModules.push({
+    code: modulePrd.project.module,
+    application: modulePrd.project.application,
+    prdFile: prdFile,
+    entityCount: moduleEntities.length
+  });
+}
+
+console.log(`PARALLEL MODE: Phase 0 — Foundation`);
+console.log(`  Generating ${allEntities.length} entities from ${allModules.length} modules`);
+console.log(`  Entities: ${allEntities.join(', ')}`);
+
+// Ralph generates ALL entities via apex foundation mode
+// INVOKE: /apex --foundation -d .ralph/prd.json
+//
+// Apex will:
+// - Generate ALL entity classes
+// - Generate ALL EF configurations
+// - Register ALL DbSets in DbContext
+// - Create ONE migration with all entities
+// - Skip services/controllers/frontend/tests
+
+console.log(`Phase 0 completed. ModelSnapshot contains ${allEntities.length} entities.`);
+console.log(`Committing foundation...`);
+
+// Git commit
+// bash: git add . && git commit -m "chore(foundation): entities for all modules"
+```
+
+##### Phase 1-N: Spawn Teammates (parallel)
+
+```javascript
+// Determine granularity: 1 teammate per APPLICATION or per MODULE
+const teammates = [];
+const applicationsMap = {}; // group modules by application
+
+for (const mod of allModules) {
+  if (!applicationsMap[mod.application]) {
+    applicationsMap[mod.application] = [];
+  }
+  applicationsMap[mod.application].push(mod);
+}
+
+for (const [appName, modules] of Object.entries(applicationsMap)) {
+  if (modules.length <= 3) {
+    // 1 teammate per APPLICATION
+    teammates.push({
+      name: `apex-${kebabCase(appName)}`,
+      application: appName,
+      modules: modules.map(m => m.code),
+      prdFiles: modules.map(m => m.prdFile)
+    });
+  } else {
+    // Application has >3 modules → 1 teammate per MODULE
+    for (const mod of modules) {
+      teammates.push({
+        name: `apex-${kebabCase(appName)}-${kebabCase(mod.code)}`,
+        application: appName,
+        modules: [mod.code],
+        prdFiles: [mod.prdFile]
+      });
+    }
+  }
+}
+
+console.log(`Spawning ${teammates.length} teammates:`);
+for (const t of teammates) {
+  console.log(`  - ${t.name}: ${t.modules.join(', ')}`);
+}
+
+// Create team
+TeamCreate({
+  team_name: `smartstack-${kebabCase(prd.project.name || 'project')}`,
+  description: `Parallel development for ${teammates.length} modules`
+});
+
+// Spawn teammates
+for (const teammate of teammates) {
+  Task({
+    subagent_type: "apex",
+    name: teammate.name,
+    team_name: `smartstack-${kebabCase(prd.project.name || 'project')}`,
+    prompt: `
+      You are teammate ${teammate.name}.
+
+      CONTEXT:
+      - Application: ${teammate.application}
+      - Modules: ${teammate.modules.join(', ')}
+      - PRD files: ${teammate.prdFiles.join(', ')}
+
+      ENTITIES ALREADY EXIST (Phase 0 completed by Ralph):
+      All entity classes, EF configurations, and migrations are already created.
+      The ModelSnapshot is complete and the database is ready.
+
+      YOUR TASK:
+      For each module, generate:
+      - Services (Application layer)
+      - Controllers (API layer)
+      - Seed data (Navigation + Permissions + Business data)
+      - Frontend (Pages + Routes + i18n for all 4 languages)
+      - Tests (Unit + Integration)
+
+      DO NOT:
+      - Create new entities (already done)
+      - Create migrations (ModelSnapshot already complete)
+
+      EXECUTE:
+      For each PRD file: invoke /apex -d {prdFile}
+      Apex will see existing entities and skip domain/infrastructure layers.
+
+      When done, send a message to team lead with results.
+    `
+  });
+}
+
+// Ralph waits for teammates to complete
+// Each teammate will send a message when done
+// Ralph collects results and proceeds to validation
+```
+
+##### Collect Results
+
+```javascript
+// Wait for all teammates to send completion messages
+// Ralph receives SendMessage from each teammate with status
+
+const teammateResults = []; // populated from teammate messages
+
+console.log(`All teammates completed:`);
+for (const result of teammateResults) {
+  console.log(`  - ${result.name}: ${result.status}`);
+}
+
+// Cleanup team
+TeamDelete();
+
+// Proceed to step-03 for global validation
+```
+
+> See `references/team-orchestration.md` for full parallel execution protocol.
+
+**ELSE (not parallel mode):**
+
+Continue with section-split mode or standard mode below.
+
+#### 3b. Section-Split Mode
 
 ```javascript
 if (prd._sectionSplit?.enabled) {
@@ -94,7 +255,7 @@ if (prd._sectionSplit?.enabled) {
 
 > See `references/section-splitting.md` for full detection, mapping, PRD construction, and merge logic.
 
-#### 3b. Standard Mode (no split)
+#### 3c. Standard Mode (no split, no parallel)
 
 **INVOKE `/apex -d .ralph/prd.json`**