@atlashub/smartstack-cli 4.17.0 → 4.18.0

package/templates/skills/business-analyse/steps/step-05a-handoff.md

@@ -178,7 +178,7 @@ Example:
 
 ### 4. Map Specification to Files
 
-> **IMPORTANT:** Generate `handoff.filesToCreate` as structured object with 7 categories.
+> **IMPORTANT:** Generate `handoff.filesToCreate` as structured object with 8 categories.
 > Each file entry is `{path, type, linkedFRs, linkedUCs, module}`. NO free text.
 > Read `.smartstack/config.json` to extract baseNamespace for project namespace.
 
@@ -198,9 +198,9 @@ For **EACH module** in topological order:
 > - API: `src/API/Controllers/HumanResources/ProjectsController.cs`
 > - Tests: `src/Tests/Unit/Domain/HumanResources/Projects/ProjectTests.cs`
 
-#### 4.1-4.7 File Category Templates
+#### 4.1-4.8 File Category Templates
 
-See [references/handoff-file-templates.md](../references/handoff-file-templates.md) for the complete JSON templates for all 7 categories:
+See [references/handoff-file-templates.md](../references/handoff-file-templates.md) for the complete JSON templates for all 8 categories:
 
 | Category | Source | Key rules |
 |----------|--------|-----------|
@@ -211,6 +211,11 @@ See [references/handoff-file-templates.md](../references/handoff-file-templates.
 | **4.5 Frontend** | `specification.uiWireframes[]` | Pages, Components, Hooks + wireframe traceability |
 | **4.6 SeedData** | `specification.seedDataCore` | 2 app-level + per module CORE (NavigationModule + NavigationSections + Permissions + Roles) + business + IClientSeedDataProvider |
 | **4.7 Tests** | All layers | Unit, Integration, Security tests |
+| **4.8 Documentation** | `cadrage.documentation` | Technical docs, user guides, tooltips (doc-data.ts). Peut être `[]` si aucune doc requise. |
+
+> **Catégorie `documentation` :** Inclure les fichiers identifiés en step-01-cadrage §4g.
+> - Si `cadrage.documentation.userDocumentation.needed = false` ET `cadrage.documentation.technicalDocumentation.needed = false` → `"documentation": []`
+> - Sinon, lister les fichiers attendus : `doc-data.ts` (tooltips in-app), guides Markdown, specs API supplémentaires.
 
 #### Route Convention (CRITICAL)
 
@@ -336,19 +341,54 @@ Additional per-section pages (dashboard, import, etc.) are separate entries.
 > **CRITICAL:** Cross-module integration tasks MUST exist in a dedicated PRD file.
 > Without this, ralph-loop will NOT execute E2E tests or FK validation.
 
+> **FORMAT:** Must use ralph-loop v3 format with `tasks[]` array (NOT `implementation.filesToCreate`).
+> Ralph's step-01 v3 fast path requires `$version === "3.0.0"` AND `tasks[]` to be present.
+> A PRD with only `implementation.filesToCreate` will be silently ignored by ralph-loop.
+
 Generate `.ralph/prd-CrossModule.json` with:
 ```json
 {
   "$version": "3.0.0",
-  "implementation": {
-    "filesToCreate": {
-      "tests": [
-        { "path": "src/Tests/Integration/CrossModule/ForeignKeyValidationTests.cs", "type": "IntegrationTests", "module": "CrossModule" },
-        { "path": "src/Tests/Integration/CrossModule/PermissionMatrixTests.cs", "type": "SecurityTests", "module": "CrossModule" },
-        { "path": "src/Tests/Integration/CrossModule/E2EFlowTests.cs", "type": "E2ETests", "module": "CrossModule" }
-      ]
+  "feature": "CrossModule Integration Tests",
+  "status": "pending",
+  "project": { "module": "CrossModule", "application": "{AppName}" },
+  "config": { "max_iterations": 10, "current_iteration": 1 },
+  "metadata": { "sourceFeatureJson": "{path to master feature.json}" },
+  "tasks": [
+    {
+      "id": "CM-001",
+      "description": "Generate FK validation integration tests across all modules",
+      "status": "pending",
+      "category": "test",
+      "dependencies": [],
+      "acceptance_criteria": "ForeignKeyValidationTests.cs created, all FK references validated across modules, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
+    },
+    {
+      "id": "CM-002",
+      "description": "Generate permission matrix integration tests (cross-module access control)",
+      "status": "pending",
+      "category": "test",
+      "dependencies": ["CM-001"],
+      "acceptance_criteria": "PermissionMatrixTests.cs created, all cross-module permission paths validated, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
+    },
+    {
+      "id": "CM-003",
+      "description": "Generate E2E flow integration tests covering multi-module user journeys",
+      "status": "pending",
+      "category": "test",
+      "dependencies": ["CM-001", "CM-002"],
+      "acceptance_criteria": "E2EFlowTests.cs created, end-to-end flows tested, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
     }
-  }
+  ],
+  "history": [],
+  "created": "{ISO timestamp}",
+  "updated_at": "{ISO timestamp}"
 }
 ```
 
@@ -359,18 +399,52 @@ Add to progress.txt after all module tasks.
 > **Only generated when `workflow.mode === "project"`.**
 > Contains cross-application integration tests and shared entity validation.
 
+> **FORMAT:** Same v3 `tasks[]` format as 6c above — NOT `implementation.filesToCreate`.
+
+Generate `.ralph/prd-CrossApplication.json` with:
 ```json
 {
   "$version": "3.0.0",
-  "implementation": {
-    "filesToCreate": {
-      "tests": [
-        { "path": "src/Tests/Integration/CrossApplication/SharedEntityValidationTests.cs", "type": "IntegrationTests", "module": "CrossApplication" },
-        { "path": "src/Tests/Integration/CrossApplication/CrossAppPermissionTests.cs", "type": "SecurityTests", "module": "CrossApplication" },
-        { "path": "src/Tests/Integration/CrossApplication/CrossAppE2EFlowTests.cs", "type": "E2ETests", "module": "CrossApplication" }
-      ]
+  "feature": "CrossApplication Integration Tests",
+  "status": "pending",
+  "project": { "module": "CrossApplication", "application": "{ProjectName}" },
+  "config": { "max_iterations": 10, "current_iteration": 1 },
+  "metadata": { "sourceFeatureJson": "{path to project feature.json}" },
+  "tasks": [
+    {
+      "id": "CA-001",
+      "description": "Generate shared entity validation tests across all applications",
+      "status": "pending",
+      "category": "test",
+      "dependencies": [],
+      "acceptance_criteria": "SharedEntityValidationTests.cs created, shared entities consistent across apps, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
+    },
+    {
+      "id": "CA-002",
+      "description": "Generate cross-application permission integration tests",
+      "status": "pending",
+      "category": "test",
+      "dependencies": ["CA-001"],
+      "acceptance_criteria": "CrossAppPermissionTests.cs created, inter-app permissions validated, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
+    },
+    {
+      "id": "CA-003",
+      "description": "Generate cross-application E2E flow tests",
+      "status": "pending",
+      "category": "test",
+      "dependencies": ["CA-001", "CA-002"],
+      "acceptance_criteria": "CrossAppE2EFlowTests.cs created, multi-app user journeys tested, dotnet test passes",
+      "started_at": null, "completed_at": null, "iteration": null,
+      "commit_hash": null, "files_changed": [], "validation": null, "error": null
     }
-  }
+  ],
+  "history": [],
+  "created": "{ISO timestamp}",
+  "updated_at": "{ISO timestamp}"
 }
 ```
 
@@ -794,7 +868,30 @@ ELSE:
   })
 ```
 
-#### 7d. Final Verification (BLOCKING)
+#### 7d. PRD Metadata Contract (MANDATORY)
+
+> **Ralph-loop quality gate** (`step-01 section 1b`) reads `prd.metadata.sourceFeatureJson` to locate
+> the feature.json and verify `handoff.status === "handed-off"`. This field MUST be written by
+> `ss derive-prd` into each generated PRD's `metadata` section.
+
+Verify that the `ss derive-prd` MCP tool writes the following into each generated PRD:
+```json
+{
+  "metadata": {
+    "sourceFeatureJson": "{absolute or relative path to this module's feature.json}",
+    "moduleCode": "{module code}",
+    "application": "{application name}"
+  }
+}
+```
+
+**If `sourceFeatureJson` is absent from the generated PRD**, ralph-loop falls back to a file search
+(`findFile('docs/business/**/business-analyse/**/feature.json')`). This works for single-feature projects
+but may return the wrong feature.json in multi-feature projects. Report this to the MCP team if observed.
+
+---
+
+#### 7e. Final Verification (BLOCKING)
 
 ```
 count = 0

package/templates/skills/ralph-loop/SKILL.md

@@ -43,9 +43,9 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 
 **Single module:**
 1. Init: parse flags, verify MCP, setup .ralph/ (step-00)
-2. Load tasks from prd.json — unified v3 has pre-computed tasks (step-01, READ ONCE)
-3. Execute first task (step-02, READ ONCE)
-4. Commit + update progress (step-03, READ ONCE)
+2. Load tasks from prd.json — unified v3 has pre-computed tasks (step-01, step FILE read once)
+3. Execute first task (step-02, step FILE read once)
+4. Commit + update progress (step-03, step FILE read once)
 5. Check completion → enter COMPACT LOOP (step-04)
 6. **COMPACT LOOP** (step-04 → references/compact-loop.md):
    - Find eligible → batch by category (max 5) → execute → test → commit → loop
@@ -105,6 +105,7 @@ LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODUL
 | `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
 | `{parallel_mode}` | boolean | Teams mode enabled via `-p` flag. Ralph generates Phase 0 (entities) sequentially, then spawns parallel teammates. |
 | `{team_name}` | string\|null | Team name for parallel mode (e.g., "smartstack-hr") |
+| `{team_active}` | boolean | True after `TeamCreate`, false after `TeamDelete`. Used in step-04 section 3a to send `MODULE_COMPLETE` to team-lead instead of advancing the module queue locally. |
 </state_variables>
 
 <mcp_requirements>
@@ -162,6 +163,10 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 | 04 | `steps/step-04-check.md` | Check completion, compact loop entry | ~185 |
 | 05 | `steps/step-05-report.md` | Generate final report | ~150 |
 
+> **"Read Once" rule:** Each **step file** (step-01 to step-04) is loaded only once at the start of the first iteration. From iteration 2 onward, `compact-loop.md` drives the loop inline — step files are NOT re-read. This reduces context consumption. **Exception:** prd.json is re-read every iteration (it changes); step files are not.
+
+> **Distinction:** `/apex -d prd.json` is invoked every iteration (B2 of compact-loop) — that is normal and expected. "Read Once" applies only to the step instruction files, not to data files or apex delegations.
+
 **Reference files (loaded conditionally):**
 | File | Loaded when |
 |------|-------------|

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -151,14 +151,30 @@ if (guardrailsNeeded.length > 0) {
 
 ## Artifact Verification
 
-After category check, verify artifacts actually exist for completed tasks:
+After category check, verify artifacts actually exist for completed tasks.
+
+> **Patterns read from PRD metadata first** (`prd.metadata.artifactPatterns`), falling back to SmartStack defaults.
+> This allows non-standard project structures to work without hardcoded paths.
 
 ```javascript
 const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+
+// Read custom patterns from PRD metadata (set by ss derive-prd based on project structure)
+const customPatterns = prd.metadata?.artifactPatterns || {};
+
 const artifactChecks = {
-  'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0,
-  'test': () => glob.sync('tests/**/*Tests.cs').length > 0,
-  'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0
+  'frontend': () => {
+    const patterns = customPatterns.frontend || ['**/src/pages/**/*.tsx', '**/src/app/**/*.tsx'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  },
+  'test': () => {
+    const patterns = customPatterns.test || ['tests/**/*Tests.cs', '**/*.spec.ts', '**/*.test.ts'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  },
+  'api': () => {
+    const patterns = customPatterns.api || ['src/*/Controllers/**/*Controller.cs', 'src/**/controllers/**/*.ts'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  }
 };
 
 for (const [cat, check] of Object.entries(artifactChecks)) {

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -36,7 +36,7 @@ if (prd._sectionSplit?.enabled) {
 
   if (!nextPhase) {
     // All phases done — check if master PRD tasks are all complete
-    goto CHECK_COMPLETION;
+    // → STOP this section. Return to step-04 section 1 (CHECK_COMPLETION path).
   }
 
   const depsOk = nextPhase.dependsOn.every(depIdx =>
@@ -46,7 +46,7 @@ if (prd._sectionSplit?.enabled) {
   if (!depsOk) {
     // Phase blocked — should not happen with topological sort
     console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
-    goto CHECK_COMPLETION;
+    // → STOP this section. Return to step-04 section 1 (CHECK_COMPLETION path).
   }
 
   const phaseLabel = nextPhase.type === 'foundation'
@@ -54,11 +54,14 @@ if (prd._sectionSplit?.enabled) {
     : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (${nextPhase.entities.length} entities)`;
   console.log(`[{iteration}/{max}] SECTION SPLIT: ${phaseLabel}`);
 
-  // INVOKE /apex -d {nextPhase.prdFile}
-  // Apex sees a normal (smaller) PRD and executes normally
+  // ↓ MANDATORY: execute this skill call now (not pseudo-code)
+```
+
+**INVOKE `/apex -d {nextPhase.prdFile}`**
+
+Apex sees a focused PRD for this phase only. After apex returns, continue:
 
-  // After apex returns: merge results back into master PRD
-  // Read references/section-splitting.md sections 7-9
+```javascript
   const phasePrd = readJSON(nextPhase.prdFile);
   for (const phaseTask of phasePrd.tasks) {
     const masterTask = prd.tasks.find(t => t.id === phaseTask.id);
@@ -96,7 +99,7 @@ if (prd._sectionSplit?.enabled) {
   writeJSON('.ralph/prd.json', prd);
 
   // → Skip to section C (commit PRD state), then D (loop back)
-  goto COMMIT_PRD;
+  // → SKIP sections A and B. Jump directly to section C (COMMIT_PRD) below.
 }
 ```
 
@@ -112,43 +115,65 @@ if (prd._sectionSplit?.enabled) {
 ```javascript
 const MAX_RETRIES = 3;
 
+// DEAD-END PRE-CHECK: verify if we are truly stuck BEFORE resetting retries.
+// Resetting retries FIRST would mask a dead-end — the check must run on the raw state.
+const failedBeforeRetry = prd.tasks.filter(t => t.status === 'failed');
+const retriableBeforeReset = failedBeforeRetry.filter(t => (t._retryCount || 0) < MAX_RETRIES);
+const hasPendingBeforeRetry = prd.tasks.some(t => t.status === 'pending');
+const allDoneBeforeRetry = prd.tasks.every(t => t.status === 'completed' || t.status === 'skipped');
+
+const isDeadEnd = !hasPendingBeforeRetry && !allDoneBeforeRetry && retriableBeforeReset.length === 0;
+
+if (isDeadEnd) {
+  // TRUE dead-end: no pending tasks, not all done, and no retries left.
+  // Mark prd.status = 'failed' NOW so step-04 section 4 routes to step-05.
+  // Then fall through to `eligible.length === 0` below which returns to step-04.
+  console.log(`DEAD-END: ${prd.tasks.filter(t=>t.status==='completed').length} done, ${failedBeforeRetry.length} failed (retries exhausted), ${prd.tasks.filter(t=>t.status==='blocked').length} blocked`);
+  prd.status = 'failed';
+  writeJSON('.ralph/prd.json', prd);
+  // DO NOT reset retries below — skip to eligible search (will find 0 tasks → CHECK_COMPLETION)
+}
+
 // RETRY: Reset failed tasks to pending if retries remain (max 3 attempts per task)
-for (const task of prd.tasks) {
-  if (task.status !== 'failed') continue;
-  const retryCount = task._retryCount || 0;
-  if (retryCount < MAX_RETRIES) {
-    task.status = 'pending';
-    task._retryCount = retryCount + 1;
-    task.error = null;
-    console.log(`RETRY [${task.id}] attempt ${retryCount + 1}/${MAX_RETRIES}: ${task.description.substring(0, 60)}`);
+// Skipped when isDeadEnd = true (no retriable tasks remain anyway).
+if (!isDeadEnd) {
+  for (const task of prd.tasks) {
+    if (task.status !== 'failed') continue;
+    const retryCount = task._retryCount || 0;
+    if (retryCount < MAX_RETRIES) {
+      task.status = 'pending';
+      task._retryCount = retryCount + 1;
+      task.error = null;
+      console.log(`RETRY [${task.id}] attempt ${retryCount + 1}/${MAX_RETRIES}: ${task.description.substring(0, 60)}`);
+    }
   }
-}
 
-// Unblock tasks whose dependencies are no longer failed (due to retries above)
-for (const task of prd.tasks) {
-  if (task.status !== 'blocked') continue;
-  const stillBlocked = task.dependencies.some(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && (dep.status === 'failed' || dep.status === 'blocked');
-  });
-  if (!stillBlocked) {
-    task.status = 'pending';
-    task.error = null;
-    console.log(`UNBLOCKED [${task.id}]: dependencies resolved`);
+  // Unblock tasks whose dependencies are no longer failed (due to retries above)
+  for (const task of prd.tasks) {
+    if (task.status !== 'blocked') continue;
+    const stillBlocked = task.dependencies.some(depId => {
+      const dep = prd.tasks.find(t => t.id === depId);
+      return dep && (dep.status === 'failed' || dep.status === 'blocked');
+    });
+    if (!stillBlocked) {
+      task.status = 'pending';
+      task.error = null;
+      console.log(`UNBLOCKED [${task.id}]: dependencies resolved`);
+    }
   }
-}
 
-// Block pending tasks whose dependencies are still failed/blocked
-for (const task of prd.tasks) {
-  if (task.status !== 'pending') continue;
-  const depsBlocked = task.dependencies.some(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && (dep.status === 'failed' || dep.status === 'blocked');
-  });
-  if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
-}
+  // Block pending tasks whose dependencies are still failed/blocked
+  for (const task of prd.tasks) {
+    if (task.status !== 'pending') continue;
+    const depsBlocked = task.dependencies.some(depId => {
+      const dep = prd.tasks.find(t => t.id === depId);
+      return dep && (dep.status === 'failed' || dep.status === 'blocked');
+    });
+    if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
+  }
 
-writeJSON('.ralph/prd.json', prd);
+  writeJSON('.ralph/prd.json', prd);
+} // end if (!isDeadEnd)
 
 // Find ALL eligible tasks (dependencies met)
 const eligible = prd.tasks.filter(task => {
@@ -160,8 +185,8 @@ const eligible = prd.tasks.filter(task => {
 });
 
 if (eligible.length === 0) {
-  // Dead-end or all done — return to step-04 sections 2-4
-  goto CHECK_COMPLETION;
+  // All done or dead-end — return to step-04 sections 2-4
+  // [goto CHECK_COMPLETION]
 }
 
 // BATCH: group by category, take first group (max 5)
@@ -265,21 +290,28 @@ chore(ralph): update PRD state — iteration {iteration}
 Tasks: {completed}/{batch_size} completed via /apex
 Overall: {totalCompleted}/{total}
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+Co-Authored-By: Claude AI <noreply@anthropic.com>
 EOF
 )"
 ```
 
 ### C4. PRD Sync Verification (HARD CHECK)
 
-```javascript
-const prdVerify = readJSON('.ralph/prd.json');
-const actuallyCompleted = prdVerify.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed');
+> **Note:** `prdCheck` (read in C1) is the authoritative post-apex snapshot.
+> `completed` (from B3) was computed on a DIFFERENT read — do NOT mix the two.
+> Re-derive the count from `prdCheck` to avoid stale-reference mismatches.
 
-if (actuallyCompleted.length !== completed) {
-  console.error('PRD SYNC ERROR: Mismatch between apex results and prd.json');
-  // Force re-read — apex may have written after our read
-  // DO NOT overwrite — apex is the source of truth for task statuses
+```javascript
+// Re-derive completed count from the SAME object used for the commit (prdCheck)
+const actuallyCompleted = prdCheck.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed').length;
+const actuallyFailed    = prdCheck.tasks.filter(t => batchIds.includes(t.id) && t.status === 'failed').length;
+
+if (actuallyCompleted !== completed) {
+  console.warn(`PRD SYNC WARNING: B3 reported ${completed} completed, prdCheck shows ${actuallyCompleted}`);
+  console.warn('Using prdCheck as source of truth (apex may have written between reads)');
+  // DO NOT overwrite prdCheck — apex is the source of truth for task statuses
+  // Update local `completed` variable for progress reporting consistency
+  completed = actuallyCompleted;
 }
 ```
 

package/templates/skills/ralph-loop/references/init-resume-recovery.md

@@ -88,7 +88,9 @@ if (handoffStatus === 'handed-off') {
   console.log('BA artifacts detected without PRD — auto-recovering...');
 
   // Call ss derive-prd to generate PRD files
-  const result = exec(`ss derive-prd --application ${masterFeature}`);
+  // Flag: --feature (path to feature.json) — matches ss derive-prd CLI convention
+  // See also: step-05c-ralph-readiness.md section 2 "Fix: ss derive-prd --feature {path} --output ..."
+  const result = exec(`ss derive-prd --feature ${masterFeature}`);
 
   if (result.exitCode !== 0) {
     console.error('ss derive-prd failed — cannot auto-recover');

package/templates/skills/ralph-loop/references/parallel-execution.md

@@ -63,7 +63,7 @@ git commit -m "chore(foundation): entities for all modules
 
 $(allModules.map(m => m.code).join(' + ')) — ${allEntities.length} entities
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+Co-Authored-By: Claude AI <noreply@anthropic.com>"
 ```
 
 Result: ModelSnapshot contains all entities. Database ready for application layers.
@@ -159,7 +159,8 @@ DO NOT:
 - Modify DbContext (already done in Phase 0)
 
 EXECUTE:
-For each PRD file: invoke /apex -d {prdFile}
+For each PRD file:
+**INVOKE `/apex -d {prdFile}`**
 Apex will detect existing entities and skip domain/infrastructure layers.
 
 When done, send a message to team lead with results:
@@ -177,33 +178,32 @@ When done, send a message to team lead with results:
 
 ### 4. Wait for Teammates
 
-Ralph waits for all teammates to send completion messages:
+Ralph waits for all teammates to send completion messages via `TaskOutput`.
 
-```javascript
-const MAX_WAIT = 3600; // 1 hour timeout
-const POLL_INTERVAL = 5; // 5 seconds
-
-const teamMateResults = [];
-const deadline = Date.now() + MAX_WAIT * 1000;
-
-while (teamMateResults.length < teammates.length && Date.now() < deadline) {
-  // Check for new messages from teammates
-  const messages = getTeamMessages();
-  for (const msg of messages) {
-    if (msg.type === 'completion') {
-      teamMateResults.push(msg);
-      console.log(`  ✅ ${msg.teammate}: ${msg.status}`);
-    }
-  }
-  if (teamMateResults.length < teammates.length) {
-    sleep(POLL_INTERVAL * 1000);
-  }
-}
+> **How messaging works in Claude Code Agent Teams:**
+> - Teammates communicate by calling `SendMessage({ recipient: "team-lead", content: ... })`
+> - Ralph (team lead) receives messages automatically — there is NO polling loop
+> - Each message delivery triggers a new turn for Ralph
+> - Ralph stays idle between messages — this is normal behavior (not a hang)
+> - An idle notification does NOT mean the teammate has finished or failed
 
-if (teamMateResults.length < teammates.length) {
-  console.error(`TIMEOUT: ${teammates.length - teamMateResults.length} teammates did not complete`);
-  // Set status to 'partial'
-}
+```javascript
+// Track expected completions (set before spawning)
+const expectedCount = teammates.length;
+const results = []; // populated as SendMessage notifications arrive
+
+// Ralph's response to each incoming message:
+// - Parse content: "complete" | "failed"
+// - Push to results[]
+// - If results.length === expectedCount → proceed to section 5
+// - If "failed": log error, continue waiting for other teammates
+
+// If a teammate goes silent > 30 min:
+// → Send it a wake-up message (idle is normal, silence is not)
+// → If no response after 2 retries: mark as "timed-out" and continue
+
+console.log(`Waiting for ${expectedCount} teammates...`);
+// (Ralph is idle here — woken up by each incoming SendMessage)
 ```
 
 ### 5. Collect & Validate Results

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

@@ -91,21 +91,31 @@ Quick: `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json
 
 ---
 
-## 4c. Team Orchestration (multi-module, 2+ modules)
+## 4c. Team Orchestration (multi-module LEGACY — dependency layer mode only)
+
+> **MANDATORY:** Load `references/team-orchestration.md` BEFORE creating any team.
+> The full spawn protocol (teammate prompts, wait logic, layer coordination, cleanup)
+> is defined there. Creating a team without loading it results in an empty team with no teammates.
+
+> **PARALLEL MODE (`-p`):** Team creation does NOT happen here. It happens in step-02 section 3a,
+> after step-01 loads the tasks. Sections 5-7 below (completion promise, metadata, summary) must
+> still be executed. Do NOT return early when `{parallel_mode}` is true.
 
 ```javascript
 if (PRD_COUNT > 1) {
-  // Read references/team-orchestration.md for full protocol
+  // STEP 1: Load references/team-orchestration.md NOW (before any TeamCreate call)
+  // This file contains: mode selection, Phase 0 protocol (parallel), layer protocol (legacy), cleanup.
+
   const layers = master.metadata?.workflow?.dependencyGraph?.layers;
 
-  if (layers) {
-    // PARALLEL MODE: Use Agent Teams
-    TeamCreate({ team_name: `ralph-${appName}` });
-    // Spawn teammates per layer (see reference)
-    // STOP here — team orchestration takes over
+  if (layers && !{parallel_mode}) {
+    // DEPENDENCY LAYER MODE (legacy, no -p flag): team orchestration takes over here.
+    // TeamCreate + spawn logic are defined in references/team-orchestration.md section "Dependency Layer Mode".
+    // STOP here — legacy team orchestration handles everything from this point.
     return;
   }
-  // If no layers: fall through to sequential mode
+  // PARALLEL MODE (-p): fall through to sections 5-7, team created later in step-02 section 3a.
+  // NO -p, NO layers: fall through to sequential mode (compact loop per module).
 }
 ```
 
@@ -123,7 +133,7 @@ if (!completion_promise) {
 ## 6. Collect Metadata
 
 ```bash
-CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
+CLI_VERSION=$(node -e "try{console.log(require('./package.json').version)}catch(e){console.log('unknown')}" 2>/dev/null || echo "unknown")
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 PROJECT_PATH=$(pwd)
 ```

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -58,16 +58,24 @@ If `.ralph/prd.json` exists:
 
 If `.ralph/prd.json` does not exist: continue to section 1b.
 
-### 1b. BA Handoff Quality Gate (BLOCKING)
+### 1b. BA Handoff Quality Gate (BLOCKING when BA artifacts present)
 
 > **CRITICAL:** Before generating ANY tasks, verify the BA handoff is complete.
 > A missing handoff means no frontend files, no test plan, no BR-to-code mapping.
 
+> **INTENTIONAL SKIP:** If `sourceFeatureJson` is null (manual start via `{task_description}`, no BA run),
+> this quality gate is **intentionally skipped** — the loop proceeds in "manual mode" and generates tasks
+> from the task description. This is by design, not a bug. Inform the user in the summary (section 6 of step-00).
+
 ```javascript
 const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
   || findFile('docs/business/**/business-analyse/**/feature.json');
 
-if (sourceFeatureJson) {
+if (!sourceFeatureJson) {
+  // Manual mode: no BA artifacts found — skip quality gate
+  console.log('Manual mode: no BA artifacts detected — tasks will be generated from task description');
+  // Continue to section 2 (Analyze Task Description)
+} else {
   const feature = readJSON(sourceFeatureJson);
   const handoff = feature.handoff || {};
 

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

@@ -93,11 +93,16 @@ if (prd._sectionSplit?.enabled) {
     : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (services + controllers + pages + tests)`;
   console.log(`SECTION SPLIT: ${phaseLabel}`);
 
-  // INVOKE /apex -d {nextPhase.prdFile}
-  // Apex sees a normal (smaller) PRD and executes normally
+  // ↓ MANDATORY: invoke apex now (not pseudo-code — execute this skill call)
+```
+
+**INVOKE `/apex -d {nextPhase.prdFile}`**
 
-  // After apex returns: merge results into master PRD
-  // Read references/section-splitting.md sections 7-9 (execution, merging, failure handling)
+Apex sees a focused (smaller) PRD covering only this phase's scope and executes normally.
+After apex returns: merge results into master PRD.
+Read `references/section-splitting.md` sections 7-9 for execution, merging, and failure handling.
+
+```javascript
 
   nextPhase.status = 'completed';
   prd._sectionSplit.currentPhase = nextPhase.phase;

package/templates/skills/ralph-loop/steps/step-03-commit.md

@@ -52,7 +52,7 @@ chore(ralph): PRD state — iteration {iteration}, {completed}/{total} tasks
 
 Module: {current_module}
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+Co-Authored-By: Claude AI <noreply@anthropic.com>
 EOF
 )"